Installing programs by hand

Normally, you won't need to install programs using the methods described below. You should use Compile instead. You can find lots of information on Compile in the GoboLinux wiki.

However, if you want to know what kind of work Compile does under the hood and you want to have a deeper understanding of the workings of GoboLinux, then read on!

Installing programs from source

If you are used to compiling programs in Linux, you are aware that it is mostly a three-part process: prepare the sources (configure), compile them (make), and install the files generated by the compilation (make install). The process is basically the same in GoboLinux. However, it requires additional setup in the first step, in order to prepare the sources to compile targeting the GoboLinux directories, and additional actions in the third step, so that files installed in /Programs get linked in /System (in order words, to make the files from the programs available for the system).

GoboLinux fetures a series of scripts that automate this process. They are:

PrepareProgram
SymlinkProgram
CompileProgram

PrepareProgram and SymlinkProgram are wrappers to the first and third step of compilation as explained above (the second step being simply running 'make'). CompileProgram is a higher-level wrapper script, that wraps the process as a whole: well-behaved autoconf-based programs can be compiled with a single CompileProgram command.

Setting up the sources: PrepareProgram

The PrepareProgram script does two things. It creates a directory hierarchy for the program under /Programs, and it attempts to prepare the sources for compilation.

The syntax for the PrepareProgram is:

    PrepareProgram <ProgramName> <VersionNumber> [ -- <AdditionalOptions> ]

Passing a program name and version number is mandatory. These names are the ones used in the directories under programs. For example,

    PrepareProgram SuperFoo 1.0

creates the directories /Programs/SuperFoo/Settings, /Programs/SuperFoo/1.0, /Programs/SuperFoo/1.0/bin and so on.

The second task performed by PrepareProgram is to prepare the sources. Since there isn't a standardized format for distribution of source-code tarballs in the free software world, there is no way to implement completely automated preparation. Fortunately, the popularization of the GNU AutoTools brings us closer to such a standard.

PrepareProgram, in this second step, will detect availability of preparation tools and perform one of the following:

If the program includes a 'configure' script generated by GNU autoconf, PrepareProgram will run it, passing the necessary options (mainly --prefix, --sysconfdir) as well as any additional options requested by the user in the command line (as <AdditionalOptions>).
Some authors develop their own 'configure' scripts, but due to the popularity of GNU autoconf, design a command line interface similar to that used by this program. PrepareProgram tries to detect if a non-autoconf 'configure' script accepts at least the --prefix option, and use it.
If unfortunately the program does not feature a standard preparation script such as 'configure', the PrepareProgram will, as a last resort, scan for hardcoded paths in the Makefiles and attempt to modify them. Given that this automated process can be highly error-prone, PrepareProgram avoids being "automagical" and asks for the user's assistance: it asks the user for permission before attempting modifications, it saves backup copies of all Makefiles, and displays a summary of changes to the user. (Note: If the user is sure the modifications will be correct, all interaction can be suppressed passing the --batch option to PrepareProgram.)

In short, PrepareProgram can be considered a wrapper to 'configure'. Instead of running, for example,

    ~/superfoo-1.0] configure --with-shared=yes

you'll run

    ~/superfoo-1.0] PrepareProgram SuperFoo 1.0 -- --with-shared=yes

However, for most programs that use GNU AutoTools, you'll want to use the all-in-one CompileProgram wrapper script.

Linking the sources: SymlinkProgram

The final step in the compilation of a program is performed by the SymlinkProgram.

The syntax for SymlinkProgram is:

    SymlinkProgram <ProgramName> [ <VersionNumber> ]

The second argument is optional. If no version number is specified, the one linked as Current will be used.

SymlinkProgram is the script responsible for creating the symbolic links under /System/Index. It can also, optionally, provide a controlled environment for safely executing 'make install', using a sandbox provided by the FiboSandbox script. To have SymlinkProgram perform 'make install', use the --make (-m) option, like this:

    SymlinkProgram -m SuperFoo

It is recommended that 'make install' is always executed through SymlinkProgram, because the sandbox ensures that 'make install' will only have permissions to store files under /Programs/SuperFoo/Current and /Programs/SuperFoo/Settings.

SymlinkProgram features many command-line switches. Please refer to the --help page for details.

Wrapping the entire compilation process: CompileProgram

