Hello and welcome to the official documentation and wiki of the GoboLinux
project!
GoboLinux is quitedifferent from your usual linux
distribution. Therefore to make your journey as enjoyable possible, you should
carefully read and consult the documentation.
If you have just installed GoboLinux on your PC, make sure to check out the
Known Issues and Fixes
section first.
How to find your way around
You can begin with the Getting Started section on the
left. This should get you going. You can use your ←left/right→ for
navigation. Or make use of our full-text search!
The Advanced section contains some
further and advanced topics , but if you’re serious about your GoboLinux journey
you should read this one, too!
The How-To’s section holds articles to solve a specific
problem and guides you through step-by-step. We rely heavily on community
contributions here. If you feel something important is not covered, be
encouraged to submit your contribution!
The Commands section is a list of GoboLinux
specific commands and tooling, that will make your life with GoboLinux much
easier. They are what makes GoboLinux so enjoyable and are very much in the
spirit of: „Do One Thing and Do It Well!”.
Couldn’t find what you were looking for?
GoboLinux is a very broad project, that has its roots back to 2002!
Thus you may find outdated or even missing documentation… but do not
despair!!
Our community is here to help you out. If you have read the documentation but
still require further assistance, reach out to us on:
IRC chat:#gobolinux at
irc.libera.chat (slow channel, please be patient and wait up to 24h for a response!)
Please be patient, we are a small community but we do make an effort to help
everybody out.
Expectations
As an experimental distribution, you might run into some bugs along the way. We encourage you to tackle these
challenges on your own or with the support of our friendly community. While we can’t promise everything will be
handed to you, your discoveries and solutions are invaluable to us—please share them!
If you find this documentation to be lacking in any regard please refer to this article.
GoboLinux thrives on the
passion and contributions of its users, and together, we can make it even better.
Your exciting journey with GoboLinux has just begun!
Subsections of GoboLinux Knowledge Base
Getting Started
Welcome to the world of GoboLinux !
The main task of a Linux distribution is to keep track of and organize the
programs in your computer, so that they work properly. GoboLinux is no different
from the others in this goal, but it adopts a fundamentally different approach
in solving this problem.
Instead of scattering the files of programs around,
following the
decades-old conventions
of ancient UNIX systems, and then adding a layer of control (a “package
manager”) to try to give order to chaos, in GoboLinux we organize the files that
comprise the programs in an ordered way in the first place.
In GoboLinux, every program lives in its own subdirectory. Under the top level
directory /Programs; e.g you’ll find Xorg 7.0 at /Programs/Xorg/7.0, and
ping at /Programs/Netkit-Base/0.17/bin/ping. To see what programs are
installed in the system, all you need to do is look in the /Programs
directory:
ls /Programs
For each category of files, there is a directory under /System/Index grouping
files from each application as symbolic links: bin, lib, libexec,
include, share, and man. For compatibility, each “legacy” UNIX directory
is a link to a corresponding category. Therefore, /bin, /sbin, /usr/bin,
/usr/local/bin (and so on) are all symlinks to entries under /System/Index.
In short, what we have is a database-less package management system: the
directory structure itself organizes the system. Wasn’t that its original
purpose, after all? Each program directory (for example, /Programs/KDE) holds
version directories (/Programs/KDE/3.4, /Programs/KDE/3.4.2), and a
version-neutral directory for settings (/Programs/KDE/Settings), to keep files
that would normally be in /etc.
Keeping two or more versions of a library is
trivial: upgrading LibPNG to 1.2.8 means adding /Programs/LibPNG/1.2.8, but
does not automatically imply that LibPNG 1.2.7 is removed. This way, if a
program depends on the previous version, it won’t break. As you can see,
GoboLinux gives you a finer control of what is and isn’t in the system.
Historical tidbit: When most distributions switched to GCC 3 they released a
new major version, mostly incompatible with previous ones. In contrast, when the
006 series of GoboLinux adopted GCC 3, compatibility was preserved by simply
keeping old versions of libraries alongside the new ones, while they were
gradually phased out. No “compat” packages were needed.
GoboLinux has a directory structure different from most other Linux
distributions. In GoboLinux, all files for a program, including executables,
headers and libraries, are installed below a single directory that belongs to
that program.
So the ping utility might reside in
/Programs/Netkit-Base/0.17/bin/ping
and libpng.so.3 in
/Programs/LibPNG/1.2.5/lib/libpng.so.3
To be visible to other software, these files are symlinked into standard
locations in the new directory hierarchy under /System/Index:
As a result, most things just work. For example, GoboLinux will correctly
dispatch scripts with shebang lines such as #!/usr/bin/env perl or
#!/usr/bin/python to the proper interpreter.
This architecture —installing each program under its own directory, and making
executables, headers other resources available via symlinks— has significant
advantages:
Unfortunately, not all programs have the flexibility to be installed anywhere.
Occasionally, hardcoded paths creep in even in programs that belong to userland,
and should, at least theoretically, allow themselves to be installed inside,
say, a user’s home directory.
As much as we’d like to see this done in the long term, patching all
applications is not an option. For this reason, GoboLinux keeps, as stated
earlier, a legacy tree where all usual Unix paths are mapped to GoboLinux
equivalents. That way, if a Makefile looks for
/usr/X11R6/include/X11/Xaw3d/XawInit.h, it will find it, although it is really
at /Programs/Xaw3d/1.5/include/X11/Xaw3d/XawInit.h, where it belongs. When two
applications have a directory entry with the same name, the GoboLinux scripts
recursively expand them. Both Xorg and Xaw3d have X11 under include. A
directory /System/Index/include/X11 is created automatically, holding links
from both X11 directories.
Another interesting feature is that the GoboLinux scripts execute make install
using a special user id that only has write permissions inside the program’s
source directories and the program’s entry under /Programs. This way, files
can’t “escape” from the GoboLinux hierarchy and slip a directory into the legacy
tree.
A detail that might surprise you at first is that when you look at the root
directory (with ls or graphical tools), you don’t see the legacy directories,
even though you can cd into them. They are certainly there — they are just
kept hidden using GoboHide, a kernel modification
designed to conceal the legacy tree from the usual system view. (GoboHide is of
course optional — GoboLinux works just as well using standard Linux kernels.)
Influences and roots
As you read this, you have probably found many familiar concepts (not to mention
directory names). GoboLinux has clearly found inspiration in other operating
systems, like NeXT, BeOS and AtheOS, but it was the notion that they build
“something different” using an existing Unix base (be it using a BSD foundation
as in macOS, or using GNU tools as in AtheOS) was the most important influence
of all. There are several other projects, in various stages of development, that
use the Linux kernel as a foundation and feature alternative directory trees.
Interestingly, most of them are clones or heavily inspired by a specific
proprietary operating system. (At different points in time, we’ve seen clones of
RiscOS, NeXT, BeOS.)
GoboLinux, on the other hand, is not a clone of anything else. It uses standard
Linux desktop software. We believe that the well-organized directory structure
makes it a good testbed for new ideas — possibilities are wide open (see the
forum and moreso the mailing list for discussions, and to a lesser extent the
IRC channel #gobolinux on libera.chat).
Differences between GoboLinux and a traditional Linux system
What follows is not a thorough description of GoboLinux, but a quick cheat-sheet
of facts that are good to know when you are getting acquainted to the system.
In the GoboLinux hierarchy, files are grouped by their functional category
(executables, libraries, and so on). There are links at the classic
directories you are used to (/bin, /usr/bin, and so on), but remember
that they all point to the same place. This is a huge advantage, as it
means, for example, that you’ll never have to search for a library
throughout your filesystem again – it will always be in /lib (and in
/usr/lib, because they point to the same place! – no worries about
compatibility).
There are symbolic links relating most of the usual UNIX directories to the
GoboLinux tree. Therefore, you will find directories such as /etc,
/var/log and /usr/bin in the expected places. However, some directories,
such as the users’ directories, didn’t need to be linked to their “legacy”
locations. This way, for a given user called “joe”, you’ll have, instead of
/home/joe, /Users/joe. Notice also that the superuser’s directory is no
different than the ones from the other users, so, root’s directory is at
/Users/root. Mount points are under /Mount, not /mnt.
Another major difference between GoboLinux and most Linux distributions is
that it does not use a BSD nor a System V initialization procedure. Instead,
it has its own. At /System/Settings/BootScripts you will find a few files
that command the entire boot procedure: BootUp and Shutdown run at system
boot and shutdown, respectively; you can define custom “runlevel” scripts to
define different ways you want your system to be initialized (say, Single
and Multi for single and multi-user, Graphical for boot into graphic mode,
etc.) and control that from the boot loader menu. The
/System/Settings/BootOptions file separate site-specific settings from the
rest of the scripts. You can also find a library of application specific
tasks at /System/Tasks that can be used during boot (those are installed
by the apps).
For a better overview of how it looks and feels right, nothing beats giving the
LiveCD a spin. You’ll be running a full GoboLinux system without having to
install anything.
Just flash a USB-Drive and give it a go !!
GoboLinux Filesystem Hierarchy
Here is an overview of the GoboLinux filesystem tree. The legacy folders (on the
“:” part of the tree) are links to the corresponding GoboLinux folders. The
legacy folders are excluded from default directory view by
GoboHide.
/
|-- Data - for resources belonging to the system and to individual programs
| |-- Compile - sources, recipes and other files used by the Compile tool
| | |-- Archives
| | |-- LocalRecipes
| | |-- PackedRecipes
| | |-- Recipes
| | `-- Sources
| `-- Variable - for spool files, log files, temporary files, etc.
| |-- cache
| |-- empty
| |-- lib
| |-- lock
| |-- log
| |-- run
| |-- spool
| `-- tmp
|-- Mount - mountpoints for filesystems
|-- Programs - where programs (with all their files) are installed
|-- System
| |-- Aliens - files managed by programming language package managers
| |-- Environment - links to program files declaring environment variables
| |-- Index - links to files in each program's
| | |-- bin + bin/ and sbin/ directories
| | |-- include + include/ directory
| | |-- lib + lib/ directory
| | |-- libexec + libexec/ directory
| | `-- share + share/ directory
| | |-- consolefonts
| | |-- fonts
| | `-- man
| | |-- info + info/ directory
| | `-- man{1-9} + man{1-9}/ directories
| |-- Kernel
| | |-- Boot - kernel images, config files and programs needed to boot
| | |-- Devices - device files (managed by Udev).
| | |-- Modules - loadable kernel modules (device drivers)
| | |-- Objects - a view of the kernel's device tree
| | `-- Status - kernel status files (belonging to the /proc filesystem)
| |-- Settings - system config files and links to files in program's Settings/ directories.
| | `-- BootScripts - scripts used for boot, symlink to /Programs/BootScripts/Settings/BootScripts/
| `-- Tasks - links to programs' boot tasks (from their Resources/Tasks/ directory)
|-- Users - contains users' home directories
:
:
:-- etc -> System/Settings
:-- dev -> System/Kernel/Devices
:-- sys -> System/Kernel/Objects
:-- proc -> System/Kernel/Status
:-- var -> System/Variable
:-- tmp -> System/Variable/tmp
:-- sbin -> System/Index/bin
:-- bin -> System/Index/bin
:-- lib -> System/Index/lib
:-- lib64 -> System/Index/lib
`-- usr
|-- X11R6 -> .
|-- local -> .
|-- bin -> ../System/Index/bin
|-- sbin -> ../System/Index/bin
|-- include -> ../System/Index/include
|-- lib -> ../System/Index/lib
|-- lib64 -> ../System/Index/lib
|-- libexec -> ../System/Index/libexec
`-- share -> ../System/Index/share
System Index
Compiled programs in C and C++ typically have a lib/ directory and often also
a bin/ directory.
On GoboLinux, these will be symlinked into /System/Index such as for ping:
Installer is a program included on the GoboLinux Live-ISO that installs
GoboLinux to your hard drive.
It takes care of basic configuration, package selection, and boot
loader setup. It can be run from the command line or via the window manager
menu.
Graphical Install
The GoboLinux Live-ISO supports a complete graphical display environment.
In most cases, the X server automatically detects the keyboard and display
hardware, so you can start the graphical mode by typing:
startx
Clicking on the top-left icon brings up a menu. Look under System Tools, select
“Install GoboLinux”, follow the instructions.
Console install
Type Installer in the console. Note the capital “i”. (GoboLinux utility
scripts are generally named with an initial capital and follow the CamelCase
convention.)
QEMU provides a networking stack so that the guest OS running on this virtual
machine can access the internet, or ssh to the host.
The only extra setup needed is to run Gobo’s DHCP client inside the guest.
dhcpcd
By default QEMU acts as a firewall and does not permit any incoming traffic. It
also doesn’t support protocols other than TCP and UDP. This means that ping and
other ICMP utilities won’t work.
The script has some library dependencies. The most convenient way to install
them (and any CPAN modules) is to use cpanminus (cpanm). So install
cpanminus, then the dependencies:
The script follows below. Edit the QEMU options to your liking, put the script
in somewhere in your $PATH, and make it executable with something like
chmod a+x ~/bin/qemust.
#!/usr/bin/env perluse strict;
use warnings;
# qemust - start QEMUuse5.012;
use Getopt::Long::Descriptive;
my ($opt, $usage) = describe_options(
'%c %o',
[ 'iso=s', "ISO file to boot" ],
[ 'image=s',"OS disk image file" ],
[ 'help', "print usage message and exit" ],
[ 'n', "print QEMU startup command and exit" ],
);
print($usage->text), exit if$opt->{help} or ! keys %$opt;
my$boot_drive = $opt->{iso} ? 'd' : 'c';
my@cmd = grep{! /^\s*$/} map{s/\s*#.*$//; $_} split "\n",<<"CMD";
sudo # run as root
qemu-system-x86_64 # for 64-bit CPUs
-enable-kvm # faster virtualization
-show-cursor #
-boot $boot_drive # boot from DVD/CDROM if present
-m 768 # use memory 768MB
-cpu host # same CPU model as host
-daemonize # avoid race conditions when QEMU started by external program
-vga std # probably -vga vmware would work, too
-soundhw ac97 # typical soundcard, -soundhw hda should also work
-rtc base=utc # timer related
-usb # enable USB driver
-usbdevice tablet # so QEMU can report mouse position without grabbing mouse
-device usb-mouse #
-clock unix #
CMDpush @cmd, "-cdrom $opt->{iso}"if$opt->{iso};
push @cmd, "-hda $opt->{image}"if$opt->{image};
my$cmd = join " \\\n",@cmd;
say $cmd;
system($cmd) unless$opt->{n};
__END__
Running under VirtualBox
Note
This article has been written for an older GoboLinux
release, and is potentially out of date!!
Setting up VirtualBox guest additions
VirtualBox requires its own graphics drivers in order to perform advanced
features such as smart mouse sharing and running at a window-dependent full
resolution.
These drivers can be built using the “Guest Additions” ISO image included with
VirtualBox.
The catch is that we are already using the virtual CD drive from VirtualBox to
run the ISO, so we need to add a second one. With the virtual machine shut down,
right-click the image, then at the Storage pane, add a second optical drive, and
insert the VBoxGuestAdditions.iso file that should be somewhere in your
VirtualBox installation:
Then, boot GoboLinux normally in VirtalBox, and do the following:
mount /dev/sr1 /Mount/CD-ROM
cd /Mount/CD-ROM
./VBoxLinuxAdditions.run
udevadm trigger
When you run udevadm trigger the drivers should be loaded, and the console
will change resolution immediately. (It will also lose the nice-looking
GoboLinux font: to reload it, type setfont lode-2.0-lat1u-16.)
Now, you can start Xorg normally with:
startx
If you want to resize your VirtualBox window, make sure “Auto-resize guest
display” is turned on in the VirtualBox “Machine” menu, then, after resizing the
VirtualBox window, type in the GoboLinux terminal the following
xrandr --output VGA-0 --preferred
This will resize the desktop to match your window size.
Note that this installation of the VirtualBox guest additions will only last for
the current Live-CD session. If you install GoboLinux into a VirtualBox virtual
hard drive, you will have to do the same again.
Running under GNOME Boxes
GNOME Boxes is a new virtual machine manager and remote desktop manager powered
by QEMU, KVM, and libvirt virtualisation technologies. Running Gobolinux under
GNOME Boxes is quite easy, even more so than under Virtualbox.
Setup Instructions
Create a new Virtual Machine by clicking “New” in the top left corner.
Click “Select a file”.
Select the Gobolinux LiveCD ISO file.
Boxes will be ready to create a virtual machine with 2GB of RAM and 21.5GB of
storage. If that is sufficient, click “Create”.
Otherwise you can click “Customize” and adjust the sliders for RAM and
storage respectively, then click the back arrow.
The LiveCD session will then start. Continue normal installation procedures.
Remember to eject the LiveCD prior to reboot by going to the top right menu
and clicking “Properties” -> “Devices & Shares” and then clicking “Remove”
beside the CD/DVD section.
Installing SPICE
Spice allows for integration with the host system including setting native
resolutions, file transfers, clipboard support etc.
Compile SPICE-VDAgent
Run StartTask Spice-VDAgent after login
Run spice-vdagent
Run xrandr --output Virtual-0 --preferred to update the resolution
Installing to external storage devices
Note
This article has been written for an older GoboLinux
release and is potentially out of date!!
GoboLinux 016 comes with two installation modes: UEFI and BIOS-compatibility
mode. Depending on how your computer firmware is configured you may need to
follow one or another recipe below.
BIOS-compatibility mode
Ensure that your external disk has been configured with a MSDOS partition
table. You need to have at least one Linux partition (e.g., ext4), with the
BOOT flag set.
You can then proceed with the installation of GoboLinux by selecting that Linux
partition as install target and by enabling the installation of the bootloader
on the master boot record (MBR) of that disk.
UEFI mode
Ensure that your external disk has been configured with a GPT partition
table. You need to have at least one Linux partition (e.g., ext4) and a FAT
(32/16/12) partition which is where the UEFI application embedding the GRUB
bootloader will be stored. The FAT partition needs to have both the ESP and
BOOT flags set. If you are using GParted, that FAT partition will be
automatically formatted by the tool. If you are not, then make sure to invoke
mkfs.msdos to format it yourself.
Once the partitioning is arranged, you can proceed with the installation of Gobo
by selecting the Linux partition as system install target and by selecting the
FAT partition (also called EFI System Partition) as bootloader install target.
Troubleshooting
Unable to mount root fs
Both USB-Storage and UAS (USB-Attached-SCSI) drivers are built into the kernel.
However, at times the kernel may not have time to discover the partitions on
your external disk and may fail to mount the root filesystem. This particular
problem can be fixed by adding the rootwait parameter to the kernel command
line.
For BIOS-compatibility mode:
Mount your system partition using the LiveCD under /Mount/GoboLinux
Edit the file at /Mount/GoboLinux/System/Kernel/Boot/grub/grub.cfg. Look
for the lines starting with linux /System/Kernel/Boot/kernel-4.8.2-Gobo and
append the word rootwait to the very end of those lines
Unmount the partition under /Mount/GoboLinux and reboot.
For UEFI mode:
Mount your boot partition (the one with a FAT filesystem) using the LiveCD
under /Mount/GoboLinux
Edit the file at /Mount/GoboLinux/EFI/BOOT/grub-efi.cfg. Look for the lines
starting with linux /System/Kernel/Boot/kernel-4.8.2-Gobo and append the
word rootwait to the very end of those lines
Regenerate the UEFI application. This is a large command, so it’s better to
just copy+paste it.
Afterwards, unmount the partition under /Mount/GoboLinux and reboot.
GoboLinux 017.01 Known Issues and Fixes
Installation in a VM
In a VM environment, installing GoboLinux’ bootloader onto a GPT partion currently fails. Please set up MBR partitioning!
On bare metal systems GPT partitions worked fine in our testing (if in doubt, configure your bootloader manually).
Other outstanding issues
Some problems have been reported by our users and are currently being fixed by
our team. They are:
Copy-and-paste does not work out of the box from a VM. Compiling
spice-vdagent and loading its daemon should fix that.
Sometimes when trying to Compile an already-installed Program, the build
process will fail (see
Compile bug 51). Sometimes
this can be worked around by first manually doing a
RemoveProgram <failing program> before re-attempting to Compile it. Note
that it is generally a Bad Idea™ to try to RemoveProgram, say,
Python3 like this as it will break Compile.
ContributePackage is not working – use
ContributeRecipe instead.
With Compile, GoboLinux build utility, software sources can be downloaded,
compiled and installed in a single step. An example will follow next.
In order to install irssi, a text-based IRC client from the command line,
you would type the following instruction:
Compile irssi
Depending on the speed of your computer, internet connection and what packages
you have installed, Irssi should download and install in a few minutes.
Compile manages the build process using GoboLinux recipes. Each recipe contains
a list of build directives and supplemental control files for compiling a
particular software library.
Finding recipes
Typically, you can just try the name of the recipe you want from the command
line. There is also an online recipe viewer,
listing the most recently uploaded recipes first.
Command-line options
Compile has a number of command-line options, which are listed
here. The following are especially useful.
When using the --batch or -b automatically attempts to process all
dependencies of the requested program.
Separating download and compile phases
The next two options are useful when working with intermittent internet access,
or if you’d like to run your compiling jobs at night when you’re asleep.
Calling Compile with the --no-build flag downloads sources only.
Later, in the event that you wish to use the --no-web flag, this will direct
Compile to search to your system’s own download cache and build the sources
found there instead. This commandline switch is obviously very useful if you do
not have a working internet connection for the time being.
In general it is recommended to always use the latest stable version of
Compile. Compile is very important to GoboLinux so if
there is any problem in it, it is normally fixed very quickly.
Binary packages
Warning
We do not maintain a binary package repository at this time! |
Please build your packages from source using Compile!
Binary packages in GoboLinux are precompiled software packages built for the
GoboLinux directory tree and made available through the GoboLinux software
repository (recipe store). Since these packages are already compiled, you can
save the many hours needed to build larger applications. On the other hand, with
binary packages you don’t have the ability to set compile flags for optimization
or specific architectures.
Installing packages
InstallPackage is the GoboLinux script for
installing binary packages. If you want
InstallPackage to look for the most recent Gimp
package available, you can run
InstallPackage Gimp
The script will check if the package is available in the GoboLinux repositories.
(See /System/Settings/GetAvailable.conf for the specific URLs scanned. You may
add your own repositories if you desire.)
If you want to select a specific version, you can pass it as the second
parameter:
InstallPackage Gimp 2.8.18
If you downloaded the package and want to install it, run:
InstallPackage Gimp--2.8.18--i686.tar.bz2
The script normally runs interactively, asking about each dependency of the
requested package before installing it. You can avoid these queries by adding
the --batch or -b flag. This is particularly useful with large packages such
as Gimp or Xorg, which have many dependencies.
InstallPackage -b Gimp
Dependencies
InstallPackage will warn you if dependencies of a package you are trying to
install are unavailable and ask if you want to continue. This is valuable,
because some software may still work satisfactorily even if a particular plug-in
or other dependency is missing.
In GoboLinux, all binary packages (as well as all user-compiled software) is
installed under /Programs in a “program directory” provided for each version
of each application, for example:
/Programs/Gimp/2.8.18
When compiling software under GoboLinux the installation target directories such
as bin/, lib/, and etc/ that are required for a typical program are placed
inside the program directory.
With this self-contained directory structure, all that is needed to generate a
binary package is to make a tarball of the program directory, copy over the
Resources/ directory from the Compile recipe, and generate a few additional
files, which are also placed under Resources/.
Before creating a package, be careful to vet the contents of the program’s
Settings/ directory to ensure that it does not include personal information.
A package submitted for inclusion in the GoboLinux packages repository must have
sensible default settings, honoring the application defaults if possible.
The CreatePackage command
In order to create a package, run the
CreatePackage utility with the package name as a
parameter. For example,
CreatePackage rxvt
will create a binary package in the current working directory.
The two main parts of GoboLinux are /Programs and /System. If you stick to
using InstallPackage and
Compile, these two parts will be implicitly kept in
sync by SymlinkProgram. But a lot of power lies
in the fact that you can tune how these two worlds interact.
Program entries under /Programs feature a Current symlink pointing to a
specific version that is “active” in the system. This Current version is taken
as the default version when you don’t specify a version in scripts, and the link
is updated when you install a new version with
InstallPackage or
Compile.
That doesn’t mean that you can only have one version linked into the system: you
can have files of multiple versions show up in /Programs. In fact, when you
install a new version with InstallPackage but
keep the old version in /Programs, files for which there’s no version with the
same name in the new package are still linked – this is especially useful for
libraries.
The default behavior of SymlinkProgram is to
replace symlinks under /Programs that belong to a different version of the
same program. So, now, we’ll have the following links related to Foo under
system:
So, now, when you run foo, it will fetch version 2.0 of the program through
your system $PATH (which looks at /System/Index/bin). But, as you can see,
libfoo.so.1 is still there. This way, if you have other programs installed in
the system that are linked specifically to version 1 of the libfoo library will
continue working.
This means you won’t have the old problem “I upgraded package Foo and now my
other apps are broken”. Of course, you can still break things when you remove
a version which other programs depend in (or if buggy programs link to a version
independent name of a library (libfoo.so) but depend on features of a specific
version).
Besides SymlinkProgram (see section “Compiling
manually” and its reference
entry for details on it), there are other scripts
that give you more control over what is linked in the system and what is not.
With DisableProgram, you can remove from
/System all links that refer to a specific version of a program, effectively
“turning it off” – it is as if it were not present in the system.
With RemoveProgram, you can remove a program
from /Programs and its references from /System in a single step.
Use the UpdateRecipes command to refresh your
local cache of the GoboLinux recipe store.
You can query available updates using the utilities
SuggestUpdates and
SuggestDuplicates. The output of each of
these commands is suitable for piping into commands.
Keep in mind that most operations that change the file-system state in Gobo
require super user privileges:
Ensure that Scripts are up to date
cd /Programs/Scripts/Current
sudo git pull && sudo UpdateSettings --auto Scripts && sudo make
Ensure that Compile is up to date
cd /Programs/Compile/Current
sudo git pull && sudo UpdateSettings --auto Compile
UpdateRecipes - Update local copy of recipe store
cd /Data/Compile/Recipes
sudo UpdateRecipes
SuggestUpdates - List packages with an update available
cd /Data/Compile/Recipes
SuggestUpdates
Install updates
Currently, there is no way to update packages automatically. This used to be
done with the Freshen script, which is currently not
in working order.
Updates thus need to be installed manually via
InstallPackage or
Compile as appropriate.
Removing programs
In GoboLinux, all programs, whether binary packages or user-compiled software,
are installed into a single directory under the /Programs hierarchy, such as,
for instance, gimp:
/Programs/Gimp/2.8.18
Removing this program can be, in theory, as simple as:
rm -rf Gimp/2.8.18
But since this leaves behind dangling symlinks, GoboLinux offers the
RemoveProgram utility, which removes the program
and all links pointing to its files in /System/Index.
RemoveProgram Gimp 2.8.18
Sometimes you may want to “turn off” a program temporarily, without erasing it
from your hard disk. In other words, you want to remove program’s executables
from the execution path, and remove libraries and headers from the lookup path.
In GoboLinux, this can be accomplished by removing the associated symlinks for
/System/Index. The DisableProgram script facilitates this:
DisableProgram gimp 2.1.18
The version parameter given here, in this case 2.1.18, is optional. If it is
not provided, the Current link is used to determine the program version to
disable. Also note that the program name is case insensitive, but it appears to
be simpler to use a downcased variant - easier to type at the least.
To re-enable the program, all you need to do is recreate the symbolic links:
SymlinkProgram gimp 2.1.18
Maintaining symlinks
GoboLinux has a script called RemoveBroken. that
removes dangling symlinks from /System/Index tree. It can be useful to run
after manipulating directories under /Programs.
RemoveBroken takes a list of files, and removes
those that are dangling symlinks. If no arguments are provided, the script takes
filenames from standard input (typically through a pipe).
The usual procedure to clean up dangling links, is
cd /System/Index
find | RemoveBroken
Dependencies blacklist
Configuring Dependencies
Today there are many programs implementing a given feature in different ways.
One such example is the OpenGL API, with implementations floating in packages
such as Xorg, MesaLib and Nvidia. However, not every user owns a Nvidia card,
and here comes a problem: how should one mask Nvidia from the automated
Dependencies list generated after creating a recipe? This problem is now fixed
with a configurable file called
/Programs/Scripts/Settings/Scripts/Dependencies.blacklist.
Dependencies.blacklist
This file allows one to specify packages that should not appear in the
Dependencies file after creating a new recipe. Its format is pretty simple: one
package per line, without the need to specify its version.
A Dependencies.blacklist example
The following example blacklists the packages Glibc and Nvidia. Comments and
blank lines are ignored by the parser, so it’s ok to include them.
# Dependencies.blacklist is documented in detail at
# http://wiki.gobolinux.org/Dependencies
GlibcNvidia
Note: presently blacklisting specific versions is not supported, but the same
behaviour can be achieved by creating an empty directory in the /Programs
directory. For example, to blacklist GCC version 4.1.2 you may:
Compile.conf is the file where you can configure the various paths and URLs used
by Compile.
It is stored at /Programs/Compile/Settings/Compile/Compile.conf – which, once
installed, has a link at /System/Settings/Compile/Compile.conf (if you’re used
to the GoboLinux tree, you should know by now that this is the same as
/etc/Compile/Compile.conf).
These are the usual contents of the file:
Your name here so that credit is added to recipes.
compileRecipeAuthor="Paul McCartney"# example only! change the name (unless of course, you're Paul ;) )
The standard locations for your local Compile files.
Some of the main free software repositories are treated especially: recipes use
these variables in their url declarations, so that you can pick your favorite
mirror without having to edit recipes one by one:
A variable to set the make command called by Compile. ColorMake provides the
highlighting that GoboLinux has by default:
compileMakeCommand="ColorMake"
Options to use with the make command. This can be used to run multiple threads
in parallel on different CPUs or for other customisation:
compileMakeOptions="-j2"
Environment variables
Some environment variables influence the behavior of some GoboLinux tools. You
may want to set them. Just remember that GoboLinux uses zsh (not bash) as its
default shell, so you should edit .zshrc (not .bashrc). Zsh is a
Bourne-style shell, though, so the syntax you’re used to is still valid.
Of course, if you really prefer bash (though we really recommend giving zsh a
try!), you can change your default shell using the chsh command. See the
chsh man page for details.
The $EDITOR variable should be set to your favorite text editor. Whenever a
GoboLinux tool needs to run an editor, it will run the one indicated in this
variable (in fact, this is not a GoboLinux variable, several programs use it).
GetAvailable
Warning
We do not maintain a binary package repository at this time! |
Please build your packages from source using Compile!
GetAvailable.conf is the file where you can configure paths and URLs used to
locate binary packages.
It is stored at /Programs/Scripts/Settings/Scripts/GetAvailable.conf – which,
once installed, has a link at /System/Settings/Scripts/GetAvailable.conf (if
you’re used to the GoboLinux tree, you should know by now that this is the same
as /etc/Scripts/GetAvailable.conf).
These are the usual contents of the file:
The timeout (in seconds) when trying to fetch the packages list from a sever.
timeout=15
The paths from which local packages will be automatically be found. Notice that
both compressed (e.g. /Depot/Packages/Qt--4.0.0--i686.tar.bz2) and
uncompressed (e.g. /Mount/SquashFS/Programs/Qt/4.0.0) packages can be matched.
The URLS from which lists of tracked versions will be retrieved. A tracked
version is a program version that actually may not have a correspondent Recipe
or binary package, but that is already made available by the program developers
The Linux kernel differs from standard packages. It has nothing to be linked
against the legacy tree: no libraries, no binaries, no headers, no manuals or
info pages. Moreover, there are many things on a regular system which are very
tied to the kernel itself, such as the proc and sys filesystems, the device
nodes and the boot loader files.
These characteristics led to the creation of a special directory for the kernel,
called /System/Kernel. This tree is organized in the following way:
/System/Kernel/Boot - Bootloader files, including the kernel image
/System/Kernel/Devices - Device nodes, populated by Udev + Hotplug
/System/Kernel/Modules - Kernel modules
/System/Kernel/Objects - Sysfs, providing information gathered from Linux
2.6
/System/Kernel/Status - The mounted proc filesystem
Installing a kernel
Thanks to Compile, installing a new kernel is pretty straightforward on
GoboLinux. The Linux recipe takes into account the existence of a file called
config.gz inside /System/Kernel/Status. This file contains the current
configuration for the running kernel, and is used thereby to feed the new kernel
options.
In short, running Compile Linux will fetch the latest available recipe
(which already contains GoboLinux optional patches). After doing that, the
kernel itself is automatically downloaded, patched and filled with the current
configuration, taken from config.gz.
The menuconfig entry then appears, and allows for the user to modify their
kernel options. Just selecting Exit and telling the script to save the changes
will finish the user’s interaction with the Linux kernel compilation. After
completed, a new entry will appear under
/System/Kernel/Modules/$KERNEL_RELEASE, and the new bzImage and System.map
files will get installed under /System/Kernel/Boot.
The old bzImage and System.map files aren’t overwritten, though. They’re just
symlinks to the current kernel image, and this guarantees that if something goes
wrong, a rollback can be done by simply modifying the kernel image at the GRUB’s
bootloader prompt, and later by reverting the symlink’s target to the previous
release.
To install a kernel which is newer than the available recipe, or one other than
vanilla, you may use NewVersion.
If you already have a kernel downloaded, or have a special source package, you
may place it in /Data/Compile/Archives.
Use
NewVersion Linux <Version> https://kernel.org/pub/linux/kernel/v6.12/<your-archive-name>
to create a recipe. Using a fake URL is all right if you don’t intend to
distribute the recipe.
Place any custom patches you need to apply into the
/Data/Compile/LocalRecipes/Linux/<Version> directory.
Then Compile as usual.
Kernel patches
The Linux recipe comes with a few patches in order to improve the user’s
experience with the system. The patchset includes, but is not restricted to, the
following modifications:
GoboHide: allows the legacy tree to be hidden from
userspace applications
SquashFS: A compressed filesystem which gets uncompressed on demand. This
filesystem is currently used on the GoboLinux ISO, and so it’s interesting
to have it in order to get the CD contents easily accessible through the
mount command
This page describes the boot process and how to configure your GoboLinux system
by editing the configuration files used for startup.
General architecture
The BootDriver script
(/Programs/BootScript/<version>/bin/BootDriver) manages boot-related tasks.
The init program (from the Sysvinit package) running as PID 1 calls
BootDriver as specified in /System/Settings/inittab.
BootDriver first loads the boot theme
file specified in /System/Settings/BootOptions.
Then BootDriver runs the appropriate boot script for the task at hand (startup,
shutdown, etc.)
Boot Scripts
GoboLinux boot scripts initialize and configure the system, manage daemons, and
perform shutdown. They are located at /System/Settings/BootScripts.
BootUp, the primary startup script, is invoked when you turn on the power
and the system boots. It contains generic initializations common to most
Linux systems. Additional scripts are provided to support particular boot
scenarios.
Console runs BootUp and performs initializations required for a
console session.
Graphic runs BootUp and starts X to provide a login window.
Shutdown is the primary shutdown script, analogous to BootUp. It is used
by the following termination scripts:
Reboot runs Shutdown to terminate system services then reboots the
machine.
Halt runs Shutdown and turns off the power, if possible. Otherwise it
halts the processor.
Each of these scripts contains lines of the form:
Exec"Message..." SomeCommand [ parameters ]
For example, to adjust the keyboard delay and repeat rate in the console, you
can add this line to /System/Settings/BootScripts/Console:
GoboLinux also provides “boot tasks” as a more
sophisticated way of managing services.
Configuration options
When GoboLinux boots, the boot scripts launch programs to configure the
keyboard, set the system clock, initialize the network, etc.
The parameters for calling these programs are placed in
/System/Settings/BootOptions and /System/Settings/NetworkOptions. Both files
contain entries of the form:
Option=value
Note that no space is allowed before or after the = character. This is shell
syntax, allowing the options to be imported into the boot scripts using the
source command.
The following sections document options available in
/System/Settings/BootOptions and /System/Settings/NetworkOptions.
Clock mode
GoboLinux needs to know if your hardware clock is set to GMT or local time.
Specify this by editing the ClockMode option. Set ClockMode=GMT if your
hardware clock is set to GMT. Set ClockMode=LocalTime if your hardware clock
is set to local time.
For obtaining time zone information, Linux applications rely on information
provided by Glibc, the C library. Glibc, on its turn, uses the localtime
symlink in its Settings directory (/Programs/Glibc/Settings/localtime) to
indicate the active time zone. This symlink is created by the installer
according to the time zone you selected. You can set this setting manually, by
pointing the localtime symlink to a different file under
/Programs/Glibc/Current/Shared/zoneinfo.
The ClockMode information is used for the hwclock utility, which is launched at
boot time through the SetClock task.
Console setup
Fonts
Fonts in GoboLinux are stored under /System/Index/share/consolefonts and
/System/Index/share/fonts. They provide character typefaces for the Linux
console, the X Window System, and ghostscript, the Linux postscript
interpreter.
Font path configuration for X can be found in /System/Settings/X11/xorg.conf
and /System/Settings/fonts/fonts.conf.
To change the default console font used by GoboLinux, use the ConsoleFont option
in /System/Settings/BootOptions.
You can also change the console font using the setfont utility. See
man setfont for details.
Remember that this setting changes only the console font. On X, applications
have their own font settings.
Keymap
Use the KeymapLayout option in /System/Settings/BootOptions to select an
appropriate console keyboard layout.
The available keymaps are in the KBD package; they are the .map files. You can
set the console keyboard layout at any time by running loadkeys. For example, to
set the Dvorak keymap, just type in:
loadkeys dvorak.map
Mouse
The MouseType and MouseDevice options in /System/Settings/BootScripts/BootUp
configure mouse support on the console. They are disabled by default.
Graphical display setup (X server)
Keymap
The keyboard layout for programs running under the window manager is mapped
according the InputDevice section in /System/Settings/xorg.conf when the
graphic display (X server) starts. With the window manager running, you can
change keyboard mappings and display settings using setxkbmap, xmodmap, and
xset tools. To select a Dvorak keyboard layout, type setxkbmap dvorak in a
terminal. These commands can also be placed in $HOME/.xinitrc.
Some desktop environments also offer graphical tools for setting the keyboard
layout. For example, in KDE you can configure this at the KDE Control Center.
Mouse
The mouse pointer for the graphical display is defined in an InputDevice
section in /System/Settings/xorg.conf. The Installer
should correctly detect your hardware and set suitable defaults for your system.
If not, you can always try a failsafe setup such as:
There is nothing GoboLinux-specific about mouse setup on X. You can find HOWTOs
and tutorials around the net that can give you more detailed instructions about
this. (But feel free to drop by at the mailing list if you’re still stuck!)
Kernel modules
Through the use of Udev, GoboLinux is capable of loading kernel modules (e.g.
device drivers) automatically at boot. In cases Udev doesn’t load some wanted
drivers, the user can explicitly request them.
One way is to edit /System/Settings/modprobe.conf (similar to other Linux
distributions), however a simpler way in GoboLinux is to list desired modules in
/System/Settings/BootOptions. This is how to load the i810_audio audio driver
and sk98lin ethernet driver:
UserDefinedModules=(
"i810_audio""sk98lin")
The startup scripts read this array and run modprobe each line. The entries may
include additional parameters.
Network configuration
Wi-Fi
If you are using Wi-Fi, just select your network using the
GoboNet widget in the AwesomeWM system
tray:
Wired network
If you have a wired network, initialize it on boot using standard Linux commands
in your bootscripts sequence.
First, check which are your network interfaces typing
ifconfig
You should have a network interface named something like eth0 or enp0s3.
Edit the /System/Settings/BootScripts/BootUp script. If you are using DHCP,
just add this:
dhcpcd eth0 &
If you have a static network configuration, place commands similar to the
following in BootUp.
The nameserver can be specified in /etc/resolv.conf
(/System/Settings/resolv.conf). To use Google’s nameservers, you can edit
resolv.conf to:
nameserver8.8.8.8nameserver8.8.4.4
Automated login
If you wish to use an automated login, there are several ways to achieve this
goal.
For KDE (or KDM, it also has a configuration which allows you to tweak it a lot)
you can use this:
Open Control Center in administrative mode.
Select Login Manager.
Under the Convenience tab check “Enable auto-login” and select which user
you should log in as.
Click “Apply”.
If you do not use KDE or want a non-GUI based solution, one way is to use
rungetty.
In your inittab file (for example, nano /etc/inittab) find the line which
includes tty1 (it’s your first terminal, the default showing up on login).
Now, you will see agetty in there - change this agetty line to
rungetty tty1 --autologin your_username.
Of course, replace your_username with the user you want to login as.
Using another tty than 1 may be useful too.
Printers
GoboLinux comes with CUPS installed by default.
Audio
Note that ALSA is muted by default, to automatically save and restore changes
done in e.g. alsamixer, add these lines to your boot scripts.
Done: Exec "Storing ALSA settings..."alsactl store
Boot Script Tasks
Your boot scripts can make use of “boot tasks”, which are little service scripts
that can be shipped by programs. A program includes its tasks under
Resources/Tasks, and they’re linked in /System/Tasks. This is roughly
equivalent to the /etc/init.d scripts found in many distributions.
You can launch or stop tasks from the command line, using
StartTask and StopTask.
For example, the following command will load the SSH daemon:
StartTask OpenSSH
Within boot scripts, you don’t need to use these launchers, but you have to add
a parameter indicating whether the task is being started or stopped:
Strictly speaking, a task is simply a shell script put in the appropriate
directory, which accepts start and stop parameters. In this imaginary
example, one could have a file /Programs/Foo/1.0/Resources/Tasks/Foo with
these contents:
#!/bin/sh
case"$1" in
[Ss]tart)
# actions to start foo go here
foo --silly-walk
;;
[Ss]top)
# actions to stop foo go here
killall foo
;;
esac
It’s a good idea to use the above example as a template for tasks you create.
The [Ss] syntax ensures that both start and Start are recognized, which is
nice to avoid typos.
Boot Themes
GoboLinux is flexible enough to offer you a choice of themes to control how your
GoboLinux looks when starting up.
You can select a theme by setting BootTheme=<ThemeName> in
/System/Settings/BootOptions. Available themes include:
CheckList - Shows tasks and others that depend on them, then checks
them off.
Hat - A Red-Hat look-alike: lots of colored [ OK ]s and [FAILED]s
are echoed as things are initialized.
Progress, Progress-II, or Progress-III - Fancy themes that
stress your terminal with tons of escape codes.
Quotes - Prints short random quotes to indicate success or failure of
every initialized item.
Slack - This theme is inspired by the feel of old-school Slackware
boots: no distracting messages, no colors, no special effects.
Check /Programs/BootScripts/Current/Themes/ to see all the available themes.
You can use the TestBootTheme script to see how a boot theme looks like without
actually rebooting your computer. TestBootTheme is described on section Testing
a boot theme.
You can also set the boot theme from GRUB by adding BootTheme=<ThemeName> to
the boot line. This can be handy if BootOptions file specifies a broken or
nonexistent theme, because GoboLinux will not boot without a valid one.
Physically, a GoboLinux boot theme is a single script file located in
/Programs/BootScripts/*<version>*/Themes.
The theme file is loaded by the boot scripts core, and is called once for every
runlevel change. Although interesting stuff can be done in the script body, a
compliant boot script has only to implement the following functions:
ThemeInit
ThemeFile
ThemeBefore
ThemeAfter
ThemeFinish
These functions are the hotspots that glue the theme and the boot scripts core
together.
This section explains how you can create your own boot script theme.
Section “The boot scripts anatomy” already explained that a theme is a single
script file. In fact, if you really want, you can create a theme that spreads
through multiple files (but this is not necessarily a good idea). The point here
is that one file is enough. This file implements a five functions: ThemeInit,
ThemeFinish, ThemeBefore ThemeAfter, and ThemeFile.
So, if you want to create a boot theme for GoboLinux, all you have to do is to
create a script file like
/Programs/BootScripts/*<version>*/Themes/MyVeryOwnBootTheme that implements
those functions (and optionally something in the script body) with all the bells
and whistles you want.
This section describes how each of the obligatory theme functions must be
implemented.
ThemeInit
This, as the name implies, is the standard location to perform initializations.
Below is an example on how you can use the standard $PREVLEVEL variable (from
the Sysvinit init program) to echo some message when system initializes or
goes down.
if [ "$PREVLEVEL" = "N" ]
then echo "GoboLinux is initializing..."else echo "GoboLinux is going down..."fi
ThemeFile
GoboLinux boot scripts work by processing a sequence of files (again, check
section
“Customizing the initialization”
for more details). Before starting to process each of these files, the boot
scripts core will call ThemeFile passing as the first (and only) parameter the
name of the file that is starting to be processed. Needless to say, you are not
obligated to give feedback on what file is being processed (the “Hat” theme,
example, does nothing in its implementation of ThemeFile.
A very simple example implementation of ThemeFile follows.
function ThemeFile() {
echo "Entering file '$1'..."}
ThemeBefore and ThemeAfter
These functions wrap the execution of commands. ThemeBefore runs before a
program is executed and ThemeAfter, as expected, afterwards.
ThemeBefore is given two parameters: an identifier and a message. The
identifier is a numeric id so you can match calls to ThemeBefore and
ThemeAfter. Likewise, ThemeAfter is given two parameters, the identifier and
a numeric result code, indicating success (zero) or failure (other values).
If your theme supports only sequential booting (ie, does not use Fork and
Wait to parallelize the execution of the boot tasks), you can ignore the
identifier – most themes do, as sequential boots are more common and that makes
the themes simpler. On parallel boot, however, programs can end in a different
order than they were started; with some escape code trickery, one can represent
graphically the intrincacies of parallel booting (the CheckList theme is an
attempt at that).
Here’s a quick example of ThemeBefore and ThemeAfter:
function ThemeBefore() {
shift # ignore id echo -n "===> $@... "}
function ThemeAfter() {
if [ "$2" -eq 0 ]
then echo "{SUCCESS}"else echo "{ERROR}"fi}
ThemeFinish
The ThemeFinish function is called as the last step in a runlevel switch
(after everything else was done). Hence, this is the place to add any
finalization code. A common task performed by ThemeFinish is writing to the
issue file, whose contents are displayed on the screen just before the login
prompt. The issue file name is passed as the first (and only) ThemeFinish
parameter.
The following example shows a sample ThemeFinish implementation that just
writes an issue file that clears the screen.
function ThemeFinish() {
clear > $1 echo "Welcome!!" >> $1}
Testing a boot theme
Fortunately you don’t have to reboot your computer to test every feature you add
to your boot theme. The TestBootTheme script is your friend. Just run it
passing your boot script name as a parameter:
TestBootTheme MyVeryOwnBootTheme
This will simulate a boot procedure with lots of things getting executed. Some
of them will be quiet, some will echo a lot of text, some will succeed, some
will fail… Just press enter when it ends up at the “login” prompt to finish.
If you don’t give it a Theme name, it will output the list of available Themes
from /Programs/BootScripts/Current/Themes/ instead.
Of course, this script is also useful to see how the various boot themes are, so
that you can choose which one is your favorite.
Note
Some themes may not display correctly in an
Xterm/Konsole/other graphical terminal, or with a non-standard console font.
It’s probably best to run TestBootTheme in the same environment you boot in!
GoboLinux Scripts
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).
All command-line options have to be passed first, before other types of
arguments (file names, package names, etc).
In other words:
FooScript -m Foo
works, but
FooScript Foo -m # WRONG! Switches must come first.
does not.
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).
Note
Many of the restrictions above are actually
implementation limitations. “Fixing” them is not a high-priority in the project,
but patches to lift this restrictions are welcome. See
/Programs/Scripts/Current/Functions/OptionParser if you’re curious.
Subsections of GoboLinux Scripts
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 hyphens (as in --foo, --bar).
Order of Command-Line Arguments
All command-line options have to be passed first, before other types of
arguments (file names, package names, etc). In other words,
FooScript -m Foo
works, but
FooScript Foo -m # WRONG! Switches must come first.
does not.
Switches taking arguments
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.
Do not conglomerate
Each option should be passed in a separate token, even when in short mode. If
-a, -b and -c are options for an imaginary FooScript, then
FooScript -a -b -c blah.txt
is correct, but
FooScript -abc blah.txt # WRONG! Options must be separated.
is not.
Help
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).
GoboPath
This script is used everywhere inside many scripts. It exports shell variables
such as $goboExecutables, $goboUsers, $goboKernel, and so on, which
contains a string specifying where in the file system these entries are
(/System/Index/bin, /Users, /System/Kernel, and so on).
For example, in the Scripts package, within the bin/ subdirectory are files
such as ScriptFunctions or SuggestUpdates, among others. These source
GoboPath via:
. GoboPath
This is normally within the Scripts package, at bin/GoboPath. The whole
GoboLinux hierarchy is kept as referential prefix in that file. The variable
$goboPrefix keeps track as to where GoboLinux is mounted at.
Let’s avoid hardcoding things, sourcing this file and using these variables
makes the world a better place :-)
Guidlines for script authors
This section documents the coding style used in GoboLinux shell scripts.
It’s important to note that not all scripts follow these guidelines, because of
historical baggage (some of the scripts are older than GoboLinux itself).
Patches to correct the non-conformities are welcome.
Indentation and block organization
A few rules of thumb:
Three spaces for indentation. Avoid joining do and then in the same line
with ;, instead put it on a line by itself, aligned with for, while or
if.
Prefer using if rather than idioms like && { }, but apply your common
sense.
Be generous in you use of quotes whenever referring or defining variables,
and the ${x} syntax when merging variables inside strings.
Bear in mind that esac is ridiculous.
When doing weird stuff such as functional-like programming with eval, hide
it in a pretty function to pretend it is a bit more readable. Eventually we
might make a Functional module. By now, Map() is defined in the Array
module.
It’s hard to believe, but the only shell module containing GoboLinux-specific
stuff is the one aptly called GoboLinux. Keep that in mind when submitting
functions for inclusion in one of the modules.
Names
The idea in the naming convention is to orthogonally describe scope and purpose
of each name. We define “local scope” as names that are specific to a given
script, and “library scope” as names defined in Scripts modules such as
GoboPath, ScriptFunctions or one of the imported
function modules.
These are the guidelines:
Function names have underscores between words
Example: local_function, Library_Function
Variable names do not, they’re just connected
Example: localvariable, LibraryVariable
Library names (for functions and variables) have capital letters
Example: Library_Function, LibraryVariable
Local names (for functions and variables) are in all-lowercase
Example: local_function, localvariable
All-uppercase variables are reserved for standard Unix usage
Example: PATH, LD_LIBRARY_PATH
Configuration variables used in .conf
files start with the script name in
lowercase, resulting in a case style similar to that used in Java variables
Example: compileRecipeDirs, editKeymapLayout
GoboHide
To simplify the users’ view of filesystem, GoboHide conceals legacy unix
directories such as /usr, /lib, /sbin, and /etc, which contain links to
files placed elsewhere under The GoboLinux Filesystem
Hierarchy.
GoboHide works by hooking directory read operations directly in the root of the
problem: since every readdir() call is translated and performed by the kernel,
we have added a list which is kept in kernel, checking every readdir()
operation. If the current inode being read is stored in this list, then it
simply doesn’t get copied onto the destination buffer, which should be returned
to the user.
The user’s interface to the GoboHide ioctl’s is through a userspace tool, called
gobohide, and has the following options:
gobohide --help
gobohide: Hide/Unhide a directory
-h, --hide Hide the directory
-u, --unhide Unhide the directory
-l, --list List the hidden directories
--version Show the program version
--help Show this message
In order to hide a directory, one would need to run gobohide with -h, passing
the target entry. A subsequent ls will not show the hidden entry, then:
ls /
Depot Mount System bin etc proc sys usr
Files Programs Users dev lib sbin tmp var
gobohide -h /usr
gobohide -h /etc
ls /
Depot Mount System bin lib sbin tmp
Files Programs Users dev proc sys var
This allows entries to be really hidden from the filesystem. But don’t worry,
this can be only performed by the superuser, and he/she has power to ask the
kernel for the entries being hidden. This ensures that nothing gets hidden
without the superuser’s conscience:
gobohide -l
Hidden directories:
/etc
/usr
And the best of it all: you can still access your files inside these hidden
entries, and even bash would tell you that files exist in these directories:
if [ -f /etc/fstab ]; then echo "okay"; fiokayls /etc/zshrc
rwxrwxrwx28 /etc/zshrc -> /Programs/ZSH/Settings/zshrc========================================================
28 in 1 file - 7614808 kB used (96%), 388760 kB free
GoboHide currently supports hiding entries on any mounted filesystem. Because it
is implemented at the level of the Linux virtual filesystem, it is independent
of specific filesystems.
Steps of the compile process
Normally, you shouldn’t need to compile “manually”, i.e., without using the
Compile tool. However, it is possible to manually run
the same commands that Compile uses.
Compiling programs in Linux is typically a three-part process: prepare the
sources with ./configure, compile them with make, and install the compiled
program with make install.
To this process, Gobo adds a source configuration step to target the GoboLinux
directory structure, and after the install phase, a step that symlinks the files
from the application directory under /Programs to /System/Index. It is this
last step that makes programs “visible” to the GoboLinux system.
PrepareProgram is a wrapper to the first step
described above. SandboxInstall is a wrapper to
the third step, ensuring safe execution of make install.
SymlinkProgram performs the final operations
that integrate the new program into the system.
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.
Passing a program name and version number is mandatory. These names are the ones
used in the directories under programs. For example,
PrepareProgram --tree Foo 1.0
(the --tree switch) creates the directories /Programs/Foo/Settings,
/Programs/Foo/1.0, /Programs/Foo/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 much closer.
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
<additional-options>).
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 autoconf. PrepareProgram tries to
detect if a non-autoconf configure script accepts at least the --prefix
option, and uses it.
In short, PrepareProgram can be considered a
wrapper to configure. Instead of running, for example,
cd foo-1.0./configure --with-shared=yes
you’ll run
cd foo-1.0PrepareProgram Foo 1.0 -- --with-shared=yes
SandboxInstall
Strictly speaking, if everything were configured correctly you could simply run
make and make install, and all files would be installed under the
appropriate subdirectory under Programs/.
To ensure this happens is to guarantee the modularity of the software
installation.
To prevent any possibility of files being copied elsewhere in the directory tree
than the target under /Programs, GoboLinux conducts the install step in a
“sandbox” that is isolated from the rest of the filesystem.
SandboxInstall constructs a container for
make install. It uses a sandbox provided by the
FiboSandbox script, which configures custom
permissions for an allowed set of paths to a special user,
fibo. On systems with a UnionFS backend (such as
FunionFS, UnionFS-FUSE or OverlayFS), the sandbox is provided by the alternative
script UnionSandbox. Installation then runs
confined to a sandbox, with no permission to write anywhere but the few places
SandboxInstall allows it to, such as
/Programs/Foo/Current and /Programs/Foo/Settings. Therefore, no files can be
installed in “random places”. A typical call to
SandboxInstall looks like this:
The final step in the compilation of a program is performed by the
SymlinkProgram. This is the script responsible
for creating the symbolic links under /System/Index.
The second argument is optional. If no version number is specified, the one
linked as Current will be used. A commonly used command-line parameter is -coverwrite, which tells it to overwrite any existing symlinks in case of
conflicts (the default action is to preserve the existing links in order to not
affect previously existing applications). To integrate a program Foo into the
/System structure, overwriting any links, you would type:
Symbolic links play a major role in a GoboLinux system, but some programs don’t
behave as expected when they are used. This section lists the files that cannot
be symlinks.
“That is the reason why /System/Settings is not /System/Index/Settings: it does
not only contain links, by definition (or, better put, by necessity)” – Hisham
Muhammad
/System/Settings/sudoers
The configuration file for sudo must be a regular file. If it is not, sudo
will complain and do nothing.
/System/Settings/passwd and friends
The settings files used by the Shadow package are quite interesting.
Theoretically, they can be symlinks, but there is a caveat: utilities like
useradd don’t just modify these files; they remove and recreate them as regular
files. Hence, in practice, they cannot be symbolic links.
Sandboxing under GoboLinux
The build system in GoboLinux uses sandboxing to ensure that all the
filesystem writes during the software install phase are limited to an
appropriate part of the filesystem. GoboLinux 016 ships with two different
sandbox implementations.
UnionSandbox is a modern implementation which uses
file system unions to achieve isolation. It is the default sandbox installer.
FiboSandbox is a fallback method used when a union-filesystem implementation
is not available in the running kernel. It sets up an isolated environment and
commands are run by a special user (named fibo) without root privileges.
During the installation phase of the software build process, most build systems
call the install program to copy files to their destination directories with
the proper ownership and attributes. install belongs to the CoreUtils
package.
Since user fibo lacks authority to change file ownership, the link at
/System/Index/bin/install points to a wrapper script in the Scripts package.
Under UnionSandbox, this wrapper script translates the superuser name if
necessary and calls real_install, a symlink to the CoreUtils install
utility, passing along the modified arguments.
Under FiboSandbox, the wrapper discards change-of-owner directives before
calling real_install.
Replacements for standard commands
GoboLinux has its own replacements for a few standard commands like su and
make. The reasons for making a replacement ranges from adding necessary
functionality (su) to making prettier output (make).
While having these “replaced programs” is not a problem in itself (in fact, most
provide enhanced functionality which adds to the GoboLinux experience), it’s
important to point out these differences here so that you can know what’s going
on with these perhaps unexpected behaviors.
The replacements are provided by several different packages. All except
install are handled by making an alias in the shell initialization scripts.
This way, you can easily disable the alias and restore the original version of a
program, if you so wish. They can be often found in their own subdirectory
Resources/Wrappers inside the program directory.
su - aliased to Su in the Shadow package to handle names other than root as
super user
sudo - aliased to Sudo in the Sudo package to handle names other than root
as super user
top - aliased to htop in the Htop package
make - aliased to ColorMake in the Scripts
package to produce colorful output
info - aliased to Info in the Pinfo package
man - aliased to Man in the Pinfo package
install - install in CoreUtils has been renamed to real_install with install
in the Scripts package as a wrapper (see section Sandboxing under
GoboLinux for a detailed
explanation)
which - the Scripts package provides a “which” script which resolves
symlinks in the path of the returned program, so that it indicates the
/Programs path the binary refers to.
Aliases enabling “enhanced replacements” such as Htop and Pinfo are set in the
Environment section of these packages. This way, if you want to stick to plain
top and/or info, all you need to do is to remove (or just not install) these
replacements.
Recipes
Recipes are directions to Compile on how to configure,
build, and install a particular software package.
where <arch> represents one or more optional architecture directories named
i686/, x86_64/, arm/, ppc/, etc.
Package Naming Guidelines
If the program name already has capitals (e.g. XFree86, LyX, Qt) use it
exactly as is.
If the name is all lowercase or inconsistent (for example, different forms
in the README), our set of capitalization rules apply.
If the application uses hyphens or underscores in the name, follow it
exactly.
GoboLinux packages should never have spaces in their names. “Acrobat Reader”
should become “AcrobatReader”, not “Acrobat_Reader”.
There should never be two package names differing only in capitalization.
Package names differing only in capitalization should be considered to be
two versions of the same app.
The NamingConventions script applies these
rules and several heuristics to generate a suitable GoboLinux package name from
an input.
The Recipe file
The Recipe file contains a series of directives using shell assignment and shell
function syntax. Supported directives presented below, divided into categories:
A minimal recipe will have at least two directives, one specifying how to get
the source (such as url) and recipe_type to tell what is the method to use
when building it.
Subsections of The Recipe file
Getting the Source
Source archives may be downloaded from static urls or from various version
control systems. In the case of a static url, a size and md5sum should be
included for verification.
The following Recipe options control this phase - all
these options are valid for all recipe types:
Static URLs
url=<url>
Note:
For Sourceforge URLs, use the variable $httpSourceforge, as in
url=$httpSourceforge/<project name>;/<filename>;
Example:
url=$httpSourceforge/xmule/xmule-1.8.2.tar.bz2
Similarly, use $ftpGnu, and $ftpAlphaGnu, for downloads from GNU’s ftp
servers.
urls=(<array of urls>)
If the Program has multiple source packages, you may specify a list of them. If
a partial file exists, resumption is attempted. FTP transfers are always
performed in passive mode.
mirror_url=<url>
mirror_urls=(<array of urls>)
URLs to be used, in case the URLs listed in url/urls fail. Multiple mirrors
may be specified. For sets of URLs, each mirror needs to specify the same number
of URLs.
The name of the package file containing the program’s sources. If not specified,
it is assumed to be the same as the final part of the URL, after the last slash.
If urls is used instead of url, files is expected to contain the same
number of entries as urls. All of them are unpacked relative to the same
directory by default. To change this behaviour see unpack_files
below.
file_size=<size>
file_sizes=(<array of sizes>)
This is the file size(s), in bytes, of the packed archive(s) (e.g. foo.tar.gz)
as reported by ls -l.
Specify the CVS server and repository to be used. Note that cvs, svn and
url are mutually exclusive, since you should be either fetching from SCM or
getting a tarball.
Some server configurations require additional options to be passed to the cvs
command. You shouldn’t normally need this command, but it is available in case
the documentation of the project you’re checking out instructs you to give
special options to cvs.
cvs_options is a synonym to cvs_opts.
cvs_password=<password>
Password to log into the cvs server.
cvs_checkout_options=<string added to cvs checkout operation>
Some configurations require additional options to be passed specifically to the
cvs checkout command, such as for getting a snapshot from a specific date.
Normally, you shouldn’t need this command.
cvs_rsh=<string>
Specify a value for the CVS_RSH variable (see cvs documentation for details). If
unset, ssh is used by default.
svn=<SVN server>
svns=(<array of SVN servers>)
Specify the Subversion server and repository to be used. Note that cvs, svn
and url are mutually exclusive, since you should be either fetching from a SCM
or getting a tarball.
Similarly, specify an URL for checkout from a Git, Mercurial, Bazaar server,
respectively.
Recipe Types
Supported recipe types (also known as modes), to be given as argument to
recipe_type:
configure
recipe_type=configure
is used for Programs based on “configure” scripts,
(autoconf or not.) Some options are only relevant for configure:
configure_options=(<array of options>)
Flags to be passed to the configure script. These flags are passed in addition
to default flags detected by PrepareProgram
(such as --prefix and --sysconfdir on autoconf-based configure scripts), unless
the override_default_options declaration is used.
autogen_before_configure=yes
Use it if you need to run ./autogen.sh in order to generate the configure
script.
autogen
The program to run for the above. Defaults to autogen.sh.
configure=<program name>
By default the configure script is assumed to be called configure. Use this
variable to override this value. Remember that the current directory during
execution will still be the one set by the dir variable, even if a directory
path is given (as in the second example below). If the behavior you intended is
for Compile to cd to the unix directory and run its build sequence there,
use dir instead.
Examples (only one applies at a time):
configure=Configure.gnu
configure=unix/configure
cabal
recipe_type=cabal
is used for Programs based on Cabal, the package manager for Haskell. Some
options are only relevant for cabal:
cabal_options=(<array of options>)
Flags to be passed to the Cabal configure operation.
These flags are passed in addition to default flags detected by
PrepareProgram (such as –prefix) unless the
override_default_options declaration is used.
runhaskell
Specifies the method of invoking Haskell to perform a Cabal-based compilation.
The default is runhaskell.
cmake
recipe_type=cmake
is used for Programs based on CMake. Some options are
only relevant for cmake:
cmake_options=(<array of options>))
Flags to be passed to the CMake configure operation. These flags are passed in
addition to default flags (such as -DCMAKE_INSTALL_PREFIX).
cmake_variables=(<array of assignments>)
Variables to be defined in the environment during the execution of cmake.
makefile
recipe_type=makefile
is used for Programs based on Makefiles. No options
are relevant only for makefile.
meson
recipe_type=meson
is used for Programs based on Meson. Some options are
only relevant for meson:
meson_variables=(<array of assignments>)
Variables to be defined in the environment during the execution of meson.
python
recipe_type=python
is used for Programs based on Python Distutils. Some
options are only relevant for python:
python_options=(<array of options>)
Array of options to be passed to the Python Distutils build script. This works
similarly to the configure_options array.
build_script=<name>
Specify the same for the Python build script. If none is given, Compile tries a
few default ones, such as setup.py.
scons
recipe_type=scons
is used for Programs based on SCons. Some options are
only relevant for scons:
scons_variables=(<array of assignments>)
Variables to be passed to scons.
xmkmf
recipe_type=xmkmf
is used for Programs based on X11 Imake. No options are
relevant only for xmkmf.
manifest
recipe_type=manifest
is used to directly copy appropriate files from the
archive into place. Some options are only relevant for manifest:
manifest=(<array "file:dir">)
Specify which files should be copied over, and to where. Destination is relative
to target.
only depends on other Recipes. All included recipes are
built relative to the same installation prefix. Some options are only relevant
for meta:
include=(<array of recipes>)
In a meta-recipe, this array holds the list of recipes that should be built to
constitute the complete program. Recipe names should be in the format
App--1.0. The order of the entries in the array is significant, because it is
the order in which the recipes are built.
Note
Be careful with
the order, because re-building a meta-package that’s already installed may cover
up ordering problems.
part_of=<parent>
Indicates that this recipe is generally included as part of a meta-recipe.
Unless Compile is called with -i/--install-separately, the Program will be
installed into the parent Program’s directory. Implies keep_existing_target.
update_each_settings=yes
In meta-recipes, Compile only calls UpdateSettings for the meta-recipe and not
for its sub-recipes. Set this variable to override this behavior and have
UpdateSettings called in every sub-recipe.
Other directives
compile_version=<version-number>
Valid modes: all
The version number of Compile used to create this recipe.
environment=(<array of variables>)
Valid modes: all
Environment variables to be applied to the shell where the compilation takes
place. Each entry of the array must be in the format variable=value.
Example:
environment=(
"PYTHONOPTIMIZE=2")
uncompress=no
Valid modes: all
Used for urls where the files are going to be used directly. Not a common
option.
unpack_files
Valid modes: all
Possible values:inside_first, contents_inside_first, dirs, files_in_root.
Relevant when files=(more than one file to download) is used, or when a single
archive has “loose files” without an enclosing directory.
By default, all entries in files are unpacked in the same directory. This flag
can be used to override this behavior. inside_first tells it to unpack
files[0] and then unpack all subsequent files inside the resulting directory.
contents_inside_first tells it to unpack files[0], then unpack the remaining
files, and move the contents of the resulting unpacked dirs into the first
directory.
dirs tells it to use the directories explicitly specified in the dirs array
as destinations for each file.
For example, if files is (foo.tar.gz bar.tar.gz) and foo.tar.gz contains
foo/1 foo/2
and bar.tar.gz contains
foo/3 bar/4 bar/5
The default unpacking behavior, without redefining dirs explicitly, generates:
foo/1 foo/2 foo/3 bar/4 bar/5
unpack_files=inside_first generates
foo/1 foo/2 foo/foo/3 foo/bar/4 foo/bar/5
unpack_files=contents_inside_first generates
foo/1 foo/2 foo/3 foo/4 foo/5
Using dirs, virtually any path structure can be used. Since the first entry in
the dirs array is special, it is not used by unpack_files. If any of the
dirs entries contains the value of the target array, the
keep_existing_target is implied (it can still be explicitly overridden in the
recipe, but then the user might delete the data that was just unpacked).
Using files_in_root, Compile assumes files are stored in the archive without a
directory. A directory is created so that files are unpacked inside it, avoiding
scattering files in $compileSourcesDir (typically /Data/Compile/Sources).
dir=<directory>
dirs=(<array of directories>)
Valid modes: all
Indicates the directory to cd into after the package is unpacked. If not
specified, the name of the package file (stripped of its extension) is assumed.
If dirs is used instead of dir, dirs is expected to contain the same
number of entries as urls. The first entry in the array is special: the
compilation method is applied only on the first directory. To compile multiple
packages into a single program, use meta-packages (is_meta). The usage of
dirs affects the way files are unpacked. See unpack_files for details.
docs=(<array of filenames>)
Valid modes: all
A list of filenames, relative to the program’s sources root, of files to be
copied to the program’s doc/ dir (or doc/$app/ for meta-packages). Wildcards
are supported but must be single-quoted. Note that some default names such as
README*, AUTHORS and TODO are automatically fetched.
Example:
docs=(
'docs/*.html')
create_dirs_first=yes
Valid modes: configure, makefile
By default, Compile only generates directories in the target location right
before the installation step. This is useful for the –no-install option (see
the Compile reference entry). Unfortunately, some
programs fail during the configuration of compilation step if the target
directory does not already exist. Use this entry to appease those programs.
keep_existing_target=yes
Valid modes: all
When set, it will not ask the user if they want to erase the contents of the
$target (if any) prior to compiling the program. This is implicitly set if the
dirs array contains any reference to target. See unpack_files for details.
build_variables=(<array of assignments>)
Valid modes: configure, makefile, scons
An array used when redefining variables for the first execution of make
Variables to be passed to make install. See build_variables.
make_variables=(<array of assignments>)
Valid modes: configure, makefile
Variables to be passed to both make and make install. A shorthand to avoid
having to set everything twice, once in build_variables and then again in
install_variables.
makefile=<makefile name>
Valid modes: configure, makefile, xmkmf
By default the makefile is assumed to be called Makefile. Use this variable to
override this value. See the note in configure for observations about
directory names given in variables of this kind.
The target to be used when calling make or equivalent build script/program to
build the program. More than one target may be given at a time, separating them
with spaces in a single declaration (you must use quotes).
The target to be used when calling make or equivalent build script/program to
build the program. More than one target may be given at a time, separating them
with spaces in a single declaration (you must use quotes).
Compile should skip the install phase, and only do the build run. That is,
for Makefile-based recipes, it should run make only once.
needs_build_directory=yes
Valid modes: configure
Some programs like Glibc recommend that a directory is created and used as a
working path during the execution of configure and make. Use of this variable is
transparent to other relative paths in other variables (such as configure),
but be aware that this special build directory will be active as a working
directory during the hook shell functions, instead of dir.
needs_safe_linking=yes
Deprecated
Valid modes: all
This option was used in older versions of the Scripts package to ensure that
some critical programs were symlinked into the /System/Index hierarchy in a
single step.
override_default_options=yes
Valid modes: configure, python, scons
Compile chooses some options by default according to the specified target type.
In configure recipes, it passes some standard autoconf options to the configure
script; in python recipes, distutils options for the Python build script; in
scons recipes, some standard options passed in invocations of scons.py. Use this
option to disable those options and have your own options (given in
configure_options or python_options) overwrite instead of append the option
list.
post_install_message="message"
Valid modes: all
A message to display to the user after installation.
sandbox_options=(<array of options>)
Valid modes: all
Additional options to be passed to
SandboxInstall. This is typically used to
expand the sandbox to allow additional directories in special situations (such
as the installation of kernel modules). Avoid using this option as much as
possible, and make sure you know what you’re doing when you do use it.
Example:
sandbox_options=(
"--no-sandbox")
symlink_options=(<array of options>)
Valid modes: all
Additional options to be passed to
SymlinkProgram. This should be used sparingly,
in order to remedy unusual situations (the FreeType package used it to avoid a
XFree86 conflict which affected the proper functioning of the system). Avoid
using this option if possible; there are almost always better alternatives.
Example:
symlink_options=(
"--conflict overwrite")
unmanaged_files=(<files>)
Valid modes: all
Files to be installed in an unmanaged way to system locations such as
/System/Variable. One cannot install files under /Programs using this array.
Basically, unmanaged files are used to place files outside a program’s $target
directory, and are to be used only when no real alternatives exist. That is, you
should not use this array to install files under /usr just because the
recipe’s makefile define it as the default install location (this can be fixed
by changing the makefile variable defining it to $target).
Good examples of such files are kernel modules, which can’t be linked but need
to be actually present under /System/Kernel/Modules.
Besides the declarative variables, recipes can also contain imperative commands,
in the form of bash shell functions. This is the order the functions are called
for each recipe type:
Note
pre_patch will not be called if there are no patches.
configure:
pre_patch()
patch, if any
pre_build()
configure
make
pre_install()
make install
pre_link()
symlink
post_install()
cabal:
pre_patch()
patch, if any
cabal configure (affected by $runhaskell and $cabal_options)
pre_build()
cabal build (affected by $runhaskell)
pre_install()
cabal install (affected by $runhaskell)
symlink
post_install()
makefile:
pre_patch()
patch, if any
pre_build()
make
pre_install()
make install
pre_link()
symlink
post_install()
manifest:
pre_patch()
patch, if any
pre_install()
copy files
pre_link()
symlink
post_install()
python:
pre_patch()
patch, if any
pre_build()
python setup.py build
pre_install()
python setup.py install
pre_link()
symlink
post_install()
scons:
pre_patch()
patch, if any
pre_build()
scons.py
pre_install()
scons.py install
pre_link()
symlink
post_install()
xmkmf:
pre_patch()
patch, if any
pre_build()
xmkmf
make
pre_install()
make install
pre_link()
symlink
post_install()
Private shell functions
For shell functionality to be shared, for example between sub-recipes of
different architectures, it is possible to define additional shell functions in
the recipe. Their names must be prefixed with private__.
Use flag hooks
Additional shell functions using_<flag>() will be run for each use flag flag
which is set. Do not do anything in such a function which depends on time of
execution. Instead, use using_<flag>_<hook>(). For instance,
using_gtk_pre_build() is run at the time specified above, in the event that
the gtk use flag is set.
Since version 1.12.0, Compile supports a new set of hooks. These hooks can be
used to override any of the steps in the compilation process, and are available
to all recipe types. As with the “old” hooks discussed above, the new hooks
shouldn’t be necessary for most recipe types, but they are useful for cases in
which the compilation process needs to perform nonstandard steps.
In order of invocation, these are the new hooks:
do_fetch()
do_unpack()
do_patch()
do_configuration()
do_build()
do_install()
If any of these hooks are defined in your recipe, Compile will call it instead
of performing the standard corresponding step for the recipe type you are using.
So, for instance, if your recipe needs to perform the installation step in some
nonstandard way, your recipe should include something like this:
do_install() {
# ... your code for nonstandard installation goes here ...
}
Notice that this will not perform the standard configuration steps. If you
need to perform some nonstandard steps in addition to the standard steps, you
can call the default Compile functions from your own hook. The function that
performs the default installation step for recipes of type manifest, for
instance, is called manifest_do_install(). Using it would look like this:
do_install() {
# Perform the regular installation (for recipes with manifest type)
manifest_do_install"$@"# Perform some additional, nonstandard steps
# ... some ...
# ... nonstandard ...
# ... installation ...
# ... steps ...
# ... here ...
}
Dynamic variables
Dynamic variables
Compile automatically creates variables that can be used in the functions.
System variables
To help you in recipe writing, Compile gives you the following run-time
variables to use, each referring to a specific filesystem hierarchy’s member.
Thus, if you’re writing a recipe for some program which accepts configure
options and for which you need to manually specify a library path, you can use
the $goboLibraries variable like
The same applies to the remaining as well, depending on specific program’s
needs.
Program variables
For every recipe there will always be variables for the program prefix as well
as variables for the settings directory and the variable directory for the
program.
$target
$settings_target
$variable_target
For the recipe for Foobar 2.1 those variables will have the values of
$goboPrograms/FooBar/2.1, $goboPrograms/FooBar/Settings and
$goboPrograms/FooBar/<b></b>Variable respectively.
Dependency variables
There will also be variables for every dependency listed in the Dependency file.
If for example Foo 1.2 is listed as dependency, the variables will be called
$foo_path
$foo_settings_path
$foo_variable_path
Note
Note that these variables will point to the latest installed version of
Foo, instead of the version listed in the Dependency file.
Also note that special characters will be replaced with underscore. If, for
example, GTK+ is listed in the Dependency file, the variable will be called
$gtk__path, and Tcl-Tk will be $tcl_tk_path.
Patches
Patches are applied in filename order, with the -p1 option. Creation by
diff -Naur old_dir new_dir
or
diff -Nau old_file new_file
works well. They should be named 01-explanation.patch, where the initial
numbers increase in the order for patches to be applied, and explanation is a
short title giving some inkling of the patch’s purpose. Additionally, the first
few lines of the patch (before the
--- foo/1.0/file.bad
+++ foo/1.0/file.good
lines) should contain an explanation of why the patch is necessary. GoboLinux
avoids patches to add features or optimizations; patches should fix compilation
or installation, or true bugs.
Dynamic patches
These patches are modified by Compile prior to being applied. They should be
named 01-explanation.patch.in. Dynamic variables may be
used, prefixed with the string @%Compile_ and postfixed with %@. Such
variables include (where the Program being compiled has some dependency Foo):
@%Compile_target%@
@%Compile_settings_target%@
@%Compile_variable_target%@
@%Compile_foo_path%@
@%Compile_foo_settings_path%@
@%Compile_foo_variable_path%@
Resources/
The Recipe subdirectory Resources/ can contain various metadata. These files
are copied to /Programs/Foo/Version/Resources upon installation. All these
files are optional except for Dependencies and Description.
BuildDependencies
This file lists dependencies which must be present to successfully compile the
Program. They may include compilers or build tools. The format is the same as
Dependencies, below.
Informational file about which versions of dependencies were actually linked
against when compiling.
Defaults/
This is a directory which may contain, in Defaults/Settings, the default
contents of the /Programs/Foo/Settings directory. The contents of this
directory will be reconciled with the currently active settings, if any, by
UpdateSettings. The original defaults will
remain in /Programs/Foo/Version/Resources/Defaults, so that a user may revert
to them as necessary.
Defaults/ may also contain a subdirectory Variable/. These files are copied
to /System/Variable/, if not already present.
Dependencies
This file lists programs which should be installed for this Program to work
properly. The format is like
The tags such as [lame] specify Use Flags, optional
dependencies which affect the compilation of the package, if present.
When the range string (i.e., =, >=, etc) is omitted, the dependency
resolution algorithm assumes it to be >=.
The exact algorithm for complex dependencies is specified in
CheckDependencies but allows for a sequence
of options separated by | (or) each of which is a sequence of versions
separated by “,” (and). Precedence is left to right. Thus:
GCC < 4.0.0 | >= 4.1.0, != 4.1.2 | ICC > 2.0.0
means a GCC version less than 4.0.0 or a GCC version greater than 4.1.0 but not
equal to 4.1.2 or an ICC version greater than 2.0.0. See the code for
CheckDependencies for the exact algorithm.
Dependencies to language-specific package managers can be fulfilled using the
Aliens subsystem, using the syntax
AlienType:alien_package, as in the examples above.
Note that there are limitations in version handling for Aliens, as it depends on
the Alien provider and the package manager itself:
This file contains information of interest to humans regarding the program. A
typical example is
[Name] GCC
[Summary] The GNU Compiler Collection
[Description] The GNU Compiler Collection contains frontends for C, C++,
Objective-C, Fortran, Java, and Ada...
[License] GNU General Public License (GPL)
[Homepage] http://gcc.gnu.org/
Environment
This file contains environment variables which should be set for this program,
as bash assignments. For example, the Firefox recipe has
These contain hints for UpdateSettings on when to overwrite, delete, or skip
updating of certain settings. See [[Hints File]].
PostInstall
A bash script which is executed by Compile (or
InstallPackage) after installation. This is for
one-time actions which should not be associated with any stage of the
compilation or installation process, but run after the Program is symlinked.
They are kept separate from the Recipe file so that they are retained in binary
packages which may be distributed.
Requirements
These list conditions that must be met on the system, but which do not entail an
action unless they’re not met. The only implemented requirements so far are
required_users and required_groups.
Entries in required_groups can have a gid parameter, as seen in this example:
required_groups=(
"users""yes gid=90125")
Individual entries in required_users, on the other hand, can have uid=<num>
and groups=<name[,name]*> options, as in:
Files in this subdirectory are boot script
tasks, linked to System/Tasks. These are
roughly equivalent to the /etc/init.d scripts found in many distributions.
Note that files under System/Tasks/ should be marked as executable! Otherwise
they will fail to execute during boot time!
Wrappers/
This subdirectory contains scripts which are typically GoboLinux-specific
wrappers for commands in the installed package. They may call the real program
with options or environment appropriate for a GoboLinux system. They are linked
into the /System/Index/bin directory along with the normal binaries.
Use Flags
Note
Although Use Flags are fully functional, currently - due to
increased maintainance - they are rarely employed in our recipes.
Use Flags are a way to affect the compilation of a Recipe based on
the Programs installed on a system and the user’s preferences, without having to
edit the Recipe explicitly. Different configure options may be passed to the
program being compiled, and additional hook functions may be run by Compile,
depending on which flags are activated. Flags may be activated by the presence
of installed dependencies, or explicitly by the user.
Flags are lower-case alphanumeric plus underscore, and should be named after
what they do - the other program, tool, hardware, or functionality they enable,
with any other characters stripped out if necessary.
Example names would be python, ipw2200, gtk.
Enabling Use Flags
Flags are enabled in three ways. The first is through the global default flag
set, in /Programs/Scripts/Current/Data/SystemUseFlags.conf. At the moment,
this set is empty, but it will probably end up populated based on what is used
for packages and the ISO. The second is the local flags, set in
/System/Settings/UseFlags.conf. Finally, the USE environment variable is
read for flag specifications. It is intended that this be used for single
Compile runs, such as for testing recipes, and not to set flags for your system
(use UseFlags.conf for that). Later flag specifications overwrite earlier
ones, both in the order listed above and within the files.
A flag specification has the format (-|+)<flag>[ program1[ program2 ...]]. +
enables the flag, - disables it, and providing a space-separated list of
programs after the flag makes that specification apply only to those programs.
Only one flag specification should be included on each line, and everything
after a # is ignored as a comment. An example file for clarity:
+foo # Enable foo globally. This text is ignored.
-bar
+bar FooBar
This enables the foo flag globally and disables bar, but then enables the bar
flag for only the program FooBar. If the last two lines were the other way
around, bar would be globally disabled again. A special specification is -*.
This disables all flags, and is probably most useful in the environment
variable.
The environment variable takes a space-separated list of flag specifications
(rather than newline), so it accepts a special syntax for the specifications,
with @ instead of a space when listing programs to go with a flag. It takes
the ugly syntax because it’s likely to be by far the least common way of using
it. The same set of flags from above could be applied with:
USE="+foo -bar +bar@FooBar"
Use Flags in Recipes
Flags should be listed in the
Dependencies or
BuildDependencies
file in the same manner as the existing cross/!cross flag:
FooBar >= 1.2 [foo,bar]
Flags are separated by commas, and treated as a disjunction - the dependency
will be enabled if and only if at least one of the listed flags is enabled. If
the cross/!cross flag is specified, it must be the first flag listed
(technical limitation; may be lifted in time).
If a flag has no associated dependency, first consider whether it is necessary
at all, or whether support should just be enabled by default. If the flag is
necessary, it should be listed at the end of the Dependencies file as an entry
without a corresponding dependency:
FooBar >= 1.2 [foo,bar]
[baz,quux]
Dependency-free flags may be necessary when associated with hardware, or when
there is some lengthy compilation, large filesize, or mutual incompatibility
associated with them.
Within a Recipe file, the with_<flag> variable may be set for the common case
of adding a configure option:
This will add the value of the variables to the most common configuration array
for the recipe type. For configure, this is configure_options; Other options
are: python, python_options; makefile, build_variables; scons,
scons_variables; cmake, cmake_options; cabal, cabal_options. In the case
where more complicated changes are needed to enable support, there is a function
using_<flag>() available:
This example does the same thing as the with_gtk one above, but the function
can alter other variables as well. It should not alter code, execute scripts,
move files, or apply patches; that is what the flag hook functions are for. Each
of the existing hook functions (pre_link, pre_patch, pre_build,
pre_install, post_install) has a corresponding using_<flag>_<hook>()
function:
using_gtk_pre_build() {
rm -rf *
}
These are run through Run_Hook and so are sudoed the same as the bare hooks
(for the moment). This may cause problems if you create files or directories
from the hook, so keep it in mind (it applies to all hook functions, but it
should be noted especially too). If necessary, you can unsudo yourself with
exec sudo -u "$SUDO_USER" -H env SUDO_OK=1 $0 "${@}". That won’t affect
anything other than the currently-executing hook, so it should be safe.
In most cases, dependencies are autodetected by configure correctly and no
change to the Recipe file will be necessary. In that case, the with_<flag>
variables should not be used only to convey redundant information, and the
flag should just be listed appropriately in Dependencies. Note that this means
that unlike Gentoo’s, our flags are not exclusive: their support may be compiled
in even if the flag is disabled, if the dependency is installed and autodetected
correctly. Compilations using ChrootCompile will not experience this effect, as
the dependency will be left out of the chroot environment.
This means that in the ideal world of well-behaved software, the Recipe file
itself should need no modification at all. Complex or less well-behaved software
will inevitably end up with longer and more complicated recipes, but in most
cases they should be concise and simple.
In all cases, only the variables and functions for flags that are both enabled
and listed in the (Build)?Dependencies file will be applied, and others have
no effect even if the flag is enabled. This avoids looping through many
inapplicable flags several times during the Compile process.
The flags enabled for a given compilation are saved into Resources/UseFlags in
the installed program directory. This enables tools such as Freshen to display
which flags have changed state since the last installation of a given program,
or find programs that could benefit from recompilation.
Use Flags in Tools Development
Flags are accessed from the shell through the UseFlags script, which takes
either a program name or a recipe directory as its first argument. The latter
method is preferred where possible, because it will read the Dependencies file
and limit the flags to only those listed there; giving just a name will include
all flags that would be enabled for that program (including global flags that it
doesn’t use at all). With only one argument, it will output the list of flags to
standard output, one per line, suitable for iterating in a script or saving to a
file. If called with no arguments, it will do the same for only global flags.
Given a second argument of a flag to test, the script returns true if the flag
is enabled, and false otherwise. If the -v option is specified, it will also
output a message giving the state of the flag.
From Python, the module is named UseFlags and may be imported as usual. The
most important method is UseFlags, which takes an (optional) program
parameter, which can also be either a recipe directory or a program name. It
returns a frozenset of the enabled flags. The return value is cached, so the
method may be called repeatedly with the same arguments without much penalty.
Another useful public method is potentialFlags, which takes only a recipe
directory and returns a frozenset of all the flags that could possibly be
enabled for that recipe. Freshen uses that to provide output on which flags
could be enabled, modeled after emerge, only without the ugliness. The other
methods should be treated as private.
Subsections of Use Flags
Available Use Flags
aclavahi# use avahi for bonjour support
bonjourcursescyrus_sasldbusgnomegnome_vfsgnutls# use gnutls for ssl
gstreamergtkgui# enables gui regardless of what toolkit is used.
ldaplibgnomelibgnomeuimeanwhile# use meanwhile for sametime support
mononetworkmanagernss# use nss for ssl
oggopenssl# use openssl for ssl
pampangoperlqt4rtl#right-to-left text support
sametimesqlitesslstartup_notificationtheoratcltkx11 # enabled graphical interface
Once the recipe is done and compiled, a packed version of it will show up in
/Data/Compile/PackedRecipes (or the location specified in
/System/Settings/Compile/Compile.conf.
The GoboLinux developers encourage you to contribute your recipes, so that the
community can benefit.
To send a recipe for inclusion into the main Compile tree, just run
ContributeRecipe <program name> to submit it for review.
Setting up Compile.conf
We only need to do one thing here, add your name to Compile.conf (for credits
on recipes you may make). Open Compile.conf in a text editor such as nano:
nano /System/Settings/Compile/Compile.conf
On the 2nd line of text, there should be a line for the setting
compileRecipeAuthor. Uncomment it (remove the leading #), and enter your
name between the double quotes.
If you have any other recipe store URLs that you want to use (friends or your
other machines), add them to the getRecipeStores list.
Then save the file and exit nano (Control+O, Enter, Control+X).
Updating old recipes
When a recipe for an older version of a given package already exists, you don’t
need to run MakeRecipe again. Instead, use
NewVersion with the package name and version to
create a new recipe starting with the previous recipe contents. For example:
NewVersion GCC 4.4.4
This command will fetch the latest GCC recipe, create a new subdirectory
called 4.4.4 inside /Data/Compile/Recipes/GCC and will replace the package
version in $url by 4.4.4.
You can also give the full URL for the package sources:
If the version of the package has not changed, and only minor recipe updates are
needed, NewVersion will not work as it will not
copy the same version of a recipe over. In this case,
EditRecipe is the tool to use.
Creating new recipes
If you are writing a recipe from scratch, the “Recipe Format
Specification” documentation will prove
useful.
Naming new recipes
One important, but often overlooked aspect of creating a recipe is naming it.
There are guidelines and tools to ease this process, but nothing beats common
sense really: keep in mind that the name you’re giving to the recipe is the name
that will show up under /Programs and in the binary package name. Pick names
that won’t look “out of place” in a GoboLinux setup.
You usually don’t have to worry a lot about this: Compile and related tools
attempt to do their best to do this job for you, suggesting a name when one is
not explicitly given. But if you spot that it messed up, please abort
compilation and give it a good name as a parameter.
What’s a good name? One that follows our set of package naming guidelines:
The app authors are sovereign about the capitalization, if they define it.
Examples are: XFree86, LyX, Qt.
If the capitalization is undefined (ie, all-lowercase) or inconsistent (for
example, showing up in different forms in the README), our set of
capitalization rules, as defined by the
NamingConventions script, apply.
Applications are sovereign in defining their usage of hyphens and underscores
to separate words in their names, when they are consistent.
Packages should never have spaces in their names. For example, use
“AdobeReader” as the name, rather than “Adobe Reader” or “Adobe_Reader”.
There should never be two package names differing only in capitalization. The
GoboLinux scripts refer to package, program and recipe names in a
case-insensitive manner.
The set of rules are defined in
NamingConventions and deal with detecting
common prefix and suffix patterns, such as “Tools” and “Utils” and
vowel-consonant heuristics.
When a program name is not explicitly given to Compile (e.g., if it assumes it
from an URL), it passes the inferred name through
NamingConventions. In recent versions, some
rules are enforced even in explicitly given names – one of them is that all
program names must start with a capital letter.
MakeRecipe
In this example we’ll make a recipe, starting from the source code for a program
on your computer. We’ll use joe, a text
editor (console based). This is my first recipe, and it is now in the main
Compile tree.
Based on the filename of the URL, MakeRecipe
detects that the program it is compiling is called joe (which, after a run of
the NamingConventions script, becomes Joe),
and that the version is 3.1.
Note
In case it didn’t, you could have passed it explicitly as
parameters:
MakeRecipe should now report that it has downloaded
the sources, and found that it uses autoconf. Which is a good thing, as that
means there is very little work to be done on our part. So now we compile and
install the package on our machine.
Compile joe
Wait a few minutes, and Joe will be compiled and installed on your system.
When you create a new recipe for a program that’s not yet available in the
GoboLinux recipe, please consider contributing it to the community! (See section
“GitHub Contributor Workflow” for
details.)
TODO: Compile‘ing progams that don’t use autoconf, ones that escape the
sandbox, etc.
Meta Recipe
Writing Meta recipe is like putting small things inside some larger container.
For example consider the following meta recipe:
# Recipe for version 1.4.5 by Hisham Muhammad, on Wed Jan 23 01:28:21 BRST 2008
# Recipe (MakeRecipe) for Audacious by Andre Detsch <detsch@gobolinux.org>, on Wed Nov 30 15:01:27 BRST 2005
compile_version=1.8.2recipe_type=meta
include=(
"Audacious-Itself--1.4.5""Audacious-Plugins--1.4.4")
Where two packages (Audacious-Itself and *-Plugins) are being regrouped
behind 1 “bigger” recipe called Audacious. So with meta recipe you can have
lots of small recipes regrouped in one big recipe. It simplify installation and
can help too in some case with stubborn project that don’t get along immediately
with Gobo’s directory layout. Thus creating a meta recipes can help porting
quickly a project in one big chunk (all the parts will be installed into the
same prefix), before making it nicer and modular later.
Share your recipes
Share your recipes with the Gobo community! Recipes you create or update will be
located in /Data/Compile/Recipes. Consider using a text editor to write a
Description file for your recipe before you share it.
To share your recipe, use this command:
ContributeRecipe <program name>
ContributeRecipe will submit a Pull Request on
GitHub so that the project maintainers can review it and merge it. Please note
that you will need a valid account at github.com in order to contribute recipes.
Compile has built-in support for applying patches distributed with recipes.
There are some things that should be considered when creating a patch for an
application. First of all, if the patch is generic, consider sending it
upstream, to the original project, as well. If that is done, here is how one
should do to get the patch working with Compile.
Patch structure
Compile applies the patch from within the source directory with the -p1
option, stripping one directory from the patch’s search path. This is to ensure
that the patch is appliable without editing even if the recipe is updated. The
patch should therefore add one level to the source directory in the path. An
example taken from the rlocate recipe, created with diff:
This diff should then be in a file, say 01-root_to_uid.patch, wich is placed
in the Rlocate 0.4.3 recipe directory. Of course the filename should be
somewhat descriptive to what the patch does. The filename should also be
prefixed with a number, which ensures that the patches are applied in the
correct order, as there can be a number of patches, some of them being applied
to the same source file.
Creating a patch
To create a patch you need the edited source and the “clean” source, then use
diff to create the patch. To create the patch in the example above I used
cd /Data/Compile/Sources
diff -Naur rlocate-0.4.3 rlocate-0.4.3.new > 01-root_to_uid.patch
where rlocate-0.4.3.new was the directory holding the edited source. This may
work if you only have one type of change made. But if you made several different
edits and want them in different patches one can specify the exact file to
‘diff’ or you can make a full diff and edit the resulting file, spliting it into
smaller patches.
Converting patches
Perhaps there are already patches for the project, but they have the wrong path
in them. You can experience that the patches wont apply, even though they are
made for the specific application and version you are trying to Compile.
Either you can edit the patches and add or remove directories to the patch (more
precisely to the rows string with +++ and ---,
--- rlocate-0.4.3/doc/rlocate.html 2006-01-19 10:04:52.000000000 +0100 in the
example above), so that there are exactly one directory above the source
directory. This can be tedious if it is a big patch. Then an easier way is to
apply the patch to the source and make a diff between the patched source and a
“clean” copy, just as when you create a new patch.
Dynamic patches
Sometimes you want to add paths to the patches that are dependent on the host
system the application is installed on. Instead of adding the path statically to
the patch Compile has support for dynamically created patches. By placing the
suffix .in, e.g. 01-root_to_uid.patch.in, on the patch you tell Compile
that it should parse the file and generate the patch 01-root_to_uid.patch,
with certain strings replaced with values dependant on the system. The same
variables used in
recipes can be used
in patches but prefixed with the string Compile_ and padded with @% and
%@. So, for example, if rlocate depended on the application foo, the
variable used in recipes to reference foo’s installation directory would be
$foo_path and therefore the string used in patches to reference this path
would be @%Compile_foo_path%@. Below are valid variables for target
application as well as directories belonging to the dependency foo:
Binary recipes are used to install vendor-supplied precompiled binaries of
software. They are usually created using the manifest recipe type, and have
_bin suffixed to their version.
The Compile tool can handle numerous types of packages, each of them with a
different build technique.
When MakeRecipe is invoked, it downloads the
program’s source, uncompresses it and tries to detect what kind of build system
it uses. And, surely, there are some packages on which
MakeRecipe cannot detect that. This is when the
user’s interaction is needed, and some manual modifications on the Recipe must
be done.
As presented in the Compile section, Compile handles
compilation of programs according to a few number of “recipe types”. For each
type, there are valid declarations that you can specify, to adapt the behavior
of Compile to the needs of the program that is about to be compiled. The full
list of declarations is at Appendix “Recipe format
specification”. Let’s see some of the
main options for each type:
configure recipes
These are autoconf-based packages, and are indicated with
recipe_type=configure. The most common variation in recipes of this type is
the need to pass additional flags to the configure script. You can do so with
the configure_options flag, like this:
Keep in mind that by passing explicit flags to configure, you are affecting
the dependencies of the package. Ideally, the configure script should be
able to detect what’s available in the system and enable or disable features.
Much progress in this area has been made in the last few years, especially with
Pkgconfig, but still some programs require
flags to be passed explicitly.
In configure-based recipes, Compile uses
PrepareProgram to detect if some standard
parameters such as --prefix are supported by the configure script. If the
program does not support these parameters and
PrepareProgram detects them incorrectly, you
can use override_default_options=yes to have configure use only the
options given by you in configure_options.
Another occasionally necessary flag is autogen_before_configure=yes. Some
programs distribute the necessary input files for generating configure (such
as configure.ac or configure.in) but do not ship the generated script, only
a builder script autogen.sh. Using this flag, autogen.sh will be executed as
a first step.
If configure or autogen.sh have non-standard names, you can explicitly
provide them with configure and autogen, like this:
configure=configure.gnu
autogen=gen_all.sh
If present at <architecture>/Recipe, an architecture-specific Recipe file is
sourced in addition to the base Recipe file. Variable assignments in it will
override earlier ones, so to append to a variable, you must do so explicitly,
e.g.
Since “compileprogram” recipes also run make, most of the observations about
“makefile” recipes, discussed below also apply.
makefile recipes
These are packages that use Makefiles directly. You can easily spot programs
of these type: when the program’s installation instructions just tell you to run
make from command line without a previous step, they are recipes of this kind.
For this kind of recipe, Compile runs make twice: the “build” run and the
“install” run. A few programs require only one run; you can disable either with
do_build=no and do_install=no.
In “makefile” recipes, you will always have to pass at least one additional
option in the recipe, to tell the Makefile to use the
/Programs/program-name>/version> directory. If we’re lucky, the Makefile has
one main variable that controls the installation prefix. Variables of this kind
are usually called PREFIX, DESTDIR, INSTDIR… you’ll have to look inside
the Makefile to find out. Remember that the installation prefix is set by
Compile as the target shell variable. To give make variables, we can
either use build_variables and install_variables, which give options to the
“build” and “install” runs of make, or just make_variables which passes
options to both runs. Their use is similar to that of configure_options.
make_variables=(
"DESTDIR=$target")
Sometimes, paths are defined in several variables of the Makefile. No problem:
If there are no variables of this kind in the Makefile, that is, if the
Makefile has hard-coded locations in its installation rules, then
unfortunately you’ll have to patch the Makefile (and possibly the source code,
look for references to paths like /usr using grep).
Like with configure and autogen, if the makefile uses a different name from
the standard (Makefile), you can pass it explicitly using the makefile
variable:
makefile=GNUmakefile
python recipes
The “python” recipe type is used for programs using Python Distutils as a build
system. Since it is so recent, there is a number of minor variations floating
around (some packages use setup.py, others use build.py, etc.) – “python”
tries to detect these variations where possible, but ultimately there are flags
to specify special cases explicitly.
The name of the build script can be given with build_script. You can control
the two runs of the Python build script using the same options as “makefile
recipes” (do_build=no and do_install=no to disable runs, build_target and
install_target to name the runs). Custom options can be passed with
python_options. Again, override_default_options=yes can be passed to skip
auto-detected flags if needed.
xmkmf recipes
This is for recipes based on the old “xmkmf –>–> imake” system historically
used by the X Window System. This is being phased out in Xorg 7.0 in favor of
GNU autoconf.
scons recipes
This is for recipes based on SCons.
manifest recipes
“Manifest” recipes are used for programs that just need to copy files over. The
manifest array-style entry lists colon-separated pairs, indicating source file
and target destination, relative to target. (See “Recipe format
specification” for details).
Binary Recipes
Binary recipes (recipes that install precompiled binaries of software, rather
than compiling it from source) are permitted but discouraged where possible.
These recipes should have _bin suffixed to the version number as a marker, for
exampleFirefox 1.36.0_bin, even where there is no corresponding source
recipe.
Source recipes are preferred where possible, as these allow optimisation and
bugfixing, but binaries are acceptable in some circumstances.
In general, a binary recipe will be accepted if it meets one of the following
criteria:
The software is only available in this form from the vendor. Sun-JDK is an
example of this.
Compiling the software cleanly is not possible or plausible on GoboLinux
yet. Programs using the Maven build system are an example of this.
The vendor provides prebuilt binaries in addition to the source, and:
The software is sufficiently large for compilation to be a large task
with little gain (Firefox, Chromium, LibreOffice)
The vendor binaries are customised in some fashion, or multiple parallel
products from the same source are built with different tasks (the
various Eclipse builds: -Java, -C++, -EE, etc). In this case, the
program name should be specific to the type of build: Eclipse-Java,
Eclipse-SDK.
The software requires a copy of itself to build, and isn’t shipped with the
default system. GHC is an example of this. In this case, the binary version
should be named differently: GHC-Bin installs the pre-built GHC, which can
be used to compile the source GHC.
A source recipe would present some difficulty, and nobody has made one yet.
Each program is assessed individually, and some may be accepted outside these
guidelines. In any case, it never hurts to ask or submit a recipe if you’re
unsure.
Guidelines for binary recipes
Submitters should append an extra _bin string to the application’s
version. This is the adopted convention to identify binary recipes.
Everything specific to a given architecture shall be inside its arch subdir.
This includes url=, file=, file_md5=, file_size= and any functions
dealing with specific tarball contents that might change from one
architecture’s tarball to another. MD5 sums are especially important for
binary recipes are they are used to assess the validity of the installed
data, which could not be verified as usual by looking at the sources. Make
sure the file_md5 entry exists.
Distribution license must be filled in Resouces/Description. If the
license is unknown, Resources/Description should set it as
[License] Other (or the license name as appropriate), and a file named
Resources/COPYING should contain the license in question. “Known licenses”
are those found in these
OSI list or the
FSF list.
GitHub Contributor Workflow
This page is intended to document the new GitHub workflow for contributing to
GoboLinux.
Compile.conf and attribution
Fire up your favourite editor, open
/Programs/Compile/Settings/Compile/Compile.conf and edit the
compileRecipeAuthor key as appropriate:
# set up proper attribution for GitHub pull requests
compileRecipeAuthor="A. Random Contributor <somebody@some-email-address>"
If you are not comfortable using your real name, using a nick/alias is also
acceptable.
For more options, check out the dedicated
Compile.conf page.
Create a GitHub pull request using ContributeRecipe
In short, ContributeRecipe does the following:
Creates a fork of the Recipe tree on the user’s GitHub space
Creates and checks out a branch on said fork
Commits the modifications to the given Recipe in said branch
Sends a GitHub PR to the GoboLinux project
Set up git to use the correct user name and e-mail
Git needs to be set up to use the same git user.name and user.email
combination as the one used in Compile.conf in the compileRecipeAuthor= key.
cdgit config --global user.name "A. Random Contributor"git config --global user.email "somebody@some-email-address"# list the git configuration
git config --get user.name
git config --get user.email
Check for changed files in the Recipes repository
It is considered good practice to double check the changes about to be committed
by ContributeRecipe:
cd /Data/Compile/Recipes
git status
# if existing files have been modified, you can run:
git diff
Run ContributeRecipe
Once the attribution is correctly set up and the changes have been double
checked, it’s time to run the ContributeRecipe script.
The script has been designed such that all there is to the contribution process
is to supply a name and a version to ContributeRecipe:
# cd into /Data/Compile/Recipes if you haven't already
sudoContributeRecipe ExampleRecipe 0.0.1
Note
Please ensure that you use a GitHub account where your
name/alias and e-mail address has been added as a verified GitHub identity when
using ContributeRecipe.
ContributeRecipe will prompt for your GitHub username and password a couple of
times (see note about 2FA below), do its magic and the end result will be
a nice GoboLinux GitHub Pull Request which will hopefully get merged.
Configure hub to use GITHUB_TOKEN for authentication
As part of its first run, ContributeRecipe will call both git and hub
(hub is used to interface with the GitHub API). During this first run, hub
will create a GitHub API token and save it in ~/.config/hub.
Note
If you have 2-Factor Authentication (2FA) enabled, git
and hub expect you to supply the oauth token that was saved in ~/.config/hub
and NOT your normal password when authenticating.
For convenience, hub can be set up to re-use this token for authentication
with your GitHub account by exporting the environment variable GITHUB_TOKEN in
your shell’s configuration file (by default, this is ~/.zshrc):
exportGITHUB_USER="<the value of your github username>"exportGITHUB_TOKEN="<the value of oauth_token in ~/.config/hub>"
To verify that GITHUB_TOKEN works as expected, this example might prove
useful:
. ~/.zshrc
echo "${GITHUB_TOKEN}"echo "My first gist sent via hub" | hub gist create
How to recover from mistakes/failures and start over
If something goes awry during a ContributeRecipe run, you might need to delete
the remote branch for subsequent ContributeRecipe attempts to be successful.
Once you know the name of the branch that was created, it’s as simple as firing
off a git push <remote> --delete <branch> command.
Typically, for remote branches the necessary command will look something like
git push origin-fork --delete submit-<recipe>-<version>.
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.
If you use a local tarball, be sure to have the tarball
placed at /Data/Compile/Archives. Also make sure you know whether you have a
recipe locally or not, if you ie do not have access to the www on that machine.
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.
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.
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:
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 /Programsapplication_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
makePrepareProgram -t Foo 1.0SandboxInstall Foo 1.0SymlinkProgram Foo 1.0
NAME
ApplyVariables -
SYNOPSIS
ApplyVariables
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
-o, --open <entry>
Opening mark. The default value is '@%'.
-c, --close <entry>
Closing mark. The default value is '%@'.
-i, --identifier <entry>
Add a prefix identifier in the form of '<entry>_' to the opening markup.
Notes:
ApplyVariables processes a file replacing instances of variables marked
with special indicators ('@%', '%@' by default) with the contents of equivalent environment variables.
GoboLinux March 2017 APPLYVARIABLES(1)
This commands augments the existing database for
CommandNotFound suggestions with data from the running
system. In other words, it looks at which executables exist in the installed
system and adds them to the /Data/CommandNotFound.data file from Scripts.
This is useful to improve the quality of the “command not found” suggestions.
Users are encouraged to send patches to Scripts improving the
CommandNotFound.data database.
Executes a command in the background, similarly to nohup, but without echoing
messages to the console by default, and without appending output to a log file.
Syntax: BackgroundExec [options] <command> [arguments]
Available options are:
-h, --help This help
-v, --verbose Run in verbose mode
BootDriver
The BootDriver script should not be run directly from the command line. It is
intended to be specified in the inittab file (/System/Settings/inittab), to
be launched by process 1, init.
BootDriver takes a parameter, indicating which “runlevel” script should be
executed. Here’s a sample inittab with calls to BootDriver:
CheckDependencies
Check dependencies. No decent help yet.
Options:
-t [t1,t2,...]
--types=[t1,t2,...] Sets what kind of packages repositories that can be
searched to match the dependencies.
Default list is set at Settings/Scripts/FindPackage.conf
-s
--add-self= Tell if the program passed as parameter should be
returned too.
Can be set to:
never - do not return the passed program
always - return the passed program
if_required - return the passed program iff type or
version from the program was not passed
as paramater (default)
-i
--install-optional= Install optional dependencies? 'always', 'never', 'ask'
-b
--batch Same as --install-optional=always
-m, --mode= Can be set to:
missing - report matches only for missing packages
updating - report all packages (dependencies from the
passed program) that can be updated
all - report matches for all dependencies, even
it they are already installed
list - only list the dependencies, without printing
matches
convert - convert a Dependencies file of a recipe to
the coresponding Dependencies file for the
compiled binary
-W, --no-web Do not access the internet.
-R
--no-recursive Only the direct dependencies are considered
-B
--no-blacklist Do not skip packages listed at Dependencies.blacklist
--blacklist= List of application names to blacklist
--no-prompt Do not prompt to install anything
--quiet-progress Do not show progress indicator
-f
--file Check for the dependencies listed in the given file.
-p
--gobo-programs= Override default /Programs as path of installed packages
--local-dirs=[d1,..] Where to look for local binary packages. By default,
uses the paths defined at GetAvailable.conf.
In default GoboLinux systems, make is an alias to ColorMake.
Multiple CPUs
Users on dual-core and similar high-end machines may want to take advantage of
existing CPU capabilities. This can either be done via the MAKEOPTS option or by
modifying the simple ColorMake script.
At
makecmd=
Edit the line to i.e.:
makecmd='/bin/make -j5'
About the -j5 part, the rule of thumb is that the number after -j should
equal the number of your cores +1: on a typical dual-core machine, the number
would be 3.
CommandNotFound
Usage: CommandNotFound <command>
Intended to be run automatically from shell hooks.
Compile
NAME
Compile - Build software from GoboLinux recipe
SYNOPSIS
Compile <program> [<version>]
DESCRIPTION
Automated program compilation tool.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
-n, --app-name <entry>
Override application name.
-e, --version-number <entry>
Override version number.
-c, --configure-options <entry>
Options to be passed explicitly to './configure'.
-k, --keep
Keep files if program directory already exists.
-b, --batch
Batch mode: avoid asking questions.
-B, --no-build
Do not build, just fetch the sources.
-I, --no-install
Do not actually install the program.
-W, --no-web
Do not check remote site for recipes, and bypass fetching of archives.
-S, --no-symlink
Do not symlink. Deprecated - use --symlink=no instead.
-l, --symlink <entry>
If symlinks should be created and wether they should be forced on conflicts. Valid
entries are: 'yes' 'no' 'force' The default value is 'yes'.
-T, --no-strip
Do not strip executables.
-G, --no-sign
Do not sign program.
-U, --no-updatesettings
Do not update settings for the program
-M, --no-unmanaged
Do not install unmanaged files.
-L, --lazy
'Lazy mode': cut some corners when rebuilding; debugging aid: do NOT use it for building
packages.
-A, --start-at <entry>
Skip sub-recipes when building a meta-recipe: start include list at given recipe; effec‐
tive only with --lazy; debugging aid: do NOT use it for building packages.
-D, --no-dependencies
Do not try to fulfill dependencies.
-i, --install-separately
If the application is part of a meta recipe, do not install it into the containing
application but install it into a separate directory.
-a, --remove-archive
Remove archive(s) after a successful build
-s, --remove-sources
Remove sources after a successful build
-P, --no-postinstall
Do not run the PostInstall script after installation
-R, --no-requirements
Do not process the Requirements script after installation
(C)2003-2007 by Hisham Muhammad et al. Released under the GNU GPL.
GoboLinux March 2017 COMPILE(1)
Usage: Corrections [options]
Options:
-h, --help show this help message and exit
--dir=DIRECTORY take options from DIRECTORY
--log-name=LOG_NAME name to show in log message
--stdin read options from stdin
--threshold=THRESHOLD
leniency in matching
Scan a file to find the capitalization of a program name.
Usage
DeduceName <file> <name>
The script scans the given file looking for instances of name, and returns which
is the most frequent capitalization used.
Example
DeduceName README gtkglarea
Dependencies
NAME
Dependencies -
SYNOPSIS
Dependencies { [-c] { <package> [<version>] | -d <dep_file> } |
DESCRIPTION
Queries dependencies in a GoboLinux package.
-f <file> }
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
-f, --file
show dependencies of one file only.
-c, --check
check the package's dependency file, instead of generating one.
-r, --reverse
reverse dependency match: indicate who uses a given program.
-a, --all
inspect all files, not only those in 'bin', 'sbin' and 'lib'.
-m, --missing-only
Display missing dependencies only. (check mode only)
-H, --higher-or-missing-only
Display missing dependencies or higher versions only. (check mode only)
-l, --list
List dependency file, if any (generate if not present).
-d, --dependencies-file
Check for the dependencies listed in the given file.
-e, --execute <entry>
Execute the command on each missing/higher. (check mode only)
-b, --batch
Batch mode: avoid asking questions.
-p, --programs <entry>
<dir> to check dependencies against.
-w, --write
Write dependencies to Resources/Dependencies.
-k, --keep-going
Don't quit immediately if any executed program fails. (check+execute mode only)
Notes:
If no version is specified, Current is assumed.
Released under the GNU GPL.
GoboLinux March 2017 DEPENDENCIES(1)
DescribeProgram
DescribeProgram
Returns the description of the program, if available.
-Options:
-a, --update-all downloads all descriptions available at the servers and
cache them locally
-m, --mode=<mode> Output mode: html, terminal or ascii.
-W, --no-web do not try to download remote descriptions if they are not
locally available
Examples of usage:
DescribeProgram gimp
DescribeProgram -W gimp
DescribeProgram -a
NAME
EditRecipe -
SYNOPSIS
EditRecipe [<recipe-url>|<recipe-path>|<program-name> [program-version]]
DESCRIPTION
Fetch a recipe and place it in /Data/Compile/LocalRecipes, chopping its revision number. Calls a text editor on the Recipe file afterwards.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
-E, --no-edit
Do not edit Recipe file, just place the recipe to .
(C) 2006 Andre Detsch. Released under the GNU GPL.
GoboLinux March 2017 EDITRECIPE(1)
FetchArchive
NAME
FetchArchive -
SYNOPSIS
FetchArchive <recipe> [arch-recipe]
DESCRIPTION
Given a recipe, download the files required to compile it.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
-d, --save-directory <entry>
Rename the directory into which the archive is unpacked/files checked out.
-s, --save-to <entry>
Save the files to the given directory
-P, --program <entry>
Program name The default value is 'Bash'.
-V, --version-number <entry>
Version number with revision The default value is '4.0-r1'.
-b, --batch
Avoid asking questions.
EXAMPLES
FetchArchive /K3B/0.10/Recipe
GoboLinux March 2017 FETCHARCHIVE(1)
NAME
FilterColors -
SYNOPSIS
FilterColors
DESCRIPTION
Filter to monochrome.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
Notes:
Piping output through FilterColors removes terminal escape codes (which usually define color, but may have
other uses).
EXAMPLES
FilterColors is usually used through a pipe: some_command | FilterColors
GoboLinux March 2017 FILTERCOLORS(1)
FilterLines
A flexible grep-like tool.
Examples:
cat foo.txt | Filterlines "bla"
shows all lines from foo.txt that contain the regexp bla
cat foo.txt | Filterlines "bla""goob"
shows all lines from foo.txt that contain the regexp bla OR the regexp
goob
cat foo.txt | Filterlines "bla""goob" -n "mac"
shows all lines from foo.txt that contain the regexp bla OR the regexp
goob but NOT the regexp mac
shows all lines from foo.txt that don’t contain bla, goob, mac or ops
FindPackage
FindPackage Searches, chooses an occurence and prints where some package (or
recipe) can be found, based only on the program name (case insesitive) or on the
program name and program version.
Options:
-t [t1,t2,...]
--types=[t1,t2,...] Sets what kind of packages can be searched, in the
passed order. Valid types are:
local_package, official_package, contrib_package,
installed, recipe, tracked, all
Using only the first character from any of the above
is also valid:
l, o, c, i, r, t, a
Default types are:
local_package, official_package
Notice that when "recipe" type is used, Compile.conf is
read to set recipe-store locations and local recipes
locations.
--local-dirs=[d1,..] Where to look for local binary packages. By default,
uses the paths defined at GetAvailable.conf.
--force-update Downloads required packages list even if there is a
local copy (cached in /Data/Variable/tmp/Scripts-jroth/cache/) newer than one hour.
-l, --full-list Prints all the occurences that match the passed
parameters, not only the "best".
-n, --newest-on-server Tries to sort the result set by how recently the
packages have been modified on the server.
Automatically enables '--full-list'.
-s, --substring Match packages whose names contains the passed substring.
-W, --no-web Do not try to download anything and don't lists
remote recipes and packages (if not explicitly listed
in '--types='). Overrides '--force-update' and
'--newest-on-server'.
-p
--gobo-programs Override default /Programs as path of installed packages
Examples of usage:
FindPackage kde
FindPackage kde 3.2.3FindPackage KDE 3.2.3FindPackage --types=recipe kde3.2.3FindPackage --types=local_package,official_package kde3.2.3FindPackage -t l,o kde 3.2.3FindPackage --full-list kde 3.2.3FindPackage --force-update --full-list kde 3.2.3FindPackage --types=recipe kde-base3.2.3FindPackage --types=recipe --substring kd 3.2.3FindPackage --types=installed gcc
FindQuick
NAME
FindQuick -
SYNOPSIS
FindQuick <file_to_search> [<path>]
DESCRIPTION
find files.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
Notes:
if <file_to_search> contains "*", it is used directly as an expression for the search. If not, "*" is added to
the beginning and the end. if <path> is not specified, the working directory is assumed.
EXAMPLES
FindQuick "*.c" .. FindQuick # Note the added quotes to avoid shell expansion.
GoboLinux March 2017 FINDQUICK(1)
Usage:
Freshen [ <opts> ] [ <list> ]
Options:
- --binaries, -b - Include binary packages [default]
- --cache-only, -c - Update caches only
- --debug - Enable debug mode
- --downgrades, -d - Include downgrades
- --empty-tree, -e - Behave as though the installed program tree
were empty - include dependencies all the way back
- --excluding, -x - Do not include *list* or anything with a
dependency in it
- --help, -h - Display this help
- --info, -i - Get information on <program>
- --limit, -l <n> - Include no more than *n* updates
- --lower-limit, -L <n> - Skip the first *n* updates
- --no-binaries, -B - Do not include binary packages
- --no-cache, -C - Do not use cached data for /Programs
- --no-downgrades, -D - Do not include downgrades. [default]
- --no-recipes, -R - Do not include recipes
- --no-upgrades, -N - Do not include upgrades
- --recipes, -r - Include recipes [default]
- --shallow, -s - Shallow mode: don't include any upgrades that
aren't strictly necessary. Requires *list*
- --upgrade-system, -U - Upgrade all programs, or *list* and
dependencies if specified.
- --upgrades, -n - Include upgrades [default]
- --verbose, -V - Enable verbose mode
- --version, -v - Show program version
Common options are:
- -U for system updates
- -l <n> to limit the number of updates to a few at a time
- -s to limit the updates to those strictly necessary
- -R to skip recipes and perform no compilation
- -i <program> to get information on <program>
Freshen outputs its update lists in the form:
[IUX] Foo 2.0 1.0
Meaning an upgrade to Foo version 2.0, from 1.0, which is available as both a
recipe and a package.
The mnemonics mean:
I - Installed
U - Upgrade
D - Downgrade (color code: red)
R - Recipe available (color code: green)
B - Binary available (color code: yellow/brown)
X - Recipe and binary available (color code: blue)
Examples:
Freshen
Produce an ordered list of everything that can be updated on the system.
Freshen -R
Produce an ordered list of everything that can be updated on the system using
only binary packages.
Freshen -U -l 5
Update the first five programs on the list.
Freshen -U Firefox
Update Firefox and its dependencies
Freshen -U -x Qt
Update everything except Qt and anything that depends upon it.
Freshen -s Firefox Kopete
Ordered list of upgrades needed in order to upgrade Firefox and Kopete to
their newest releases. Add -U to perform the upgrade.
GenBuildInfo
NAME
GenBuildInformation -
SYNOPSIS
GenBuildInformation <package> [<version>]
DESCRIPTION
Generates the list of packages from the current environment used by a GoboLinux package.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
-s, --store
Store the information in Resources/BuildInformation. Default is standard output.
-a, --all
Search all files, not just standard directories.
Notes:
If no version is specified, Current is assumed.
Released under the GNU GPL.
GoboLinux March 2017 GENBUILDINFORMATION(1
GetAvailable
GetAvailable
Get available packages, recipes and tracked versions.
Options:
-t [t1,t2,...]
--types=[t1,t2,...] sets what kind of packages can be searched, in the
passed order. Valid types are:
local_package, official_package, contrib_package,
installed, recipe, tracked, all
using only the first character from any of the above
is also valid:
l, o, c, i, r, t, a
Default types are:
local_package, official_package
notice that when "recipe" type is used, Compile.conf is
read to set recipe-store locations and local recipes
locations.
--local-dirs=[d1,..] where to look for local binary packages. By default,
uses the paths defined at GetAvailable.conf
--force-update downloads required packages list even if there is a
local copy (cached in /Data/Variable/tmp/Scripts-jroth/cache/) newer than one hour.
-W, --no-web do not try to download anything and don't lists
remote recipes and packages (if not explicitly listed
in '--types='). Overrides '--force-update'
-p
--gobo-programs Override default /Programs as path of installed packages
Examples of usage:
GetAvailable --types=recipe
GetRecipe
NAME
GetRecipe -
SYNOPSIS
GetRecipe [<recipe-url>|<recipe-path>|<program-name> [program-version]]
DESCRIPTION
Fetch a recipe and insert it in the recipes tree.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
-W, --no-web
Do not check remote site for recipes.
(C) 2003-2004 Carlo Calica et al. Released under the GNU GPL.
GoboLinux March 2017 GETRECIPE(1)
Usage: GuessLatest [-s] <version1> [version2] ...
Accepts package names, recipe names or version numbers as parameter
Options:
-h, --help show this help message and exit
-s, --stable try to return a stable version as result
-l, --list returns a sorted list of versions
GuessProgramCase
NAME
GuessProgramCase -
SYNOPSIS
GuessProgramCase <program> [<version>]
DESCRIPTION
Try to guess the case of a program based on the installed packages.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
Notes:
If no version is specified, Current is assumed.
(C)2003-2007 by Andre Detsch et al. Released under the GNU GPL.
GoboLinux March 2017 GUESSPROGRAMCASE(1)
Installer is a program included on the LiveCD to install GoboLinux to your hard
drive. It takes care of basic configuration, package selection, and boot loader
setup. Installer uses a common framework for command-line and GUI interfaces.
NAME
InstallPackage -
SYNOPSIS
InstallPackage <package_file>|<package_dir>
DESCRIPTION
Install GoboLinux packages.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
-b, --batch
Do not ask for confirmation.
--use-contrib
Look in contrib store as well.
-D, --no-dependencies
Do not try to fullfit dependencies.
-I, --no-install
Do not install, only locate and fetch the package. Automatically enables '--keep'
-S, --no-symlink
Do not create symbolic links in /System, just fetch and unpack the package. Deprecated - use --symlink=no
instead.
-l, --symlink <entry>
If symlinks should be created and wether they should be forced on conflicts. Valid entries are: 'yes' 'no'
'force' The default value is 'yes'.
-k, --keep
Do not remove downloaded packages.
-s, --same <entry>
What to do when unpackaging over the same version. Valid entries are: 'keep' 'remove' 'cancel' The default
value is 'cancel'.
-o, --old <entry>
What to do with a previously existing version of a package if found. Valid entries are: 'keep' 'remove' 'ask'
'cancel' The default value is 'keep'.
-u, --unmanaged <entry>
Defines what to do with unmanaged files from package. Valid entries are: 'ask' 'install' 'skip' The default
value is 'ask'.
-C, --no-sign-check
Do not check the signature.
-U, --no-updatesettings
Do not update settings for the package
-W, --no-web
Do not check remote site for packages, and bypass fetching of archives.
Notes:
Default behavior for --same is 'cancel', for --old is 'keep'.
EXAMPLES
InstallPackage Gimp--2.0.5.tar.gz
Released under the GNU GPL.
GoboLinux March 2017 INSTALLPACKAGE(1)
IsExecutable
Returns 0 (success) if the file looks like a Linux executable (starting with a
hash-bang magic or an ELF header), or 1 (failure) otherwise.
____________________________________________________________________________________________________________________________
NAME
list - Create a list
SYNOPSIS
list ?arg arg ...?
____________________________________________________________________________________________________________________________
DESCRIPTION
This command returns a list comprised of all the args, or an empty string if no args are specified. Braces and back‐
slashes get added as necessary, so that the lindex command may be used on the result to re-extract the original argu‐
ments, and also so that eval may be used to execute the resulting list, with arg1 comprising the command's name and
the other args comprising its arguments. List produces slightly different results than concat: concat removes one
level of grouping before forming the list, while list works directly from the original arguments.
EXAMPLE
The command
list a b "c d e " " f {g h}"
will return
a b {c d e } { f {g h}}
while concat with the same arguments will return
a b c d e f {g h}
SEE ALSO
lappend(n), lindex(n), linsert(n), llength(n), lrange(n), lrepeat(n), lreplace(n), lsearch(n), lset(n), lsort(n)
KEYWORDS
element, list, quoting
Tcl list(n)
ListProgramFiles
Gives you the list of files which belong to some program you have installed on
your machine.
Which files belong the current installed version of Wireless-Tools?
ListProgramFiles wireless-tools
or, equivalently:
ListProgramFiles wireless-tools Current
Which files belong to version 28 of Wireless-Tools?
ListProgramFiles wireless-tools 28
Notice how <program> field is not case-sensitive although <version> field
is.
Which files belong to all versions of Wireless-Tools?
ListProgramFiles /Programs/Wireless-Tools
Notice that we passed the program’s directory instead of its name.
NAME
MergeTree -
SYNOPSIS
MergeTree <source> <destination>
DESCRIPTION
Mirrors one directory structure into another.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
-d, --delete
On conflicts, overwrite original file.
Notes:
All files and directories in <source> appear as symbolic links in <destination>
EXAMPLES
MergeTree /Programs/KOffice/Current /Programs/KDE/Current
GoboLinux March 2017 MERGETREE(1)
NamingConventions
NAME
NamingConventions -
SYNOPSIS
NamingConventions <name>
DESCRIPTION
Heuristics to determine a capitalized, GoboLinux-like name.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
GoboLinux March 2017 NAMINGCONVENTIONS(1)
Note that NamingConventions is part of the Scripts package. You can find in
the bin/ subdirectory there.
Here are some usage examples; note that presently NamingConventions appears to
prefer only the program name, so if you have a full remote URL, make sure to
only pass the name of the program towards NamingConventions.
NAME
PackRecipe -
SYNOPSIS
PackRecipe [<program> [<version>]]
DESCRIPTION
Generate "packed recipes", ready for submission.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
-L, --no-lint
Do not verify recipes (not recommended).
-W, --no-web
Offline operation when running RecipeLint (avoid if possible).
Notes:
Given no arguments, this script will take all recipes in
and pack them as Foo--1.0--recipe.tar.bz2 files at .
(C) 2003-2004 Carlo Calica et al. Released under the GNU GPL.
GoboLinux March 2017 PACKRECIPE(1)
Scripts version: 016.01Compile version: 016.01-r1
BootScripts version: 016.01-r1
Glibc version: 2.24Linux-Headers version: 4.7.4Xorg-Lib version: 7.7-r1
GCC version: 6.2.0-r4
Python version: 3.6.0-r5
KDE-Libs version:
Linux version: 4.9.4-r1
--help version:
Installed versions of --help
Compile.conf
# Add your name here so that credit is added to recipes.
#compileRecipeAuthor=""
compileDir="${goboPrefix}/Data/Compile"compileDependenciesDir="$compileDir/Recipes"compileArchivesDir="$compileDir/Archives"compileSourcesDir="$compileDir/Sources"compileRecipeDirs=(
"$compileDir/LocalRecipes""$compileDir/Recipes")
# List Store mirrors here
getRecipeStores=(
"http://gobolinux.org/recipe-store")
# Where GetRecipe places its recipes. Should be in $compileRecipeDirs
compileGetRecipeDir="$compileDir/Recipes"# These specify the source and destination to GenRecipeStore
compileLocalRecipesDir="$compileDir/LocalRecipes"compilePackedRecipesDir="$compileDir/PackedRecipes"# Main free software repositories
ftpGnu=ftp://ftp.gnu.org/gnu
#ftpGnu=ftp://ftp.unicamp.br/pub/gnu
ftpAlphaGnu=ftp://alpha.gnu.org/gnu
httpSourceforge=http://downloads.sourceforge.net
#httpSourceforge=http://voxel.dl.sourceforge.net/sourceforge
UseFlags.conf
# List your use flags, one per line, prefixed with a + to enable
# or a - to disable. Lines starting with # are ignored as comments.
# If a space-separated list of programs is given after the flag specification,
# the specification only applies to those programs.
# Note that if multiple use flags with same functionality is enabled, e.g.
# "ssl", "openssl", "gnutls" and "nss", the default implementation is choosen
# by the recipe author
# Example declaration:
#+foo
#+bar
#-bar foo quux
#-baz
# Generic flags specify a functionality to be enabled, and may list
# several different specific flags that provide it.
# Specific flags are ordered by preference for each generic flag. Only the
# first valid specific flag will be enabled for each generic flag.
ssl: openssl gnutls nss
gui: qt4 qt3 gtk2 fltk gtk1 lesstif
qt: qt4 qt3
gtk: gtk2 gtk1
sql: sqlite mysql postgresql
tui: ncurses
sound: alsa jack pulseaudio arts nas
spellcheck: enchant aspell ispell hspell gnome-spell
file_monitor: fam gamin
rtl: pango graphite
sametime: meanwhile
zeroconf: avahi mdnsresponder howl monozeroconf bonjour rendezvous
ac3: a52dec
diracvideo: schroedinger dirac
xmp: exempi
ldap: openldap
desktop_search: strigi beagle tracker
gadu_gadu: ekg
motif: openmotif lesstif
GenericFlags.conf
Not all directories in the /System/Index hierarchy can be rebuilt using this
tool because it would render the system in an inconsistent state during the
program’s execution.
Examples:
RebuildLinks --shared
RecipeLint
NAME
RecipeLint -
SYNOPSIS
RecipeLint <recipe-file>
DESCRIPTION
Perform all sorts of sanity checks in a recipe.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
-t, --thorough
Perform thorough URL/file testing (don't use cache).
-D, --quick-and-dirty
cut some corners (don't download files, etc; not recommended).
-W, --no-web
fully offline operation (not recommended).
EXAMPLES
RecipeLint Foo--1.0--recipe.tar.bz2
(C)2005-2006 Hisham Muhammad, released under the GNU GPL.
GoboLinux March 2017 RECIPELINT(1)
RemoveBroken
Given a file name, this script verifies if it’s a broken link or not. Being a
broken one, it gets deleted.
This script is very useful when used together with find to find stray, broken
links.
Example:
find /System/Index | RemoveBroken
This is functionally equivalent to
find /System/Index -xtype l -delete
The source code to RemoveBroken can be found
here:
Executes a command with a read-only view of /System/Index overlaid with
dependencies extracted from the program's Resources/Dependencies and/or
from the given dependencies file(s).
Syntax: Runner [options] <command> [arguments]
Available options are:
-a, --arch=ARCH Look for dependencies whose architecture is ARCH (default: taken from
Resources/Architecture, otherwise assumed to be x86_64)
-d, --dependencies=FILE Path to GoboLinux Dependencies file to use
-h, --help This help
-q, --quiet Don't warn on bogus dependencies file(s)
-v, --verbose Run in verbose mode (type twice to enable debug messages)
-c, --check Check if Runner can be used in this system
-f, --fallback Run the command without the sandbox in case this is not available
-R, --no-removedeps Do not remove conflicting versions of dependencies from /System/Index view
NAME
StartTask -
SYNOPSIS
StartTask <task> <options>
DESCRIPTION
Run boot tasks from the command line.
OPTIONS
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
EXAMPLES
StartTask OpenSSH
Released under the GNU GPL.
GoboLinux October 2008 STARTTASK(1)
StopTask
NAME
StopTask -
SYNOPSIS
StopTask <task> <options>
DESCRIPTION
Run boot tasks from the command line.
OPTIONS
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
EXAMPLES
StopTask OpenSSH
Released under the GNU GPL.
GoboLinux October 2008 STOPTASK(1)
SuggestDuplicates
NAME
SuggestDuplicates -
SYNOPSIS
SuggestDuplicates
DESCRIPTION
Check for non-current programs.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
COPYRIGHT
Copyright 2005 MJ Ray. Released under GNU GPL v2.
GoboLinux March 2017 SUGGESTDUPLICATES(1)
NAME
SystemInfo -
SYNOPSIS
SystemInfo
DESCRIPTION
Display some basic system information. Useful for /etc/issue.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
GoboLinux March 2017 SYSTEMINFO(1)
The UpdateKdeRecipe script is assumingly aiding in updating KDE recipes.
It is a component of the Scripts collection and will normally reside under the
Scripts/bin subdirectory.
It was in particular useful for the qt3/kde3 stack several years ago - presently
(Sep 2017) it may need some modifications due to upstream changes to kde.
NAME
UpdateRecipes -
SYNOPSIS
UpdateRecipes [<program>]
DESCRIPTION
Update local recipe list from recipe stores.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
-a, --all
Download contents of updated recipes. By default, UpdateRecipes will only fetch the recipe list and generate
empty recipe directories (except when updating a single program).
-l, --all-latest
Like --all, but only fetch the latest versions of each recipe.
-t, --thorough
Check all availabe mirrors for updates. By default, only the first working mirror (as configured in Com‐
pile.conf) is used.
Notes:
When updating a single program, UpdateRecipes will download all its available recipes. When no program is
specified, UpdateRecipes will fetch the recipe list and populate with directory entries (and download the
recipes only if --all is used).
(C) 2003-2004 Carlo Calica et al. Released under the GNU GPL.
GoboLinux March 2017 UPDATERECIPES(1)
UpdateSettings
NAME
UpdateSettings -
SYNOPSIS
UpdateSettings [<options>] [<mode>] <program> [<version>]
DESCRIPTION
Interactively update settings from defaults in Resources/Defaults/Settings
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
-d, --diffs
When a file has been modified, show differences.
-c, --check
Only check whether current settings differ from the defaults.
-r, --report
Only report whether current settings and defaults differ.
-l, --list
List files that differ between current settings and defaults.
-u, --update
Update settings (default)
Update Modes:
-a, --auto
Update automatically, without prompting the user at any point
-i, --interactive
Update interactively, prompting the user before each change
-q, --quick
Quickly update, prompting only when there are conflicts (default)
(C)2005 by David Smith. Released under the GNU GPL.
Maintained by Dan Charney and the GoboLinux team
GoboLinux March 2017 UPDATESETTINGS(1)
NAME
which -
SYNOPSIS
which <executable>
DESCRIPTION
Display real location of an executable file.
OPTIONS
--terse
Enable terse messages.
--debug
Enable debug messages.
-h, --help
Show this help.
--version
Show program version.
-v, --verbose
Enable verbose mode.
--logfile <entry>
Log all output to specified file.
EXAMPLES
which ls
Released under the GNU GPL.
GoboLinux March 2017 WHICH(1)
