emsource

Langue: en

Version: Sun 11 Jan 2009 19:55:45 GMT (debian - 07/07/09)

Section: 1 (Commandes utilisateur)

NAME

emsource - get Debian source, create and apply emdebian patches using subversion.

SYNOPSIS

emsource [[-u] | [--username] STRING] [[-a] | [--arch] ARCH] [[-m] | [--machine] NAME] [[-V] | [--variant] NAME] [[--machine-path] NAME] [[-v] | [--verbose]] [[-q] | [--quiet]] PACKAGE
emsource [[-u] | [--username] STRING] [[-a] | [--arch] ARCH] [[-m] | [--machine] NAME] [[-V] | [--variant] NAME] [[--machine-path] NAME] [[-v] | [--verbose]] [[-q] | [--quiet]] {-c|--clean} PACKAGE
emsource [[-u] | [--username] STRING] [[-a] | [--arch] ARCH] [[-m] | [--machine] NAME] [[-V] | [--variant] NAME] [[--machine-path] NAME] [[--build-dep]] [[-v] | [--verbose]] [[-q] | [--quiet]] {-b|--build} PACKAGE [[--]OPTIONS]
emsource [[-u] | [--username] STRING] [[-a] | [--arch] ARCH] [[-m] | [--machine] NAME] [[-V] | [--variant] NAME] [[--machine-path] NAME] [[-v] | [--verbose]] [[-q] | [--quiet]] {-p |--chroot} PACKAGE [[--]OPTIONS]
emsource [[-a] | [--arch] ARCH] [[-v] | [--verbose]] [[-q] | [--quiet]] {--where|--where-is} PACKAGE
emsource [[-a] | [--arch] ARCH] [[-v] | [--verbose]] [[-q] | [--quiet]] {--status} PACKAGE
emsource [[-h] | [--help]] [[--version]]

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.

-c|--clean PACKAGE

Attempts to unwind a damaged or broken emsource directory.
All emdebian patch files are replaced with the current SVN versions, the $package.old pristine backup and the $package-$version unpacked source are removed. The package source files are then refreshed using apt-get and backed up to a replacement $package.old directory. The Emdebian patch files are checked for errors against the fresh source and applied if possible.
Always use the --clean before filing bugs against PACKAGE about a failed crossbuild. When filing bugs, please use the 'crossbuilt' usertag:
 $ bts user codehelp@debian.org , usertag NUMBER crossbuilt
     
 

-b|--build PACKAGE

Attempts to run an automated 'emdebuild' immediately after cleaning the emsource directory for 'PACKAGE'. You will remain in the previous working directory so ensure that you 'cd' to the relevant location before trying to upload the package or fix the build.
If you start an automated build within the build directory of the package itself, your current working directory will be removed and you may get unusual errors from your shell when viewing the results of the build. Always 'cd ../' up to the f/foo/trunk/ directory if running an automated build of the same package.

-p|--chroot PACKAGE

Attempts to run an automated 'empdebuild --build' immediately after cleaning the emsource directory for 'PACKAGE'. You will remain in the previous working directory so ensure that you 'cd' to the relevant location before trying to check or upload the package.
empdebuild does not support the --next option. Automated chroot builds are intended for buildd hosts and any failure in the patches is expected to cause a failure of the build.

--where|--where-is PACKAGE

Checks the supplied PACKAGE name against the apt cache, looking up the source package name if different, reads the cache version and prints the location of the emdebianised source for the requested package, then exits.
Useful when you simply need to cd into the emdebianised source rather than start a build or clean the package.
Example 1.2. Finding the emsource directory
 $ emsource -v --where-is libgpewidget-dev
 Using libgpewidget as source package for libgpewidget-dev (0.115)
 Working directory: '/opt/emdebian/'
 libgpewidget is located in: '/opt/emdebian/trunk/l/libgpewidget/trunk/libgpewidget-0.115/'
             
 

--status PACKAGE

