<> ||<>|| This documents describes how to setup and use the kernel team build scripts. This is meant as a reference for the kernel team. == Basic setup == The scripts are located in a public git repository (on zinc aka kernel.ubuntu.com). They are written so they can be executed from the current working directory or some directory of the PATH environment. {{{ git clone git://kernel.ubuntu.com/ubuntu/kteam-tools.git cd }}} The scripts will store and use configuration files located in ''~/.ubuild''. The base directory can be changed by exporting a shell variable set to the location of the desired location. This might be done by putting the following code into the ''.bashrc'' file. {{{ UBUILDDIR= export UBUILDDIR }}} An initial configuration can be created by calling ''build-init''. This will create the base configuration directory, the main config file, the groups, the distros and some default hosts. === Main config file === Path: $UBUILDDIR/config This contains the global options (shell syntax): || '''Variable''' || '''Setting''' || || '''DIST''' || The default distro to use. || === Group definitions === Path: $UBUILDDIR/groups/ These define groups of hosts to use for builds. The ''default'' group will be used if no other group is given. The ''autobuild'' group is used when scripts are started with the ''autobuild'' argument. The layout is one target per line. Each target can be either a or -, or . If using a hostname, this host will be used to build the native architecture of that host on that host. The - form is used to enforce builds of another supported architecture (e.q. ronne-i386 builds i386 packages on ronne which is amd64). Finally will look for a host that can build the desired architecture (do not expect this to work too well at the moment). === Distro definitions === Path: $UBUILDDIR/distros/ For each distro, this sets (shell syntax) the options that are specific for each distro: || '''Variable''' || '''Setting''' || || '''SRCDIR''' || Defines the location where the kernel sources (git) for this distro are located (local host). || === Host definitions === Path: $UBUILDDIR/hosts/ Defines the environment for each host that can be used with the build scripts. New hosts should be created by (though this can also be done manually): {{{ build-create-host }}} The script will check the target host and create a configuration for that. The name for that host will be the basic hostname (without domain). A suitable target host must satisfy some requirements: * The local system/user must be able to ssh to the target host. * The target host must have the the following packages installed: * ''git-core'' (to push the sources) * Either ''dchroot'' or ''schroot'' (builds are always done in a chroot environment) * The target host must have chroot environments ready for kernel compilation. The environments must be named '''' for the environments that use the base architecture of that host. Or ''-'' for those that are created for different architectures (e.g. ''hardy-lpia''). The following variables are set in the host config file (shell syntax): || '''Variable''' || '''Setting''' || || '''ARCHCMD''' || Optional command to set a desired architecture || || '''ARCHS''' || Supported architectures, separated by blanks. || || '''BASE''' || Base directory used for builds. This path must be valid in the chroot environment! || || '''CHROOTCMD''' || Either schroot or dchroot || || '''FAKEROOT''' || Command used to build as root (default fakeroot) || || '''HOST''' || Fully qualified hostname || || '''HOSTARCH''' || The real architecture of the host || == Running a build == === Preparations === Before starting the actual build some files have to be sent to the target host. This includes some scripts that will be run during the build as well as the git tree. This also cleans up the source directory on the target host. The basic command to prepare a target is ''build-prep'' which will take the following optional arguments: || '''--dist ''' || Specifies a different distribution than the default one specified in $UBUILDDIR/config (hardy,intrepid,...) || || '''--branch ''' || Will send a different branch (default is master) || || '''--lum''' || Does send the LUM sources instead of the kernel sources || {{{ build-prep }}} === Start a build === This will start a build on the specified target as a background process. Requires '''--dist''' to be specified if not the default. The current state can be monitored by calling ''build-status'' or ''build-monitor''. {{{ build-start }}} === Checking the status === Requires '''--dist''' if not the default. {{{ build-status [-v] [ ...] }}} Will run a one time check on the target(s). Using the ''-v'' option will produce more detail. {{{ build-monitor [-v] ] [ ...] }}} Runs a periodically updated status on the target(s) by using the ''build-status'' command in the background. == Preparing PPA builds == {{{ build-mkppa [--nopkg] [--noinc] [--base ] [--erase] }}} || '''--nopkg''' || Do not create the package files || || '''--noinc''' || Do not increment the build version number || || '''--base ''' || Create a branch (ppabuild) based on the given tag || || '''--erase''' || Deletes everything other than the directory .git || This command must be run in the top-level directory of a git tree and will try to automatically apply patches and commits necessary for a PPA build. This will also update the changelog and modify the current tree. In order to operate a certain directory layout is required: If is the current directory that contains the kernel, ''build-mkppa'' will look for a directory named that contains the following files and directories: {{{ kernel-ppa/ppa-version kernel-ppa/patches/series kernel-ppa/patches/patch1... kernel-ppa/patches-/series... kernel-ppa/abi-version }}} * ''ppa-version'' will be created and contains the version number of the last PPA build which will get incremented each time the command is run. * ''patches'' or ''patches-'' contain the patches that get applied on top of the current git tree for the PPA build. The first one is used for normal builds while the second one is used for builds based on a specific release tag. * ''abi-version'' is optional and will contain the version number of the build that defines the kABI version for this build. This is usually a link to the ppa-version file of another package (e.g. for LUM this points to the kernel-ppa version.