
		Frequently Asked Questions
		about src2pkg and trackinstall


This document attempts to answer some questions about src2pkg
and trackinstall, especially regarding the most common ways
of using src2pkg or trackinstall to create packages from many
different types of source, binary or noarch content using
the built-in features.

Easy tutorial for the simplest cases:
1. See the help or man-pages
2. Basic syntax and types of content
3. Compile and create a package from a tarball



1. How to see the help or manpages

   Running the command 'src2pkg' alone (without arguments) will show a
   help screen that summarizes basic syntax and usage. You can also see
   the same text by running the command with the '-h' or '--help' option
   like this: 'src2pkg --help'.
   
   Running the command 'trackinstall' without arguments is different, though.
   Since the trackinstall program was written to be a drop-in replacement
   for the 'checkinstall' program, running the command without arguments
   will attempt to create a package from content in the current directory
   using the command 'make install', if there is a Makefile present. To
   see the help screen for 'trackinstall' use the '-h' or '--help' as above
   for src2pkg: 'trackinstall --help'. If trackinstall finds no Makefile in the
   current directory it will show the help text.
   
   Both programs have their own manpage with similar but more complete information
   than that given in the help text. The manpage for each can be accessed by running
   the command 'man src2pkg' or 'man trackinstall'.
   
   Both programs will show their version number by running the command with
   the '--version' option.
   
   About trackinstall: I wrote it mostly to fill the needs of those who really like
   the way checkinstall works. I rarely use it myself -it's nearly always better
   to use src2pkg as it will give more consistent and complete results. src2pkg tracks
   and documents the whole process of package creation including the preparation
   of the content -usually by configuring and compiling uncompressed source archives.
   If you pass special options to the configure script or do any kind of special
   pre-processing before compiling the sources and then run trackinstall (or checkinstall),
   the next time you want to recompile the sources you may not remember the details
   of how you got it to work.
   Still, trackinstall may be a better solution if you are building packages from
   inside CVS or SVN sources or in other cases where you really need to build a package
   from content in an already-existing directory which should not be removed aftwrards.
   You may need to take special care about cleaning up or restoring the directory contents
   when doing so, though, in order to insure the repeatability of the build process.
   Creating packages from archives which contain pre-compiled binaries like the Opera browser,
   the ATI video drivers or linux (Adobe/MacroMedia)FLASH plugins may be easier using
   trackinstall, especially those that you would usually install by running an 'install.sh'
   or .run script. This even works for interactive scripts which require input from the user.

2. Basic syntax and types of content
  
## Using src2pkg to process compressed source-code archives
  src2pkg was written primarily to create packages from compiled source code which is
  most commonly available in compressed tar archive format. These are archives which have
  one of these file extensions: '.tar.gz', '.tgz', '.tar.bz2' or '.tbz'. It can also
  handle '.rpm' and '.src.rpm' which are RPM archives used by many Linux distributions
  like Fedora or Mandriva. It also can work with debian source archives using the '.deb'
  archive suffix.
  
  The above usage is obtained simply by running src2pkg followed by the archive name, like this:
  
src2pkg archive-name
  
## Using src2pkg to process compressed binary archives (generic binary content or installable
  packages using a foreign package format)
  src2pkg can also serve as a package 'convertor' for archives which contain binary or noarch
  content. Most commonly these are '.rpm' or '.deb' archives, but you can convert nearly any
  archive that contains content which is already laid-out in a 'skeleton' of the root file system.
  You can even convert Slackware packages which have been created by other means. One user has
  reported using src2pkg this way to verify (and correct!) packages which he had created using
  other build methods.
  
  In this way src2pkg serves as drop-in replacement for the utility called rpm2tgz, at least
  for the way it is most commonly used -to convert *binary* rpm's to Slackware package format.
  src2pkg does a better job than rpm2tgz in these cases as it checks and corrects permissions
  in these 'foreign' archives which may cause problems on your system. It also inserts a description
  file for the Slackware database which helps to remind you of where it came from and to insure
  that the package is properly removeable with 'removepkg'.
  However, pointing src2pkg to an .rpm archive which contains *source code* will not simply 'convert'
  the archive to the '.tgz' format, as rpm2tgz does. Instead, src2pkg will uncompress the archive
  and attempt to configure and compile the sources. This makes it possible for you to work directly
  with '.rpm' source archives without having to convert them to another format first.
  
  Usually archives which contain binary programs contain something like 'i486' or other similar
  notation which indicates the machine architecture which the binaries are built to run on. src2pkg
  automatically detects name like these for many different architectures and assumes that the archive
  is a binary package when it finds them. Usage is the same as above for source archives.
  
  
## Using src2pkg to execute an existing src2pkg build script
  src2pkg itself is just a small front-end to the src2pkg functions which are contained in the file
  /usr/libexec/src2pkg/FUNCTIONS. The functions serve as a sort of packge-building API and contain
  many options and procedures which can be controlled with more detail by using a *.src2pkg script.
  src2pkg can create these scripts for you. You can then run them as a separate program or use src2pkg
  to execute them for you. Once created you can execute them like this:
  
