Differences between revisions 18 and 19
Revision 18 as of 2008-04-01 10:59:55
Size: 8670
Editor: NeilWilliams
Comment:
Revision 19 as of 2008-09-06 16:37:02
Size: 8582
Editor: PerAndersson
Comment: Documentation overhaul, proofreading and testing of the instructions.
Deletions are marked like this. Additions are marked like this.
Line 4: Line 4:

[[TableOfContents]]
Line 22: Line 24:
Installation will ask you several questions, including where you want to build packages (ensure this directory is writable - the default is only intended for use within a chroot), your username for emdebian svn access if you have one and whether you want to use apt-get or aptitude for toolchain package installation. {{{dpkg-cross}}} will offer you the chance to set a default cross-building architecture which saves a lot of typing later on. If you choose {{{None}}}, you will need to add '{{{--arch ARCH}}}' to all the emdebian-tools commands. Now you need to configure emdebian-tools.

{{{
$ sudo dpkg-reconfigure libemdebian-tools-perl
}}}

The configuration it
will ask you several questions, including where you want to build packages (ensure this directory is writable - the default is only intended for use within a chroot), your username for emdebian svn access if you have one and whether you want to use apt-get or aptitude for toolchain package installation. {{{dpkg-cross}}} will offer you the chance to set a default cross-building architecture which saves a lot of typing later on. If you choose {{{None}}}, you will need to add '{{{--arch ARCH}}}' to all the emdebian-tools commands.
Line 28: Line 36:
=== emsetup ===
==== emdebian-tools and sudo/su ====

{{{emsetup}}}, like the rest of {{{emdebian-tools}}} does '''NOT''' need to be run as root or under {{{sudo}}}. Tools include code to avoid root as much as possible and the package depends on sudo so that sudo usage can be controlled within the script and used only when absolutely necessary. Using at least one {{{-v|--verbose}}} option will ensure that you will be reminded when {{{emdebian-tools}}} needs to use sudo so that you can enter the sudo passphrase if it is not already cached.

Running {{{emdebian-tools}}} or {{{apt-cross}}} as root or under sudo may complicate the subsequent use of {{{emdebian-tools}}} as a normal user. This includes installing the cross-building toolchain - you should let {{{emsetup}}} do that step rather than running {{{sudo apt-get install}}} yourself.


=== Install toolchain ===
Line 35: Line 51:
Check that the output is acceptable, nothing changed yet. If you have dpkg-cross earlier than 1.32 then you are likely to get some harmless "Use of uninitialized value in string eq at /usr/share/perl5/dpkg-cross.pl line 226, <F> line 59." whinges. Just ignore these, and upgrade to 1.33 if you can. Check that the output is acceptable, nothing changed yet.
Line 42: Line 58:

==== emdebian-tools and sudo/su ====

{{{emsetup}}}, like the rest of {{{emdebian-tools}}} does '''NOT''' need to be run as root or under {{{sudo}}}. Tools include code to avoid root as much as possible and the package depends on sudo so that sudo usage can be controlled within the script and used only when absolutely necessary. Using at least one {{{-v|--verbose}}} option will ensure that you will be reminded when {{{emdebian-tools}}} needs to use sudo so that you can enter the sudo passphrase if it is not already cached.

Running {{{emdebian-tools}}} or{{{apt-cross}}} as root or under sudo may complicate the subsequent use of {{{emdebian-tools}}} as a normal user. This includes installing the cross-building toolchain - you should let {{{emsetup}}} do that step rather than running {{{sudo apt-get install}}} yourself.
Line 58: Line 68:

Emdebian Quick Start

This is intended to be a quick start guide to Emdebian and ([wiki:emdebian-tools emdebian-tools]).

?TableOfContents

emdebian-tools (>= 0.9.0) has been split into multiple packages:

  • emdebian-tools - the build tools. If you expect to make any changes to the current set of packages available for ARM from Emdebian, you will need the build tools. emdebian-tools depends on all the other packages below.

  • emdebian-rootfs - the installer tools. If you only want to use the current Emdebian packages for ARM without modification to create a root filesystem you can use alongside your kernel and kernel modules, you will only need the installer tools. emdebian-rootfs depends on the keyring and library packages. See EmdebianRootfs for a quick start.

  • emdebian-archive-keyring - the key for SecureApt support. If you only want to use the current Emdebian toolchains without the Emdebian patches or prebuilt packages, you only need the keyring. You can use the key without using any other Emdebian packages.

  • libemdebian-tools-perl - used by [wiki:emdebian-tools emdebian-tools] and [wiki:emdebian-rootfs emdebian-rootfs].

This guide concentrates on emdebian-tools - i.e. package building, not installation. See also EmdebianRootfs.

emdebian-tools

You will need to install a package called emdebian-tools, either from Debian repositories or the Emdebian repository. emdebian-tools also brings in apt-cross and dpkg-cross. subversion is recommended by emdebian-tools and used by emsource later. (emdebian-tools >= 1.0.0 depends on subversion directly.)

$ sudo apt-get install emdebian-tools subversion

Now you need to configure emdebian-tools.

$ sudo dpkg-reconfigure libemdebian-tools-perl

The configuration it will ask you several questions, including where you want to build packages (ensure this directory is writable - the default is only intended for use within a chroot), your username for emdebian svn access if you have one and whether you want to use apt-get or aptitude for toolchain package installation. dpkg-cross will offer you the chance to set a default cross-building architecture which saves a lot of typing later on. If you choose None, you will need to add '--arch ARCH' to all the emdebian-tools commands.

