[[PageOutline]]

= Building Debian Packages =


== Bcfg2 Packaging ==

The Bcfg2 project provides a `debian` subdirectory with the project's source that enables users to create their own Debian/Ubuntu compatible packages (`.deb` files).  The steps to do this, assuming that you are running on a Debian/Ubuntu system, are as follows:

=== Build deps ===

If the distribution you are building on already has packaged bcfg2 (even an older version), the following command will likely install the necessary packages to enable it to be built:

{{{
apt-get build-dep bcfg2 bcfg2-server
}}}

Or, if the available repositories do not have any version of bcfg2, try something like:

{{{
apt-get install cdbs docbook-xsl libxslt1.1 python-dev sgml-base xml-core xsltproc fakeroot
}}}

=== Install source code ===

Depending on which version of bcfg2 you want build, you can obtain the source code from [wiki:Download] or from the project's git
repository.  To create a local anonymous working copy of the latest version of the bcfg2 source code, use a command like the following:

{{{
git clone git://git.mcs.anl.gov/bcfg2.git
}}}

=== Update the changelog ===

The next step is to update the Debian `changelog` file with an appropriate package version string.  Debian packages contain a version
that is extracted from the latest entry in the `changelog` file.  An appropriate version will help you distinguish your locally built
package from one provided by your distribution.  It also helps the packaging system know when a newer version of the package is available to install.

It is possible to skip this step, but the packages you build will have the same version as the source distribution and will be easy to
confuse with other similarly named (but maybe not equivalent) packages.

The basic format of the package version string to use is this:

  {{{<UPSTREAM VER>~<UPSTREAM PRE-VER>+<GIT-ID>-0.1+<LOCAL VER>}}}

'''NOTE: The '+', and '-' characters have significance in determining when one package is newer than another.  The following format is believed to do the right thing in all common situations.'''

