clarify tarball vs git builds
[openafs-wiki.git] / AFSLore / HowToBuildOpenAFSFromSource.mdwn
1 This page describes how to build OpenAFS binaries from source code.
2 The information is specific to unix-like systems. See the
3 README-WINDOWS file in the root of the OpenAFS source code tree for
4 instructions and software needed to build OpenAFS on Microsoft Windows.
5
6 Unless otherwise noted, the information on this page is for version 1.6.x
7 (available as pre-release 3 at the time of this writing).
8
9 ## Getting Started
10
11 The following shows how to download a source code tarballs and build the
12 OpenAFS binaries:
13
14     $ wget http://openafs.org/dl/openafs/<version>/openafs-<version>-src.tar.bz2
15     $ wget http://openafs.org/dl/openafs/<version>/openafs-<version>-doc.tar.bz2
16     $ tar xjf openafs-<version>-src.tar.bz2 
17     $ tar xjf openafs-<version>-doc.tar.bz2 
18     $ cd openafs-<version>
19     $ ./configure
20     $ make
21
22 See <http://openafs.org/dl/openafs> for available versions.
23
24 The following shows how to do a git checkout and build the OpenAFS binaries,
25
26     $ git clone git://git.openafs.org/openafs.git
27     $ cd openafs
28     $ git checkout <branch-or-tag>
29     $ ./regen.sh
30     $ ./configure
31     $ make
32
33
34 You will usually want to specify configure options. For example, to enable the
35 traditional Transarc/IBM AFS installation paths, run configure with the
36 --enable-transarc-paths option. (Read on for more information about configure
37 options.)
38
39     $ ./configure --enable-transarc-paths $ make
40     $ make
41     $ make dest 
42
43 See the end of this page for instructions on how to build RPM packages.
44
45 ## Build OpenAFS 
46
47 Building and packaging OpenAFS is not difficult on current unix-like
48 systems. A small number of fairly common libraries and tools are required. The
49 kernel headers and a compiler capable of building a kernel module is needed to
50 build the OpenAFS kernel module (used by the cache manager and for
51 inode-backend fileservers.) The gnu autoconf and automake tools are used to
52 configure the build system, so should be familiar to most people accustomed to
53 building binaries on unix-like systems.
54
55 Begin by verifying you have the prerequisite tools and libraries installed on your
56 build host. These are listed in the next section. You will need to obtain the
57 OpenAFS source code, either by downloading a release tar file, or by checking
58 out a version from the git repository.
59
60 See the README file for details on building OpenAFS and platform specific
61 notes. See src/SOURCE-MAP for a brief description of each source code component.
62
63 A script called regen.sh is used to build the configure script and to
64 generate the man page documentation from perl pod formatted files.
65
66 The configure sets up the build system for your platform. Configure will
67 attempt to detect your platform type and capabilities. Configure will generate
68 the makefiles using automake. You may need to specify configure options to
69 enable certain compile-time features. Run ./configure --help to see a
70 complete list of the available configure options.
71
72 After a successful run of configure, run make in the top level directory to
73 build all the client and server OpenAFS binaries. The server binaries, user and
74 admin tools, and the cache manager can be installed manually if you are not
75 using your systems package manager, for example if you are installing OpenAFS
76 on solaris, or if the target system is being used for testing and development.
77 The installation paths depend on the configure options specified.
78
79 The process for building rpm packages is actually a bit different than what was
80 just described above.  Packaging scripts in the source tree are used to build
81 rpms from a source code tree tar file. You'll need to create two tar files, one
82 of the source and one of the documentation. A script is run to build a source
83 rpm, which can be used to build the various rpm packages.  Details are given
84 below in the section Building RPMs.
85
86 ## Prerequisites
87
88 The following tools are needed to build OpenAFS from source from a tar file:
89
90 - make
91 - compiler
92 - assembler
93 - linker
94 - ranlib
95 - lex/yacc
96 - install
97
98 The following tools are needed to build OpenAFS from source from a git
99 checkout:
100
101 - git
102 - autoconf v2.60 or better
103 - automake
104 - perl v5.6 or better 
105 - make
106 - compiler
107 - assembler
108 - linker
109 - ranlib
110 - lex/yacc
111 - install
112
113 The compiler used must be capable of building kernel modules for the target
114 platform.
115
116 > Note for RHEL users: RedHat Enterprise Linux 5.5 and less shipped with a
117 > version of autoconf too old to generate the OpenAFS configure script.
118 > Fortunately, the recently released RHEL 6.0 shipped with a more up to date
119 > version of autoconf which mets the minimum version needed to generate the
120 > configure script.
121
122 The following tools are needed to build OpenAFS RPMS:
123
124 - perl 5.6 or better
125 - rpmbuild
126
127 The following development libraries are used to build OpenAFS:
128
129 - libc
130 - kerberos 5
131 - ncurses
132 - pam
133 - kernel headers
134
135 The ncurses libraries are needed to build the ncurses based admin tools
136 scout and afsmonitor. The kerberos 5 libraries are needed to build kerberos 5
137 support, which is *strongly* recommended.
138
139 ### Linux Debian Packages
140
141 On a Debian-based linux distribution, all of the required packages can be
142 install with the following commands apt-get commands,
143
144     $ apt-get install git-core autoconf automake make gcc flex bison
145     $ apt-get install libc6-dev libkrb5-dev libncurses5-dev linux-headers-$(uname -r)
146
147 ### Linux RPM Packages
148
149 On a RedHat-based linux distributions, all of the required packages can be
150 installed with the following yum commands,
151
152      $ yum install gcc autoconf automake make flex bison rpm-build
153      $ yum install glibc-devel krb5-devel ncurses-devel pam-devel kernel-devel-$(uname -r)
154
155 ### Solaris Packages
156
157 XXX: Please add the solaris pgk names
158
159
160 ## Getting the Source Code
161
162 See [[GitDevelopers]] for details on how to use git to fetch OpenAFS source
163 code and to submit source code changes to the OpenAFS project. This is the
164 preferred method to retrieve the source code.  Briefly, first create a local
165 clone of the git repository and then checkout a local branch of the version you
166 need to build.  For example,
167
168     $ git clone git://git.openafs.org/openafs.git
169     $ cd openafs
170     $ git checkout openafs-stable-<major>-<minor>-<patchlevel>
171
172 Compressed tar files of the source tree are made available for each stable and
173 development release. The most recent release is located at
174 <http://openafs.org/release/latest.html>.  Archives for releases are located at
175 /afs/openafs.org/software/openafs/ and <http://dl.openafs.org/dl>. For example,
176 to download and uncompress version 1.4.14,
177
178     $ wget http://dl.openafs.org/dl/1.4.14/openafs-1.4.14-src.tar.bz2
179     $ wget http://dl.openafs.org/dl/1.4.14/openafs-1.4.14-doc.tar.bz2
180     $ tar xjf openafs-1.4.14-src.tar.bz2
181     $ tar xjf openafs-1.4.14-doc.tar.bz2
182     $ cd openafs-1.4.14
183
184 The -src archive contains the source code and the -doc archive contains the
185 documentation in xml and pod format. Having a separate archive for
186 documentation allows people working on documentation to download just the pod
187 and xml portions of the project.
188
189 ### Regen
190
191 After a git checkout, run the regen.sh shell script to generate a
192 configure script (and a configure-libafs script) and to generate
193 the man pages. The regen.sh script runs the autoconf tools to
194 generate the configure scripts and runs perl to generate the
195 man pages.
196
197     ./regen.sh
198
199 You can skip the generation of the man pages by specifying the '-q'
200 option to regen.sh.
201
202     ./regen.sh -q
203
204 Always run regen.sh again (and then configure) if you change any of the OpenAFS
205 m4 autoconf macros, such as configure.ac or any of the macros under src/cf.
206
207 ## Configure
208
209 The OpenAFS configure script has many options available. Take some time to read
210 the README file and the output of configure --help before running configure the
211 first time. The most common options are introduced below.
212
213 ### AFS sysname
214
215 AFS uses an identifier called a *sysname* to distinguish platforms. configure
216 will automatically detect the sysname of the build system and by default
217 assumes the target system matches. If you are building for a target system
218 which is different than the build system, or if for some reason the sysname
219 detection fails, you will need to manually specify the sysname with the
220 --with-afs-sysname option.  See the README file for a complete list of sysnames.
221
222 The 'sysname' is also used as the name of the destination sub-directory for the
223 binaries created during the build. This sub-directory is automatically created
224 during the build.
225
226 ### Installation Directory Path Modes
227
228 There are two modes for directory path handling: *Transarc mode* and *default
229 mode*. The mode is selected with the --enable-transarc-paths option.
230
231 Traditionally, AFS server binaries and configuration files are located in the
232 directory /usr/afs and client binaries and configuration files are located in
233 the directory /usr/vice/etc. This convention is known as *Transarc path mode*
234 because it was the convention adopted by Transarc/IBM in the commercial
235 predecessor of OpenAFS.  Use the --enable-transarc-paths configure option to
236 build binaries compatible with the Transarc installation convention.
237
238 When configure is run without the --enable-transarc-paths option, the build
239 system is configured to be in the *default mode*. This mode builds OpenAFS with
240 installation paths more commonly used in open-source projects, for example
241 /usr/local.  The standard configure --prefix option(s) can be used to specify
242 non-default directories.  See the README for details on the type of installation
243 directories and the configure options to set the paths.
244
245 Installation paths are set at build time. Do not mix binaries for the two modes
246 on the same system.
247
248 ### Linux Kernel Headers
249
250 When building on linux, configure will attempt to detect the path to the linux
251 kernel headers.  If this path is not found on the build system, you must
252 specify the path with the --with-linux-kernel-headers option. For example,
253
254     --with-linux-kernel-headers=/usr/src/linux
255
256 ### Kerberos 5 configuration
257
258 The 1.6.0 configure scripts should automatically find the kerberos 5
259 libraries and headers.
260
261 If you need to build 1.4.x, or if the krb5-config file is in a non-standard
262 location, use the --with-krb5-conf option to specify the path to the krb5-config
263 utility (part of the kerberos 5 development package).
264
265     --with-krb5-conf=/usr/bin/krb5-config
266
267
268 ### Debugging Options
269
270 To enable a debugging build, specify the --enable-debug option on the
271 ./configure command line.  This builds with debugging compiler options and
272 disables stripping of binaries.
273
274     --enable-debug                enable compilation of the user space code
275                                      with debugging information
276     --enable-debug-kernel         enable compilation of the kernel module
277                                      with debugging information
278     --enable-checking             Enable compiler warnings when building
279                                     with gcc and treat compiler warnings
280                                     as errors
281
282 ### Feature Options
283
284 There are many configure options for OpenAFS. See the ./configure --help
285 for a complete list and README for more details.  Common options are:
286
287     --enable-bos-restricted-mode  enable bosserver restricted mode 
288                                      which disables certain bosserver functionality
289     --enable-bos-new-config       enable bosserver pickup of BosConfig.new on restarts
290     --enable-namei-fileserver     force compilation of namei fileserver
291                                     in preference to inode fileserver
292                                     on systems were inode is the default
293     --enable-supergroups          enable support for nested pts groups
294                                    WARNING: Once you make use of this option
295                                    by nesting one group inside another,
296                                    the resulting PTS database cannot be correctly
297                                    and safely used by a ptserver built 
298                                    without this option. 
299
300 ### Configure changes in 1.6.0
301
302 If you have been building the 1.5.0 freatures branch, note the following configure
303 options have been removed in 1.6.0. Each feature is now always on, except as noted:
304
305 * --disable-afsdb
306 * --disable-largefile-fileserver
307 * --enable-bos-restricted
308 * --enable-fast-restart (off, but the code is still there)
309 * --disable-full-vos-listvol
310 * --enable-disconnected
311 * --enable-icmp-pmtu-discovery
312 * --enable-demand-attach-fs (see below)
313
314 In 1.5.x, the demand attach fileserver feature was enabld by the a configure
315 switch. Starting in 1.6.0, both DAFS and legacy binaries are built. The
316 DAFS binaries are prefixed with 'da', expect for the new salvageserver, since
317 salvageserver is new with DAFS.
318
319
320 ## Make
321
322 After a successful configure, run make to build OpenAFS. The
323 default target will build all.
324
325     $ make
326
327
328 ## Install
329
330 You can install the OpenAFS binaries outside a package system
331 by copying the binaries. If you built OpenAFS in the default
332 mode (that is without --enable-transarc-paths), run the install
333 target as root to install the binaries.
334
335     $ sudo make install
336
337 If configure was run with --enable-transarc-paths, then run make to build a
338 binary distribution directory, and then manually copy the files as the root
339 user. To install the server and client binaries,
340
341     $ make dest
342     $ cd <sysname>/dest
343     $ sudo mkdir /usr/afs
344     $ sudo mkdir /usr/vice
345     $ sudo mkdir /usr/vice/etc
346     $ sudo cp -p -r root.server/usr/afs/* /usr/afs
347     $ sudo cp -p -r root.client/usr/vice/etc/* /usr/vice/etc
348
349 See the Quick Start Guide for complete instructions to setup
350 the OpenAFS cache manager and servers.
351
352 The 'make dest' command places workstation binaries in the sub-directories of
353 <sysname>/dest: bin, etc, man, lib, include. Optionally, copy these to you
354 local filesystem or install them in an appropriate path in AFS. To install
355 these file into your local filesystem:
356
357     $ sudo mkdir /usr/afsws
358     $ sudo cp -p -r bin /usr/afsws
359     $ sudo cp -p -r etc /usr/afsws
360     $ sudo cp -p -r man /usr/afsws
361     $ sudo cp -p -r lib /usr/afsws
362     $ sudo cp -p -r include /usr/afsws
363
364 See [Storing AFS Binaries in AFS](http://docs.openafs.org/QuickStartUnix/ch02s29.html) for instructions on
365 how to store the workstation binaries in AFS.
366
367 ## Post build
368
369 Some make targets of interest
370
371 - make clean - remove build artifacts
372 - make distclean - remove build and configure artifacts
373 - make tests - make the (old) afs test suite
374
375
376 ## Building RPM packages
377
378 A script is provided to build RPM packages. This script will run the
379 configure and make as part of the process. You'll need to get source
380 and document tar archives of the version you want to build, and then
381 use a script to build the source RPM, then use the rpmbuild tool to
382 build the packages from that source RPM.
383
384 To build OpenAFS RPM packages, use the OpenAFS makesrpm.pl script to build a
385 source RPM, and then use the rpm tool rpmbuild to build the various packages.
386 The makesrpm.pl requires the source and document tar archive files. If you
387 are building from a git repository, first create the source and document
388 archive files.
389
390     $ git clone git://git.sinenomine.net/openafs.git openafs-<version>
391     $ cd openafs-<version>
392     $ git checkout <tagname>
393     $ git describe >.version
394     $ ./regen.sh
395     $ cd ..
396     $ tar cjf openafs-<version>-src.tar.bz2 openafs-<version> --exclude .git --exclude doc
397     $ tar cjf openafs-<version>-doc.tar.bz2 openafs-<version>/doc
398
399 where _version_ is the dotted OpenAFS version number, such as 1.6.0,
400 and _tagname_ is the git tag for the version, such as openafs-stable-1_6_0.
401
402 Next run makesrpm.pl to build the source RPM, and then use rpmbuild to
403 build the binaries and packages. The resulting packages will be located
404 in the $HOME/rpmbuild/RPMS/_arch_ directory.
405
406     $ openafs-<version>/src/packaging/RedHat/makesrpm.pl openafs-<version>-src.tar.bz2 openafs-<version>-doc.tar.bz2
407     $ rpmbuild --rebuild openafs-<version>-1.0.src.rpm
408     $ cd ~/rpmbuild/RPMS/<arch>
409