
	HOWTO for src2pkg
	This document is a work-in-progress, but it contains the most
	up-to-date usage instructions as of src2pkg version 1.8. See the
	other included documents such as the FAQ.txt for more information.

1. What is the purpose of src2pkg?

2. What is src2pkg not for?

3. What kinds of sources are supported?

4. Getting started
	a. Simple command-line usage
	b. local sources
	c. using src2pkg over a network
	
5. How does src2pkg handle *
	a. slack-desc
	b. doinst.sh
	c. documents
	d. manpages
	e. patches
	f. configure options
	
6. Installation Methods
	a. REAL method
	b. DESTDIR method
	c. JAIL root method

7. Getting more help


1. What is the purpose of src2pkg?
	src2pkg is meant to make the creation of installable packages
	easier and more reliable for both beginners and advanced users.
	It creates packages using the simple 'tgz' format used by
	Slackware and many of its' derivatives.
	
	src2pkg makes it possible for beginners to create packages
	without knowing all the details of what makes a proper package.
	And it allows advanced package creators to focus on the more
	difficult aspects of package making which can't always be
	handled automatically, such as creating or modifying init scripts
	which allow the package to work properly when installed.
	
	src2pkg can create packages from many sources using only simple
	command-line options or no options at all. For more advanced
	or difficult packages, a src2pkg script can be used, making
	many more options available. src2pkg scripts use a simple,
	easy-to-understand syntax which is mostly self-explanatory.
	Package creation is divided into 16 basic steps, each of which
	is performed by a certain block of src2pkg code. Each block is
	written as a shell function and is meant to work independently
	of the other functions. This makes it possible to leave out
	functions when they are not needed or when the package requires
	doing things in some non-standard way.
	
	src2pkg can usually be used while logged in as a normal user.
	For some sources which are difficult to package without really
	installing the software, you must log in as user 'root' or
	other user with full permissions for writing files and running
	any commands on the system.
	
	
2. What is src2pkg not for?
	src2pkg is not a package manager or system updater. It is not
	designed to keep your system up-to-date with Slackware current.
	Nor is it designed to download and install pre-built packages,
	resolving dependencies as it goes. It is not meant to replace
	or perform the same functions as programs such as slackpkg,
	slapt-get or swaret.
	
3. What kinds of sources are supported?
	src2pkg is able to automatically handle package creation from
	many different kinds of content. The original purpose was to
	create packages from source-code tarballs -unpacking, configuring,
	and compiling the sources before creating the package content.
	But, the modularity of the src2pkg functions makes it easy to create
	packages from so called 'noarch' conetent or from pre-compiled
	binary content, such as proprietary video drivers, media players
	or any other type of content. It can also convert foreign or
	generic binary packages, such as binary *.rpm  or debian *.deb
	packages, into the Slackware format.
	
	Supported formats:
	
	a. autoconf sources -most commonly available sources use the
	'autoconf/automake' system for configuration. src2pkg handles
	these automatically -even when the sources are incomplete or
	outdated. Incomplete sources are sources from CVS or SVN which
	must have their configuration files generated first before
	running 'configure'. Many sources also use outdated configuration
	files which are incompatible with the versions of autoconf and
	automake which are installed on your system. src2pkg recognizes
	these and runs extra commands to update them first. It also
	properly handles sources which use GNUmakefiles instead of the
	more common Makefiles.
	
	b. src2pkg automatically handles sources which must be configured
	using cmake
	
	c. It also handles sources which use the 'scons' SConstruct system.
	
	d. It also handles sources whcih are configured to use the 'jam' system.
	
	e. Sources which use no configuration and contain pre-made Makefiles
	are also handled automatically. src2pkg can even correct the hard-coded
	installation paths when these are different than your default choice.
	
	e. src2pkg also handles sources whch use the Imake system for configuration.
	
	f. It can also automatically handle creating packages from python
	modules which use a setup.py script
	
	g. And it can also automatically handle sources which are normally
	installed by running an install.sh script.
	
	h. binary packages -src2pkg automatically handles the conversion of
	binary archives which use the .rpm or .deb suffix. When these are
	unpacked, src2pkg recognizes them and converts them to the Slackware-
	conformant format regarding placement of files and ownership and
	permissions of files and directories.
	
	i. generic binary content - Some programs sucg as the Opera browser
	are delivered as pre-compiled generic content. src2pkg can recognize
	these and create a package from such content.
	
	j. source code with no installation routine- Some sources don't come
	with any Makefile rule or script to do the installation for you. Many
	times src2pkg is able to create a package from them, finding the binaries,
	included documents and man-pages and packaging them for you.
	
	k. conversion/verification of Slackware-type packages-  srcpkg can be
	used to repackage or verify the content of packages which already are
	in the Slackware format. This may sound strange at first, but it can be
	used to verify packages made by others which you have downloaded. A couple
	of users have reported using src2pkg to verify packages that they have
	using other methods -src2pkg is able to scan the content for comnmon
	mistakes such as misplaced documents/manpages and also correct wrong
	file or directory permissions and ownership
	
	* Supported File Formats
	
	src2pkg transparently handles source archives which use the 'normal'
	gzip or bzip2 format -that is archives with these suffixes:
		.tar.gz
		.tgz
		.tar.bz2
		.tbz
	It also handles rpm-type source archives which have the .rpm suffix. This
	includes rpm archives which contain compressed gzip or bzip2 archives, as
	above, and also those which conatin a simple .tar archive or which have
	the sources located in an already-uncompressed directory.
	
	It also works with binary rpm packages that have the '.rpm' suffix and
	debian binary packages which have the '.deb' suffix. It also recognizes
	Slackware packages which have the '.tgz' suffix. src2pkg first uncompresses
	archives and then examines the content to figure out what it is so it
	can decide what to do with it.
	
	Support is also planned for '.tar.lzma' or '.tlz' archives as they are
	becoming more common.
	
