debian/README.HowToBuild.txt

   1 How to build the Debian wx packages
   2 ===================================
   3
   4 This file is currently just a brain dump of my experiences with
   5 building the Debian wx packages, based on various experimentations,
   6 and Googling around.  Please don't take anything said here as
   7 authoritative or written in stone.  Although I've been able to get
   8 things to work fairly reliably, I still feel pretty clueless about
   9 some things.
  10
  11
  12 Overview
  13 --------
  14
  15 Contrary to how RPM and other packaging systems work, building Debian
  16 packages is done with an expanded source tree instead of using a
  17 tarball.  Inside the toplevel of the source tree you'll find a subdir
  18 named debian, and within this dir are various files used by the build.
  19 The most important of these are the control file and the rules file.
  20 The control file specifies the metadata about each package, such as
  21 name, description, dependencies, etc.  Interestingly, the version
  22 number of the current build is not in the control file as might be
  23 expected, but is instead taken from the changelog file.  I guess this
  24 is a way for debian to make sure that there is always an updated
  25 changelog for every release, but it is very non-intuitive to say the
  26 least.  The rules file is a Makefile, and is executable with a #! that
  27 runs make on itself.  This lets you execute commands from the toplevel
  28 source dir like:
  29
  30        ./debian/rules build
  31
  32 While theoretically you could build the wx packages directly from your
  33 CVS workspace this won't work (currently) for a couple reasons.
  34 First, the debian/rules file is currently looking at the name of the
  35 toplevel source dir and extracting from it the flavour name (if
  36 present) for use in passing to --with-flavor configure flag.  (I'm
  37 considering changing how it finds this value for 2.7 so, for example,
  38 the debian packages could also be built from the wxPython source
  39 tarball...)  Second, since the build tools use the current source dir
  40 for creating the source package, you'll probably want to start with a
  41 clean source tree that has had unnecessary things removed from it.
  42 There is a Makefile target that will create a minimized and clean
  43 source tree for you, and will name it as debian/rules expects.  To use
  44 it go to a build dir where you've already run configure, and then run:
  45
  46        make debian-dist
  47
  48 This will result in a new source tree with a name like
  49 wxwidgets2.7-2.7.0.0 that is located as a sibling to the toplevel of
  50 the current source tree.
  51
  52
  53 Environment
  54 -----------
  55
  56 The various dpkg helper tools will use some environment settings to
  57 provide default values.  I have these set:
  58
  59        DEBFULLNAME='Robin Dunn'
  60        DEBEMAIL=robin@alldunn.com
  61        DEBSIGN_KEYID='Robin Dunn <robin@alldunn.com>'
  62        DEBUILD_DPKG_BUILDPACKAGE_OPTS='-i -ICVS -I.svn'
  63
  64 Notice the DEBSIGN_KEYID value.  If this is set (and you have a
  65 matching gnupg key) then the packages will be digitally signed when
  66 they are built.
  67
  68 If you are building packages that you intend to be installable on
  69 machines other than your own, then I recommend that you either have a
  70 separate machine with a minimal OS install, or set up a chroot
  71 environment and do the builds there.  The reason for this is to
  72 minimize unexpected extra dependencies that the built packages will
  73 have because of extra things you have installed on your desktop
  74 system, for example OpenGL libs installed by your video card drivers.
  75 Using a chroot will also allow you to build packages for different
  76 versions of Debian (or Ubuntu) if desired.  There is a good
  77 description of setting up a chroot environment here:
  78
  79        https://wiki.ubuntu.com/DebootstrapChroot
  80
  81 In addition to the base system packages, you'll need to install in
  82 the chroot environment any packages needed for building wxWidgets
  83 (compilers, make, autoconf, gtk and image libs, lib-dev's, python,
  84 python-dev, etc.)  as well as the packages listed in the next section.
  85
  86
  87 Build Packages
  88 --------------
  89
  90 There are a number of helper packages that are used when building
  91 debian packages.  Here are some that I have in my chroot, there may be
  92 some others that I am not seeing at the moment:
  93
  94        debhelper
  95        devscripts
  96        dh-make
  97        dpkg-dev
  98        fakeroot
  99        lintian
 100        diff
 101        patch
 102
 103
 104 Doing the Build
 105 ---------------
 106
 107 Ok, if you are not totally confused by this point you should have a
 108 minimal source tree produced by "make debian-dist" that is accessible
 109 by your chroot or other minimal install system. (Unless you are only
 110 making packages for yourself, then doing the build on in your main
 111 desktop environment would  be okay.)  The first step is to chdir to
 112 the top level of this source tree.
 113
 114 If you haven't already you'll want to edit debian/changelog to make an
 115 entry for the current build.  If the version number is changing since
 116 the last build then you'll need a whole new section.  If you are just
 117 updating something in the same version then you can just get by with
 118 editing the current changelog entry.  The 'dch' tool can be used to
 119 open the file in an editor with the cursor positioned for you.  If you
 120 use 'dch -i' then it will create a new changelog entry for you with
 121 the proper syntax.  Don't forget to copy this file back to your CVS
 122 workspace if appropriate.
 123
 124 Our debian/control file is generated from debian/control.in, so you
 125 can force it to be created now by running the following.  You may want
 126 to do this to verify its contents before proceeding with the build.
 127
 128        ./debian/rules debian/control
 129
 130 To run just the compile/link/etc. portions of the build you can do
 131 this:
 132
 133        ./debian/rules build
 134
 135 To also make a set of test binaries you can do this:
 136
 137        fakeroot ./debian/rules binary
 138
 139 To clean up from prior builds you can do this:
 140
 141        fakeroot ./debian/rules clean
 142
 143 And to automate the entire process (build, binaries, source packages,
 144 digital signing, etc.) you can do this:
 145
 146        dpkg-buildpackage -rfakeroot
 147
 148 When finished the binary and source packages will be left in the
 149 parent dir of the source tree.
 150
 151
 152 Automating the process
 153 ----------------------
 154
 155 The script debian/build_all automates the above stepds and builds both
 156 wxWidgets and wxPython packages in both ANSI and Unicode modes. You should do
 157 the build manually at least the first time however to make sure you have all
 158 the prerequisites and the build doesn't fail.
 159
 160
 161 Other Sources of Information
 162 ----------------------------
 163
 164 http://liw.iki.fi/liw/talks/debian-packaging-tutorial.pdf
 165 http://women.alioth.debian.org/wiki/index.php/English/BuildingTutorial
 166 http://women.alioth.debian.org/wiki/index.php/English/AdvancedBuildingTips
 167 http://www.wiggy.net/presentations/2001/DebianWalkThrough/handouts/handouts.html
 168 http://www.debian.org/doc/manuals/maint-guide/index.en.html
 169 http://www.isotton.com/debian/docs/repository-howto/repository-howto.html
 170