Checks for the emdebianised source for the specified package and prints some status information if the package has been built on this machine. Information includes the location of the source, full paths to all Emdebian build logs and .changes files as well as details of any uploads made. Also includes the number of emdebian patch files found and the number of new debian patches required for the cross build.
If a bug has been filed for cross-building support in Debian for this package, the bug number will be shown with a link to the bug report. Note that bugs reported against the buildd.emdebian.org pseudo-package are not shown - these bugs relate to issues within Emdebian that are not yet compatible with Debian.
Use --verbose to see more information and (if gpg is installed) verify any signature on the .changes file(s).

OPTIONS

-u|--username STRING

Your subversion username at buildd.emdebian.org.
If you already have a valid username and svn commit access within Emdebian, emsource can checkout the emdebian patch files (emdebian-rules.patch, emdebian-changelog.patch, emdebian-control.patch) and emdebuild can commit changes without further intervention. Note that your Emdebian username is not necessarily the same as any Debian username or identity. If you do not (yet) have an Emdebian username, leave this blank. (emsource will use anonymous checkouts of the patch files - changes should be notified by other means.)
Some form of SSH passphrase cache agent is strongly recommended for emsource when a username has been set.
SVN commits via emdebuild are disabled if machine:variant customisations are in use.

--build-dep

Requires--build. Passes the --build-dep option to emdebuild when starting an automated build. Note that this is the default behaviour with emdebuild -p and is useful if you need to build packages within a static chroot instead of the disposable chroot used by emsource -p.
The cross build dependencies will not be removed after the build so this option is not suitable for identifying the cross build dependencies of a new package unless care is taken to remove the cross dependency packages before the next build.

-a|--arch ARCH

Specify the target architecture. Default is set by dpkg-cross using debconf.

-m|--machine NAME

Machine:variant customisation support. See Machine:Variant for full details. $NAME refers to the designated name of a particular machine or family of machines where extra patches need to be applied over the existing Emdebian patches.

-V|--variant NAME

Machine:variant customisation support. See Machine:Variant for full details. $NAME refers to the designated name of a particular variant of a family of machines where extra patches need to be applied over the existing Emdebian patches.

--machine-path PATH

Machine:variant customisation support. See Machine:Variant for full details. $PATH specifies a replacement root path for the patch directory, replacing the default '$WORK/machine/' configured via debconf.

-v|--verbose

be verbose. -v can be repeated to increase verbosity, up to a maximum of three times. When running emsource directly, it is recommended to use at least one -v option.

-q|--quiet

be quiet (default) - can also be used to reduce verbosity set using -v.

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.

Example 1.3. Using machine:variant customisation patches.

If $WORK is set to '/opt/emdebian/' in debconf:

($ sudo dpkg-reconfigure emdebian-tools)

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

/etc/emsource.conf

System-wide configuration file handled by debconf controlling unpacking source archives to a default working directory. Can also include a subversion username setting, intended for single-user installations. /etc/emsource.conf settings can be overridden on a per-user basis by copying the current file to ~/.apt-cross/emsource and editing the values.

Three variables can be set (see also /etc/emsandbox.conf):

username: A valid Emdebian SVN username already configured to provide developer access to the Emdebian subversion repositories. The username is used to checkout and commit changes using SSH. Leave blank to use anonymous SVN.
Some form of SSH passphrase cache agent is strongly recommended for emsource when a username has been set.
aptagent: A boolean choice between command line apt agents; currently either aptitude or the default apt-get, used by emsetup to setup the toolchain packages. Set 'false' to use aptitude.
primary: Generally, this option should not be changed in ~/.apt-cross/emsource. The value is obtained from debconf only if the existing system does not use at least one Debian primary mirror in the available apt sources (excluding the emdebian sources list which is handled separately). If a primary mirror was detected by debconf, this value will be empty. If a primary mirror was not detected, one of the primary mirrors will be specified. The choice of mirror is best modified via sudo dpkg-reconfigure emdebian-tools.

~/.apt-cross/emsource

User-specific version of /etc/emsource.conf, supporting the same variables to provide user-specific overrides.

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

AUTHOR

Emdebian

Neil Williams

Debian and Emdebian developer.