4. Getting started -Simple command-line usage
	
	Here we'll cover the basic usage of src2pkg from the command line.
	First, you should know that src2pkg includes 3 command-line programs
	for helping you to create packages. The main program is, of course,
	srcpkg. It's just a small script-based program which acts as a front-end
	to the src2pkg functions which are located in separate files. src2pkg
	also inclludes the 'trackinstall' program which is a drop-in replacement
	for the 'checkinstall' program which used to be included with Slackware.
	'trackinstall' works much like checkinstall -it's meant to create a package
	from sources or other content which have already been uncompressed and
	configured/compiled if necessary. Usage is similar to checkinstall which
	is already familiar to many users. src2pkg also includes a very simple
	program called 'tracklist' which only creates a list of files and
	directories which are created when you run a command. Usage of 'tracklist'
	is covered in an appendix to this HOWTO.
	The usage and options of'trackinstall' is very similar to src2pkg itself.
	The main difference is that 'trackinstall' has less options since it only
	does half the work of src2pkg. More details about 'trackinstall' are found
	in an appendix to this HOWTO.
	
	Using src2pkg from the command line is very easy. The number of command-
	line options available is purposely limited so that the user has less to
	remember and less to be confused by. Using a src2pkg script provides many
	more options and flexibility, but usage of scripts will be discussed later
	in this document. We'll also discuss more command-line options and exact
	syntax later. Here we'll concentrate on the basics needed to get you started.
	Surprisingly, src2pkg can successfully create a package most of the time
	without using any advanced options at all.
	
	* Option types *
	The options for src2pkg can be divided into categories several ways, depending
	on which aspect we are talking about. The syntax used is slightly different
	from many Linux programs in order to keep it very simple to use.
	For command-line usage, options are divided into two types - User Options
	and - Build Options.
	* User Options are those which don't directly affect the package content.
	  They are usually given as a single capital letter and do not take any
	  arguments. Examples are the options '-A', '-N' or -'W'.
	  
	  Three notable exceptions to the single-letter rule above, are the options
	  for choosing the installation method to use. These are '-REAL', '-JAIL'
	  and '-DEST' (or '-DESTDIR') which is the default. We'll discuss what these
	  options mean later.
	  
	* Build Options usually have a direct effect on the package content. They are
	  given as small letters and require one or more arguments which is separated
	  from the option name with an '=' sign and usually enclosed with single-quotes.
	  Examples are: "-e='--disable-gnome'"  "-d='README AUTHORS'"
	  Most of the Build Options also have a long version. The above examples could also
	  be written as "-extra_configs='--disable-gnome'" and "-doclist='README AUTHORS'".
	  The long version is more explanatory but also can make for very long command
	  lines.
	  It is worth noting that the long versions of the Build Options match the names
	  of the variables and options as used internally by src2pkg and as used in
	  srcpkg scripts, except that they are all capitals. In other words, if you use the
	  "-e=" or "-extra_configs=" option from the command line, src2pkg will translate
	  that to "EXTRA_CONFIGS=" internally. It would also appear this way in a src2pkg
	  script.
	  
	
	* The Simplest Commands *
	All commands shown here are enclosed in double quotes, but you should not type
	include the double-quotes when actually typing the commands.
	
	* Typing simply "src2pkg" with no options will show the help or usage message.
	  Typing "src2pkg --help" or "src2pkg -h" will do the same thing
	
	* Usually when you want to create a package from a source tarball, you should
	  create a new empty directory in which to work. Place the source tarball inside
	  the new directory and then cd into the directory and type "src2pkg tarball-name".
	
	* If you want or need to use a src2pkg script for the package, src2pkg can create
	  it for you. You can simply type "src2pkg -N tarball-name" to have src2pkg
	  write the script for you. The '-N' option will also create a generic slack-desc
	  file which you can have included in the package. (More on the slack-desc later).
	  This option only creates the src2pkg script and slack-desc file.
	  
	  If you want or need to pass extra Build Options to src2pkg and you already
	  know what they are and want them included in your src2pkg script, you can
	  pass them to the program from the command line:
	  "src2pkg -N -e='--disable-tests' tarball-name"
	  will create a script for the program and include the line:
	  EXTRA_CONFIGS='--disable-tests'
	  in the src2pkg script
	  
	  Using the '-N' option will create a script even when the named tarball is 
	  not present. This is useful for writing scripts to work with tarballs which
	  are not even on your system yet.
	  
	  Once created, you can execute the src2pkg script with the '-X' option:
	  "src2pkg -X" will search for and execute the first src2pkg or src2pkg.auto
	  script in the current directory.
	  
	  The above two hints make it easy to create a script including extra Build Options
	  with one command and then actually run the script with another, shorter, command-
	  line which is more flexible. For instance, once you have created a script
	  you can run it to test the build with "src2pkg -X". Then while the package
	  is being built the first time, or when it has finished, you can make whatever
	  changes are needed and re-run it using "src2pkg -X -W". Adding the '-W' option
	  tells src2pkg to remove the temporary files created during the build. Note
	  that you should not include Build Options (lower-case) when you run the
	  script using "src2pkg -X". They will be ignored. If you need to add or change
	  the Build options for the script, just run "src2pkg -N other-options tarball-name"
	  again, where 'other-options' stands for any changes you need to make. It'S worth
	  noting that this is why src2pkg names these script 'something'.src2pkg.auto.
	  Every time you re-run the "src2pkg -N tarball-name" command the script gets
	  re-written. Once you have the script ding what you want, just change the name
	  to simply 'something'.src2pkg. Scripts with the simple .src2pkg suffix are
	  not overwritten.
	  
	  Note that the same holds true for automatically-generated slack-desc and doinst.sh
	  files. When src2pkg creates them they are named new.slack-desc and new.doinst.sh.
	  They will always get recreated if you re-run with the -N option. But if you change
	  the name to the 'real' name of the file, then they will be used in the package
	  and not overwritten. If you want or need to edit the generated files, do so
	  and then change the name to simply from new.slack-desc to slack-desc and from
	  new.doinst.sh to simply doinst.sh. This way they will not be overwritten even
	  if you re-run using the -N option. Naming them with their real name tells src2pkg
	  that you want it to use these files instead of creating new ones. Note also
	  that the new.* files created are copies of the files which are already included
	  in the package. In other words, src2pkg always includes a default slack-desc file
	  and doinst.sh file(if needed) in the package, even if there are none in the current
	  directory.
	  
	* A still better way to create a script and description file is to use the '-A'
	  option for auto-scripting. Unlike the '-N' option, the '-A' option actually
	  begins the normal package building process, unpacking, configuring and compiling
	  the sources. It only writes the build script when, and if, the package is
	  successfully created. The advantage is not obvious, but what happens is
	  significant. Since this option does the real work of unpacking the sources
	  and creating the package, src2pkg is able to discover more about what the
	  sources really are and what options are needed to build it. If it finds anything
	  non-standard, then it is able to automatically write this into the resulting
	  build script.
	  
	  The same holds true for the slack-desc description file. Using the '-N' option
	  simply writes a properly formatted slack-desc file which includes the name
	  of the program and the line 'No description was given for this package.' But,
	  using the '-A' option allows src2pkg to search inside the sources for a package
	  description. If it finds such descriptive information then it will include it
	  in the slack-desc file which is inserted in the package.
	  
	  Another option which can be used in combination with the '-A' option is the
	  '-Q' option which stands for 'query'. The '-Q' causes src2pkg to operate
	  interactively at certain points during the package building process. For instance,
	  if src2pkg has not found any descriptive information to include in the slack-desc
	  file and you have used the '-Q' option, src2pkg will stop before creating the
	  plain generic slack-desc file and allow you to type in a descritpion of the package.
	  It also will pause before running the 'configure' command, show you the options
	  which are available to the configure script and allow you to enter the options
	  you want.
	  
	  Using the '-A' and '-Q' options together makes a really powerful combination
	  which will usually allow for your package to be successfully built on the first
	  pass and, on completion, write a src2pkg script and slack-desc file which
	  contain all the changes you have specified or that have been discovered by
	  src2pkg during the process.
	
	  Otherwise, the behaviour regarding new.slack-desc and new.doinst.sh files is the
	  same as discussed above for the -N option.
	
	* Summary *
	  Most of the options are pretty self-explanatory from the help or usage message
	  printed by src2pkg, or by seeing the manual page with the command "man src2pkg".
	  Just keep in mind that the User Options with capital letters control things
	  'outside' the package and the Build Options with small letters control the content
	  of the package.
	  
	
	* Network Builds
	  The above discussion has centered on the use of src2pkg with sources which are
	  already on your system -usually located in the current working directory. But,
	  src2pkg can be used to download work with sources or src2pkg scripts which are
	  located on a network. Instead of giving just the name of the tarball or other
	  type of archive, pass the full URL to src2pkg. The file will be downloaded
	  before processing. In other words, you could run src2pkg with the '-N' option
	  and give the URL of a tarball. Then, when you run the script the tarball will
	  be downloaded and then unpacked and configured, etc.
	  
	  Or, you can src2pkg with a repository of src2pkg scripts. Instead of giving the
	  name or URL of a tarball to src2pkg, you can pass the name or URL of a src2pkg
	  *script* which will be downloaded and then run. Using this to its' full potential
	  actually allows you build a whole system over then network, nearly from scratch.
	  A src2pkg script can be written which includes the EXTRA_SOURCES variable which
	  is a list of all the other files to use in creating the package. This can include
	  a prepared slack-desc, doinst.sh and even patches or other material used by the
	  script. This provides an easy way to build groups of packages which should be
	  built together or which depend on each other. Including the '-I' option to src2pkg
	  will cause each package to installed to your system before the next is built.
	  Some users have reported using src2pkg this way to build their customized systems
	  'a la gentoo' or for building groups of related packages like GNOME.
	