src2pkg src2pkg-script-name

  Or, even easier:
  
src2pkg -X

  Using the '-X' option causes src2pkg to search for and run the first *.src2pkg or *.src2pkg.auto
  script that it finds in the current directory. The advantage of running your scripts this way is
  that you can take advantage of using custom code in your script while still controlling the basic
  user Options from the command line like this:
src2pkg -X -VV -C
  This tells src2pkg to run the src2pkg script, show the full output from all commands and place the
  final package in the current working directory(CWD).
  
## Using src2pkg over a network
  src2pkg can also work with either archives or src2pkg scripts which are not already on your system
  in the same way as above, except that you supply src2pkg with a valid URL to the compressed archive
  or src2pkg script. This makes it really easy to create your own source repository or use those of
  others. It also makes it possible to 'bootstrap' a system from sources with only a few programs
  already running on your system. You must be connected to the network or internet for this to work.
  Usage is like this:
  
src2pkg URL-to-archive
  Or:
src2pkg URL-to-src2pkg-script-name

## Basic understanding of the src2pkg command-line options
  Internally, the src2pkg functions use hundreds of variables which allow for lots of flexibilty of
  usage and make it easier to read, understand and extend the capabilities of src2pkg. However, the
  variables usually have long names to better describe what the variable does, and are written in
  all capital letters with underlines between the words like this: SOME_VARIABLE
  This makes the variables 'stand out' in the code but makes them hard to use from the command-line.
  src2pkg and trackinstall were written principally to provide a command-line interface to shorten
  the length of the command line and to provide command-line syntax similar to what is used with
  most other programs.
  
  Only the most commonly used options are included in the src2pkg and trackinstall programs. Otherwise
  the help pages would be several screens long and overwhelm the user with the number of options.
  Command-line options fall into two broad classes which we call 'User Options' and 'Build Options'.
  Each class of options uses a different type of syntax which makes it easier to remember.
	
	### User Options
	  These options are given on the command line with (usually) a single capital letter
	  and do not require or accept any argument to the option, typically like this:
	  src2pkg -T archive-name
	  
	  ## Test build
	  This (-T) is a useful example as it shows how to use src2pkg just to see if a source archive
	  will successfully compile on your system. The '-T' option means to just test the build
	  and is written like this: 'TEST_BUILD=1' internally. When given this option, src2pkg only
	  runs through the first part of the build -decompressing, configuring and compiling the
	  sources without trying to install them or create a package. It prints out a prompt to
	  tell you whether the program could be compiled or not.
	  
	  ## Automatic scripting
	  Another common option of this type is '-N' or '-A'.
	  These are the options used to cause src2pkg to write a src2pkg script for you. The difference
	  is this: 
	  The '-N' option means something like 'NEW' or 'NOBUILD'. If you use this option
	  src2pkg will write a src2pkg build script for the archive-name that you give. It will also
	  create a default package description (slack-desc) file for the package. It does this without
	  trying to locate, uncompress, compile or build the archive-name you give. It will, in fact,
	  write a build script for a tarball which is not on your system, or which you have given 
	  the *wrong* name for.
	  
	  The '-A' options stands for AUTO_SCRIPT. In contrast to the '-N' option, the '-A' causes
	  src2pkg to write the build script for you *after* the build is finished and only if the build
	  succeeds. This means that the archive-name or URL must be valid. The default description
	  file (slack-desc) is created and inserted into the package tree and a *copy* of it is placed
	  in the current directory, unless you have started out by supplying one in the current directory.
	  Note that src2pkg always inserts a slack-desc if none is found -even when no command-line
	  arguments are given.
	  
	  When src2pkg first creates a build script it adds '.auto' to the name like this:
	  NAME.src2pkg.auto
	  This serves 2 purposes: It shows at a glance that the script was generated automatically. If
	  you hand-edit the script or have passed other options (especially Build Options) to src2pkg
	  when creating the script, you should change the name of the script to simply name.src2pkg.
	  This keeps src2pkg from overwriting the file if you run src2pkg again with the '-N' option.
	  
	  
	  The same is true for the default slack-desc files created. They are named new.slack-desc to 
	  avoid overwriting any exisiting slack-desc file in the current directory.
	  
	  Internally src2pkg recognizes and treats both '*.src2pkg' and '*.src2pkg.auto' files the same.
	  However, if you edit the new.slack-desc file you *must* change the name of it to simply:
	  slack-desc for it to be included in the package.
	  
	  I usually begin the process of building a package by using '-N' option.
	  Then I edit the new.slack-desc file and change the name of it to just 'slack-desc'.
	  Then I begin the build by using 'src2pkg -X' to execute the name.sr2pkg.auto script.
	  I only change the name of the NAME.src2pkg.auto script to just NAME.src2pkg if I have
	  passed Build Options during script creation, or if I add code to the script. This way I can tell
	  at a glance if the script contains any extra or unusual instructions.
	  
	  Both the '-N' and '-A' options will write Build Options that you give on the command-line into
	  the NAME.src2pkg.auto script produced. But since the scripts generated with the '-A' option are
	  written *after* the build, they may contain other options which are used internally when src2pkg
	  discovers something unusual about the sources or configuration method. These are mostly noted for
	  your information. Sometimes they are filled in but then commented out. This is done in order to
	  not break the portability of your script for use by others or on a different OS version or
	  machine architecture.
	  
	  ## Cleanup of temporary files
	  Another often-used User Option is '-W' which means to WIPEOUT or delete temporary files
	  created during the package build process. this includes the SRC_DIR, PKG_DIR and any
	  logs or build reports which have been created during the build. It does *not* remove
	  src2pkg scripts or slack-desc files.
	  
	  ## Installation of packages, building groups of packages, bootstrapping
	  Using the '-I' option tells src2pkg to install the final package to your system so that it is
	  registered with the system package database. src2pkg uses a miniature internal version of
	  installpkg to do this, so it will work even to compile and upgrade pktools or if no pkgtools
	  are present on the system.
	  Group-builds are made easy this way allowing you to build and install packages as you go which
	  are required by later builds. This is especially useful for building things like GNOME or XORG.
	  Hundreds of packages can be built with a single command by using a small script which loops
	  through a list of sources. some examples are included in the documentation. Of course you test
	  each build and make sure the order is correct.
	  
	  Most User Options are used to control the general behaviour of src2pkg and do not have any
	  effect on the content of the package itself.
	
	### Build Options
	
	  The Build Options are used to control and modify the content of the package or the way it
	  is created and they require you to supply an argument to the option. These options use all
	  lowercase letters and require an argument. For most either a short or long syntax is accepted
	  so that, for example, -m='make dep all' could also be written as:--make_comand='make dep all'.
	  If the options contain spaces the whole option line should be quoted.
	  The long forms usually correspond to the way the option is written internally, except the letters
	  are all capitals like this: MAKE_COMMAND. This is the syntax used in a src2pkg script. If you
	  are having src2pkg write a src2pkg script and you pass these options with arguments to src2pkg,
	  they will be written into the script with script-style syntax. The following command:
	  src2pkg -N -m='make progname tests' archive-name
	  would create a src2pkg script that includes this line:
	  MAKE_COMMAND='make progname tests'
	  This is the same as running 'make progname' and 'make tests' in the sources
	  
	  ## Passing extra options to the 'configure' script (EXTRA_CONFIGS or -e'??')
	  For most users this is the most commonly used option of all. Many sources won't build properly
	  or won't build at all without passing some options to the configure script. src2pkg automatically
	  passes the --prefix='??' option (/usr by default) to configure. But sometimes you need to add
	  something to that, like --enable-shared, --with-included-gettext or --disable-tests. This is done
	  by using the -e='??' or --extra_configs='??' option with src2pkg similar to this:
	  -e='--enable-shared --disable-tests'
	  When you run src2pkg or a src2pkg script like this you'll see the extar options have added after
	  the --prefix='??' configure option.
	  
	  ## Customize the list of documents included
	  Using the -d='??' (--doclist='??' DOCLIST) lets you control which documents are included in the
	  final package, if needed. Otherwise src2pkg searches the uncompressed sources for commonly named
	  files which are part of any complete package -usually at least a README, AUTHORS, FAQ and, most
	  importantly, a copy of the license the software is released under.
	  
	  ## Changing the comand used to create the package content  -i='??' (INSTALL_LINE)
	  This is another commonly used option. By default, src2pkg tries to create the contents of the
	  package by executing the command 'make install' and carefully logging what happens. Files, links
	  and directories which are created on your system are then copied into the temporary PKG_DIR used by
	  src2pkg to create the final compressed, installable package.
	  
	  Packages that don't install with 'make install':
	  Some sources need extra rules passed to install in order to install features or documentation.
	  You can change the command used by src2pkg by passing the command line normally used to install
	  the software, like this:
	  src2pkg -i='make install install_data'
	  
	  
	  Using 'install.sh', '.bin' or .'run' or interactive installers:
	  You can also use src2pkg or trackinstall to create packages which use binary or script-based
	  installers. Even interactive installations can be tracked this way, though it is worth pointing
	  out that otherwise src2pkg contains no interactive routines at all. src2pkg asks no questions...
	  Example:
	  scr2pkg -i='sh install.sh'
	  This option can be further specified by passing the -S option to src2pkg. This tells it specifically
	  not to try to configure or compile the contents of the source archive and will, by default,
	  substitute the 'make install' command with 'sh install.sh'. It also makes sure that src2pkg runs
	  in verbose mode when the command is run, in case the installer is interactive. If you normally
	  run src2pkg in the default quiet mode, the verbosity is returned to quiet mode after the command
	  finishes.
	  
	  Note that if you are trying to compile sources which must be *configured* interactively, you must
	  run src2pkg in verbose mode using the -VV option. This happens very rarely, but if you normally
	  run in quiet mode and find that a build is hanging-up or stopping during configuration or installation,
	  try running the build with the verbosity turned up using the -VV option.
	  