<?xml version="1.0" encoding="UTF-8"?>
<refentry id="emsource">
  <refentryinfo>
    <productname>emsource</productname>
    <productnumber>1</productnumber>
  </refentryinfo>
  <refmeta>
    <refentrytitle>emsource</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="source">EMDEBIAN-TOOLS</refmiscinfo>
    <refmiscinfo class="manual">EMDEBIAN-TOOLS</refmiscinfo>
  </refmeta>
  <refnamediv id="name">
    <refname>emsource</refname>
    <refpurpose>get Debian source, create and apply emdebian patches using subversion.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>emsource</command>
      <group>
        <arg>-u</arg>
        <arg>--username</arg>
        <replaceable> STRING</replaceable>
      </group>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
        <replaceable> ARCH</replaceable>
      </group>
      <group>
        <arg>-m</arg>
        <arg>--machine</arg>
        <replaceable> NAME</replaceable>
      </group>
      <group>
        <arg>-V</arg>
        <arg>--variant</arg>
        <replaceable> NAME</replaceable>
      </group>
      <group>
        <arg>--machine-path</arg>
        <replaceable> NAME</replaceable>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <replaceable> PACKAGE</replaceable>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>emsource</command>
      <group>
        <arg>-u</arg>
        <arg>--username</arg>
        <replaceable> STRING</replaceable>
      </group>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
        <replaceable> ARCH</replaceable>
      </group>
      <group>
        <arg>-m</arg>
        <arg>--machine</arg>
        <replaceable> NAME</replaceable>
      </group>
      <group>
        <arg>-V</arg>
        <arg>--variant</arg>
        <replaceable> NAME</replaceable>
      </group>
      <group>
        <arg>--machine-path</arg>
        <replaceable> NAME</replaceable>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <arg choice="req">-c|--clean</arg>
      <replaceable> PACKAGE</replaceable>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>emsource</command>
      <group>
        <arg>-u</arg>
        <arg>--username</arg>
        <replaceable> STRING</replaceable>
      </group>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
        <replaceable> ARCH</replaceable>
      </group>
      <group>
        <arg>-m</arg>
        <arg>--machine</arg>
        <replaceable> NAME</replaceable>
      </group>
      <group>
        <arg>-V</arg>
        <arg>--variant</arg>
        <replaceable> NAME</replaceable>
      </group>
      <group>
        <arg>--machine-path</arg>
        <replaceable> NAME</replaceable>
      </group>
      <group>
        <arg>--build-dep</arg>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <arg choice="req">-b|--build</arg>
      <replaceable> PACKAGE</replaceable>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>emsource</command>
      <group>
        <arg>-u</arg>
        <arg>--username</arg>
        <replaceable> STRING</replaceable>
      </group>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
        <replaceable> ARCH</replaceable>
      </group>
      <group>
        <arg>-m</arg>
        <arg>--machine</arg>
        <replaceable> NAME</replaceable>
      </group>
      <group>
        <arg>-V</arg>
        <arg>--variant</arg>
        <replaceable> NAME</replaceable>
      </group>
      <group>
        <arg>--machine-path</arg>
        <replaceable> NAME</replaceable>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <arg choice="req">-p |--chroot</arg>
      <replaceable> PACKAGE</replaceable>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>emsource</command>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
        <replaceable> ARCH</replaceable>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <arg choice="req">--where|--where-is</arg>
      <replaceable> PACKAGE</replaceable>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>emsource</command>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
        <replaceable> ARCH</replaceable>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <arg choice="req">--status</arg>
      <replaceable> PACKAGE</replaceable>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>emsource</command>
      <group>
        <arg>-h</arg>
        <arg>--help</arg>
      </group>
      <group>
        <arg>--version</arg>
      </group>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1 id="description">
    <title>DESCRIPTION</title>
    <para><command>emsource</command> combines the functionality
      of <filename>apt-get source</filename> and <filename>svn checkout</filename>
      to maintain a record of Emdebian changes to Debian packages.
      </para>
    <para><command>emsource</command> supports configuration using
        <filename>debconf</filename> to set a subversion username and default
        working directory for unpacking source downloads. Default debconf values
        in <filename>/etc/emsource.conf</filename> can be overridden by
        user-specific values in <filename>~/.apt-cross/emsource</filename>.
      </para>
    <para>If you get an error about not being able to create a working
    directory for <command>emsource</command>, either reconfigure
    emdebian-tools via debconf:</para>
    <programlisting>
