src2pkg will execute its own scripts if one is named instead of a tarball. The command 'src2pkg -X' will search the current directory and run the first *.scrpkg.auto or *.src2pkg script it finds.

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 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.

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.

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 libsentry library. Libsentry 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'. Libsentry 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 merely 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 cause problems since it contains 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 who 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 libsentry library allows us to do something similar to using DESTDIR -even when the sources don't support DESTDIR at all. This method is called the 'JAIL root' method. It uses the libsentry 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-privileged 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 behavior 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

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.

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.

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

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

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.

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.

A number of programs are using Cmake (http://www.cmake.org/), the cross-platform make, so programs can be compiled on Windows, Mac, and Linux. Cmake has its own list of variables, and src2pkg can pass them from the command line or a src2pkg script to cmake during the configuration process.

Programs using cmake can be built by passing the required variables at the command line (for example):

src2pkg -e='-DQT_QMAKE_EXECUTABLE=/opt/qt4/bin/qmake -DWITH_BINDINGS=TRUE' qgis_0.10.0.tar.gz

Or in a src2pkg.auto script (only the relevant parts shown for example):

#!/bin/bash
## src2pkg script for: qgis
## Auto-generated by src2pkg-1.9.6
## src2pkg Copyright 2005-2008 Gilbert Ashley <amigo@ibilio.org>

SOURCE_NAME='qgis_0.10.0.tar.gz'
NAME='qgis'
VERSION='0.10.0'
# ARCH='i486'
BUILD='1'
PRE_FIX='usr'
# Any extra options go here
EXTRA_CONFIGS='-DCMAKE_INSTALL_PREFIX:PATH=/usr -DQT_QMAKE_EXECUTABLE=/opt/qt4/bin/qmake -DWITH_BINDINGS=TRUE'
# STD_FLAGS='-O2 -march=i486 -mtune=i686'