summaryrefslogtreecommitdiffstats
path: root/doc/installation/building-packages.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/installation/building-packages.txt')
-rw-r--r--doc/installation/building-packages.txt227
1 files changed, 227 insertions, 0 deletions
diff --git a/doc/installation/building-packages.txt b/doc/installation/building-packages.txt
new file mode 100644
index 000000000..f89b64d9e
--- /dev/null
+++ b/doc/installation/building-packages.txt
@@ -0,0 +1,227 @@
+.. -*- mode: rst -*-
+.. vim: ft=rst
+
+.. _installation-building-packages:
+
+=============================
+Building packages from source
+=============================
+
+Building RPMs
+=============
+
+Building from a tarball
+-----------------------
+
+* Create a directory structure for rpmbuild::
+ rpmdev-setuptree
+
+* Copy the tarball to ``~/rpmbuild/SOURCES/``
+* Extract another copy of it somewhere else (eg: ``/tmp``) and retrieve
+ the ``misc/bcfg2.spec`` file
+* Run the following::
+
+ rpmbuild -ba bcfg2.spec
+
+* The resulting RPMs will be in ``~/rpmbuild/RPMS/`` and SRPMs
+ in ``~/rpmbuild/SRPMS/``.
+
+Building Debian packages
+========================
+
+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).
+
+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 build dependencies::
+
+ apt-get build-dep bcfg2 bcfg2-server
+
+Install source code
+-------------------
+
+Depending on which version of bcfg2 you want build, you can obtain the
+source code from the Download_ page 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 this 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:
+
+.. glossary::
+
+ <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.
+
+External build systems
+----------------------
+
+This section describes how to build bcfg2 and deps via external build
+systems (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 `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
+"""""""""""""""
+
+Setting up gpg-agent and pinentry prevents you from having to type your
+passphrase repeatedly.::
+
+ 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"
+
+upload bcfg2 to ppa
+"""""""""""""""""""
+
+A ``dists`` file contains a space-separated list of all distributions
+you want to build PPA packages for.
+
+.. code-block:: sh
+
+ #!/bin/sh
+
+ . ./dists
+
+ # Replace 0xAA95C349 with your GnuPG Key ID
+ export GPGKEY=0xAA95C349
+
+ sudo apt-get build-dep bcfg2 bcfg2-server
+ sudo aptitude install git
+
+ VERSION=1.3.2-1
+ if [ ! -d testing ]; then
+ mkdir testing
+ fi
+ DATE=$(date +%F-%H%M)
+ ppa="testing" # "testing" or "ppa" (for stable)
+
+ # download source
+ 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
+
+ for dist in $DISTS
+ do
+ cp ../changelog.orig debian/changelog
+ (cd debian && dch --distribution ${dist} \
+ --force-bad-version \
+ --preserve \
+ --force-distribution \
+ --newversion "${VERSION}~${ppa}~${dist}${DATE}+${GITID}" \
+ "bcfg2 backport for ${dist} release ${VERSION} git commit ${GITID}")
+ debuild --no-tgz-check -rfakeroot -I -S -k${GPGKEY}
+ done
+
+ for dist in $DISTS
+ do
+ dput ppa:bcfg2/${dist}testing ../bcfg2_${VERSION}~${ppa}~${dist}${DATE}+${GITID}_source.changes
+ done
+
+.. _Download: http://bcfg2.org/download/
+.. _Bcfg2 in Launchpad: https://launchpad.net/~bcfg2