sudo dpkg-reconfigure emdebian-tools
</programlisting>
    <para>Or edit ~/.apt-cross/emsource.</para>
    <para><command>emsource</command> uses <filename>subversion</filename> to
      identify and retrieve the emdebian patch files, whether or not a username
      is specified. <command>emsource</command> is an optional component of
      <filename>emdebian-tools</filename> which does not depend on subversion
      directly. Please ensure that <filename>subversion</filename> is installed
      before using <command>emsource</command>.
      </para>
  </refsect1>
  <refsect1>
    <title>Updating existing Emdebian packages</title>
    <para>When updating an existing emdebian package,
    the <option>-c</option>|<option>--clean</option> option is recommended
    before attempting any automated builds. <filename>emsource</filename> 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 <filename>emsource</filename> will run
    <filename>em_make</filename> to initialise the package and set
    the emdebian version string.
     </para>
    <para>Before beginning to build the updated package, take a look at
    the emdebian patch files - especially if <filename>emdebian-rules.patch</filename>
    was skipped. If you have built the package, check the modified emdebian patch
    files against Emdebian SVN with <computeroutput>svn status ../</computeroutput>.
    Take care not to cause regressions in the package.</para>
    <para>Automated builds are supported but need to be used with care,
    preferably when trying to reproduce a working build in a different
    environment. <option>-b</option>|<option>--build</option> implies
    <option>--clean</option> so that the automated build always uses the
    current SVN patches.
    </para>
  </refsect1>
  <refsect1 id="commands">
    <title>COMMANDS</title>
    <variablelist remap="TP">
      <varlistentry>
        <term><option>-c</option>|<option>--clean</option> PACKAGE</term>
        <listitem>
          <para>Attempts to unwind a damaged or broken emsource directory.
        </para>
          <para>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.
        </para>
          <para>Always use the <option>--clean</option> before filing bugs against
    PACKAGE about a failed crossbuild. When filing bugs, please use the 'crossbuilt' usertag:
    </para>
          <programlisting>
$ bts user codehelp@debian.org , usertag NUMBER crossbuilt
    </programlisting>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-b</option>|<option>--build</option><replaceable> PACKAGE</replaceable></term>
        <listitem>
          <para>Attempts to run an automated 'emdebuild' immediately after cleaning
         the emsource directory for 'PACKAGE'. <emphasis role="bold">You will
         remain in the previous working directory</emphasis> so ensure that you
         'cd' to the relevant location before trying to upload the package or
         fix the build.
         </para>
          <para>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 <computeroutput>'cd ../'</computeroutput> up to the
         <filename>f/foo/trunk/</filename> directory if running an automated build
         of the same package.
         </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-p</option>|<option>--chroot</option><replaceable> PACKAGE</replaceable></term>
        <listitem>
          <para>Attempts to run an automated 'empdebuild --build' immediately after cleaning
         the emsource directory for 'PACKAGE'. <emphasis role="bold">You will
         remain in the previous working directory</emphasis> so ensure that you
         'cd' to the relevant location before trying to check or upload the package.
         </para>
          <para><command>empdebuild</command> does not support the <option>--next</option>
          option. Automated chroot builds are intended for buildd hosts and any
          failure in the patches is expected to cause a failure of the build.
         </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--where</option>|<option>--where-is</option><replaceable> PACKAGE</replaceable></term>
        <listitem>
          <para>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.
          </para>
          <para>Useful when you simply need to <command>cd</command> into the emdebianised source
          rather than start a build or clean the package.
          </para>
          <example id="where-is">
            <title>Finding the emsource directory</title>
            <programlisting>
