DESCRIPTION

emsource combines the functionality of apt-get source and svn checkout to maintain a record of Emdebian changes to Debian packages.

emsource supports configuration using debconf to set a subversion username and default working directory for unpacking source downloads. Default debconf values in /etc/emsource.conf can be overridden by user-specific values in ~/.apt-cross/emsource.

If you get an error about not being able to create a working directory for emsource, either reconfigure emdebian-tools via debconf:

sudo dpkg-reconfigure emdebian-tools

Or edit ~/.apt-cross/emsource.

emsource uses subversion to identify and retrieve the emdebian patch files, whether or not a username is specified. emsource is an optional component of emdebian-tools which does not depend on subversion directly. Please ensure that subversion is installed before using emsource.

Updating existing Emdebian packages

When updating an existing emdebian package, the -c|--clean option is recommended before attempting any automated builds. emsource will attempt to use the current emdebian patches but any or all patches will be skipped if the 'simulate' option of patch reports a likely failure. Commonly, the changelog patch will be skipped so emsource will run em_make to initialise the package and set the emdebian version string.

Before beginning to build the updated package, take a look at the emdebian patch files - especially if emdebian-rules.patch was skipped. If you have built the package, check the modified emdebian patch files against Emdebian SVN with svn status ../. Take care not to cause regressions in the package.

Automated builds are supported but need to be used with care, preferably when trying to reproduce a working build in a different environment. -b|--build implies --clean so that the automated build always uses the current SVN patches.

COMMANDS

Options for dpkg-buildpackage can be given after the -- option. The default options are -uc -us which cannot be overridden. Also certain commands do not make sense in this context, e.g. -a for architecture will be silently dropped.

OPTIONS

Emdebian SVN

emsource can work with the Emdebian subversion repository to enable coordinated package building. SVN handling by emsource and emdebuild is only possible if a valid Emdebian SVN username is supplied, either in a configuration file (/etc/emsource.conf or ~/.apt-cross/emsource) or using -u |--username.

Only patch files should be checked into Emdebian SVN. Often, only the three emdebian patch files are necessary:

emdebian-control.patch
emdebian-changelog.patch
emdebian-rules.patch

The patch files that are handled automatically by emsource and emdebuild --svn. If a 'cache' file is necessary, the patch to create the cache file will also be checked into Emdebian SVN automatically. If other patches are necessary, include the patches in debian/patches as normal and add only the new Emdebian patches to Emdebian SVN. If an existing Debian patch needs to be modified, create a new patch in debian/patches that corrects the effect of the Debian patch rather than modifying the Debian patch itself.

To ease future development, it is recommended that you configure subversion to ignore other directories and files using the svn:ignore property. A default svn:ignore property is set by emsource for files beginning with the initial letter of the source package. For example, in the package coreutils, all files beginning with c* are ignored. Depending on the package, a common prefix to ignore is lib*. To add a new wildcard to the svn:ignore property, use this command in the top level directory (where the emdebian patch files are created):

svn propedit svn:ignore .

This will open a special svn file in your default editor. Add the necessary wildcard on a new line, save the file and quit the editor. The changes to the trunk/ directory can then be committed to Emdebian SVN:

svn ci -m "adjusted ignore properties" .

You can see the current ignore settings for each directory in the Trac SVN browser at http://buildd.emdebian.org/svn/browser/current/target/trunk/.

Packages with the initial letter 'e' have no automatic svn:ignore properties set - to avoid recursion, svn:ignore will have to be set manually for these packages. (svn is not easy to automate sometimes.)

When using emdebuild, patch files are only committed to SVN if the build completes successfully. Nevertheless, it is recommended that you complete a test build without the --svn option before committing the emdebian patch files. Where a complete rebuild would take too much time, emdebuild includes a shorthand option, --svn-only.

If you specify a single package to emsource, only that portion of the Emdebian SVN tree is checked out. If you want the entire tree, move or rename the 'trunk' directory in your emdebian working directory, then use:

svn co http://buildd.emdebian.org/repos/current/target/trunk

(subversion will complain if previous directories remain). You can then move your previous work into place.

