2 include "8440head.php";
9 <font color="#931515" size="+3">COMP8440: Build Tips</font>
13 <h1>What is a package?</h1>
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>
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
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>
30 <h1>Building a package</h1>
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.
37 <h2>Downloading the source</h2>
39 There are a number of common ways to get the source code for a FOSS
40 package. The main ones are:
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>
48 <h3>Using the package manager</h3>
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>
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
60 apt-get source PACKAGE
63 This will typically download 4 things in to the current directory:
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
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>
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>
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
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:
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:
99 sudo dpkg -i FILENAME.deb
102 After that you can use the commands in the package.
104 When you no longer want the package, you should remove it using:
107 sudo apt-get remove PACKAGE
111 <h3>Using a release tarball</h3>
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>
117 Once you've unpacked that tarball using something like this:
120 tar xvzf package-x.y-z.tar.gz
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:
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
135 In each case, you will need to install any package dependencies. See
136 the build dependencies section of this guide.</p>
138 A typical set of commands to build a package would be:
141 ./configure --prefix=$HOME/prefix
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.
151 <h3>Using the source code management system</h3>
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>
158 There are a wide range of SCMs used by FOSS projects. Some of the more
169 The web site for the project usually gives instructions for how to
170 download the source code using whichever tool is appropriate.<p>
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
179 rsync -av /comp8440/sources/wesnoth .
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:
190 <h2>Build Dependencies</h2>
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>
197 There are several ways to find and install the build dependencies:
200 <li>Using your package manager
201 <li>Look at the package documentation
202 <li>Looking in the dsc file
206 <h3>Using your package manager</h3>
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:
213 sudo apt-get build-dep PACKAGE
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>
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>
228 sudo apt-get -t lucid build-dep PACKAGE
232 <h3>Looking at the package documentation</h3>
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.
241 <h3>Looking in the dsc file</h3>
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.
248 <h3>Trial and error</h3>
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>
257 The search feature in synaptic, or the command 'apt-cache search' is
258 very useful in trying to find the right package.
260 <p><div align="center">
262 print " Last modified: ";
263 $last_modified = getlastmod();
264 print(date("j/m/Y, H:i", $last_modified));
269 include "8440tail.php";