Invoking - GNU Source Installer, a graphical installer for source packages

Next: Usage for Beginners, Previous: Introduction for the Experienced, Up: Top

3 Invoking

This chapter shows the various actions, options, parameters and preferences that sourceinstall accepts.

3.1 Synopsis

     sourceinstall
     
     sourceinstall  ACTION [ ACTION_ARG... ]
                    [ OPTION [ OPTION_ARG... ]... ] [ PACKAGE_NAME ]
     
     sourceinstall  [ OPTION [ OPTION_ARG... ]... ] FILENAME

sourceinstall can be run in three different ways.

If called without any arguments, the program starts a graphical interface and waits for user input to decide the action to perform. This is what beginners should probably do.

The second way of calling the program is the complete command line interface, where a single action must be specified, followed by zero or more options, possibly followed by a final PACKAGE_NAME if the action requires it.

The third way of calling the program is without specifying any actions, and with a required FILENAME.

This is for both convenience and backward compatibility, and is a shortcut for the --add action with no custom package name.

3.2 Actions

Only ONE action can be specified on the command line. The action may require one or more parameters.

Some actions require a PACKAGE_NAME on which to act, while others behave differently if such a PACKAGE_NAME is specified.

For example, the --export action can export information about all installed packages or about a single package, depending on whether a PACKAGE_NAME is specified.

As another example, the --add action adds a new package to the sourceinstall package list (a very common operation). If PACKAGE_NAME is specified, then the new package will be called PACKAGE_NAME. Otherwise, a default value is obtained from the top source directory of the package.

-h, --help

show brief command line help

-V, --version

show program version

-l, --list

list existing packages;
if PACKAGE_NAME is specified, it is treated as a regular expression, and only matching package names are included in the output. The regular expression is a tcl ARE. Tcl regular expressions have been implemented using the package written by Henry Spencer, based on the 1003.2 spec and some (not quite all) of the Perl5 extension.
Packages are separated by newlines, and a short description is shown near the package name if such a description is available. Package name and description are separated by a “ - “ (space, dash, space) sequence.

You might be tempted to pipe the output to a pager. If you do, and have expect-5.43 installed, avoid more. There is a bug in that Expect version that causes problems with pipes, and you will get a broken pipe error with more. Expect-5.41 does not show this problem.

-a, --add FILENAME

add new source package from FILENAME;
this is the way to add and install new source packages, so you will use this often. Note that this is not the same as the --install action, which only acts on an already added (but uninstalled) package.

The --add action configures, builds and installs the source code referenced by FILENAME, then stores the configured source code and saves package information. The unique package name will be taken from the top source directory by default, but can be specified using PACKAGE_NAME (look at the SYNOPSIS above).

Note that since the source code is automatically stored (in the ~/.sourceinstall/src directory) you can safely remove FILENAME after a successful --add action.

All the above assumes the default behaviour. It can be altered by Options and Preferences.

-r, --remove

remove source package PACKAGE_NAME;
by default, the --remove action removes both installation and stored source code. In this case, after removal the package will not exist anymore, and its name will not show in the package list. You can instead fine grain what gets removed by using the --binary or --source options.

-c, --check

show package PACKAGE_NAME information;
if the package is currently installed, validation on known installed files is performed, signaling eventually missing files. If the check reports some missing files, you can rely on the --install action to reinstall over the broken installation.

-v, --update OLD_PACKAGE FILENAME

remove package OLD_PACKAGE completely, then add FILENAME as a new package.
As for the --add action, the new package name will be taken from the top source directory by default, or from PACKAGE_NAME if specified.
This action is nothing more than a twofold --remove / --add action.

-i, --install

install known package PACKAGE_NAME from stored source code.
This action is not the way to deal with a new package. If you want to add a new package, you want to use the --add action instead.

-u, --uninstall

this is an alias for -r -b .
This action only removes the installation, but not the source code. Useful to remove something you might wish to restore at a later date. If you want to remove and completely forget about a package, use the --remove action instead.

-d, --description STRING

associate first line of STRING to package PACKAGE_NAME short description,
and the remaining lines to the long description.
If STRING is empty, remove descriptions from the package.
To submit an empty string, or a string containing newlines, make use of your shell quotation characters. Two examples (bash):

          $ sourceinstall -d "STFU - Shoot The Fighters Up space game
          > This game is the famous SDL based STFU space game, where lots of noisy
          > enemy fighters dance through the screen making every kind of disturbing
          > crappy sound. Using overpowered weapons, you can finally bring them to
          > silence, and restore peace to the galaxy." STFU

Here we add a package description to the package STFU. The first line will be the short description, and the rest of the multiline text is called the long description. The descriptions will show everytime the --list and --check actions are requested (see those actions for further info).

          $ sourceinstall -d "" STFU

Here we remove all the descriptions (both short and long) from the STFU package. The --list and --check actions will not show any descriptive text anymore.

-n, --rename OLD_NAME

rename existing package OLD_NAME to PACKAGE_NAME.

-x, --export FORMAT FILENAME

export package information to FILENAME.
FORMAT can be xml, txt or lst . The xml format and txt format contain all the package information, while the lst format only exports the installed files list (and thus has only sense when applied to an installed package).
If a PACKAGE_NAME is specified, then only the information regarding PACKAGE_NAME is exported. If no PACKAGE_NAME is present on the command line, information about all known packages is exported (xml and txt formats only).

-p, --pack FILENAME

