3.1. Debian devkits repository

Debian devkit is located in Scratchbox CVS repository and it can be through CVS Viewer located at Scratchbox website [4]. This is the only public access to Scratchbox repository that is currently offered.

3.2. Debian devkits GAR build system

Scratchbox is built using GAR build system [6]. It is a mechanism for automating the compilation and installation of third-party source code. It appears in the form of a tree of directories containing Makefiles and other ancillary bookkeeping files (such as installation manifests and checksum lists). Scratchbox GAR build system is available trough CVS located on Scratchbox site [4].

Adding software to GAR build system is fairly straightforward. Adding new tools to Debian devkit can be done with following steps:

1. Obtain sources for package. Sources should be fetched with apt-get source command because Debian can have Debian specific patches against original sources. Otherwise there might be need to apply patches manually.

2. Create new directory for package to Debian devkits GAR directory 'scratchbox/debian_tools/$PACKAGENAME'.

3. Copy Debian patched source tarball to $PACKAGENAME/files directory.

   Source tarball should be at Scratchbox site at 'download/files/sbox-files/' directory for enabling GAR to download package automatically. For testing purposes a local copy is sufficient.

   
   
   

4. Create makefile under $PACKAGENAME diretory. In GAR build systems package needs to have some specific variables for enabling package to build correctly. At least following list should be included, for more information about GAR build system see [6].

   • GARNAME defines package's name.

   • GARVERSION defines package's version.

   • CATEGORIES defines package's category. In Debian devkits case this must be 'debian_tools'.

   • DISTFILES defines source (tar) package that is used to build this package. This is usually combination of GARNAME, GARVERSION and source packages extension (usually tar.gz).

   • LIBDEPS tells which libraries this package depends. These packages are compiled before compiling this package.

   • DEPENDS defines packages that must be compiled before this package can be compiled properly. This might contain tools that are required during building process of this package.

   • DESCRIPTION contains description of this package.

   • CONFIGURE_ENV defines some Scratchbox specific variables. For example Scratchboxs perl and python should be defined here if package uses them.

   • CONFIGURE_ARGS defines options that are passed to packages configure script. This should contain at least prefix to install this package properly and Debian specific options (they should be in 'debian/rules' file inside packages source tarball).

   • BUILD_ARGS defines arguments that are used to build this package. This should contain at least Scratchbox specific LDFLAGS, CC and PERL or PYTHON paths if they are used.

   • INSTALL_ARGS contains arguments that are used when package is installed. Usually they are the same as BUILD_ARGS.

   • CONFIGURE_SCRIPTS defines script that used to configure building process. Typically this is packages configure script.

   • BUILD_SCRIPT is used to define packages makefile.

   • INSTALL_SCRIPT defines packages install script. Usually this is packages makefile.

   • In addition to package specific options packages GAR makefile should include correct GAR category file. In Scratchbox this is done by including '../category.mk' file after variable definitions. Also there must be 'pre-patch' and 'pre-configure' directives in Scratchbox GAR makefiles. These are used to add Scratchbox specific patches if necessary.

   Following example makefile is from Debian devkits dpkg package:

   
   GARNAME = dpkg
   GARVERSION = 1.10.20
   CATEGORIES = debian_tools
   DISTFILES = $(GARNAME)_$(GARVERSION).tar.gz
   
   LIBDEPS =
   DEPENDS = tools/perl
   
   DESCRIPTION = dpkg
   
   CONFIGURE_ENV = PERL=/scratchbox/tools/bin/perl
   CONFIGURE_ARGS = --prefix=$(prefix) --exec-prefix=$(prefix) \
            --sbindir=$(prefix)/bin --with-admindir=/var/lib/dpkg
   
   BUILD_ARGS = -j1 LDFLAGS="$(TOOLS_LDFLAGS) -L../optlib -L../lib" \
            CC="$(TOOLS_CC)" PERL=/scratchbox/tools/bin/perl
   
   INSTALL_ARGS = $(BUILD_ARGS)
   
   CONFIGURE_SCRIPTS = $(WORKSRC)/configure
   BUILD_SCRIPTS = $(WORKSRC)/Makefile
   INSTALL_SCRIPTS = $(WORKSRC)/Makefile
   
   include ../category.mk
   
   pre-patch:
           $(MAKECOOKIE)
   
   pre-configure:
           patch -d $(WORKSRC) -p1 < files/dpkg-sbox.patch
           $(MAKECOOKIE)
   

   Above example should a give good picture about necessary elements in dpkg packages GAR makefile.
   
   

5. Type make makesums in packages directory to generate checksum information for package.

6. Package is now ready to be compiled. Compiling and installing package can be done with make install command.

   If package does not compile properly see packages Debian rules file for Debian specific configuring options and check that you have necessary library dependencies in order. In addition to Scratchbox specific configuring options also Debian might have some required options.

   
   
   

3.3. Testing a new tool

First thing is to check that new tool has been linked properly. This can be done inside Scratchbox with command ldd. Actual command is something like this:

[sbox-MYTARGET: ~] > ldd /scratchbox/devkits/debian/bin/$PROGRAMNAME

New tool should have been linked with libraries under '/scratchbox/host_shared'. If tool has links to other libraries outside '/scratchbox/host_shared' it is propably broken (usually inside Scratchbox libraries under '/lib' and '/usr/lib' directories are compiled for target platform and will not work with tools compiled for i386) and needs to be build again with correct build options. If tool was linked properly it can be tested that it works correctly.

Best way to test a new tool is to build a package that depends on that specific tool. If build process completes successfully and package can be installed and removed correctly test is considered passed and the new tool can be committed to devkits repository. Debian package building is described more closely on Debian Development with Scratchbox [3].

3.4. Inserting package to repository

After package is compiled, installed and tested properly it is ready to be put into Debian devkits repository. Adding new packages to Debian devkits repository should be done with following steps:

• If you are not a member of Scratchbox development team you do not have rights to insert packages to repository. If this is the case contact Scratchbox development team (contact information can be found at Scratchbox websites contact page [5]).

• Upload packages source tarball into 'download/files/sbox-files/' directory in Scratchbox website.

• Cleanup packages directory with 'make clean' command inside packages GAR directory.

• Use 'cvs add $PACKAGEDIRECTORY' command for packages GAR directory. This will insert packages directory to CVS repository.

• Insert packages makefile and checksums file to repository with 'cvs add Makefile checksums' command.

• If package contains patches files directory and the patch in files directory they should be also added to repository with 'cvs add' command.

• Add an entry to ChangeLog file that describes what has been added. This way modifications can be tracked later on.

• After necessary files are added modifications to repository should be committed. This can be done with 'cvs commit' command.

• New package should be also added to 'meta/debian_tools/' directory's makefiles dependency list so that package would be compiled automatically. Modifications to this file should also be committed with 'cvs commit' command.

• After package has been added to repository it is recommended that building and installing packages are verified. This can be done by checking out clean repository and testing packages with same tests than in Section 3.3.