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    ./configure --prefix=$HOME/prefix
 142    make
 143    make install
 144 </b></pre>
 145
 146 That would put the build commands in $HOME/prefix/bin. The above
 147 recipe doesn't work for all packages, but it will work for a large
 148 number of them. Read the package documentation for the details of
 149 building the package you are working on.
 150
 151 <h3>Using the source code management system</h3>
 152
 153 Most FOSS projects use a source code management system. When you are
 154 thinking about contributing to a project, this is usually the
 155 preferred way to access the source code, as you will have access to
 156 the latest developments made by other contributors.<p>
 157
 158 There are a wide range of SCMs used by FOSS projects. Some of the more
 159 popular ones are:
 160
 161 <ul>
 162 <li>cvs
 163 <li>git
 164 <li>svn (subversion>
 165 <li>bzr (bazaar)
 166 <li>hg (mercurial)
 167 </ul>
 168
 169 The web site for the project usually gives instructions for how to
 170 download the source code using whichever tool is appropriate.<p>
 171
 172 Some of the projects you will be working on for COMP8440 have very
 173 large source trees, and downloading using a SCM may take a very long
 174 time. To save time, we have put copies of a checked out copy of some
 175 of the larger projects in /comp8440/sources. To grab one of those use
 176 a command like this:
 177
 178 <pre><b>
 179   rsync -av /comp8440/sources/wesnoth .
 180 </b></pre>
 181
 182 Then cd to the directory and use the appropriate SCM to get any
 183 updates. For example, if the project uses svn, then use the command:
 184
 185 <pre><b>
 186   svn update
 187 </b></pre>
 188
 189
 190 <h2>Build Dependencies</h2>
 191
 192 One of the trickier aspects of building a FOSS project can be
 193 installing all of the necessary build dependencies. A build dependency
 194 is another package that must be installed in order to build the
 195 package you want to build.<p>
 196
 197 There are several ways to find and install the build dependencies:
 198
 199 <ul>
 200 <li>Using your package manager
 201 <li>Look at the package documentation
 202 <li>Looking in the dsc file
 203 <li>Trial and error
 204 </ul>
 205
 206 <h3>Using your package manager</h3>
 207
 208 Some package managers have a feature that allows you to automatically
 209 install all the build dependencies for an already packaged project. For
 210 example, on Ubuntu/Debian systems, you can run this:
 211
 212 <pre><b>
 213   sudo apt-get build-dep PACKAGE
 214 </b></pre>
 215
 216 <p>That is a very easy way to get the build dependencies installed. Be
 217 aware though that if you are trying to install a different version
 218 that what the distribution currently has packaged, you may find you
 219 need some additional packages.</p>
 220
 221 <p>Sometimes you may find you need newer packages than what is
 222   currently in Ubuntu Karmic. We have setup the lab machines to allow
 223   you to easily pull packages from the next Ubuntu system, Ubuntu
 224   Lucid, when you need them. To pull in the build dependencies for
 225   package PACKAGE from Lucid use:</p>
 226
 227 <pre><b>
 228   sudo apt-get -t lucid build-dep PACKAGE
 229 </b></pre>
 230
 231
 232 <h3>Looking at the package documentation</h3>
 233
 234 Many FOSS projects have developer information on their web sites which
 235 describes what packages you need to install in order to build the
 236 project. It can sometimes be tricky to match the names in the
 237 documentation to the names of the packages in your distribution. Try
 238 using the synaptic package manager, or doing a google search for what
 239 you are trying to match.
 240
 241 <h3>Looking in the dsc file</h3>
 242
 243 If you downloaded the package source using 'apt-get source' then the
 244 .dsc file should contain a Build-Depends line which lists the packages
 245 that this package depends on. That can be a very good starting point
 246 for what you need to install.
 247
 248 <h3>Trial and error</h3>
 249
 250 This approach is just what it sounds like, and it is often needed in
 251 addition to one of the methods above. You try and build the package,
 252 and you see what errors it gives. You examine the errors and from
 253 there try to work out what dependent packages need to be
 254 installed. Remember that you often want the 'development' version of
 255 the package - so if you have a choice, look for one ending in '-dev'.<p>
 256
 257 The search feature in synaptic, or the command 'apt-cache search' is
 258 very useful in trying to find the right package.
 259
 260 <p><div align="center">
 261   <?php
 262     print " Last modified: ";
 263     $last_modified = getlastmod();
 264     print(date("j/m/Y, H:i", $last_modified));
 265   ?>
 266 </div><p>
 267
 268 <?php
 269 include "8440tail.php";
 270 ?>
 271
 272
 273