You are reading version 017 of this page. The current version can be found here.
You are reading version 017 of this page. The current version can be found here.
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 OpenSSHWithin 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:
Exec "Initializing OpenSSH server..." OpenSSH StartStrictly 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
;;
esacIt’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.
You are reading version 017 of this page. The current version can be found here.
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:
ThemeInitThemeFileThemeBeforeThemeAfterThemeFinishThese functions are the hotspots that glue the theme and the boot scripts core together.
You are reading version 017 of this page. The current version can be found here.
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.
You are reading version 017 of this page. The current version can be found here.
This section describes how each of the obligatory theme functions must be implemented.
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..."
fiGoboLinux 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'..."
}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
}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
}You are reading version 017 of this page. The current version can be found here.
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 MyVeryOwnBootThemeThis 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.
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!
You are reading version 017 of this page. The current version can be found here.
You are reading version 017 of this page. The current version can be found here.
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.
compileDir="${goboPrefix}/Files/Compile"
compileArchivesDir="$compileDir/Archives"
compileSourcesDir="$compileDir/Sources"
compileRecipeDirs="$compileDir/Recipes"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:
ftpGnu=ftp://ftp.gnu.org/gnu/
ftpAlphaGnu=ftp://alpha.gnu.org/gnu/
httpSourceforge=http://unc.dl.sourceforge.net/sourceforge/The Compile recipe tree is managed by Git. The git repository and the upstream branch are both configurable through the following variables:
compileRecipesRepository=https://github.com/gobolinux/Recipes.git
compileUpstreamBranch=masterA 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"You are reading version 017 of this page. The current version can be found here.
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=15The 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.
defaultLocalPackagesPaths=(
"/Depot/Packages"
"/Mount/SquashFS/Programs"
"/Mount/CD-ROM/Depot/Packages/"
"."
)The URLS from which lists of official binary packages (packed by some core developer) will be retrieved.
officialPackagesLists=(
'http://kundor.org/gobo/packages/official/MANIFEST.bz2'
'http://gobo.calica.com/packages/official/MANIFEST.bz2'
)The URLS from which lists of contributed binary packages (contributed by some user, and placed, without garanties, at our servers) will be retrieved.
contribPackagesLists=(
'http://kundor.org/gobo/packages/contrib/MANIFEST.bz2'
'http://gobo.calica.com/packages/contrib/MANIFEST.bz2'
)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
trackedVersionsLists=(
'http://gobolinux.org/version-tracker/TrackedVersions.bz2'
)You are reading version 017 of this page. The current version can be found here.
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).
You are reading version 017 of this page. The current version can be found here.
In GoboLinux, Fibo is a special user that assists Gobo, the superuser, during
program installation. Fibo is responsible for the
FiboSandbox, he is the only one who is given
access to it.
Fibo is similar to the Unix nobody user, but the fundamental difference is
while nobody never has write access to anything, Fibo is occasionally
granted write permission to selected locations (specifically, during program
installation, to the FiboSandbox and to the
/Programs entry of the program being installed).
In a standard GoboLinux system, Fibo is userid 21 (which is, of course, a
number of the
Fibonacci sequence).
You are reading version 017 of this page. The current version can be found here.
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/sudoersThe configuration file for sudo must be a regular file. If it is not, sudo
will complain and do nothing.
/System/Settings/passwd and friendsThe 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.
You are reading version 017 of this page. The current version can be found here.
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 messageIn 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 varThis 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
/usrAnd 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"; fi
okay
ls /etc/zshrc
rwxrwxrwx 28 /etc/zshrc -> /Programs/ZSH/Settings/zshrc
========================================================
28 in 1 file - 7614808 kB used (96%), 388760 kB freeGoboHide 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.
You are reading version 017 of this page. The current version can be found here.
The GoboLinux port for ARM CPUs has been happening with a focus on the armv5te, having the XScale as optimization target. The entire process of development has been done with the Bootstrap tool, described some sections below, which consists on a menu based interface to select and compile packages. All of this is free software and you’re heavily encouraged to try it, enhance it and join us with the development of GoboLinux for the embedded.
The next sections are going to show you how to download and install the ARM port, pre-compiled packages and how to compile new packages from scratch, using the Bootstrap tool.
In order to make things easier for embedded developers, GoboLinux is currently shipping two versions of the ARM port: one consisting of a small (yet functional) initrd, and another containing the full version, with graphical desktop and tools suited for the end-user.
It’s very common to install the initrd image in the flash and then mount the
bigger image from a NFS server or from another media, such as an SD card. This
is how we’re currently proceeding, and it has been doing quite good. One can
then perform a chroot/pivot_root in the full media, or just union-mount both
images by putting the command in the initrd’s boot script.
The tarballs for the initrd and for the full version can be fetched here:
Alternatively, one can download the ISO image instead, which offers an uncompressed file system created around Rocket-Ridge/Joliet extensions. The following links provide access to the ISO and its checksum, respectively:
In order to uncompress the tarball with the full version, one must to supply the ‘p’ flag to tar, so that permissions are kept. Uncompressing the full version, thus, is done through the following commands:
mkdir GoboLinux-003-armv5te
cd GoboLinux-003-armv5te
tar zxpf /path/to/GoboLinux-003-armv5te.tar.gzGiven that ARM platforms usually need to have their own special kernel image,
there’s no point on shipping one with the distribution. There is, however, an
optional patch used to hide the legacy tree, so that only the GoboLinux tree
appears in the filesystem (/System, /Programs and so on). This patch is
called GoboHide, and it can be downloaded for various kernel releases on its
documentation page.
The installation is pretty much dependent on the platform used, but it’s a common thing to have a bootloader capable of downloading files over the serial port or over the network and storing them at specific locations in the flash. Take a look in the documentation for your platform to check how to update your initrd.
The initrd image is actually an gzip’ed ext3 filesystem, which can be extracted and mounted on your local filesystem. In a GoboLinux system, the following commands are enough to mount it read-write on any distribution:
mkdir -p /System/ARM-SoftFP
gzip -d GoboLinux-003-armv5te.gz
mount -o loop GoboLinux-003-armv5te /System/ARM-SoftFPAt this point, the filesystem will be available at /System/ARM-SoftFP, where
you’ll be able to read and write its contents. It’s important to note the
directory name used as mount point: since the filesystem was all compiled
against that prefix, all symlinks inside the image will be available and will
not be broken, with a few exceptions in the root filesystem.
The major configurable part of the distribution is sitted in /System/Settings.
You’ll probably want to take a look at /System/Settings/NetworkOptions and at
/System/Settings/BootScripts, which holds the bootscripts. The latter has a
file named BootUp, which is the script launched by init at boot time.
There are also tasks, which are simple scripts with start/stop commands.
They are stored at /System/Tasks, where you’ll see files such as GoboHide,
LoadModules, Mouse and Swap. Take a look there if you have something to modify
on these standard tasks.
After finished with the modifications, just leave /System/ARM-SoftFP and
compress the image again with the following commands:
umount /System/ARM-SoftFP
gzip GoboLinux-003-armv5teYou’re now ready to upload your modified filesystem to your platform, according to the instructions provided by your vendor.
There’s a repository for precompiled packages where you can download the available ones. These are not stripped, though. They include headers, static libraries, documentations and all sort of thing that one would expect from a standard package. If you need to reduce their size, please take a look at the shrink scripts inside each program’s directory at Bootstrap’s CVS tree. There are many scripts already written for the available packages, and we welcome new contributions to help us to reduce packages even more.
After the desired packages are downloaded, store them somewhere in your
filesystem and then run InstallPackage <package.tar.bz2>. The InstallPackage
script shipped with the TinyScripts package on ARM is not smart as the one in
the Scripts package, used on the i686 port, though. It doesn’t look for
dependencies yet, so you still need to take a manual look at the file
Resources/Dependencies inside the unpacked program at /Programs. A minimal
support for dependencies is going to be added on the next versions.
Please subscribe to the GoboLinux ARM mailing list (archives) for getting help from our community. You can also visit us on #gobolinux at irc.freenode.net.
The process of creating a distribution from scratch involves many steps which are very error prone. Bootstrap is a tool which concentrates many scripts for these purposes, abstracted in a simple yet powerful menu based interface. It also deals with cross-compilation automatically, so it can be used to create a distribution targetting another architecture or the same one serving your host operating system. (If you’re interested on doing cross-compilation, please take a look below on how to prepare the cross-compiler’s terrain).
In short, Bootstrap is able to either compile new packages, or to start a new port from scratch, performing the following steps:
Create a Gobo directory structure for the new port, populating it with a few
necessary system files. The target directory is defined by
$cross_prefix_dir in the cross config file;
Installation of BootScripts / TinyScripts package;
Compilation of packages selected by the user, running optional hooks defined in some individual packages;
Reduction of the filesystem’s size by running scripts capable of doing:
Automated creation of ramdisk images.
Given that the cross config file had been written, using it is just a matter of
running ./Bootstrap. This command is responsible of fetching descriptions for
the available packages and then opening a menu based interface where the target
platform can be configured. The following snippet shows the available options:
Bootstrap Configuration
Build options --->
Base system --->
Development --->
Fonts and XML parsers --->
Audio --->
Networking --->
X servers --->
Video and graphics --->
GTK suite --->
Misc --->
Desktop --->
Shrink Options --->The first entry allows to select the target platform on which the compilations will be targeted to. Currently, Bootstrap’s build menu presents profiles for SH-4 and ARM processors, allowing a subsequent selection of a specific implementation of the chosen processor. This allows Bootstrap to keep configuration files specific to each platform, such as bootscripts, package selection and so on:
Build options
Cross-Compiling (ARM target) --->
ARM implementation (SiriuStar board) --->
Target profile (Embedded platform) --->
Network interface (DHCP configuration) --->
---
(2.6.16.18) Kernel version for Linux-Libc-Headers package
(GoboLinux) Hostname
(gobo) Super-user nameThis configuration shows that we’re going to create a distribution for an ARM processor. More especifically, we’re targetting it to the SiriuStar board, so any special scripts needed by that board are going to be integrated automatically into the filesystem. A practical example of such profile script is one that needs to read a specific driver’s /proc entry to update the RTC.
Apart from creating a distribution for ARM or SH-4, it’s also possible to create a distribution which will run in the same processor as the one executing the script. So, if you’re running on a x86 and would like to create an embedded version of GoboLinux for the same architecture, it’s just a matter of disabling the cross-compiling feature of Bootstrap:
Cross-Compiling
(X) Native compiling
( ) ARM target
( ) SH-4 targetThe development of Bootstrap also took care of those who’d like to create a distribution to another platform, but which didn’t need to care about space. This situation doesn’t need to count on replacements for the standard GoboLinux tools, neither on the strip of individual files so that the filesystem can fit in the flash or hard disk. The selection of this kind of profile is possible through the Target profile menu, where one of Desktop and Embedded options can be chosen.
Target profile
(X) Embedded platform
( ) Desktop platformOne final step configuring the target’s platform is choosing its network connectivity. Due to the common fact that many bootloaders focused on the embedded allows to boot the kernel with bootp and to assign IPs even before the operating system is up, it might not be feasible to reconfigure the network after the system has booted. To avoid having GoboLinux’ bootscripts to reconfigure the network, it’s possible to disable that in Network Interface:
Network interface
(X) Disabled
( ) DHCP configuration
( ) Manual configurationOne last important option is related to the kernel version on which headers will be available to the filesystem. The generation of the headers is currently done by an external script developed by Linux From Scratch guys, which is capable of removing portions not used by userspace applications. The last version known to work was 2.6.12.
The remaining options are related to the configuration of the hostname and the super-user’s name. The super-user name can later be modified by editing passwd and shadow on the generated filesystem, as there’s a big attention in Gobo community to remove hardcoded references to root in applications.
The selection of packages that will be compiled can be done through the subsequent menus. The menu entries are disposable in a way so that the base packages are always shown first, and optional packages built or linked against them are shown later in the screen.
Selecting them is pretty much straightforward, so only the base system is going to be described here. Many small systems can be created by just using this first menu, so you can start populating your filesystem in small steps, starting with this one.
Base system
Libc implementation (Glibc) --->
[ ] Module Init Tools
[*] BusyBox
[*] LibGCC
[ ] ZLib
[ ] GPM
[ ] GoboHide
[ ] Listener
[ ] Udev
---
[ ] Ncurses
[ ] BashThis setup allows to configure a small environment, where only the BusyBox suite will be available. It already features a replacement for udev (called mdev), so the system is going to be fully functional. The LibGCC package is generated by some libraries taken from by the cross-compiler that will be needed at runtime by some applications. One final note is made to the Libc implementation: if the target filesystem really needs to be that small, uClibc can be used instead of the default, Glibc.
This is one of the more interesting features of Bootstrap. Due to the nature of GoboLinux packages, all files related to a given package are stored inside a unique entry at /Programs. This makes it very easy to cleanup the filesystem and find big packages, and even more to automate this process with the help of per-package scripts.
Making these scripts aware of which files are necessary and which ones aren’t needed to get the package up and running is an easy task to be performed on GoboLinux, and are reflected through the following options in the shrink menu:
Shrink Options
[ ] Remove and shrink as much as possible
[ ] Remove headers
[ ] Remove static libraries
[ ] Remove libtool related files
[ ] Remove pkgconfig related files
[ ] Remove documentation
[ ] Remove backup of the default settings
[ ] Remove internationalization files
[ ] Remove aclocal macros
Removal of symbols (All symbols from executables and libraries) --->
Native language support --->Please note that there will be no automatic cleanup of the filesystem. You must invoke the make shrink command so that it performs a backup of the generated filesystem, followed by the cleanup based on the selected options.
Finished with the menuconfig configuration, Bootstrap is ready to start doing its work. The Bootstrap script automatically invokes make, which on its turn will download, compile and install all packages selected, according to the following snippet:
PrepareTarget: Creating the GoboLinux tree...
PrepareTarget: Populating the device directory...
PrepareTarget: Creating the LibGCC package...
(...)At the end of this process, the filesystem generated will be available at the directory specified at the cross config file (usually under /System), and will be ready for usage on the target platform. Files can always be modified manually after they are generated, as they’re not overwritten by subsequent make calls. The filesystem can then be shared for remote mounting over NFS at boot time, or copied to different medias, depending on your interests and resources available on your platform.
If you’re porting Gobo to an architecture which is not listed by Bootstrap, you
can create a new entry for it by editing functions/Platforms and Config.in
inside Bootstrap’s root dir.
BootStrap can be downloaded as a package or directly from the Subversion repository. The current stable release is 1.1, and it can be downloaded here. SVN snapshots can be obtained in the following way:
svn checkout http://svn.gobolinux.org/tools/trunk/BootstrapSo, do you want to try Gobo on a different architecture? That’s cool, and that’s why this documentation was created for: we want to encourage you to join in the developers’ and users’ corner with interesting experiments.
This documentation is here to guide you on porting Gobo to a new embedded architecture. The steps, examples and tools shown on this document have reached a stable branch, being used in projects such as the Brazilian’s Digital TV research, where a Gobo port to the SuperH has been done, as well as the Gobo ARM port which happened in parallel in another projects.
The remaining sections are going to focus on 2 ways of porting Gobo to a new system: by cross-compiling and by using an existing distribution as a basis to compile packages using the Gobo hierarchy. The latter has not been written yet; see http://www.gobolinux.org/index.php?page=doc/articles/porting_guide for inspiration.
While we try to make porting as easy as possible, doing this kind of task always needs some background on the subject. Cross compiling a whole set of packages and preparing the root filesystem requires that you have an understanding of the boot process, of the manual installation of a kernel image, shell scripts and many more. Reading other chapters of the GoboLinux Documentation Project might help you to acquire some of that knowledge.
Finished with the introduction, let’s make a list of what you’ll need. Firstly, this tutorial assumes that you have a host computer running GoboLinux. The Gobo team has developed numerous tools to help on the automation of the system, such as compiling programs based on simple description files, detecting the latest versions of a given application, enjauling the compile process so that the host system doesn’t interfere in the compilation environment, and so on.
For this reason, the tools developed to aid on the port are based on Gobo’s own infrastructure. After all, since you’re porting Gobo to a new architecture we would at least expect that you’re also running it on your host computer, right?
Secondly, you’ll need a working cross-compiler. Since we’re going to create a distribution from scratch to a different architecture than the one running on the host system, that’s the way we will generate programs to it. There are many cross-compilers ready for usage out there, and some scripts that might help you to prepare your own. The following projects and cross-compilers have been tested and are recommended:
Crosstool: Consists in a set of scripts and patches to generate a toolchain for many architectures, such as Alpha, ARM, i686, IA64, MIPS, PowerPC, PowerPC64, SH4, Sparc, Sparc64, s390 and x86_64. The current toolchains used by Gobo developers were generated by this tool;
CodeSourcery: This is the major source for ARM toolchains, and is one of the leading companies developing the ARM EABI. If you want to get a tested and ready-to-use cross compiler for ARM, this is the place to get one;
uClibc toolchain: If you’re looking for a very small distribution it’s probably better to look at this alternative. The uClibc is a tiny libc implementation which targets devices with small storage capabilities. Please note, however, that this might come with small performance penalty on some applications.
Finally, you’ll need to write cross-compiler rules for the Compile tool.
Compile has the ability to create binaries to different platforms, so there’s a
need to write a configuration file for the one you’re going to use, respecting
the naming convention Cross-<ARCH>.conf, where ARCH will represent the
target architecture. Cross configuration files are stored at
/System/Settings/Compile.
The Compile tool ships 2 sample files for the ARM and SH4 architectures. Let’s give a look into the variables exported by them, taking the ARM rule as reference:
cross_kernel_dir: specifies the path on which the kernel sources for this
platform are found. Since it’s very usual to maintain the kernel for the
working platform on a special directory during development stage, you can do
that and just specify its location here;
cross_kernel_version: for the same kernel, specifies its release, based on
the VERSION, PATCHLEVEL, SUBLEVEL and EXTRAVERSION variables
exported in the Makefile;
cross_kernel_arch: when cross compiling the kernel, one must call
make menuconfig ARCH=*kernel_arch_name. Specify your architecture’s name
under the kernel tree here;
cross_prefix_dir: where in the host’s filesystem the new filesystem tree
will be stored;
cross_toolchain_dir: where in the host’s filesystem the toolchain is
installed;
cross_sys_incdir: path to stdio.h inside the toolchain’s dir;
cross_gcc_incdir: path to stdarg.h inside the toolchain’s dir;
cross_cpp_incdir: C include dirs (is an array) in the toolchain’s dir;
cross_gcc_libdir: path to libgcc.* files in the toolchain’s dir;
cross_libc_libdir: path to libc.* files in the toolchain’s dir;
cross_uname_m: output for uname -m on the target machine;
cross_configure_host: parameter to the configure script when building
applications based on autoconf (-host=target_machine_string). This string
describes the CPU on which the binary generated will run on;
cross_configure_build: parameter to the configure script when building
applications based on autoconf (-build=build_cpu_string). This string
describes the CPU which is doing the cross-compiling;
cross_optimization_flags: optimization flags to be used by the cross
compiler. A useful place to look for available options is the GCC info page;
cross_compiler: prefix to the cross-compiler’s executable files, such as
arm-xscale-linux-gnu-gcc and arm-xscale-linux-gnu-strip.
You are reading version 017 of this page. The current version can be found here.
The idea for this page is to collect and document various FAQs about GoboLinux, that is, frequently asked questions pertaining to the project at hand - especially when encountering problems. It is different to the mailing list in that it should be “more general”, that is, not necessarily tied to any individual person at hand (whereas on a mailing list, you usually have communication from one-to-one user that also eventually becomes forgotten or may have to be asked again at a later time).
That way if a user runs into a problem, or wants to understand this or that about GoboLinux, then this can be used as a “jumper” page to jump to the proper documentation - either within the wiki itself, or as part of a program’s –help option or elsewhere.
The old FAQ can be found here:
https://gobolinux.org/faq.html
But keep in mind that this was written quite a long time ago; a lot of things have changed including who runs/maintains/invests time to keep GoboLinux running and so on and so forth.
The attempt for this FAQ here is to refer to the present GoboLinux - the latter is mostly to dive into history. And who knows which FAQ may be the current one in 5 years from now (2017). :)
(The following subsection is incomplete… I just wanted to get things started going for easy “setup”… please remove this sentence here and the —- once this FAQ has a few more entries answered.)
Q: How do I compile/install a program on GoboLinux?
Q: How do I uninstall a program on GoboLinux again?
Q: What is /System/Index?
You are reading version 017 of this page. The current version can be found here.
A while ago it was announced on the GoboLinux mailing lists that there was work ongoing for a PowerPC port. That was a one-man work (by hisham). It is now fairly complete (my main computer is now an iBook running GoboLinux) but it not as polished for release as the x86 version.
What’s missing:
So, yeah, it is now at a state where you could call it a “half-a**ed-job”, but it works for me. So, to avoid the flamefests we’ve seen on the list, I’m not going to release this until somebody shows up who is willing to work on the missing parts.
I intend to integrate the changes/additions I did to the recipe store on this work, though.
That’s it for now, have a nice day.
You are reading version 017 of this page. The current version can be found here.
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:
. GoboPathThis 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 :-)
You are reading version 017 of this page. The current version can be found here.
Freshen is a console application that checks for
updated GoboLinux recipes and packages, with an output similar to “emerge”
in Gentoo.You are reading version 017 of this page. The current version can be found here.
The Manager program is presently (August 2017) no longer maintained.
More information about it may be provided at a later time here at the wiki.
The old code can still be found here, at the least as of August 2017:
You are reading version 017 of this page. The current version can be found here.
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).
All command-line options have to be passed first, before other types of arguments (file names, package names, etc). In other words,
FooScript -m Fooworks, 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 anotherThese 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 imaginary FooScript, then
FooScript -a -b -c blah.txtis 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).
You are reading version 017 of this page. The current version can be found here.
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.
ColorMake in the Scripts
package to produce colorful outputAliases 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.
You are reading version 017 of this page. The current version can be found here.
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.
You are reading version 017 of this page. The current version can be found here.
The current update process in gobolinux requires super-user privileges. This is sub-optimal.
In the following, a rough sketch of how to remedy this is proposed.
gobo user/group by defaultgobo group during
installation.gobo group to run
system-update related scripts with no password for convenience/Data/Compile/{Archives,Recipes,Sources} are reset to
chown -Rc gobo:gobo and chmod ug+rw on each system-update related script
run, possibly in a function (a script version of which should be part of the
set of commands allowed to run without a sudo password for convenience).root
or gobo – possibly using functions?You are reading version 017 of this page. The current version can be found here.
GoboLinux 016.01 ships with the xf86-video-modesetting driver overriding the deprecated xf86-video-intel driver. Modesetting is noticeably more stable, but it won’t offer acceleration for 2D operations by default.
You will have to recompile the following packages to achieve Gallium-based 2D acceleration on 016.01 systems:
Compile libdrmCompile libvaCompile intel-vaapi-driverCompile mesaCompile xorg-server 1.18.4Furthermore, you will need to modify two Xorg settings files:
/System/Index/share/X11/xorg.conf.d/20-intel.conf and add an
"AccelMethod" entry to the "Device" section:Section "Device"
Identifier "Intel Graphics"
Driver "modesetting"
Option "AccelMethod" "glamor"
EndSection/System/Index/share/X11/xorg.conf.d/glamor.conf so it reads:Section "Module"
Load "dri2"
Load "dri3"
Load "glamoregl"
EndSectionNow you should be able to get 2D acceleration the next time you launch the X server.
Link to Mailing List for this issue:
http://lists.gobolinux.org/pipermail/gobolinux-users/2017-May/009865.html