using "diff old new" is preferred
[tridge/comp8440.git] / 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 'aptitude 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 aptitude 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 aptitude 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 <h3>Looking at the package documentation</h3>
224
225 Many FOSS projects have developer information on their web sites which
226 describes what packages you need to install in order to build the
227 project. It can sometimes be tricky to match the names in the
228 documentation to the names of the packages in your distribution. Try
229 using the synaptic package manager, or doing a google search for what
230 you are trying to match.
231
232 <h3>Looking in the dsc file</h3>
233
234 If you downloaded the package source using 'apt-get source' then the
235 .dsc file should contain a Build-Depends line which lists the packages
236 that this package depends on. That can be a very good starting point
237 for what you need to install. 
238
239 <h3>Trial and error</h3>
240
241 This approach is just what it sounds like, and it is often needed in
242 addition to one of the methods above. You try and build the package,
243 and you see what errors it gives. You examine the errors and from
244 there try to work out what dependent packages need to be
245 installed. Remember that you often want the 'development' version of
246 the package - so if you have a choice, look for one ending in '-dev'.<p>
247
248 The search feature in synaptic, or the command 'apt-cache search' is
249 very useful in trying to find the right package.
250
251 <p><div align="center">
252   <?php
253     print " Last modified: ";
254     $last_modified = getlastmod();
255     print(date("j/m/Y, H:i", $last_modified));
256   ?>
257 </div><p>
258
259 <?php
260 include "8440tail.php";
261 ?>
262
263
264