#pragma section-numbers on
= Working Emdebian build environment =

== Introduction ==

This scratchbox-based environment is intended for building [[Embedded_Debian|emdebian]] [1]
packages.  It uses a scheme based on the emdebian STAG framework ideas [2].  It can
also be used for making root filesystem images out of emdebian packages.

This is an attempt to share the Nokia experience of Nokia 770 development and
building bootable root filesystem images using the emdebian packaging scheme.

Embedded Debian(Emdebian) is a project to make Debian GNU/Linux a mainstream
choice for embedded projects.

This was taken from emdebian website [4] as an explanation of one of the
project's ideas: "We need a scheme that allows emdebian to stay in sync with
Debian as much as possible, whilst having fine control over package generation.
To do this we need to keep emdebian package modifications in each package,
maintained by package maintainers as much as possible." [4]

The first implementation of this scheme is the STAG embedded framework [2] The
idea is to have a separate emdebian directory included in the debian source
package, i.e. to have the option to make both debian and emdebian packages
out of the same source package. STAG proposes a patched version of dpkg and
debhelper packaging tools using emdebian directory instead of debian.

This enviroment uses STAG ideas, but a slightly different way. It also offeres
patched debian packaging tools, but modifications allow the developer to make both
emdebian and debian packages using the same tools. This is done by changing
the DEBIAN_DIR environment variable. Moreover, it's possible to have even more
debian-like directories and have more than one type of package built from the
same sources.

This implementation uses scratchbox as a cross-compilation environment. It
includes modified scratchbox, emdebian development rootstrap, set of about 40
emdebianized debian packages and 3 root filesystems built out of these
packages: minimal, dpkg+apt, dpkg+apt+xserver.  Rootfses have been tested on
Nokia 770 device. Only basic tests like booting, ability to log in and get
working shell, working apt and dpkg and xserver depending on image.

The project infrastructure includes an svn source repository, a debian package
repository filled with emdebianized packages and downloadable rootfs and
rootstrap images.

Please note that this is a work in progress and any kind of
help/feedback/suggestionsfrom emdebian developers is more than welcome. If
you're interested in this you can look at the TODO list at the end of this
document.


== Initial setup ==


First of all it's assumed that you have Debian installalled on your PC.  This
is a requirement. At least all this environment was developed and tested on
Debian.

All you need for building is to install and configure scratchbox environment,
configure scratchobox target, install development rootstrap into this target.
Below is explanations of the setup in details.

=== Setting up scratchbox environment ===

==== Installing scratchbox packages ====

 * Add the following lines to your /etc/apt/sources.list:
{{{
     deb http://repository.maemo.org/ emdebian/tools glibc
     deb-src http://repository.maemo.org/ emdebian/tools glibc
}}}
 * and update apt cache
{{{
     $ sudo apt-get update
}}}
 * Install scratchbox [3] 0.9.8.5 packages modified for emdebian:
{{{    
     $ sudo apt-get install scratchbox-core scratchbox-libs scratchbox-devkit-debian scratchbox-doctools
}}}
 * Install needed toolchains (you shouldn't install all of them, just those that you're going to deal with):
{{{
     $ sudo apt-get install scratchbox-toolchain-arm-gcc3.4.cs-glibc scratchbox-toolchain-i686-glibc_0.9.8.5 scratchbox-toolchain-arm-gcc3.4.cs-uclibc
}}}
     Note that toolchains have not been modified and can be
     downloaded and installed from scratchbox site [3]

 * Add scratchbox user(s):
{{{
     $ sudo /scratchbox/sbin/sbox_adduser 
}}} 
==== Creating new scratchbox target ====
    
 * Create new target inside scratchbox:
{{{
     $ scratchbox

     [sbox-HOST: ~]> sbox-config -ct 
}}}
     You'll be asked for the compiler number.<<BR>>
     Choose arm-linux-gcc3.4.cs-glibc2.3 for arm-glibc target, arm-linux-gcc3.4.cs-uclibc0.9.27 for arm-uclibc target and so on.
    
     Choose quemu-arm as a CPU-transparency method for arm target or
     'none' for i386 target.

     Choose debian devkit.

 * select target you've just created:
{{{
     [sbox-HOST: ~]> sbox-config -st 
}}}
 *  copy fakeroot and c libraries:
{{{
     [sbox-target: ~]> sbox-config -cc
     [sbox-target: ~]> sbox-config -cf
}}}