$ 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/'
            </programlisting>
          </example>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>--status</option>
          <replaceable> PACKAGE</replaceable>
        </term>
        <listitem>
          <para>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.
        </para>
          <para>Use <option>--verbose</option> to see more information and (if gpg is installed)
        verify any signature on the .changes file(s).</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1 id="options">
    <title>OPTIONS</title>
    <variablelist remap="TP">
      <varlistentry>
        <term><option>-u</option>|<option>--username</option> STRING</term>
        <listitem>
          <para>Your subversion username at buildd.emdebian.org.</para>
          <para> If you already have a valid username and svn commit access
            within Emdebian, <command>emsource</command> can checkout
            the <filename>emdebian patch</filename> files
            (<filename>emdebian-rules.patch</filename>,
            <filename>emdebian-changelog.patch</filename>,
            <filename>emdebian-control.patch</filename>) and
            <filename>emdebuild</filename> 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. (<command>emsource</command>
            will use anonymous checkouts of the patch files - changes should be
            notified by other means.)
            </para>
          <para>Some form of SSH passphrase cache agent is strongly recommended
        for <command>emsource</command> when a username has been set.
        </para>
          <para>SVN commits via <command>emdebuild</command> are disabled if machine:variant
        customisations are in use.
        </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>--build-dep</option>
        </term>
        <listitem>
          <para><emphasis>Requires</emphasis><option>--build</option>. Passes the <option>--build-dep</option>
          option to <command>emdebuild</command> when starting an automated build. Note that this is the default
          behaviour with <command>emdebuild</command> <option>-p</option> and is useful if you need to build
          packages within a static chroot instead of the disposable chroot used by <command>emsource</command>
          <option>-p</option>.
          </para>
          <para>The cross build dependencies will <emphasis>not</emphasis> 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.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-a</option>|<option>--arch</option><replaceable> ARCH</replaceable></term>
        <listitem>
          <para>Specify the target architecture.
              Default is set by <filename>dpkg-cross</filename> using debconf.
              </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-m</option>|<option>--machine</option><replaceable> NAME</replaceable></term>
        <listitem>
          <para><emphasis role="bold">Machine:variant customisation support</emphasis>. 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 <emphasis>over</emphasis>
         the existing Emdebian patches.
         </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-V</option>|<option>--variant</option><replaceable> NAME</replaceable></term>
        <listitem>
          <para><emphasis role="bold">Machine:variant customisation support</emphasis>. 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 <emphasis>over</emphasis>
         the existing Emdebian patches.
         </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>--machine-path</option>
          <replaceable> PATH</replaceable>
        </term>
        <listitem>
          <para><emphasis role="bold">Machine:variant customisation support</emphasis>. See
         Machine:Variant for full details. $PATH specifies a replacement root path for the
         patch directory, replacing the default '$WORK/machine/' configured via debconf.
         </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-v</option>|<option>--verbose</option></term>
        <listitem>
          <para>be verbose. <option>-v</option> can be repeated to increase verbosity,
              up to a maximum of three times. When running <command>emsource</command>
              directly, it is recommended to use at least one <option>-v</option> option.
              </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-q</option>|<option>--quiet</option></term>
        <listitem>
          <para>be quiet (default) - can also be used to reduce verbosity set
              using <option>-v</option>.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1 id="svnhandling">
    <title>Emdebian SVN</title>
    <para><command>emsource</command> can work with the Emdebian subversion
           repository to enable coordinated package building. SVN handling by
           <command>emsource</command> and <command>emdebuild</command> is only
           possible if a valid Emdebian SVN username is supplied, either in
           a configuration file (<filename>/etc/emsource.conf</filename> or
           <filename>~/.apt-cross/emsource</filename>) or using <option>-u</option>
           |<option>--username</option>.
           </para>
    <para>Only patch files should be checked into Emdebian SVN. Often, only
           the three emdebian patch files are necessary:
<programlisting>
emdebian-control.patch
emdebian-changelog.patch
emdebian-rules.patch
</programlisting>
        The patch files that are handled automatically by
        <command>emsource</command> and <command>emdebuild --svn</command>.
        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 <filename>debian/patches</filename> that corrects
        the effect of the Debian patch rather than modifying the Debian patch itself.
           </para>
    <para>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 <command>emsource</command>
           for files beginning with the initial letter of the source package. For example,
           in the package <filename>coreutils</filename>, all files beginning with
           <emphasis>c*</emphasis> are ignored. Depending on the package, a common prefix
           to ignore is <emphasis>lib*</emphasis>. 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):
           </para>
    <programlisting>