5. How does src2pkg handle *
	a. slack-desc files
	   src2pkg always includes a slack-desc file in the finished package, even
	   if none is supplied. If you have a prepared slack-desc file already, simply
	   place it in the same directory as the sources and/or build script. It will
	   be included in the package, but only after being checked for validity. The
	   name of the package used in the slack-desc should match the name of the package
	   and a certain range of lines should be found with the right format. If there
	   are mistakes in the slack-desc file it will be renamed to rej.slack-desc and
	   a new one will be generated for the package by src2pkg. Usually a copy is
	   written to the current directory named new.slack-desc.
	   Original Slackware package directories contain description files for each
	   package which are the same as the slack-desc file included in the package.
	   these files are name "package-name".txt. If you place one of these files in
	   the current directory, it will be treated the same as a slack-desc file.
	   
	   If no slack-desc is supplied, sr2pkg can search the sources for files which
	   may contain a description. If the sources contain and rpm-type *.spec file
	   then the description used there will be used to generate the slack-desc file.
	   in the same way, if the sources are 'debianized', then there will be a 'debian'
	   subdirectory in the sources. In that directory is a file called 'control' which
	   contains a description of the package. src2pkg will use this text if the
	   'control' file is found. If the sources happen to be a python module, they will
	   contain a PKG-INFO file. src2pkg will use the description found in the PKG-INFO
	   file to create the slack-desc in this case.
	   
	   If you are using src2pkg with the '-Q' option and no *.spec, control or PKG-INFO
	   file is found, then src2pkg will pause during the creation of the package and
	   allow you to manually type in a descritption for the package. This can be fairly
	   long description of over 500 characters, but should be entered all as one line.
	   
	   In any other case, src2pkg will produce a correctly formatted slack-desc file
	   that just has the name of the package and the line 'No description was given
	   for this package.' In nearly every case, a copy of the file named new.slack-desc
	   will be placed in the current directory.
	   
	   src2pkg also adds dependency information to the last lines of the slack-desc
	   file. This information shows which installed packages are needed by the newly-
	   created package. This same information is also written to a 'slack-required'
	   file which is placed in the same directory of the package with the slack-desc
	   and doinst.sh files. The slack-required file provides compatibility with the
	   slapt-get program and is required for packages which are submitted to the
	   popular website linuxpackages.net which hosts non-official Slackware-type 
	   packages created by users and uploaded to the site.
	   
	b. doinst.sh
	   doinst.sh files are scripts which are run when the package is actually installed
	   to your system. They take care of details which make the program easier to use
	   or that help you to configure it for correct usage on Slackware-type systems.
	   They often conatain lines of code which create symbolic links to the main program
	   or some of it components or man pages. src2pkg can automatically create these
	   link-creation lines for the script in the same way that the Slackware 'makepkg'
	   program does. And like makepkg it can append these lines to an existing doinst.sh
	   script which you have prepared. But src2pkg is even more flexible -it can create
	   a 3-part doinst.sh script which starts with manually-written lines of code which
	   you want executed before the link-creation code is run. Then come the lines of
	   code which create the links. And finally, you can have src2pkg append lines of
	   manually written code after the links-creation code. This allows for a great
	   deal of flexibility while still allowing src2pkg to handle the link-creation
	   lines dynamically -especially useful for packages which must have the doinst.sh
	   upgraded each time the progarm version changes.
	   To use src2pkg this way, include any code you want inserted in the doinst.sh
	   before link-creation in a file called doinst.prepend. And any code which should
	   be added to the doinst.sh after the link-creation code should be placed in a file
	   called doinst.append
	
	   As with slack-desc files, a copy of the file, as included in the package content,
	   will be created in the current directory and named new.doinst.sh
	   Occasionally the installation routine for the program doesn't correctly create
	   the links. So, when src2pkg deletes the links from the package and creates
	   the link-creation code it may not be correct. If needed, you can edit the file
	   named new.doinst.sh and then rename it doinst.sh. Then src2pkg will include it
	   as-is.
	
	c. documents
	   src2pkg always tries to include at least some documents in the package. If no
	   documents are installed by the normal installation routine for the program, src2pkg
	   will search for a number of standard-named documents within the sources. It will
	   search the main source directory and some subdirectories for files called README,
	   AUTHORS, COPYING and many other such standard documents. If you need to, you can
	   specify the complete list of documents to include using the "-d=" or "--doclist="
	   option in the src2pkg command-line. You can use this to specify any kind of file
	   to be included, but they will be copied into the standard document directory for
	   the package.
	   
	   As part of an effort to create packages that conform to the Slackware format,
	   src2pkg will automatically detect documents which have been improperly installed.
	   This includes docs which are installed to /usr/share/doc -these get moved to
	   /usr/doc as per Slackware tradition. Also, some packages install documents without
	   a version number. These also get changed so that they are installed to
	   /usr/doc/NAME-VERSION
	   
	d. manpages & info pages
	   manpages get basically the same treatment as the doucuments above. src2pkg makes
	   an extensive search fro man-pages if none were installed by the installation
	   routine for the sources. And it does the same corrections for directory location
	   as for the documents -man-pages installed to /usr/share/man are moved to /usr/man.
	   All pages are first decompressed and then recompressed. This insures that all
	   pages are compressed using the same format. Some sources install pre-compressed
	   manpages which are compressed with bzip2. By deafult, src2pkg uses gzip to compress
	   manpages so any manpages found already compressed are decompressed first and then
	   re-compressed with gzip.
	   Info pages get the same treatment as man pages
	   
	e. patches
	   src2pkg can automatically apply patches to the sources, simply by placing them
	   in the same directory with the source tarball, or in a subdirectory named 'patches'.
	   Or you can specify some other path to the patches if using a src2pkg script.
	   src2pkg makes this very easy and flexible. If using the '-N' or '-A' options,
	   src2pkg will automatically add the list of patches to the src2pkg script. It looks
	   first for patches in the current directory and then in a subdirectory named
	   patches if no patches are found in the current directory. If you have a large
	   collection of patches for use with the sources, it may look neater to place them
	   in a 'patches' subdirectory.
	   
	   By default, patches are applied with the patch options -p1 -l. If you have patches
	   that need to use some other 'depth'(the -p option), you can still use them
	   by simplay naming them with the -p option in the name. Say you have a patch
	   named add-new-features.diff which should be apllied to the sources with the
	   command: 'patch -p0 add-new-features.diff'. src2pkg can correctly apply the patch
	   simply by renaming it to add-new-features.p0.diff.
	   
	   src2pkg automatically handles both .patch and .diff files and those which are
	   compressed and have the bz2 or gzip suffix. It also verifies that the patches are
	   really compressed. This is because some patches (especially from debian) are named
	   with (usually) a .gz suffix when they are not really compressed. This is done to
	   trick browsers into handling the files as binary data instead of as plain-text
	   files to avoid them being corrupted.
	   
	   If you have many patches that you want to keep with a certain source tarball, but
	   don't want to actually apply all of them, it's best to place the ones you want to
	   use in the current directory. The others can be kept in a subdirectory -even if it
	   is named 'patches', since src2pkg looks for patches first in the current directory
	   and will ignore others unless you edit the src2pkg script to specify the path to
	   each patch or diff file.
	
	f. configure options
	   Passing extra options to the configure script is the first and most common thing
	   for most users. Many programs will not even compile unless you pass some arguments
	   to the configure script. By default, src2pkg passes only the installation prefix
	   to the configure script. If other options are needed or wanted you can pass them
	   to configure by using the "-e=" or "extra_configs=" option to src2pkg. When passing
	   multiple options you should enclose the whole string in single quote marks like this:
	   "-e=--disable-tests --enable-static". If you want to change the '--prefix=' option
	   you should do that with the '-p=' option instead of including it with the other
	   configure options. Since src2pkg sets the prefix by default it is done separately.
	   
	   If the sources contain a .spec file or debian 'rules' file, src2pkg can extract
	   the configure options from these files if used with the '-A' option. This can
	   often make it easier to get a successful build and will only rarely do the 'wrong'
	   thing. src2pkg will automatically strip out the --prefix option and translate
	   options such as --docdir or --mandir into the proper Slackware options. If src2pkg
	   is run with the '-Q' option, when it reaches the configuration stage it will run
	   the './configure --help' command in the sources so you can easily see the available
	   options. It will pause and wait for you to input any extra options before proceeding
	   with configuration. For finer control you can always have src2pkg write a src2pkg
	   script for you with the '-A' or '-N' option and then edit it and re-run the build
	   to have the changes take effect.
	   src2pkg does not pass any options at all by default, except for the '--prefix' option.
	   This is because even the most basic and seemingly universal options will cause more
	   failures than they prevent.
	   
	g. Other common options
	   src2pkg also makes it easy to change other basic commands such as the commands used
	   to compile or install the program. By default, src2pkg compiles software using simply
	   'make'. But some programs require you to use 'make all' or 'make name-of-program' or
	   some other special command. You can specify the command to use with the '-m=' or
	   '-make_command=' option.
	   In the same way, you can change the command or 'rule' used to install the program.
	   Many times a program needs more than one rule to properly compile or install. For
	   these cases you can compile or install with multiple rules in one command. Examples
	   are:
	   "-m='make dep all'" (the same as 'make dep' and then 'make all')
	   "-i='make install install_data'" (the same as 'make install' and then 'make install_data')
	   
	   It is also quite common to specify the DOCLIST using the "-d=list of docs'" option
	   and to change the BUILD or release number of the package using the '-b=??' option.
	   
	   Also, src2pkg is usually able to guess the correct name and version number for
	   the package, but not always. It recognizes many standard name-plus-version schemes
	   such as those used by debian-type sources and most rpm sources. But sometimes it may
	   get it wrong -especially for names which contain a CVS version or date string.
	   src2pkg automatically changes all capital letters to lower-case for better name
	   conformity. Any time that it doesn't guess right or that you simply want to
	   give the package a different name or version, you can override the guessed name
	   using the '-n=' or '--name=' option. To change the program version number use
	   the '-v=' or '--version=' options. Of course, you'll include the desired name
	   or version number after the '=' sign. Note that internally and in src2pkg scripts
	   these overriding name and version variables are called ALT_NAME and ALT_VERSION.
	   When you see simply NAME and VERSION in src2pkg scripts these are printed out
	   simply as information to show the guessed name and version. ALT_NAME and
	   ALT_VERSION override the NAME and VERSION variables.
	   
	   
