Contributing to the Wiki

We greatly value community contributions to our wiki! If you notice any gaps or errors in the documentation, you have the power to make a difference!

Simply click the edit button ✏️ in the top right corner of any wiki article to access an editable form on GitHub. We use Markdown formatting, by the way.

The wiki’s content and source code are housed in a dedicated repository on Github.

Check out the README for guidance on navigating the wiki’s code, or feel free to file an issue if you need assistance!

Manual Compile

Building and installing manually from source. This should only be done if one is unable to create a recipe or as an excercise. With very few exceptions, the work of creating a recipe is rewarded by the ease of using Compile.

See also: Advanced → Steps of the compile process

I’m using dosbox from CVS as an example here.

First, go into the folder where you have the source (change directory).

phed@Arjuna ~/]cd dosbox
phed@Arjuna ~/dosbox]

Run PrepareProgram with the option -t or –tree to generate the directory tree in /Programs/DOSBox/CVS.

phed@Arjuna ~/dosbox]PrepareProgram -t DOSBox CVS
phed@Arjuna ~/dosbox]

Then run PrepareProgram again without options to run configure

phed@Arjuna ~/dosbox]PrepareProgram DOSBox CVS

PrepareProgram: Preparing...
PrepareProgram: Autoconf configure script detected.

checking build system type... i686-pc-linux-gnu
...
config.status: creating config.h
config.status: executing depfiles commands
phed@Arjuna ~/dosbox]

Then we have to do whatever is required in order to build the application. In the case of DosBox we have to issue make in order to compile the program.

phed@Arjuna ~/dosbox]make
make[1]: L/bin/make  all-recursive
make[1]: Entering directory `/Users/phed/dosbox'
...
make[1]: Leaving directory `/Users/phed/dosbox'
phed@Arjuna ~/dosbox]

Next run SandboxInstall to install the program into the Programs-tree

phed@Arjuna ~/dosbox]SandboxInstall dosbox CVS
SandboxInstall: unionfs is available.  Using UnionSandbox!
SandboxInstall: Installing DOSBox...
...
SandboxInstall: Postprocessing Sandbox
phed@Arjuna ~/dosbox]

And at last, run SymlinkProgram to link it into the LHS tree.

phed@Arjuna ~/dosbox]SymlinkProgram DOSBox CVS
SymlinkProgram: Symlinking DOSBox CVS.
...
SymlinkProgram: Done.
phed@Arjuna ~-->dosbox]

And then we’re done. Enjoy!

Installing Packages from the LiveCD

After installing GoboLinux and booting from the hard disk, you may want to choose software packages from the Live CD to install. To do so, you must mount the squashfs file that contains the image from the Live CD system.

To do that, first mount the CD then mount the desired GoboLinux squashfs file:

mount /Mount/CD-ROM
mount /Mount/CD-ROM/GoboLinux-NonBase.squashfs /Mount/ SquashFS -t squashfs -o loop=/System/Kernel/Devices/loop0`

Now, you can use InstallPackage to install software from the Program/ directory of the Live-CD:

InstallPackage /Mount/SquashFS/Programs/Inkscape

Note 1: after using the squashfs file, you may want unmount it:

umount /Mount/SquashFS

Note 2: To have the dependencies required by an application installed automatically, use the --batch or -b parameter:

InstallPackage --batch Gimp

-or-

InstallPackage --batch /Mount/SquashFS/Programs/Gimp

Filesystem Virtualization with Runner

Runner is a utility for launching programs under GoboLinux that ensures that the filesystem view of a process will match its dependencies. In other words, Runner eliminates the possibility of library conflicts when running an executable.

Runner is a filesystem virtualization tool that sets up a constrained view of /System/Index for a process based on the executable program’s Dependencies file. It is run as a wrapper, e.g. Runner SomeApp.

Runner builds a custom mount table for the process, like container tools do, but without duplicating files. It dynamically picks the correct parts of your /Programs tree. This approach is feasible in GoboLinux due to way programs are each confined to their own subdirectories.

Preparing the filesystem view

All you have to do is to make sure the dependencies of the program you want to run are correctly listed under the program’s Resources directory - more specifically, in the Dependencies file at /Programs/Name/Version/Resources/Dependencies. You may list program names (e.g., LibPNG), specify a particular version (as in LibPNG 1.4.4) or even let Runner pick the best version given a certain range (e.g., LibPNG >= 1.4.0, < 1.5.0).

Most likely, the program you want to run will already have a sane Dependencies file - every binary package we distribute will have one, just like every compilation recipe do.

The Compile tool

Compile makes use of Runner to control the environment for building software packages. When you type Compile Foo, Compile fetches the recipe for Foo and passes both the Dependencies and BuildDependencies files of that recipe to Runner. This ensure that the right versions of the libraries, headers, and executables needed by that package will be mapped onto /System/Index.

Spawning an application with Runner

For regular GoboLinux packages, simply type Runner application_name. Runner will figure from which entry under /Programs application_name comes from, and will create a custom filesystem view for that application by overlaying its dependencies over /System/Index.

For non-regular GoboLinux packages, such as third-party executables downloaded on your home directory, you can hand-craft a Dependencies file and then provide that file to Runner, as in Runner -d MyDependenciesFile ./third_party_app.

Multi-arch setups

Running a 32-bit application on a 64-bit distro is no different with Runner. Provided that you have the 32-bit dependencies installed under /Programs (such as Glibc/2.18-i686 and Bash/3.1-i686), the Dependencies file of your program simply needs to state the versions of the 32-bit packages it relies on. Afterwards, simply type Runner <application_name> and you are all set.

Sandbox Install

If I wanted to run make my self, what would I need to do to sandbox it?

This is how its done.

tar xvzf Foo.tar.gz
cd Foo
PrepareProgram Foo 1.0 -- --enable-crazy-feature-x
make
PrepareProgram -t Foo 1.0
SandboxInstall Foo 1.0
SymlinkProgram Foo 1.0

See also: How To’s → Manual Compile