Internal execution of the src2pkg functions

It's helpful to know a little about how src2pkg runs in order to get the most use out of it.
Most of the code for src2pkg is in the FUNCTIONS file. As the name implies most of it is written as BASH functions -blocks of code which can be given a name and then executed one or more times just by calling them by the given name. The main functions are a list of 16 generic steps, each of which carries out a specific set of commands that have to do with package creation, like downloading, unpacking, configuring or compiling source code and creating a package tree, compressing the final package, deletion of temporary files, etc. These 16 functions, run in order, make up the standard execution order for a src2pkg build, whether called by a *.src2pkg script or from the command-line.

The src2pkg and trackinstall programs are just small scripts which mostly rely on the functions to do the main work. The code in the functions is meant to be driven by a script and each function operates separately, using a few variables which are supplied by the script, the config files, the DEFINES file or from the command line.

An example of the simplest src2pkg build script possible helps to understand the overall way things work. Say you have placed a source tarball called di-3.11.tar.bz2 in some writable directory. Only the following 3 lines of code are needed to make a script:

SOURCE_NAME=di-3.11.tar.bz2
source /usr/libexec/src2pkg/FUNCTIONS
do_all_processes

After pasting them into a blank document named di.src2pkg and saving it in the same directory as the tarball, it can be executed with the command 'bash ./di.src2pkg'.
When bash 'runs' the script it reads it top to bottom:
1. Declare any variables needed by the package. Internally, src2pkg uses a huge number of variables which are written in capital letters, usually named in a plain-language way to help explain what it does.
Error-free builds which require no customization may only need SOURCE_NAME, the name of the tarball you want to build which is already located in the current working directory.

Though there are many variables which you might possibly use to control the build process, the most common customizations can be handled by knowing just a few of them. Generally, variable declarations should be at the first of the build script. Variables which are necessary for a build to succeed or which affect the content of the specific package should be included in the script to insure build repeatability.
All other variables used internally are set or calculated to defaults by the configuration and DEFINES files and can usually be configured or overridden, if needed. The variables usually used in the /etc/src2pkg/src2pkg.conf file are for controlling general system options such as where you want sources and packages to be built on your system, color and verbosity options. The DEFINES file contains some basic defaults that affect the way packages are built, but usually don't need changing.

2. 'source' the FUNCTIONS file. What does that mean? When bash 'sources' a file it reads in the code contained in the file and interprets it. When the src2pkg script sources the FUNCTIONS file, only the first few lines of code are executed. These read the src2pkg.conf  file and then the DEFINES file which finishishes declaring all the internal variables to sane defaults unless they have already been declared earlier in the script. Since the rest of the code is written as functions it is not executed until called later.
Each function is a block of code which performs a specific set of related operations.

3. Execute the instructions given. What's this do_all processes? I cheated and created a function called do_all_processes which runs the 16 main steps in order. It's just a way to abbreviate your scripts in case you don't need to alter the standard build order. The functions for the standard build are named as below and called in the order shown:

pre_process
find_source
make_dirs
unpack_source
fix_source_perms
configure_source
compile_source
fake_install
fix_pkg_perms
strip_bins
create_docs
compress_man_pages
make_description
make_doinst
make_package
post_process

Standard *.src2pkg scripts from a template or written by the src2pkg progam use the detalied list as above. This makes it easier to edit them, if needed, to add code or skip certain steps.
Once finished with the list of functions the src2pkg script quits. The functions are always named with small letters and have a 2-3 word name, each name separated by '_'. The names are fairly descriptive of what each function does. Each works with only a few variables and performs just a few steps having to do with that particular aspect of creating a package. Since the code is modular, each step performing a small part of the process, it is easier to modify the execution by commenting-out steps which are uneeded or don't do what you need, or by adding code between the functions.

The main thing to remember is that a src2pkg runs by
1. first taking at least variable assignment, usually the name of a source tarball
2. then reading in the configuration defaults and functions
3. and finally executing the functions in a certain order using the variables values

Running the src2pkg *program* does much the same thing except it translates command-line arguments to the variable names as used in a *.src2pkg script.
In other words, running:
src2pkg di-3.11.tar.bz2

would do the same thing as running a script with this content:
SOURCE_NAME=di-3.11.tar.bz2
source /usr/libexec/src2pkg/FUNCTIONS
do_all_processes

The src2pkg functions parse the full tarball name and derive some basic variables related to the package. A Slackware-type package name consists of these elements: NAME, VERSION, ARCH and BUILD. The Slackware package name for the example would be di-3.11-i486-1.tgz. Most other essential variables are either calculated to match your system or set to the normal defaults unless you override them from the command-line, in your script, or in your src2pkg.conf file.

Understanding a few of the internal variables is essential to getting the most use from src2pkg. Variables are used extensively in src2pkg -nearly always in capital letters like VARIABLE. Most are more than one syllable like VARIABLE_NAME, joined with and '_' character. Variables are used to control everything so some are required while others are used to control options which affect the package or output from src2pkg.  Most users may never be aware of the majority of the variables, but understanding of a few is needed, if only to understand the documentation.

