Building GSB: GNOME SlackBuild =============================== Written by: Darren 'Tadgy' Austin Updated by: Steve Kennedy GNOME SlackBuild (GSB) has two components; a full and complete system to build Slackware compliant packages from GNOME sources, and a binary distribution of those pre-built packages, suitable for Slackware and Slamd64. This document provides information on using the GSB build system to produce your own packages of GNOME. Included in the GSB build system are all the SlackBuilds and required files to build a package, an automatic source downloader (we do not distribute the GNOME sources with GSB) and several other tools which are used to create a binary tree of GSB. For detailed information on the build process, or how to obtain the pre-built GSB packages (which, in most cases, is far far easier than trying to build GSB yourself), please see the website at: Table of Contents ----------------- 1. Before You Begin 2. Obtaining the GNOME SlackBuild Source 3. Quick Start Guide 4. Starting GSB/GNOME APPENDIX A. Customising the Build Environment APPENDIX B. SlackBuild Arguments ********************************************************************************** 1. Before You Begin -------------------- This version of GSB is designed to build packages using: Slackware 12.2 Slamd64 12.2 If you are trying to build GSB on systems other than the above you *will* encounter problems during the build. We cannot offer any form of support to users trying to build GSB on earlier versions of Slackware or Slamd64. However, if you do manage to get GSB built on other versions, please let us know what modifications you had to make to the build system in order to do so - if those changes can be integrated into our build system, you may find those versions supported out of the box in our future releases. The developers use a strictly controled base of packages to build the binary packages for the project - we only install the minimum packages required to perform a build. We work from a set of 'tagfiles' which specify exactly which packages get installed into our build environment. We have included our tagfiles set in the lib/gsb/tagfiles/ directory for reference. When it comes to building your own packages it is doubtfull your build will succeed if you do not have every package marked with an "ADD" in our tagfiles installed on your system. Those packages marked "ADD" form the basis of our build requirements - any missing packages from your system will likely cause the build to fail. If you have a full installation of Slackware or Slamd64 you should not have any problem doing a build, but the resulting packages may have more dependancies than indicated in our slack-required files (because many of the sources will find extra libraries when being configured and automatically link against them). Unless you really know what you are doing with packages, understand what tagfiles and dependancies are all about, and really feel the need to "roll your own", it would be a far far better choice for you to download the pre-built binaries and install those. 2. Obtaining the GNOME SlackBuild Source from SVN -------------------------------------------------- We currently maintain several SVN branches to produce our GSB releases. The following is a list of our trees and the URIs which should be used to 'svn co' one of them before building. Bleeding edge 'gsb-current' tree: (At the time of writing, GNOME 2.26.1) http://svn.gnomeslackbuild.org/gsb/trunk/ This tree contains the latest and most up to date GSB sources. As such, at any time it may be broken (ie, will not build fully) or may cause your system to explode in a shower of wires and capacitors if you run it. This tree is usually only for the latest Slackware/Slamd64 current and may not work on other releases. GNOME 2.22 tree: http://svn.gnomeslackbuild.org/gsb/branches/gsb-2.22/ This is our GNOME 2.22.3 stable tree for Slackware 12.1 and Slamd64 12.1. This tree is kept up to date with the GNOME 2.22.3 sources and will be maintained (at least for the short->medium timeframe) with the minor 2.22.x releases GNOME provide. GNOME 2.20 tree: http://svn.gnomeslackbuild.org/gsb/branches/gsb-2.20/ This is our GNOME 2.20 stable tree for Slackware and Slamd64 12.0 ONLY. This tree is kept up to date with the GNOME 2.20 sources and will be maintained (at least for the short->medium timeframe) with the minor 2.20.x releases GNOME provide. 3. Quick Start Guide --------------------- You must be root in order to build GSB. You must be running one of the supported build platforms and have all the required dependancies installed (see above) to build GSB. The GNOME (etc) source files are not distributed with GSB - part of the build process will download the source files for you. Obviously you need an (active) internet connection to download the sources. Here's what to do: $ ./bin/gsb_update.pl --dl --edit --build=gsb $ cd src/ $ ./gsb.SlackBuild Downloading the sources (gsb_update.pl) may take a while depending on the speed of your internet connection. Don't be surprised if it takes a few hours :) The '--dl' option to gsb_update tells it to download the required sources. Without this option nothing will be downloaded. You can stop and start the process as much as you like - gsb_update will not re-download sources it has downloaded previously. With '--edit', gsb_update will edit the SlackBuild files with the version information from the source downloaded - you want this. Finally, '--build=gsb' provides a build tag for the packages. You can specify any build tag you wish for your packages - we use 'gsb' to mark ours. If no '--build' option is given, no tag is added to the BUILD and the built packages will be named just like standard packages (and thus very difficult to remove once installed). The build is started by running './gsb.SlackBuild' in the src/ directory. The gsb.SlackBuild script has several options which effect the whole build process. Normally, however, none of those options are required for a build; and you are advised *not* to use them unless you are a developer. The options are explained in detail further down in this document. GSB requires that some standard Slackware/Slamd64 packages be upgraded to newer versions in order for other packages to compile and work correctly. As part of the GSB build process, gsb.SlackBuild (and section SlackBuilds) will remove (using removepkg) any such packages which need to be updated. The new (updated) package from GSB will then be built and installed. Building GSB will take a very long time unless you have some top-notch hardware or small cluster system. It took 1-2 days to perform a full build of GSB on my build box (2.5GHz CPU, 2GB RAM) - you have been warned. If the build fails for some reason, you can correct the error and re-run the './gsb.SlackBuild' command - the build system will continue from where it failed, not restart the whole process again. At the end of the build process you will have a full copy of GSB installed on your system ready to go, and a copy of the completed GSB binary package tree in /tmp/gsb-tree/ (see below for how to change this). 4. Starting GSB/GNOME ----------------------- Starting the GSB GNOME environment will depend on how you start your current X Window environment. Both techniques are described below. If you login to your system at the text console and use 'startx' or similar, you should log in as your usual (not root!) user and run: $ xwmconfig ... and select the GNOME option from the menu. You can also repeat the above as root to set the default for the whole system, but using root as your every day login user is a *really* *stupid* *idea*. Secondly, if you login to your system via a graphical login manager (such as kdm, xdm or other) you will need to exit the graphical login manager in order to allow gdm (the GNOME graphical login manager) to take over. To get gdm up and running you need to be at a text console [yes, an Xterm will work but you'll have to re-login after X Windows exits - it's just easier to do it this way, trust me]: hold down Ctl and Alt and press F6 once. After a couple of seconds you should see a text based "login" prompt. At the text "login" prompt, login to your system as root and then run: $ init 3 ... and wait for the system to close all of the X Window processes and return you to the usual prompt. It may take up to a minute to do this, and try hitting Enter a couple of times to see when it's done. Once back to the prompt, run: $ init 4 ... and wait for the new gdm graphical login manager to appear. You can now login to your new GSB GNOME desktop. Make sure you select "GNOME" from the session selection menu, if it is not already the default. If you are returned to the prompt or your display keeps going on and off repeatidly, the gdm application has not started sucessfully and there is a problem. You will need to return your system to the text based state in order to debug the problem - use the same 'init 3' command as detailed above. If you do have a problem like this or cannot figure out what the issue is, please visit us on the IRC channel for help - details are on the website. APPENDIX A. Customising the Build Environment --------------------------------- When building GSB, there are several environment variables which can be used to tweak and customise the build process. GSB supports two methods of setting these environment variables, described below. The first option is to use the bash builtin 'export' to manually set the option and export it to all sub-processes. This can be done with a command like: $ export VAR="VAL" ... which can be repeated for as many environment options as you want to set. You must remember to set these options every time you begin a build process as they will not be saved accross multiple builds. The second option is to create a 'gsb.options' file in the src/ directory. The gsb.options file is read at the begining of every build process, and the options specified in this file will be saved accross multiple builds. Using the gsb.options file is especially useful for repeat builds or for developers who want to set specific options when testing. The gsb.options file should contain exactly the same 'export' commands which would be used manually on the command line (see above). The advantage of putting them into the gsb.options file is that the options will always be read, no matter whether you remember to manually export them on the command line. Here are the common environment variables which can be set to effect, tweak or customise the build process: ARCH Setting the ARCH allows you to over-ride the default base architecture type for GSB. You can use this environment option to build GSB for, say, x86_64 or the powerpc architecture type. The architecture type set when building GSB determines the absolute minimum processor type required to run the produced binaries. In other words, if you set ARCH=i686 the resulting code will NOT work on an i586 or earlier CPU. These ARCH types are currently recognised by the GSB SlackBuild scripts: i386, i486, i586, i686, x86_64 and powerpc. The default is "i586". TUNE This option is very similar to the ARCH environment option except that the resulting binaries are scheduler-tuned to the given processor type. This means that the binaries will be tuned to run with better performance on the CPU type specified with TUNE, but will still work without problems on CPU types going back to the value specified for ARCH. TUNE can be set to any valid CPU type within the architecture type specified with ARCH. For example, if ARCH=i586, TUNE could be set to i686. For an ARCH type of x86_64, TUNE must be set to one of the 64 bit processor types, currently: k8, opteron, athlon64 and athlon-fx. The default is "i586", except for an ARCH type of x86_64 where it is "k8". DISTRO Setting DISTRO to anything other than "slackware" allows GSB to be built on different (Slackware based) distributions. For example, this can be set to "slamd64" when building GSB on the 64 bit Slackware based distro Slamd64. The default is "slackware", and should not be over-ridden unless you are specifically building for another distribution. TMP During the package builds, temporary data will need to be stored on disk. This option specifies the directory where that temporary data can be written. Make sure the default (or any directory you specify) has enough free space for the build process, plus the completed packages and logs. The default is "/tmp". PKGDEST Once a package has been built, it will be stored in a sub directory of the path specified with this option. The default for this option is affected by the value of the TMP environment variable (referred to as $TMP below). The default is "$TMP/gsb-tree", except for an ARCH type of x86_64 where it is "$TEMP/gsb64-tree". LOGSDIR As the GSB build process proceeds, a log of the output from each package build is logged for later debugging. This environment option specifies the directory where these log files will be stored. This option is not used by individual package SlackBuilds but is used by the top-level SlackBuilds which control the build processes. The default for this option is affected by the value of the TMP environment option detailed above (referred to as $TMP below). The default is "$TMP/gsb-buildlogs". The following options are less common but allow highly specific customisation of the build process. You should not set these options unless you know exactly what needs to be set for each. GSB_SECTIONS This environment option can be used to specify exactly what GSB sections should be processed. This option should contain a space separated list of (valid) GSB sections (available using the '--list' option to gsb.SlackBuild), in the order they should be processed. Care should be taken to insure the processing order is correct - packages in some sections rely on packages previously built in others. The default is to process all GSB sections (in the correct order). GSB_CONFIGURE_FLAGS Any options specified in this environment variable are ADDED to the package specific options passed to the ./configure command in the SlackBuilds. If this option is set globally (ie, set with export or in gsb.options) it sets the additional options passed to ./configure for EVERY SlackBuild in GSB. Therefore, mkae sure that any setting given in this environment option is valid for EVERY ./configure used in GSB. When ARCH=x86_64, ./configure is automatically passed "--libdir=/usr/lib64". GSB_TUNE_CFLAGS This environment option allows you to set the specific tuning options gcc should use when compiling/linking the binaries in packages. There are many, many gcc options which can be set to optimise/tune the binaries - see the gcc man page for full details. Setting this option over-rides the default tuning options specified in the SlackBuild files - these options are NOT added to the default ones. Make sure you add any of the default options from the SlackBuilds back to this environment option if you choose to use it. Tuning is specific to each ARCH, with the defaults being: i386, i486: -O3 -march=$ARCH -mtune=$TUNE i586, i686: -O3 -march=$ARCH -mtune=$TUNE -pipe -fomit-frame-pointer x86_64, with default TUNE: -O3 -march=k8 -mtune=k8 -pipe \ -fomit-frame-pointer -fPIC x86_64, with custom TUNE: -O3 -march=$TUNE -mtune=$TUNE -pipe \ -fomit-frame-pointer -fPIC powerpc: -O2 -march=$ARCH GSB_EXTRA_CFLAGS This setting is used to add custom/additional gcc options to be used during the compiling/linking phase. As with the above, there are many options which can be used with gcc and the best place to look for these is the man page. Setting this option over-rides the default extra options specified in the SlackBuild files - these options are NOT added to the default ones. Make sure you add any of the default options from the SlackBuilds back to this environment option if you choose to use it. There is no default for this option. GSB_MAKE_FLAGS Using this environment option allows additional command line arguments and/or options to be given to the "make" command when building the sources. This option may be useful for people with multi core/processor machines which can perform parallel builds using an option such as "-j2" or "-j4". See the man page for make for full details of command line arguments and options. Setting this option over-rides the default make arguments specified in the SlackBuild files - these options are NOT added to the default ones. Make sure you add any of the default arguments from the SlackBuilds back to this environment option if you choose to use it. There is no default for this option. APPENDIX B. SlackBuild Arguments ---------------------------------- There are several options which can be passed to gsb.SlackBuild when begining the build process. Options given to a top-level SlackBuild will be passed down to the individual package Slackbuilds as a the build process continues. The following options are recognised: --help Show this help screen. --list List the packages which will be built in this section. --force A package will not be built if a package of the same name is already installed, or any of the pre-requisite packages are not installed. This option over-rides the checks and attempts a build (which will probably fail) anyway. --no-cleanup By default, any source, temporary build and package directories will be deleted once the package is built. This option prevents those files from being removed. --no-patchesdir When rebuilding packages which already exist in the main package directory, the default is to put the new packages in the patches directory. Using this option completely disables the use of a patches directory. --no-skip During the build process, packages that are up to date (ie, the package version and build numbers match the coresponding SlackBuild) will not be rebuilt. This option forces packages to be rebuilt regardless of the version and build numbers. This option doesn't affect the pre-build checks for installed packages (see the --force option). This option implies --no-patchesdir. --no-prune Normally, when a package is built and copied to the destination directory (whether it be the main package directory or the patches directory), any previous package(s) of the same name in that directory are deleted - it is assumed the new package is to replace any which are already present. This option prevents previous packages being deleted, possibly leaving more than one package of the same name (but with different version or build numbers) laying around. --no-install Build the packages but don't install them afterwards. This should only be used for testing as it WILL cause serious problems - most builds rely on other GSB packages being automatically installed first. --no-metafiles Do not create the package's .txt and .md5 meta files which would usually be produced during a build. -- Good luck!