6. Installation Methods
	   src2pkg now offers 3 distinct methods for creating package content. src2pkg
	   usually creates package content based on the files and directories created by the
	   normal installation methods of the sources. In the past, src2pkg always ran the
	   real installation -usually the command 'make install'- and logging the events
	   using the installwatch library. installwatch works like a barrier between commands
	   like 'mkdir', 'install' and 'ln' and the underlying glibc functions which actually
	   do the work. Most common commands used in Makefiles or installation scripts rely
	   on the same fundamental glibc 'function calls'. installwatch is able to intercept
	   these calls and log them. It can even create backups of any files which are about
	   to be overwritten -before it happens of course. src2pkg can then restore these
	   original files after copying the newly installed files into the package tree. This
	   used to be the only way src2pkg created packages and is still the most accurate
	   since it merley tracks what happens when you really run 'make install' or nearly
	   any other command use to install a program. However, it is very intrusive since
	   it writes file to your real running system. If used to install programs which are
	   currently running on your system it can in a few rare cases cause real problems.
	   For example, if you tried to compile glibc or bash with this method you'd probably
	   have a mild disaster to deal with. Even though src2pkg does a pretty good job of
	   restoring files which are overwritten it can't deal well with restoring the very
	   programs and libraries which src2pkg itself uses. Since bash is the shell used by
	   src2pkg and glibc is the libraries used by bash and every other program, they are
	   especially difficult. Also, the coreutils package can caues problems since it conatins
	   most of the other utilities used by src2pkg itself. src2pkg provides a few statically-
	   compiled programs which it uses during the critical phase of restoring overwritten
	   files. This makes packaging most packages problem free. Still, many users are
	   hesitant to use such intrusive methods for creating package content. Using this
	   method also meant that you had to be logged in as root in order to use src2pkg.

	   So, src2pkg now provides two other methods for creating package content which
	   are less intrusive and do not require you to be running as root. The method 
	   mentioned above is now known as the 'REAL root' method. One of the two new methods
	   will be familiar to most people wh have any experience in creating packages.
	   It is called the DESTDIR or 'DEST root' method. The Makefiles for many source
	   archives make it possible to pre-pend a directory path to the normal installation
	   paths, allowing you to safely install software in some temporary subdirectory
	   before compressing the final content into a finished package. Normally, such
	   package content can be created with a command such as:
	   'make DESTDIR=/tmp/pkg-name install'
	   src2pkg now allows you to run the installation commands using DESTDIR, but you
	   don't even need to give the DESTDIR location. src2pkg will automatically use
	   the src2pkg package-tree directory, known internally as the PKG_DIR. This is
	   the subdirectory created by src2pkg for assembling and correcting the package
	   content before compressing it into the final package.
	   
	   The disadvantage to using the DESTDIR method is that not all sources are able
	   to understand and use this variable. Perhaps worse, some badly-prepared sources
	   only partially support DESTDIR. This is especially bad because it means that
	   some files are installed into the DESTDIR subdirectory and some are installed
	   to the real root '/' of your system without you knowing about it.
	   
	   One feature of the installwatch library allows us to do something similar to
	   using DESTDIR -even when the sources don't support DESTDIR at all. Ths method
	   is called the 'JAIL root' method. It uses the installwatch library to do the same
	   thing as DESTDIR by intercepting the normal installation commands and substituting
	   an alternate path before running the command in the alternate subdirectory. This
	   method will often work when the sources don't support using DESTDIR. Unfortunately
	   it is also not foolproof. Some commands will not be successful when using the JAIL
	   method. Most commands will work, but certain conditional tests will fail -especially
	   when the commands are supposed to find directories which already exist on your system
	   or when the commands try to edit already existing files. This can actually be a
	   blessing as it sometimes keeps critical system files from being altered without
	   letting you know about it or cancel the action.
	   
	   The 'DESTDIR' and 'JAIL' methods can both be used while running src2pkg as a normal
	   user. This adds an extra layer of protection to your system since commands run by
	   a normal user will be unable to write to system directories. The DESTDIR method
	   is now the default method used by src2pkg. Before running the installation commands,
	   src2pkg checks the Makefiles to see if DESTDIR is *apparently* supported. If not,
	   src2pkg reverts to using the 'JAIL' method. Since the content of packages should
	   usually be given ownership by 'root', src2pkg uses a feature of the 'tar' program
	   to set all file ownerships to 'root' before compressing the final package. Several
	   users had asked for this feature and by doing it this way, it turned out to be easy
	   to implement in a dependable way.
	   If you want or need to create package content by using the 'REAL' method, you'll
	   have to log in as root or 'su' to root before running src2pkg. Some sources which
	   are very difficult to package may require this, but most software can now be compiled
	   and packaged while running as a normal non-priviledged user.
	   
	   The installation method can be passed to src2pkg from the command-line using the
	   '-REAL' or '-JAIL' options. As mentioned, the DESTDIR method is the default so
	   you don't need to specify it unless you have changed the default behaviour by editing
	   your /etc/src2pkg/src2pkg.conf file. In case you do, the DESTDIR option can be
	   passed to src2pkg using the '-DESTDIR' or simply '-DEST' syntax. If a particular
	   package *requires* using a certain method, you can specify the package creation
	   method in the src2pkg script with the INSTALL_TYPE variable like this:
	   INSTALL_TYPE=REAL
	   