==== installing development rootstrap inside scratchobx: ====
    
 * Run scratchbox if you're not inside it already:
{{{
     $ scratchbox
}}}
 * Download rootstrap from stage.maemo.org:
{{{
     [sbox-target: ~]> wget http://repository.maemo.org/emdebian/configurations/arm-glibc-emdebian-dev/arm-glibc-emdebian-dev-rootstrap.tgz
}}}    
 * Install rootstrap:
{{{
     [sbox-target: ~]> sbox-config -er arm-glibc-emdebian-dev-rootstrap.tgz
}}}    
  At this point environment is ready and you can start to build packages.

=== Svn source repository ===

  The repository contains sources for emdebianized packages. There are about 40
  packages at the moment.

  The repostitory is laid out according to svn-buildpackage recomendations
  (see /usr/share/doc/svn-buildpackage/HOWTO.html/index.html)

==== Repository location ====

     https://repository.maemo.org/svn/emdebian/
     you should use guest/guest username/password for read-only access.
  
==== Repository layout ====

 * target/trunk/ - source directories ready to be built using svn-buildpackage (for packages which go to target root filesystem)   
 * target/tags - directory for svn tags
 * target/branches - directory for branches
 * target/releases - directory for release tags
 * tools/trunk/ - tools modified for emdebian usage (dbs,cdbs...)
 * tools/{tags,branches,releases} - the same as for target
 * doc/ - documentation
 * configurations/ - rootfilesystem or scratchbox rootstap images and lists name conventions for configurations is:
          arch - architecture (arm,i385...) <<BR>>
          libc - libc variant (glibc or uclibc) <<BR>>
          name - name of configuration. Coudld be device-specific or usage-specific, for example (nokia770 - for nokia 770 device) <<BR>>
          type - image type (for example minimal,apt,dev) <<BR>>
 

==== How to check out source from repository: ====

 * Run scratchbox:
{{{
     $ scratchbox
}}}     
 * Check out the stuff:
{{{
     [sbox-target: ~]> svn co https://stage.maemo.org/svn/emdebian/
}}}
     You should use 'guest/guest' as username/password

     You can also browse the repository through http whith your browser.
     Just point browser to https://stage.maemo.org/svn/emdebian/.


== Building packages ==

 * Run scratchbox:
{{{
   $ scratchobox
}}}

 * Set DEBIAN_DIR variable to 'emdebian'. After that packaging tools will be
   using emdebian as a name for directory with packaging-related files
   (control, rules, changelog etc.):
{{{
   [sbox-target: ~]> export DEBIAN_DIR=emdebian
}}}

   (you might want to add this line to your ~/.bashrc)

 * Go to source directory for your package:
{{{
   [sbox-target: ~]> cd emdebian/target/trunk/
}}}

 * Build it using svn-buildpackage:
{{{
   [sbox-target: ~]> svn-buildpackage -rfakeroot -uc -us -sa -D
}}}

   You can start with already emdebianized packages from svn repository
   discribed in section 2.2 of this document.

== Root filesystem creation ==

=== initial setup ===

     Install rootimagescripts outside scratchbox:
{{{
     $ sudo apt-get install rootimagescripts
}}}   
=== Rootstrap creation using emdebian package repository ===

 * Run scratchbox:
{{{
     $ scratchbox
}}}  
 * Rootfs configurations are ready for build:
{{{
     [sbox-target: ~]> cd emdebian/configurations/
     [sbox-target: ~]> make_rootimage.sh -p arm-glibc-nokia770-apt/packages -o arm-glibc-nokia770-apt/arm-glibc-nokia770-apt --jffs --rootfs --genlists -f
}}}
     or
{{{
     [sbox-target: ~]> make_rootimage.sh -p arm-glibc-nokia770-minimal/packages -o arm-glibc-nokia770-minimal/arm-glibc-nokia770-minimal --jffs --rootfs --genlists --strip=all -f
}}}

=== Rootstrap creation using local directory with packages ===

 * Run scratchbox and go to the configuration directory:
{{{
     $ scratchbox
     [sbox-target: ~]> cd emdebian/configurations/
}}}
 * Make 'workarounds' directory and put packages there:
{{{
     [sbox-target: ~]> mkdir workarounds
     [sbox-target: ~]> cp *.deb workarounds/
}}}
     Run make_rootimage.sh with necessary options. All packages
     from workarounds directory will be installed on the target.

== TODO list ==

 * uclibc builds (arm and i386)

 * i386 glibc build (-dev rootstrap and rootfses)

 * build system

 * continue stripping unneeded binaries/libraries from packages
     
 * cleanup rootimage scripts

 * upgrade packages to Etch.

 * implement lintian check for emdebian packages


== References ==

 * [Emdebian home: http://emdebian.sourceforge.net/]

 * [STAG embedded framework: http://stag.mind.be/]

 * [Scratchbox http://www.scratchbox.org/]

 * [Emdebian and Debian http://emdebian.sourceforge.net/emdebian/emdebian.html]

----
CategoryEmdebian