Introduction to using src2pkg

src2pkg is a set of programs (actually BASH scripts) for producing
installable packages from source-code archives or other content. It's
mainly meant for use with Slackware, but includes compatibility for
other systems which use similar package installation tools (like Jaguar
Linux, tukaani)

src2pkg can create packages from the command-line or by using a .src2pkg
build script. src2pkg can create the script for you which can then be
edited to add or delete instructions, as needed.

src2pkg can be used to convert binary RPM or Debian archives into
safely installable packages. It will also package other binary or no-arch
content, including pre-compiled binaries (like Opera browser, flash_player_plugin
or ATI drivers) which are usually installed with an install.sh script
or .run file.

Basic usage is much like using SlackBuild scripts. src2pkg will, by default
look for the sources in the same directory from which it is run and will include
doinst.sh or slack-desc files found there in the package. It will also
insert pkgconfig '.pc' files or .desktop files found in the current directory.
src2pkg also will automatically apply patches found in the current directory
or in a subdirectory called /patches.

By default, most of the files created(or unpacked) by src2pkg are found in
subdirectories under /tmp. But, src2pkg does create installation log files in
the current working directory, so be sure that you are running from a directory
which is writable. Ideally, each program should have its' own subdirectory, since
files specific to that program may be created during packaging. You should not
run src2pkg from some general system directory, like /usr/share or /bin, etc.
src2pkg checks for many system directories specifically and will refuse to
run from them.

src2pkg includes a lot of code which verifies the package content and will
correct many common packaging 'errors', such as non-conformant installation
of man-pages or documents, incorrect permissions and capital letters in the
name. If you don't like this, most of these features can be easily disabled,
though I don't recommend it.

srcpkg also includes a lot of code which analyzes the source content and can
automatically handle many different configuration and compilation types. It
can detect incomplete, faulty or outdated configuration files and correct them
before continuing.

During package creation, src2pkg tracks the creation of all files, directories
and links on your system. It creates backups of anything which will be overwritten
and then restores them before proceeding. (After installing files to your system
they are copied into the package tree, then the originals are immediately restored
before further processing of package content. Any directories created are also
removed.) This makes src2pkg extremely safe to use for most sources, but don't try
rebuilding glibc with it! src2pkg does not use DESTDIR and installs files directly
to your system, so it should be used with care when compiling basic system libraries,
compilers or packages like util-linux.

src2pkg is ideal for both beginners and advanced users. For beginners, it makes it
very easy and safe to produce packages, even without knowing anything about scripting
or the ins-and-outs of making packages
For advanced users it provides enough flexibility to allow complex package creation,
while reducing the tedious steps of packaging -allowing the user to concentrate
on the 'fine' details of the package.

src2pkg can install the packages created as you go, so it can be used to create
groups of packages which depend on each other, or even bootstrap a system from
sources the way Gentoo does.

If given a valid URL, src2pkg will download one, or more, source files or archives
for use in making the package.

src2pkg can only be run as root, so you must be logged in as root or 'su' to user
root before running.

Getting started:

The easiest way to show basic usage is with an example. We'll use a small program
which you probably don't have on your system and should compile without any trouble.
Let's take the program 'di' for our example. (This is a small program which shows
disk information similar to the output from the command 'fdisk -l').

1. Create a directory called di-3.11 somwhere on your system like your HOME directory,
or in /usr/src.
2. Download the source tarball from here:
http://distro.ibiblio.org/pub/linux/distributions/amigolinux/examples/di-3.11/di-3.11.tar.bz2
 and place it in the directory created above.
3. cd into the di-3.11 directory and type 'src2pkg di-3.11.tar.bz2'. This is a small program,
so after less than a minute you should have an installable package in /tmp/di-3.11-i486-1.tgz

Actually, you can do this even easier by letting src2pkg do the download for you. If
your internet connection is up, you can cd into your new directory and type this:
src2pkg http://distro.ibiblio.org/pub/linux/distributions/amigolinux/examples/di-3.11/di-3.11.tar.bz2
(maybe you don't find that easier in this case, but you'll see the utility of this later)

If you look in /tmp, you'll see not only the package, but also 2 directories called
di-3.11-src-1 and di-3.11-pkg-1. These contain the uncompressed sources and package
content, respectively. Make a habit of checking the content in the package directory.
src2pkg can't forsee everything and many packages need special handling or manually-
written code to include everything you want in the package.

Now we'll see some User Options of src2pkg. These basic options which all use capital
letters and don't take any arguments afterward like -A, -N -W.
From the same di-3.11 directory type:
src2pkg -A di-3.11.tar.bz2
This will erase the previous temporary files and package and start a new build. The
-A option causes src2pkg to write the di.src2pkg.auto script and place it in the
current directory. The -A option also generates a new.slack-desc file in
the current directory which you can edit if needed. Renaming it to slack-desc will cause
it to be placed in the package if you now rebuild it.

Open the di.src2pkg.auto file in a text editor and you'll see that the script is quite
simple, with a few variables declared at the top and a list of instructions at the bottom.
It actually is much longer than really necessary, but keeping scripts is not just about
being able to repeat a build dependably, it's also about having detailed information
about the build. (The simplest .src2pkg script can be as short as 3 lines)

The di.src2pkg.auto script can be executed to repeat the build and can be run in
several ways. They are created as non-executable files to avoid accidental builds if
you happen to click on the script. But you can make the file executable and run it directly:
chmod 755 di.src2pkg.auto
./di.src2pkg.auto
You can also run the script(without it being executable) by invoking it with bash:
bash di.src2pkg.auto

Or you can use src2pkg to run it like this:
src2pkg di.src2pkg.auto
Or, again, you could just run:
src2pkg -X
The -X option will search the current directory for .src2pkg or .src2pkg.auto scripts
and execute the first one it finds.
The advantage of using src2pkg to execute the script for you is that it lets you
control some of the src2pkg User Options from the command-line, while still running the
fixed code and Build Options in your script.

This src2pkg script can be edited, if needed, allowing a nearly unlimited flexibility
for building packages with special needs, like noarch packages, etc. By default the
starting scripts have the '.auto' extension so you can easily see that it was generated
by src2pkg. If you edit the script, I recommend renaming it to just ???.src2pkg without
the .auto extension. This will keep it from getting 'clobbered' -if you run src2pkg -A
repeatedly, a new src2pkg.auto script and new.slack-desc will be created each time
you run it. Renaming them to their 'real' name causes them to be preserved. The same
holds true for doinst.sh files - if found they are inserted as is. Otherwise src2pkg
searches for links in the package tree(PKG_DIR) and creates a doinst.sh script which
is inserted in the package and a copy named new.doinst.sh is created in the current
working directory(CWD)

The -N option is similar to the -A option, except it produces a src2pkg.auto script
and new.slack-desc without doing anything else, even if the tarball is not present or
you type the name incorrectly. The -A option causes the script to be written *after*
the build is finished, so it may contain information not found in a script produced
first with the -N option and is only produced if the build is successful. As the build
proceeds and src2pkg discovers more about the sources, some extra info or options may
be included by using the -A option.

The src2pkg -T option attempts to build the sources without trying to install them 
or create a package. This is useful for testing builds to see if they will succeed.

The -W option causes sr2pkg to remove the temporary files created during package
creation, including the SRC_DIR (directory where sources are unpacked), the PKG_DIR
()