svn propedit svn:ignore .
</programlisting>
    <para>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 <filename>trunk/</filename>
        directory can then be committed to Emdebian SVN:
        </para>
    <programlisting>
svn ci -m "adjusted ignore properties" .
</programlisting>
    <para>You can see the current ignore settings for each directory in the Trac SVN browser
        at <link url="http://buildd.emdebian.org/svn/browser/current/target/trunk/">
        http://buildd.emdebian.org/svn/browser/current/target/trunk/</link>.
        </para>
    <para>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.)
        </para>
    <para>When using <command>emdebuild</command>, patch files are
           only committed to SVN if the build completes successfully.
           Nevertheless, it is recommended that you complete a test build
           without the <option>--svn</option> option before committing the emdebian
           patch files. Where a complete rebuild would take too much time,
           <filename>emdebuild</filename> includes a shorthand option,
           <option>--svn-only</option>.
           </para>
    <para>If you specify a single package to <command>emsource</command>,
        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:
<programlisting>
svn co http://buildd.emdebian.org/repos/current/target/trunk
</programlisting>
        (subversion will complain if previous directories remain). You can then move
        your previous work into place.
        </para>
    <para><command>emsource</command> 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.
        </para>
  </refsect1>
  <refsect1 id="machinevariant">
    <title>MACHINE:VARIANT CUSTOMISATION</title>
    <para><emphasis role="bold">emsource machine:Variant support is experimental</emphasis>!
    Support will be retained but methods and paths may change.
    </para>
    <para>Machine:variant customisation uses patches stored (or accessible via)
    your Emdebian working directory, configured via debconf. Patches
    are only used when the <option>-m</option> option is used. If <option>-V</option>
    is omitted, the <emphasis>'default'</emphasis> variant is assumed. The full path
    to the patches is constructed from the default root path ('<filename>$WORK/machine/</filename>'),
    the machine-variant path ('<filename>$machine/$variant/</filename>') and the package path
    ('<filename>$initial_char/$package_name/</filename>') - similar to the path used in the
    <command>apt</command> repositories and <command>emsource</command>. Use
    <option>--machine-path</option> to change the default root path - the rest of the
    patch path is unchanged.
    </para>
    <example id="emsourcemachine">
      <title>Using machine:variant customisation patches.</title>
      <para>If <userinput>$WORK</userinput> is set to '<filename>/opt/emdebian/</filename>' in
      <command>debconf</command>:</para>
      <para>(<command>$ sudo dpkg-reconfigure emdebian-tools</command>)</para>
      <programlisting>
$ 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
      </programlisting>
    </example>
    <para><command>emsource -m</command> 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'.
      </para>
    <para>Patch files should be named in a similar convention to existing Emdebian patch
      files, matching this regular expression: <computeroutput>/^emdebian-.*\.patch$/</computeroutput>
      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 <filename>.patch</filename>
      suffix.
    </para>
    <para>The intention is to allow '<filename>$WORK/machine</filename>' 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,
    '<filename>$WORK/machine</filename>' should contain whatever patches may be necessary along
    with <filename>packages.conf</filename> and the <filename>setup.sh</filename> and
    <filename>config.sh</filename> scripts to provide a fully customised system, based on Emdebian,
    for your specific machine variant.
    </para>
    <formalpara>
      <title>Machine:variant patches will need ongoing maintenance.</title>
      <para>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 <emphasis>debian-embedded</emphasis> mailing list
      to see if the Emdebian default package can be adapted to your needs.
      </para>
    </formalpara>
    <para>One way to handle patching patches is to keep a copy of the file in question in the relevant
    patch directory beneath <filename>$WORK/machine</filename> along with a copy of (or symlink to)
    the patched file in the build directory, then refresh the patch with:
    </para>
    <programlisting>
