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