build binary tarball from the installed package PACKAGE_NAME, and save it as FILENAME.
Permissions and ownership are preserved. This functionality is experimental, unstable, slow, sketched. You will need to have or acquire root privileges to complete this operation.

3.3 Options

Many options can be specified on the command line, but each option can be chosen only once. Options modify specific actions' behaviour.
Some of these options overlap with the preferences in the sourceinstall configuration file, and could even overlap with the package information. These command line options take precedence in these cases.

-s, --source

apply add or remove action to source only.
During an --add action, use this option to specify that you do not want the software to be installed, but only want to store the source internally for future needs. You can combine this with the --configure option to prepare a configured source package and then store it for later use.
During a --remove action, use this option to specify that you want only the source code to be removed. If the package is currently installed, this leaves only the binary installation, without the stored source code that generated it. If you have enough disk space, it is recommended to keep the source code.

-b, --binary

apply add or remove action to installation only.
During an --add action, use this option to skip the “store source code” phase. If you have enough disk space, it is recommended to keep the source code.

-t, --strip

strip binaries during installation if possible (not recommended)

-z, --compression FORMAT

use FORMAT as compression format for storing source code. Can assume values gz, bz2, Z .
This overrides the SRC_COMPRESS preference .

-C, --configure STRING

(re)configure package using STRING.
First char of STRING cannot be a '-'. This is worth saying because a common usage of the -C option is to override the default installation prefix set in the Preferences. The command line parser will take your “–prefix” string for another option and will complain about a missing -C parameter. To avoid this, just prepend your configuration string with a harmless space.
You can take the habit to prepend a space to every configuration string you submit, and you will be fine. Here is an example:

          $ sourceinstall --install -C " --prefix=/home/claudio/usr" unshield-0.5

Note that if you want to submit some environment variables to configure, a nice way to do it is to specify them in the configure STRING. This way they will appear in the package information. For example:

          $ sourceinstall --add cmdftp-0.9.2.tar.gz -C " CFLAGS=-Os LDFLAGS=-s"

-D, --subdir STRING

use STRING as build subdirectory for the package.
Some packages' build system is nested in some subdirectory. Use this option to specify a directory to move to before configuring and building the package.
This is a real example with tcl source package, that has a unix subdirectory that contains the configure script. Trying to build it normally gives:

          $ sourceinstall --add tcl8.4.11-src.tar.gz -C " --enable-shared --disable-threads --enable-symbols"
          sourceinstall: warning in `Configuration': A configure script for this package has not been found in the top source directory. However, configure scripts have been found in subdirectories
          
          unix/configure
          win/configure
          tools/configure
          
          Use the `--subdir' option to specify a build subdirectory containing one of these configure scripts
          # configure script not available
          sourceinstall: warning in `Configuration': configure script not available. Default prefix and configure options will be ignored.
          # compile software
          sourceinstall: error in `Install package': Could not compile the code.

In this case, the subdirectory to indicate is of course the unix subdirectory:

          $ sourceinstall --add tcl8.4.11-src.tar.gz -C " --enable-shared" -D unix

-f, --force

force execution of the action even when not recommended (Not Implemented Yet).
Currently this option has absolutely no effect.

-U, --user STRING

privileged user login to revert to if required [default=root] .
When running sourceinstall as a regular user, sometimes privileges will be needed, for example to install to a part of the filesystem that belongs to root, or even to prepare binary packages (see --pack action).
You can choose to use a login different than root in these cases, by specifying this option.

-P, --pass STRING

privileged user password to revert to if required [default=] .
WARNING! USING THIS OPTION IN A MULTIUSER ENVIRONMENT IS VERY INSECURE!
When running sourceinstall as a regular user, sometimes privileges will be needed, for example to install to a part of the filesystem that belongs to root, or even to prepare binary packages (see --pack action).
You can use this option to specify the password to use in these cases. Note however that the program invocation, with all its parameters, could be stored in some log files, or in the system running processes list.
If you want to run sourceinstall from the command line in a multiuser environment, you will probably do best by running sourceinstall as the root user.

-q, --quiet

be very quiet: only indispensable information will be sent to the standard output.

3.4 Preferences

Preferences are very much like options, but they are stored in a specific file that is loaded each time sourceinstall starts.

Every time a command line option and a preference clash, the command line option takes precedence.

To change the preferences you can edit your ~/.sourceinstall/sourceinstallrc file.
Note that each user (root too!) has his own preferences file.

MANUAL_CONFIGURE: bool: (Tk interface only) This preference controls whether the configuration window should be shown in the Tk interface. It has no effect if you are using the command line interface.
The bool value can be 0 (do not show configure window) or 1 (do it).
KEEP_SOURCE: bool: This preference controls whether the source code should be stored when adding or installing software. Of course, this preference clashes with options --source, --binary, and their aliases. The bool value can be of course 0 or 1.
INSTALL: bool: This preference controls whether the software should be installed when adding software. Of course, this preference clashes with options --source, --binary, and their aliases. The bool value can be again 0 or 1.
ADD_DIRECTORY: path: (Tk interface only) This preference controls the initial directory PATH to browse when clicking Add.
STRIP: bool: This preference mimics the --strip option.
PREFIX: path: This is the default prefix to use when adding/installing software. Note that you can override this setting by providing a --prefix configure string (see the --configure option). The default value is /usr/local, a safe choice for systemwide installs.
SRC_COMPRESS: format: This is another preference that mimics an option. In this case it is the --compression option.