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