emsource disables automatic SVN handling if the current suite is not unstable. This is because packages built on stable or testing should not be uploaded to the normal target repository, just like in Debian, by default all builds go to unstable and need to be built on unstable. Emdebian currently has neither delayed queues nor security updates and when such methods become available, patches can be uploaded to a branch in SVN rather than the main trunk.

MACHINE:VARIANT CUSTOMISATION

emsource machine:Variant support is experimental! Support will be retained but methods and paths may change.

Machine:variant customisation uses patches stored (or accessible via) your Emdebian working directory, configured via debconf. Patches are only used when the -m option is used. If -V is omitted, the 'default' variant is assumed. The full path to the patches is constructed from the default root path ('$WORK/machine/'), the machine-variant path ('$machine/$variant/') and the package path ('$initial_char/$package_name/') - similar to the path used in the apt repositories and emsource. Use --machine-path to change the default root path - the rest of the patch path is unchanged.

$ emsource -a arm -m balloon -V gpe -c gpe-go
 ...
Checking for customised patches for balloon:gpe
Patch directory: '/opt/emdebian/machine/balloon/gpe/g/gpe-go/'
 ...
$ ls -1 /opt/emdebian/machine/balloon/gpe/g/gpe-go/
emdebian-tweak-desktop.patch
emdebian-fix-prefix.patch
emdebian-replace-ldflags.patch
      

emsource -m does not recurse through subdirectories of the patch directory. Support is modelled on the simple-patchsys system of CDBS - any matching filename in the specified directory is passed to 'patch'.

Patch files should be named in a similar convention to existing Emdebian patch files, matching this regular expression: /^emdebian-.*\.patch$/ and, in the same way as with CDBS, patches can be omitted by simply renaming the file to not comply with the above regular expression, e.g. by removing the .patch suffix.

The intention is to allow '$WORK/machine' to be a self-contained directory tree which can be stored in your preferred revision control system (e.g. alongside your kernel build) or just as ordinary files. For each machine family and each machine variant, '$WORK/machine' should contain whatever patches may be necessary along with packages.conf and the setup.sh and config.sh scripts to provide a fully customised system, based on Emdebian, for your specific machine variant.

Machine:variant patches will need ongoing maintenance. The downside of this customisation is the need for continuing updates of the patches. Emdebian will change our patches according to changes in the Debian package and customised patches need to be applied on top of the Emdebian patches. This extra maintenance means that machine:variant patches are only worthwhile in specific circumstances where the default Emdebian package simply will not work on a specific machine or machine variant without the patch. Please coordinate with the debian-embedded mailing list to see if the Emdebian default package can be adapted to your needs.

One way to handle patching patches is to keep a copy of the file in question in the relevant patch directory beneath $WORK/machine along with a copy of (or symlink to) the patched file in the build directory, then refresh the patch with:

$ diff -u package-version/file.old package-version/file > emdebian-mycustomchange.patch
    

emsource-m will ignore the other files and only use the emdebian-.*\.patch file.

Remember to copy the directory hierarchy so that patch can work with the correct strip option (-p1) - patches should be created as if running diff from the directory above the top source directory.

To avoid inadvertently committing machine specific changes into the main Emdebian SVN, emdebuild --svn or --svn-only will abort without making the commit until emsource -c is run without using -m.

Automated builds

Watch the emsource output for emdebian patches that fail to apply. emdebian-changelog.patch will always fail to apply if a new Debian version exists, emsource -b will handle this situation. If other emdebian patch files fail to apply, the build may fail. Clean up the results of the failed build and then 'cd' into the emsource directory to fix the build. (i.e. repeat the previous emsource command, replacing -b with -c.)

FILES

Most emdebian-tools use configuration data from apt-cross and dpkg-cross. emsource also supports configuration using debconf to set a subversion username and default working directory for unpacking source downloads. Default debconf values can be overridden with user-specific values using ~/.apt-cross/emsource.

Author

emsource was written by Neil Williams <codehelp@debian.org>.

This manual page was written by Neil Williams <codehelp@debian.org>

SEE ALSO

See also apt-cross (1), emsetup (1), emdebuild (1), dpkg-cross (1), em_make (1), emdebian-tools (1).