$ diff -u package-version/file.old package-version/file &gt; emdebian-mycustomchange.patch
    </programlisting>
    <para><command>emsource</command><option>-m</option> will ignore the other files and only
    use the <filename>emdebian-.*\.patch</filename> file.
    </para>
    <para>Remember to copy the directory hierarchy so that <command>patch</command> can work with
    the correct strip option (-p1) - patches should be created as if running <command>diff</command>
    from the directory <emphasis role="bold">above</emphasis> the top source directory.
    </para>
    <para>To avoid inadvertently committing machine specific changes into the main Emdebian SVN,
    <command>emdebuild</command> <option>--svn</option> or <option>--svn-only</option> will abort
    without making the commit until <command>emsource</command> <option>-c</option> is run without
    using <option>-m</option>.
    </para>
  </refsect1>
  <refsect1 id="automation">
    <title>Automated builds</title>
    <para>Watch the <filename>emsource</filename> output for emdebian patches that fail
    to apply. <filename>emdebian-changelog.patch</filename> will always fail to apply
    if a new Debian version exists, <command>emsource -b</command> 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
    <option>-b</option> with <option>-c</option>.)
    </para>
  </refsect1>
  <refsect1>
    <title>FILES</title>
    <para>Most <emphasis>emdebian-tools</emphasis> use configuration data from
        <filename>apt-cross</filename> and <filename>dpkg-cross</filename>.
        <command>emsource</command> also supports configuration using
        <filename>debconf</filename> to set a subversion username and default
        working directory for unpacking source downloads. Default debconf values
        can be overridden with user-specific values using
        <filename>~/.apt-cross/emsource</filename>.
        </para>
    <refsect2>
      <title>/etc/emsource.conf</title>
      <para>System-wide configuration file handled by <command>debconf</command>
           controlling unpacking source archives to a default working
           directory. Can also include a subversion username setting, intended for
           single-user installations. <filename>/etc/emsource.conf</filename> settings
           can be overridden on a per-user basis by copying the current file to
           <filename>~/.apt-cross/emsource</filename> and editing the values.
           </para>
      <para>Three variables can be set (see also <filename>/etc/emsandbox.conf</filename>):
           </para>
      <itemizedlist>
        <listitem>
          <para><emphasis>username</emphasis>: 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.</para>
          <para>Some form of SSH passphrase cache agent is strongly recommended
              for <command>emsource</command> when a username has been set.
              </para>
        </listitem>
        <listitem>
          <para><emphasis>aptagent</emphasis>: A boolean choice between command line
        apt agents; currently either <filename>aptitude</filename> or
        the default <filename>apt-get</filename>, used by emsetup to
        setup the toolchain packages. Set 'false' to use aptitude.
        </para>
        </listitem>
        <listitem>
          <para><emphasis>primary</emphasis>: Generally, this option should not be
          changed in <filename>~/.apt-cross/emsource</filename>. 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 <emphasis>not</emphasis>
          detected, one of the primary mirrors will be specified. The choice of
          mirror is best modified via <command>sudo dpkg-reconfigure emdebian-tools</command>.
          </para>
        </listitem>
      </itemizedlist>
    </refsect2>
    <refsect2>
      <title>~/.apt-cross/emsource</title>
      <para>User-specific version of <filename>/etc/emsource.conf</filename>,
          supporting the same variables to provide user-specific overrides.
          </para>
    </refsect2>
  </refsect1>
  <refsect1>
    <title>Author</title>
    <para><command>emsource</command> was written
      by Neil Williams <email>codehelp@debian.org</email>.
    </para>
    <para>This manual page was written by Neil Williams
      <email>codehelp@debian.org</email>
    </para>
  </refsect1>
  <refsect1 id="emsourceseealso">
    <title>SEE ALSO</title>
    <para>See also <filename>apt-cross</filename> (1),
        <filename>emsetup</filename> (1), <filename>emdebuild</filename> (1),
        <filename>dpkg-cross</filename> (1), <filename>em_make</filename> (1),
        <emphasis>emdebian-tools</emphasis> (1).
        </para>
  </refsect1>
</refentry>