The components of the package version string are explained below:

 `<UPSTREAM VER>`::
   This is the version of the Bcfg source code you are working from. It will likely be something like `0.9.6` or `1.0`.
 `<UPSTREAM PRE-VER>`::
   If you are using a published pre-release of Bcfg2, it will have a name like `pre1` or `rc1`.  Use that string here, otherwise drop this component from the package version string.
 `+<GIT-ID>`::
   If you are building from a local working copy of the git repository, it is useful to include the revision in the package version. If you are building from a downloaded copy of the source, drop this component (including the preceding plus-sign (`+`) from the package version string.
 `+<LOCAL VER>`::
   This is a locally relevant name like your last name or your domain name, plus the digit `1`.  For example, if your family name is ''Smith'', you could use `smith1`.  If you work for ''Example Inc'', you could use `example1`.

Here are some examples:

 * If you are building packages for revision 6c681bd from git, and the latest published version is 1.2.0rc1, the version string should be `1.2.0rc1+6c681bd-0.1+example1`.
 * If you are building packages for the published 1.0 rc1 version, the version string should be `1.0rc1-0.1+example1`.
 * If you are building packages for the published 1.0 version, the version string should be `1.0-0.1+example1`.

If you are working on a git working copy of 1.0 pre5 and have the `devscripts` package installed, the following command is a convenient way to create a well formatted changelog entry:

{{{
REV=$(git log --oneline | head -n 1 | cut -d' ' -f1)
debchange --force-bad-version --preserve --newversion "1.0~pre5+${REV}-0.1+example1" git revision $REV
}}}

=== Building the package ===

With the preliminaries out of the way, building the package is simple.

{{{
cd ..  # Change into the top level of the source directory
fakeroot dpkg-buildpackage -uc -us
}}}

The freshly built packages will be deposited in the parent of the current directory (`..`).  Examine the output of `dpkg-buildpackage` for details.

== Backport Packaging ==

Bcfg2 uses some newer packages which need to be backported to most debian-based GNU/Linux distributions. In most cases you'll need to have these working before doing the above Bcfg2 packaging.

=== debhelper ===

Bcfg2 1.0.0rc2 and later require debhelper 7.0.50 or later.

Versions that work are in:
 * '''debian''': lenny-backports, squeeze, sid
 * '''ubuntu''': karmic, lucid

=== python-ssl ===

To run bcfg2-server 1.0.0 and later on platforms with python 2.5 and earlier, you'll need a python-ssl backport.

As of Bcfg2 1.0.0, Bcfg2 has switched to the in-tree ssl module included with python 2.6. A backport exists for 2.3, 2.4, and 2.5. The ssl module can be found [http://pypi.python.org/pypi/ssl here]. See [wiki:Authentication] for details. 

There is packaging for python-ssl in the bcfg2 trunk. Do: 

{{{
sudo aptitude install python-all-dev fakeroot python-setuptools libssl-dev debhelper python-support \
                      subversion libbluetooth-dev 
wget http://pypi.python.org/packages/source/s/ssl/ssl-1.15.tar.gz#md5=81ea8a1175e437b4c769ae65b3290e0c
tar xvfz ssl-1.15.tar.gz
mv ssl-1.15 python-ssl-1.15
cd python-ssl-1.15
svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2/misc/python-ssl-1.15/debian
dpkg-buildpackage -rfakeroot -uc -us
sudo dpkg -i ../python-ssl_1.15-1_*.deb
}}}

=== sqlalchemy ===

For the bcfg2-server 1.0 snapshots reporting feature, you need SQLAlchemy 0.5 or later.

== External build systems ==

This section describes how to build bcfg2 and deps via external build system. Currently only a PPA. Some other possibilities are:
 * #651 Look into project-builder to make more native-system bcfg2 packages available
 * http://en.opensuse.org/Build_Service/Deb_builds

=== Launchpad PPA ===

 * https://launchpad.net/~bcfg2

To upload to the PPA you need to be on the active member list of [https://launchpad.net/~bcfg2 Bcfg2 in Launchpad].

Note that '''after each successful upload''', you should wait until the PPA is built, and then '''install it locally''' using "sudo aptitude update; sudo aptitude install (packagename)" so the next build doesn't fail on your local machine. If you don't want to wait for a PPA binary build to complete, you can "apt-get source (packagename)" and do a local build before the PPA build is done.	

==== setup gpg-agent ====

So you won't be prompted for your passphrase a whole bunch of times...
{{{
sudo aptitude install gnupg-agent pinentry-gtk2 pinentry-curses
# replace 0xAA95C349 with your GPG Key ID
export GPGKEY=0xAA95C349
killall -q gpg-agent
eval $(gpg-agent --daemon)
}}}

==== setup debuild ====

Tell dpkg-buildpackage who you are, for example:
{{{
export DEBEMAIL="dclark@pobox.com"
export DEBFULLNAME="Daniel Joseph Barnhart Clark"
}}}

==== setup dput ====

Make a ~/.dput.cf file:
{{{
[bcfg2-force-hardy]
fqdn = ppa.launchpad.net
method = ftp
incoming = ~bcfg2/ppa/ubuntu/hardy
login = anonymous
allow_unsigned_uploads = 0

[bcfg2-force-lucid]
fqdn = ppa.launchpad.net
method = ftp
incoming = ~bcfg2/ppa/ubuntu/lucid
login = anonymous
allow_unsigned_uploads = 0

[bcfg2-force-maverick]
fqdn = ppa.launchpad.net
method = ftp
incoming = ~bcfg2/ppa/ubuntu/maverick
login = anonymous
allow_unsigned_uploads = 0

[bcfg2-force-natty]
fqdn = ppa.launchpad.net
method = ftp
incoming = ~bcfg2/ppa/ubuntu/natty
login = anonymous
allow_unsigned_uploads = 0

[bcfg2-testing-force-hardy]
fqdn = ppa.launchpad.net
method = ftp
incoming = ~bcfg2/hardytesting/ubuntu/hardy
login = anonymous
allow_unsigned_uploads = 0

[bcfg2-testing-force-lucid]
fqdn = ppa.launchpad.net
method = ftp
incoming = ~bcfg2/lucidtesting/ubuntu/lucid
login = anonymous
allow_unsigned_uploads = 0

[bcfg2-testing-force-maverick]
fqdn = ppa.launchpad.net
method = ftp
incoming = ~bcfg2/mavericktesting/ubuntu/maverick
login = anonymous
allow_unsigned_uploads = 0

[bcfg2-testing-force-natty]
fqdn = ppa.launchpad.net
method = ftp
incoming = ~bcfg2/nattytesting/ubuntu/natty
login = anonymous
allow_unsigned_uploads = 0
}}}

==== bcfg2 ====

===== upload debhelper =====

Upload:
{{{
#!/bin/sh -x

sudo apt-get build-dep debhelper

wget https://edge.launchpad.net/~ressu/+archive/bcfg2-backport/+files/debhelper_7.0.52.dsc
wget https://edge.launchpad.net/~ressu/+archive/bcfg2-backport/+files/debhelper_7.0.52.tar.gz
dpkg-source -x debhelper_7.0.52.dsc
cd debhelper-7.0.52
cp debian/changelog debian/changelog.orig
ppa="testing" # "testing" or "ppa" (for stable)
try="1"

for dist in hardy intrepid jaunty; do
cp debian/changelog.orig debian/changelog
(cd debian && debchange --force-bad-version --preserve --newversion \
"7.0.52~${ppa}${try}~${dist}${try}" \
backport to ppa ${ppa}, dist ${dist}, try ${try})
# Replace 0xAA95C349 to your GnuPG Key ID
debuild -S -k0xAA95C349
dput bcfg2-testing-force-${dist} ../debhelper_7.0.52~${ppa}${try}~${dist}${try}_source.changes
done
}}}

And then make sure it's installed locally for the next step.

===== upload bcfg2 =====

Upload:
{{{
#!/bin/sh -x

sudo apt-get build-dep bcfg2 bcfg2-server
sudo aptitude install git

VERSION=1.2.3-1
cd testing
git clone git://git.mcs.anl.gov/bcfg2
cd bcfg2
GITID=$(git log --oneline | head -n 1 | cut -d' ' -f1)
cp debian/changelog ../changelog.orig
ppa="testing" # "testing" or "ppa" (for stable)
try="1"
attempt="1"

for dist in hardy lucid maverick natty oneiric precise; do
    cp ../changelog.orig debian/changelog
    (cd debian && debchange --distribution ${dist} --force-bad-version --preserve --newversion \
    "${VERSION}~${ppa}${try}~${dist}${attempt}+${GITID}" \
    backport to ppa ${ppa}, dist ${dist}, try ${try}, attepmt ${attempt}, git commit ${GITID})
    # Replace 0xAA95C349 to your GnuPG Key ID
    debuild -rfakeroot -S -k0xAA95C349
done
for dist in hardy lucid maverick natty oneiric precise; do
    dput ppa:bcfg2/${dist}testing ../bcfg2_${VERSION}~${ppa}${try}~${dist}${attempt}+${GITID}_source.changes
done
}}}

==== bcfg2-server snapshots ====

The new 1.0.0 snapshots reporting feature needs a newer sqlalchemy than is included with some distributions.

===== upload sqlalchemy =====

Upload:
{{{
#!/bin/sh -x

sudo apt-get build-dep sqlalchemy

wget http://backports.org/debian/pool/main/s/sqlalchemy/sqlalchemy_0.5.6-1~bpo50+1.dsc
wget http://backports.org/debian/pool/main/s/sqlalchemy/sqlalchemy_0.5.6.orig.tar.gz
wget http://backports.org/debian/pool/main/s/sqlalchemy/sqlalchemy_0.5.6-1~bpo50+1.diff.gz
dpkg-source -x sqlalchemy_0.5.6-1~bpo50+1.dsc
cd sqlalchemy-0.5.6
cp debian/changelog debian/changelog.orig
ppa="testing" # "testing" or "ppa" (for stable)
try="1"

for dist in hardy intrepid jaunty; do
cp debian/changelog.orig debian/changelog
(cd debian && debchange --force-bad-version --preserve --newversion \
"0.5.6-1~${ppa}${try}~${dist}${try}" \
backport to ppa ${ppa}, dist ${dist}, try ${try})
# Replace 0xAA95C349 to your GnuPG Key ID
debuild -S -k0xAA95C349
dput bcfg2-testing-force-${dist} ../sqlalchemy_0.5.6-1~${ppa}${try}~${dist}${try}_source.changes
done
}}}

==== bcfg2-server + python <= 2.5 ====

To run on GNU/Linux distributions that do not ship with python 2.6 or newer, you need the python-ssl backport.

===== upload python-ssl =====

Upload:
{{{
#!/bin/sh -x

sudo aptitude install patch python-setuptools libssl-dev debhelper devscripts dput \
                      python-setuptools python-all-dev libssl-dev libbluetooth-dev

wget https://launchpad.net/~bcfg2/+archive/hardytesting/+files/python-ssl_1.15-1~testing102~hardy102.dsc
wget https://launchpad.net/~bcfg2/+archive/hardytesting/+files/python-ssl_1.15-1~testing102~hardy102.tar.gz

dpkg-source -x python-ssl_1.15-1~testing102~hardy102.dsc
cd python-ssl-1.15

cp debian/changelog debian/changelog.orig
ppa="testing" # "testing" or "ppa" (for stable)
try="1"

for dist in hardy intrepid; do
cp debian/changelog.orig debian/changelog
(cd debian && debchange --force-bad-version --preserve --newversion \
"1.15-1~${ppa}${try}~${dist}${try}" \
backport to ppa ${ppa}, dist ${dist}, try ${try})
# Replace 0xAA95C349 to your GnuPG Key ID
debuild -S -sa -k0xAA95C349 # Using -sa here because we need .orig.tar.gz file
dput bcfg2-testing-force-${dist} ../python-ssl_1.15-1~${ppa}${try}~${dist}${try}_source.changes
done
}}}