building.php

   1 <?php
   2 include "8440head.php";
   3 ?>
   4
   5
   6
   7 <center>
   8 <h1>
   9 <font color="#931515" size="+3">COMP8440: Build Tips</font>
  10 </h1>
  11 </center>
  12
  13 <h1>What is a package?</h1>
  14
  15 <p>A 'package' contains a set of binaries for a particular program. On
  16 the Ubuntu systems used in the COMP8440 lab, these packages normally
  17 have a filename ending in '.deb'.</p>
  18
  19 <p>Normal users of Ubuntu systems would usually install packages using
  20   the 'package manager' of the system. That can either be done on the
  21   command line using the 'apt-get install' command, or via the
  22   graphical package manager under the System->Administration menu on
  23   your desktop.</p>
  24
  25 <p>In this course you are learning how to participate in FOSS
  26   development, so you will be learning how to build your own packages
  27   from the source code.</p>
  28
  29
  30 <h1>Building a package</h1>
  31
  32 Building a FOSS project can be tricky. You need to work out where
  33 to get the source from, you need to install all the package
  34 dependencies, and you need to sort through the idiosyncrasies of the
  35 packages build system.
  36
  37 <h2>Downloading the source</h2>
  38
  39 There are a number of common ways to get the source code for a FOSS
  40 package. The main ones are:
  41
  42 <ul>
  43 <li>Using the package manager for your distribution</li>
  44 <li>Downloading a release tarball</li>
  45 <li>Downloading via the projects source code management system</li>
  46 </ul>
  47
  48 <h3>Using the package manager</h3>
  49
  50 Nearly all FOSS operating system distributions include a 'package
  51 manager' which allows you to manage what software packages are
  52 installed on your system. On the COMP8440 Ubuntu lab systems the
  53 package manager is called 'apt'.<p>
  54
  55 Most package managers have the ability to ask for the source code
  56 for a particular package to be downloaded. With apt on Ubuntu the
  57 command is:
  58
  59 <pre><b>
  60   apt-get source PACKAGE
  61 </b></pre>
  62
  63 This will typically download 4 things in to the current directory:
  64
  65 <ul>
  66 <li>The original tarball of the upstream package
  67 <li>A .dsc description of the package
  68 <li>A set of compressed patches to the upstream package
  69 <li>An unpacked, patched, version of the package that is ready to
  70 build
  71 </ul>
  72
  73 The original tarball is useful if you want to see what the upstream
  74 maintainer provided (this is usually a copy of the official release
  75 from the package author).<p>
  76
  77 The .dsc file is useful because it contains a text description of the
  78 package, and in particular it contains a list of all of the packages
  79 build dependencies.<p>
  80
  81 The patches show you what changes the distribution made to the package
  82 when including it into the distribution. These changes may be just
  83 cosmetic, or may fix bugs that are not yet fixed in the official
  84 release<p>
  85
  86 The unpacked source is what you will need to actually build the
  87 package yourself. On Debian/Ubuntu systems this contains rules which
  88 tell the system how to build the package. To build the package, run
  89 the following command from within the source directory of the package:
  90
  91 <pre><b>
  92   dpkg-buildpackage
  93 </b></pre>
  94
  95 That will build one or more '.deb' files in the directory above the
  96 source directory. You can install that deb file like this:
  97
  98 <pre><b>
  99   sudo dpkg -i FILENAME.deb
 100 </b></pre>
 101
 102 After that you can use the commands in the package.
 103
 104 When you no longer want the package, you should remove it using:
 105
 106 <pre><b>
 107   sudo apt-get remove PACKAGE
 108 </b></pre>
 109
 110
 111 <h3>Using a release tarball</h3>
 112
 113 Once you find the home page for the package you are interested in, you
 114 can usually find a 'release tarball'. This contains the source code
 115 for an official release of the package.<p>
 116
 117 Once you've unpacked that tarball using something like this:
 118
 119 <pre><b>
 120   tar xvzf package-x.y-z.tar.gz
 121 </b></pre>
 122
 123 You can start looking at the source code. Usually there is a text file
 124 in the top level directory which explains how to build the package, or
 125 there may be build instructions on the packages web site. There are
 126 many variants on how to build FOSS packages, but some common ones are:
 127
 128 <ul>
 129 <li>A configure script, followed by make
 130 <li>A bootstrap.sh script
 131 <li>A autogen.sh script, followed by make
 132 <li>A build.sh script
 133 </ul>
 134
 135 In each case, you will need to install any package dependencies. See
 136 the build dependencies section of this guide.</p>
 137
 138 A typical set of commands to build a package would be:
 139
 140 <pre></b>
 141    ./autogen.sh
 142    ./configure --prefix=$HOME/prefix
 143    make
 144    make install
 145 </b></pre>
 146
 147 That would put the build commands in $HOME/prefix/bin. The above
 148 recipe doesn't work for all packages (for example, many don't have an
 149 autogen.sh script), but it will work for a large number of them. Read
 150 the package documentation for the details of building the package you
 151 are working on.
 152
 153 <h3>Using the source code management system</h3>
 154
 155 Most FOSS projects use a source code management system. When you are
 156 thinking about contributing to a project, this is usually the
 157 preferred way to access the source code, as you will have access to
 158 the latest developments made by other contributors.<p>
 159
 160 There are a wide range of SCMs used by FOSS projects. Some of the more
 161 popular ones are:
 162
 163 <ul>
 164 <li>cvs
 165 <li>git
 166 <li>svn (subversion>
 167 <li>bzr (bazaar)
 168 <li>hg (mercurial)
 169 </ul>
 170
 171 The web site for the project usually gives instructions for how to
 172 download the source code using whichever tool is appropriate.<p>
 173
 174 Some of the projects you will be working on for COMP8440 have very
 175 large source trees, and downloading using a SCM may take a very long
 176 time. To save time, we have put copies of a checked out copy of some
 177 of the larger projects in /comp8440/sources. To grab one of those use
 178 a command like this:
 179
 180 <pre><b>
 181   rsync -av /comp8440/sources/wesnoth .
 182 </b></pre>
 183
 184 Then cd to the directory and use the appropriate SCM to get any
 185 updates. For example, if the project uses svn, then use the command:
 186
 187 <pre><b>
 188   svn update
 189 </b></pre>
 190
 191
 192 <h2>Build Dependencies</h2>
 193
 194 One of the trickier aspects of building a FOSS project can be
 195 installing all of the necessary build dependencies. A build dependency
 196 is another package that must be installed in order to build the
 197 package you want to build.<p>
 198
 199 There are several ways to find and install the build dependencies:
 200
 201 <ul>
 202 <li>Using your package manager
 203 <li>Look at the package documentation
 204 <li>Looking in the dsc file
 205 <li>Trial and error
 206 </ul>
 207
 208 <h3>Using your package manager</h3>
 209
 210 Some package managers have a feature that allows you to automatically
 211 install all the build dependencies for an already packaged project. For
 212 example, on Ubuntu/Debian systems, you can run this:
 213
 214 <pre><b>
 215   sudo apt-get build-dep PACKAGE
 216 </b></pre>
 217
 218 <p>That is a very easy way to get the build dependencies installed. Be
 219 aware though that if you are trying to install a different version
 220 that what the distribution currently has packaged, you may find you
 221 need some additional packages.</p>
 222
 223 <p>Sometimes you may find you need newer packages than what is
 224   currently in Ubuntu Karmic. We have setup the lab machines to allow
 225   you to easily pull packages from the next Ubuntu system, Ubuntu
 226   Lucid, when you need them. To pull in the build dependencies for
 227   package PACKAGE from Lucid use:</p>
 228
 229 <pre><b>
 230   sudo apt-get -t lucid build-dep PACKAGE
 231 </b></pre>
 232
 233
 234 <h3>Looking at the package documentation</h3>
 235
 236 Many FOSS projects have developer information on their web sites which
 237 describes what packages you need to install in order to build the
 238 project. It can sometimes be tricky to match the names in the
 239 documentation to the names of the packages in your distribution. Try
 240 using the synaptic package manager, or doing a google search for what
 241 you are trying to match.
 242
 243 <h3>Looking in the dsc file</h3>
 244
 245 If you downloaded the package source using 'apt-get source' then the
 246 .dsc file should contain a Build-Depends line which lists the packages
 247 that this package depends on. That can be a very good starting point
 248 for what you need to install.
 249
 250 <h3>Trial and error</h3>
 251
 252 This approach is just what it sounds like, and it is often needed in
 253 addition to one of the methods above. You try and build the package,
 254 and you see what errors it gives. You examine the errors and from
 255 there try to work out what dependent packages need to be
 256 installed. Remember that you often want the 'development' version of
 257 the package - so if you have a choice, look for one ending in '-dev'.<p>
 258
 259 The search feature in synaptic, or the command 'apt-cache search' is
 260 very useful in trying to find the right package.
 261
 262 <p><div align="center">
 263   <?php
 264     print " Last modified: ";
 265     $last_modified = getlastmod();
 266     print(date("j/m/Y, H:i", $last_modified));
 267   ?>
 268 </div><p>
 269
 270 <?php
 271 include "8440tail.php";
 272 ?>
 273
 274
 275