7. Getting more help
	   src2pkg and trackinstall both include a 'usage' function which will print
	   a help message to the screen. Running the command 'src2pkg --help' or
	   'trackinstall --help' will show the help message. You can also get slightly
	   more detailed help by seeing the manpage for each of the programs. In a
	   terminal, type 'man src2pkg' or 'man trackinstall' to see the man page
	   for each program.
	   
	   Other documents such as an FAQ are included with the program. Reading
	   them will provide additonal details which are not covered here.
	   
	   The code itself contains many comments and explanations which are more
	   suited to advanced users. These are found mostly in the files which
	   conatin the src2pkg functions, located in /usr/libexec/src2pkg.
	   
	   Some of the basic behaviour of src2pkg can be changed by editing the
	   configuration file in /etc/src2pkg/src2pkg.conf. The file contains
	   comments which will help you understand what can be changed and when
	   or why you might want to do so. Note that the src2pkg.conf file is
	   not needed for src2pkg to function properly. Most common defaults
	   are set when src2pkg reads in the file /usr/libexec/src2pkg/DEFINES,
	   but settings in the src2pkg.conf file will usually override these settings
	   depending on how you specify them in the src2pkg.conf file.
	   
	   You can always contact me directly for more help or if you have problems.
	   e-mails can be sent to amigo@ibiblio.org. Be sure to include the word
	   'src2pkg' in the subject line so that I'll notice it. I get lots of
	   spam e-mails so its' easy to overlook your message if it doesn't have
	   'src2pkg' in the subject line.
	   
	   Also, many users post their questions on the official Slackware forum
	   at linuxquestions.org. Since I am a frequent poster there you can usually
	   get help there pretty quickly. Also there are many friendly users of
	   src2pkg whioch are members of the forum and they often answer questions
	   about src2pkg before I see the posts myself. I live in Europe so the
	   time difference between myself and users in the Americas or Asia means
	   that I sometimes don't see your question until the next day.