First of all, understand that CWD means the current working directory -the directory from you run the src2pkg program or script. This should usually be an individual directory for each package that you build and should always be writable as src2pkg generates some temporary and/or permanent files there and may also download items the CWD. CWD is equal to the ouput from the command 'pwd'. The value of CWD is, of course, supplied by src2pkg itself and depends on where you are running from.

As seen in the above example, NAME and VERSION should be pretty obvious. They are worked out by src2pkg from the SOURCE_NAME. ARCH is also figured out by src2pkg unless you override it. The usual default is "i486". BUILD is the last number you see (-1) in the example package name. The BUILD number is also sometimes called the 'release' number. This number is used to denote upgraded packages or rebuilds of packages using the same NAME and VERSION. To make things easy, src2pkg supplies a default number of BUILD=1 so you don't have to give it all when first building a package. These basic variables are all specific to the package being built and are written into src2pkg scripts as separate values for easy editing and to show the package details in an understandable form.

Other variables which are package-specific and commonly changed are written into src2pkg scripts to ensure repeatability of the package build process, but with an eye to 'portability' to other machines. That means that when src2pkg creates a script for you, some values like STD_FLAGS or PRE_FIX get written into the script with the values really used in the package, but some lines are commented out as they may be specific to your machine or environment. Unless you specified the value, STD_FLAGS (the CFLAGS passed to configure and gcc) is calculated by src2pkg according to your machine architecture and gcc compiler version. Commenting the line out allows us to show the information as it applies to the package built, but still allow the script to be portable to some other system. This is important of you plan to share your build scripts with others. The most commonly-used option of this type is EXTRA_CONFIGS, which are options and arguments that are passed to the configure script in most source pckages. Many sources won't compile correctly, or at all, unless you pass certain options to configure -something like '--without-gnome' or '--with-libdir=/usr/lib64'.

Note that we are not using a fixed path to the di-3.11.tar.bz2 tarball. By default, running a src2pkg script behaves much like a Slackware SlackBuild script in that it expects to find the sources in the same directory as the script itself, no matter where the script is placed. src2pkg goes further by allowing you to use a link (in the same directory) to the tarball which may be located in another directory. It also allows you to place all your sources in a single directory or sort them by category. This is accomplished by using a variable called SOURCES_DIR. When src2pkg 'finds' your di-3.11.tar.bz2 archive it hasn't looked for `pwd`/di-3.11.tar.bz2. It doesn't even look for $CWD/di-3.11.tar.bz2. It looks for $SOURCES_DIR/di-3.11.tar.bz2. By default, src2pkg sets $SOURCES_DIR=$CWD. This variable is provided so you can separate, sort or specify paths to your sources and still not break compatibility if you change your mind or share your scripts. src2pkg actually looks for $SOURCES_DIR/$SOURCE_NAME

src2pkg works similarly with other the important working directories. SlackBuild scripts usually simply unpack the sources in subdirectory of /tmp with whatever name the unpackaged archive has. It will also create a directory for the 'package-tree' where compiled or other sources are copied into an installable directory structure before being compressed into the final package. A SlackBuild package-tree is usually hard-coded to /tmp/package-$NAME-$VERSION and the variable PKG is used to refer to this location. Some later SlackBuild scripts allow you to set TMP instead of always using /tmp ($TMP/package-$NAME-$VERSION) src2pkg allows you to separate the two if you really want. Instead of TMP it uses SOURCE_BUILDS_DIR and PKG_BUILDS_DIR which can be individually configured. These options are usually setup by editing your src2pkg.conf script and not used in src2pkg scripts. src2pkg gives the directories where the sources are unpackaged and the package-tree are a more specific name which includes the BUILD number so you can build an updated package without overwriting old source or package trees. For the user it is quite simple -what a SlackBuild script calls $PKG is called $PKG_DIR by src2pkg(alright it understands PKG, too, if you forget). Referring to the directory where the sources are is done simply with the corresponding $SRC_DIR.

src2pkg allows you to configure the location where your final compressed packages are located, as well, using the PKG_DEST_DIR.

This system provides very simple, portable and flexible syntax to be used if you need to add code to a build script. For example:
cp $SRC_DIR/example.xpm $PKG_DIR/usr/share/pixmaps
 would always copy the example.xpm file from the sources directory into the usr/share/pixmaps directory of the package tree(PKG_DIR) -no matter where the SRC_DIR and PKG_DIR were set to. It prevents you having to write it like this:
cp /tmp/di-3.11/example.xpm /tmp/package-di/usr/share/pixmaps
Note that it isn't that using the variable always makes for shorter code, but it is flexible code which doesn't have to be edited every time you change your mind about how/where to build your sources and packages. In this example, the real value of SRC_DIR would be /tmp/di-3.11-src-1. src2pkg puts it together like this: SRC_DIR=$SOURCE_BUILDS_DIR/$NAME-$VERSION-src-$BUILD.

If you've understood the basic package variables of NAME, VERSION, ARCH and BUILD, plus the location variables CWD, SRC_DIR and PKG_DIR you should be ready for a closer look at some of the main options for controlling or modifying the way your packages are built.