The CompileProgram script wraps PrepareProgram, make and SymlinkProgram in a single command, while adding other niceties.

The syntax for CompileProgram is:

    CompileProgram <FileOrPath> [ <ProgramName> [ <VersionNumber> ] ] [ -- <AdditionalOptions> ]

The first argument is the filename of the source tarball or the path where the sources are located. Normally, you'll want to use the '.' (current) directory as an argument, doing something like this:

    ~] aunpack superfoo-1.0.tar.gz 
    ~] cd superfoo-1.0 
    ~/superfoo-1.0] CompileProgram .

Note that, unlike in PrepareProgram and SymlinkProgram, here both the program name and version are optional. CompileProgram performs a number of heuristics to determine the program name (and capitalization) and version. These heuristics, among other things, read the directory name and scan the README file. CompileProgram will display the name and version detected, and ask for confirmation. If those are not satisfactory, the user can cancel the process and enter the correct names in the command line, like:

    ~/superfoo-1.0] CompileProgram . 
    Press Enter to compile Superfoo, version 1.0 or Ctrl-C to cancel. 
    [Ctrl-C] 
    ~/superfoo-1.0] CompileProgram . SuperFoo 
    Press Enter to compile SuperFoo, version 1.0 or Ctrl-C to cancel. 
    [Enter]

Prior to compilation, CompileProgram will display on screen the README and INSTALL files, if present. They may contain relevant information for the user such as additional switches to be passed to configure. These options can be passed to CompileProgram like in PrepareProgram: appended to the commandline options, after '--'.

CompileProgram then runs 'make' (with no arguments as default, or with an argument passed with --make-target) and then SymlinkProgram.

CompileProgram features additional command-line switches to further refine its behavior for special cases. Please refer to the --help page for details.

Using binary packages

GoboLinux binary packages

GoboLinux uses a very simple format for binary packages. For a given program, say Foo 1.0, a package is simply an archive in .tar.bz2 format containing the Foo/1.0/ and Foo/Settings/ directories (and their contents). For a package built for a i686 architecture, the package will be named Foo--1.0--i686.tar.bz2.

Installing binary packages

To install binary packages, simply run InstallPackage passing the package name as a parameter. For example:

    InstallPackage Foo--1.0--i686.tar.bz2

This will unpack the archive inside /Programs, and will call SymlinkProgram to update /System/Index.

Creating binary packages

To create a binary package, use the CreatePackage script. It has the following syntax:

    CreatePackage <ProgramName>

It will create a package of the Current version of the specified program, and store the generated archive at /Programs.

Note: please be careful with the contents of the Settings directory when creating a binary package, so that it does not include personal information. A package submitted for inclusion in the packages directory at GoboLinux.org must feature sensible default settings, preferrably the defaults as specified by the application right after its compilation.

Cleaning up

GoboLinux does not feature a specific script to clean up the broken links that will emerge when programs are deleted, but it has a generic script for cleaning broken symbolic links, called RemoveBroken.

RemoveBroken will verify if any of the files passed to it in the command line is a broken link, and remove those. If no arguments are passed, it receives filenames from standard input (tipically through a pipe).

The usual procedure to clean up symbolic links, is, then:

    ~] cd /System/Index 
    /System/Index] find | RemoveBroken

Notes on command-line switches

Many scripts accept command-line options. All options feature a short, one-letter form, and a long form. Following the GNU conventions, short form options are preceded by a single hyphen (as in -a, -b) and long form options are preceded by two hyphend (as in --foo, --bar).
Some command-line options accept arguments. These arguments must be passed as the word following the argument, both in short and long forms. For example, say that -s and --long are options that take a parameter. This is the correct way to use them:
```
    FooScript -s value --long another
```
These are not recognized:
```
    FooScript -s=value --long another      # WRONG! Use distinct tokens.
```
Each option should be passed in a separate token, even when in short mode. If -a, -b and -c are options for an immaginary FooScript, then
```
    FooScript -a -b -c blah.txt
```
is correct, but
```
    FooScript -abc blah.txt      # WRONG! Options must be separated.
```
is not.
All scripts have a --help option (or, in short form, -h). When a program that needs arguments is run without arguments, the help text will be displayed. (Note: Actually, not all scripts conform to this yet, but this is being worked on).