Changes between Version 14 and Version 15 of BuildingDebianPackages

Timestamp:

09/27/09 22:29:50 (14 years ago)

Author:

mccallis

Comment:

--

BuildingDebianPackages

@@ -2 +2 @@
 
 == Bcfg2 Packaging ==
- * Install packages necessary for building bcfg2 [[BR]]
-   {{{apt-get build-dep bcfg2 bcfg2-server}}} [[BR]]
-    or, if the available repositories do not have any version of bcfg2, try something like: [[BR]] 
-   {{{apt-get install cdbs docbook-xsl libxslt1.1 python-dev python2.4-dev sgml-base xml-core xsltproc fakeroot}}}
- * Untar the sources - or for bleeding edge, {{{svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2}}}
- * cd into the debian/ subdirectory
- * Optional: if you want to have a special name for your own package, edit the first line of changelog: change eg. "(0.9.5.7-0.1)" to "(0.9.5.7-0.1myname)"
- * run ./buildsys-select.sh <python version> [[br]]This will setup the package to install python properly. [[br]]
-   <python version> is either:
-   * 2.3 (for debian sarge), 
-   * 2.4 (for breezy, dapper, and nexenta <= alpha 6)
-   * pycentral (for etch, feisty and edgy, gutsy, hardy). 
-   
- * cd ..
- * run "fakeroot dpkg-buildpackage -uc -us"
- * enjoy your freshly built 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).  The steps to do this, assuming that you are
+running on a Debian/Ubuntu system, are as follows:
+
+=== Install packages necessary for building bcfg2 ===
+
+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 python2.4-dev sgml-base xml-core xsltproc fakeroot
+}}}
+
+=== Install the Bcfg2 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 Subversion
+repository.  To create a local anonymous working copy of the latest
+version of the bcfg2 source code, use a command like the following:
+
+{{{
+svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2 bcfg2-trunk
+}}}
+
+=== Configure the Bcfg2 working copy ===
+
+Once you have a copy of the source code, there are a couple of final
+steps.
+
+First, Bcfg2 as packaged for Debian supports several different
+versions of Python.  To select the appropriate version you will need
+to run the `buildsys-select.sh` script from within the `debian`
+subdirectory.  You must pass it an argument ''<PYTHON_VERSION>'' that
+is one of the following values:
+
+ `2.3`:: for Debian sarge.
+ `2.4`:: for Ubuntu breezy, dapper, and Nexenta <= Alpha 6.
+ `pycentral`::
+    for Debian etch or newer; Ubuntu edgy, feisty, gutsy, and hardy or
+    newer.
+
+As Debian and other related distributions have matured, many of these
+are fading from use and the correct choice for ''<PYTHON_VERSION>'' is
+almost always `pycentral`.
+
+Once you have figured out the correct value for ''<PYTHON_VERSION>'',
+run the following command:
+
+{{{
+cd bcfg2-trunk/debian
+./buildsys-select.sh <PYTHON_VERSION>
+}}}
+
+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>+r<UPSTREAM SVN REV>-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 and the preceding tilde (`~`) character from the
+   package version string.
+ `+<UPSTREAM SVN REV>`::
+   If you are building from a local working copy of the Subversion
+   repository, it is useful to include the repository revision in the
+   package version.  It will be a number like '5464'.  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 5463 of the Subversion
+   trunk, and the latest published version is 1.0pre5, the version
+   string should be `1.0~pre5+r5463-0.1+example1`.
+ * If you are building packages for the published 1.0 rc1 version, the
+   version string should be `1.0~rc1-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 Subversion 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=$(svn info|grep '^Revision' |cut -d' ' -f2)
+debchange --force-bad-version --preserve --newversion "1.0~pre5+r${REV}-0.1+example1" SVN revision $REV
+}}}
+
+=== Building the Bcfg2 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.
+
  
 == Python SSL Backport Packaging ==