Appendix A The 'trackinstall' program
	   trackinstall is an accessory program which is installed as part of the src2pkg
	   package. It is a drop-in replacement for the 'checkinstall' program which used
	   to be inluded with Slackware. trackinstall is used for creating packages from
	   software which has already been configured and compiled. Whereas src2pkg takes
	   care of finding the source archive, creating temporary directories, unpacking
	   the archive, configuring the sources and compiling them, then creating package
	   content usually from the results of the 'make install' command, trackinstall
	   only performs the last of these steps. Both src2pkg and trackinstall perform
	   several steps after the initial package content is created which add to or
	   modify the package content to create a final package which is conformant with
	   the norms followed by official Slackware packages.
	   
	   Many users prefer to just use trackinstall since they are already familiar
	   with checkinstall. And trackinstall is sometimes easier to use when creating
	   packages from certain kinds of content. Still, I recommend that you use the
	   full src2pkg program when possible as it allows you to easily control and
	   repeat all the steps for making a package and also allows you to keep a script
	   which you can use later for duplicating the process. This is especially
	   useful if the software requires special handling or commands during 
	   configuration and compiling. Having a script keeps you from forgetting the
	   exact steps or configuration options needed.
	   
	   The options and syntax usage for trackinstall are mostly the same as for
	   src2pkg, except that the options for the steps for the early processes
	   such as unpacking the sources and configuration are not included.
	   
APPENDIX B The 'tracklist' program
	   tracklist is a simple program which is included in the src2pkg package. It simply
	   creates a log of all files and directories created by a command, without
	   doing any modifications of the files or creating a package. It is completely
	   non-intrusive and creates a file called FILELIST in your home directory
	   which shows the files and directories created.
	   Usually you'd use it like this: 'tracklist make install'  or perhaps like:
	   'tracklist sh install.sh'  It will track most any command with arguments.
	   
	