root/current/website/trunk/english/stage.wml

#use wml::emdebian::mainpage title="STAGE - Emdebian with scratchbox"

<pre>
Embedded Debian build environment

$Id$

---------------------------------
Table of Contents

1. Introduction

2. Initial setup

   2.1 Setting up scratchbox environment
       2.1.1 Installing scratchbox packages
       2.1.2 Creating new scratchbox target
       2.1.3 installing development rootstrap inside scratchobx

   2.2 Svn source repository
       2.2.1 Repository location
       2.2.1 Repository layout
       2.2.2 How to check out stuff from repository

3. Building packages

4. Root filesystem creation

5. TODO list

6. References

--------------------------------------------------------------------------------


1. Introduction
---------------

This scratchbox-based environment is intended for building emdebian [1]
packages.  It uses scheme based on 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 Nokia experience of Nokia 770 development and
building bootable root filesystem images using 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]

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

This enviroment is used STAG ideas, but a bit different way. It also offered
patched debian packaging tools, but modifications allow developer to make both
emdebian and debian packages using the same tools. It can be done by changing
DEBIAN_DIR environment variable. Moreover, it's possible to have even more
debian-like directories and have more than one type of packages 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 loging and get
working shell, working apt and dpkg and xserver depending on image.

Project infrastructure includes svn source repository, debian package
repository filled by emdebianized packages and downloadable rootfs and
rootsrtap 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.


2. 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.

 2.1 Setting up scratchbox environment
 ------------------------------------

  2.1.1 Installing scratchbox packages

    Add the following lines to your /etc/apt/sources.list:

        deb http://stage.maemo.org/ emdebian/tools glibc
        deb-src http://stage.maemo.org/ emdebian/tools glibc

    And perform the command

     $ 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 \
        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 <username>
    
  2.1.2 Creating new scratchbox target
    
     Run scratchbox:
     $ scratchbox

     Create target (ct):
     [sbox-HOST: ~] > sbox-config -ct <target_name>

     You'll be asked for the compiler number.
     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 <target_name>

     copy fakeroot and c libraries:
     [sbox-target: ~] > sbox-config -cc
     [sbox-target: ~] > sbox-config -cf

  2.1.3 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://stage.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.

 2.2 Svn source repository
 -------------------------

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

  Repostitory layout is according to svn-buildpackage recomendations
  (see /usr/share/doc/svn-buildpackage/HOWTO.html/index.html)

  2.2.1 Repository location

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

     target/trunk/<package> - 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/<package> - tools modified for emdebian usage (dbs,cdbs...)
               ...
     tools/{tags,branches,releases} - the same as for target
     doc/ - documentation
     configurations/<name> - rootfilesystem or scratchbox rootstap images and lists
       name conventions for configurations is <arch>-<libc>-<name>-<type>
          arch - architecture (arm,i385...)
          libc - libc variant (glibc or uclibc)
          name - name of configuration. Coudld be device-specific or usage-specific,
                 for example (nokia770 - for nokia 770 device)
          type - image type (for example minimal,apt,dev)
 

  2.2.2 How to check out stuff 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/.


3. 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-relatet 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/<package>

   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.

4. Root filesystem creation
---------------------------

   4.1 initial setup:

     Install rootimagescripts outside scratchbox:

     $ sudo apt-get install rootimagescripts
   
   4.2 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

   4.3 Rootstrap creation using local directory with packages

     $ 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.

5. TODO list
------------

     o uclibc builds (arm and i386)

     o i386 glibc build (-dev rootstrap and rootfses)

     o build system

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

     o upgrade packages to upstrim(testing?) versions.

     o implement lintian check for emdebian packages


6. References
-------------

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

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

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

 [4] Emdebian and Debian http://emdebian.sourceforge.net/emdebian/emdebian.html
</pre>