After you have the tools, you need to setup an emdebian environment using emsetup. This sets up the ~/.apt-cross dir which contains apt caches and configuration files and adds the Emdebian toolchain repository to your apt sources list. apt will then keep your toolchain updated as normal.

New users are recommended to use at least one -v|--verbose option to all emdebian-tools commands.

emdebian-tools and sudo/su

emsetup, like the rest of emdebian-tools does NOT need to be run as root or under sudo. Tools include code to avoid root as much as possible and the package depends on sudo so that sudo usage can be controlled within the script and used only when absolutely necessary. Using at least one -v|--verbose option will ensure that you will be reminded when emdebian-tools needs to use sudo so that you can enter the sudo passphrase if it is not already cached.

Running emdebian-tools or apt-cross as root or under sudo may complicate the subsequent use of emdebian-tools as a normal user. This includes installing the cross-building toolchain - you should let emsetup do that step rather than running sudo apt-get install yourself.

Install toolchain

$ apt-cross --update
$ emsetup --verbose --simulate

Check that the output is acceptable, nothing changed yet.

$ emsetup -v

emsetup will install a toolchain for you if a suitable one is available from Emdebian.

If ~/.dpkg_cross/cross_compile isn't fully configured yet, (hint in the manpage), or you have chosen to have no default cross-building architecture, then emsetup requests the use of --arch to determine the target architecture:

$ emsetup -v -s --arch m68k
...
$ emsetup -a m68k

Once emsetup is complete, you can use sudo apt-get update; sudo apt-get upgrade to ensure you have the latest versions of apt-cross and emdebian-tools as updates are uploaded to Emdebian between Debian versions.

Package source and Emdebian patches

Now you can run emsource <package> to get a debian package, unpack it and apply / generate any emdebian patches. This is directly equivalent to apt-get source in mainstream debian and then applying some patches. emsource tells you where the package has been unpacked - in an SVN tree beneath your emdebian working directory. (target denotes that these packages are intended for installation directly onto the target embedded device.)

$ emsource -v foo
Using foo 0.1.23.4-0.1
Working directory: '/path/to/working/dir'
Checking for existing emdebian patches
Checking out working copies of existing emdebian patches
Checked out revision 1234.
Checking for existing build tree in foo-0.1.23.4.

Emdebianised source tree for 'foo' exists at '/path/to/working/dir/target/trunk/f/foo/trunk/foo-0.1.23.4'
Change to this directory before running 'emdebuild'

Now you can cd into the package directory.

cd /path/to/working/dir/target/trunk/f/foo/trunk/foo-0.1.23.4
gedit debian/rules &

Emdebian patches

  • If you are using Emdebian for ARM, patches are prepared and maintained in Emdebian.
  • If you are using ARM but with a customised toolchain or libc environment, you will need to review and possibly modify the Emdebian patches.
  • If you are using a different architecture, you will need to review the current Emdebian patches and modify values in the architecture-specific cache files - see the [:EmdebianGuide: Emdebian Developer Guide] for detailed information on cache files.

Manual edits of debian/* files

As with any automated packaging process, take a moment to read through amended debian/rules before attempting to do emdebuild to actually build the package. This will you familiarise yourself with the kind of changes that Emdebian makes to Debian packages.

Common additions are noted in the [:EmdebianGuide: Emdebian Developer Guide] but always take care to check for manual rules that install documentation or manpages. You should always check that copyright, changelog and all manpages are removed. If the package uses make install to put such files into debian/ directories, include a line to remove those directories before the debhelper or dpkg commands that build the package:

        $(pkgme)  $(MAKE) -C . install
        $(pkgdev) $(MAKE) -C . install-dev
        $(pkglib) $(MAKE) -C . install-lib
        $(pkgme)  $(MAKE) -C build src-manifest

        dh_strip
        dh_compress
        dh_fixperms
        dh_makeshlibs -N $(library)
        dh_makeshlibs -p $(library) -V 'libattr1 (>= 2.4.4-1)'
        dh_installdeb
        dh_shlibdeps
        dh_gencontrol

        dh_md5sums
        dh_builddeb

becomes:

        $(pkgme)  $(MAKE) -C . install
        $(pkgdev) $(MAKE) -C . install-dev
        $(pkglib) $(MAKE) -C . install-lib
        $(pkgme)  $(MAKE) -C build src-manifest

        $(RM) -r debian/libattr1-dev/usr/share/
        $(RM) -r debian/attr/usr/share/

        dh_strip
        dh_compress
        dh_fixperms
        dh_makeshlibs -N $(library)
        dh_makeshlibs -p $(library) -V 'libattr1 (>= 2.4.4-1)'
        dh_installdeb
        dh_shlibdeps
        dh_gencontrol

        dh_md5sums
        dh_builddeb

You will need to install any build dependencies as needed with apt-get or aptitude and cross-dependencies with emdebuild --build-dep. emdebuild creates a .build log for you.

$ emdebuild -v

Packages, .changes, .dsc, .diff.gz, patch files and the .build log are created in the directory above:

$ ls /path/to/working/dir/target/trunk/f/foo/trunk/

You could check the [http://linux.codehelp.co.uk/emdebian/man/ Emdebian manpages] and the ["Embedded_Debian"] wiki pages for documentation.

All questions to the debian-embedded mailing list - emdebian developers are also available on IRC. See the [http://www.emdebian.org/ emdebian website] for details.

The next stage is the [:EmdebianGuide: Emdebian Developer Guide].


CategoryPermalink CategoryEmdebian