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.
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).
11 For the impatient, this section describes how to get a code tree and
12 build it, assuming you have a development environment already setup.
14 The following shows how to download source code tarballs and build the
17 $ wget http://openafs.org/dl/openafs/<version>/openafs-<version>-src.tar.bz2
18 $ wget http://openafs.org/dl/openafs/<version>/openafs-<version>-doc.tar.bz2
19 $ tar xjf openafs-<version>-src.tar.bz2
20 $ tar xjf openafs-<version>-doc.tar.bz2
21 $ cd openafs-<version>
25 See <http://openafs.org/dl/openafs> for available versions.
27 The following shows how to do a git checkout and build the OpenAFS binaries,
29 $ git clone git://git.openafs.org/openafs.git
31 $ git checkout <branch-or-tag>
36 You will usually want to specify configure options. For example, to enable the
37 traditional Transarc/IBM AFS installation paths, run configure with the
38 --enable-transarc-paths option. (Read on for more information about configure
41 $ ./configure --enable-transarc-paths $ make
45 See the end of this page for instructions on how to build RPM packages.
49 Building and packaging OpenAFS is not difficult on current unix-like
50 systems. A small number of fairly common libraries and tools are required. The
51 kernel headers and a compiler capable of building a kernel module is needed to
52 build the OpenAFS kernel module (used by the cache manager and for
53 inode-backend fileservers.) The gnu autoconf and automake tools are used to
54 configure the build system, so should be familiar to most people accustomed to
55 building binaries on unix-like systems.
57 Begin by verifying you have the prerequisite tools and libraries installed on your
58 build host. These are listed in the next section. You will need to obtain the
59 OpenAFS source code, either by downloading a release tar file, or by checking
60 out a version from the git repository.
62 See the README file for details on building OpenAFS and platform specific
63 notes. See src/SOURCE-MAP for a brief description of each source code component.
65 A script called regen.sh is used to build the configure script and to
66 generate the man page documentation from perl pod formatted files.
68 The configure sets up the build system for your platform. Configure will
69 attempt to detect your platform type and capabilities. Configure will generate
70 the makefiles using automake. You may need to specify configure options to
71 enable certain compile-time features. Run ./configure --help to see a
72 complete list of the available configure options.
74 After a successful run of configure, run make in the top level directory to
75 build all the client and server OpenAFS binaries. The server binaries, user and
76 admin tools, and the cache manager can be installed manually if you are not
77 using your systems package manager, for example if you are installing OpenAFS
78 on solaris, or if the target system is being used for testing and development.
79 The installation paths depend on the configure options specified.
81 The process for building rpm packages is actually a bit different than what was
82 just described above. Packaging scripts in the source tree are used to build
83 rpms from a source code tree tar file. You'll need to create two tar files, one
84 of the source and one of the documentation. A script is run to build a source
85 rpm, which can be used to build the various rpm packages. Details are given
86 below in the section Building RPMs.
90 The following tools are needed to build OpenAFS from source from a tar file:
99 - perl 5.6 or better (only to build the documention)
101 In addtion to the above, the following tools are needed to build OpenAFS
105 - autoconf 2.60 or better
108 The compiler used must be capable of building kernel modules for the target
111 > Note for RHEL users: RedHat Enterprise Linux 5.5 and less shipped with a
112 > version of autoconf too old to generate the OpenAFS configure script.
113 > Fortunately, the recently released RHEL 6.0 shipped with a more up to date
114 > version of autoconf which mets the minimum version needed to generate the
117 The following tools are needed to build OpenAFS RPMS:
122 The following development libraries are needed:
126 - ncurses (optional, needed to build scout/afsmonitor)
130 The ncurses libraries are needed to build the ncurses based admin tools
131 scout and afsmonitor. The kerberos 5 libraries are needed to build kerberos 5
132 support, which is *strongly* recommended.
134 ### Linux Debian Packages
136 On a Debian 6, the required packages can be install with the following commands apt-get commands,
138 $ apt-get install git autoconf automake make gcc flex bison
139 $ apt-get install libc6-dev libkrb5-dev libncurses5-dev linux-headers-$(uname -r)
141 ### Linux RPM Packages
143 On a RedHat-based linux distributions, all of the required packages can be
144 installed with the following yum commands,
146 $ yum install git-core gcc autoconf automake make flex bison rpm-build
147 $ yum install glibc-devel krb5-devel ncurses-devel pam-devel kernel-devel-$(uname -r)
151 For Solaris packages, start by installing pkg-get, if you have not already.
153 $ wget http://www.opencsw.org/pkg-get
154 $ pkgadd -d /path/to/pkg-get
155 $ wget --output-document=/tmp/gpg.key http://www.opencsw.org/get-it/mirrors/
156 $ gpg --import /tmp/gpg.key
158 Check to make sure pkg-get is installed properly by doing a pkg-get compare.
159 It should output a list of installed packages compared to up-to-date remote packages.
161 With pkg-get installed, go ahead and begin installing the necessary packages
163 $ pkg-get install gcc flex bison automake autoconf gmake
164 $ pkg-get install krb5_kdc ncurses
166 ## Getting the Source Code
168 See [[GitDevelopers]] for details on how to use git to fetch OpenAFS source
169 code and to submit source code changes to the OpenAFS project. This is the
170 preferred method to retrieve the source code. Briefly, first create a local
171 clone of the git repository and then checkout a local branch of the version you
172 need to build. For example,
174 $ git clone git://git.openafs.org/openafs.git
176 $ git checkout openafs-stable-<major>-<minor>-<patchlevel>
178 Compressed tar files of the source tree are made available for each stable and
179 development release. The most recent release is located at
180 <http://openafs.org/release/latest.html>. Archives for releases are located at
181 /afs/openafs.org/software/openafs/ and <http://dl.openafs.org/dl>. For example,
182 to download and uncompress version 1.4.14,
184 $ wget http://dl.openafs.org/dl/1.4.14/openafs-1.4.14-src.tar.bz2
185 $ wget http://dl.openafs.org/dl/1.4.14/openafs-1.4.14-doc.tar.bz2
186 $ tar xjf openafs-1.4.14-src.tar.bz2
187 $ tar xjf openafs-1.4.14-doc.tar.bz2
190 The -src archive contains the source code and the -doc archive contains the
191 documentation in xml and pod format. Having a separate archive for
192 documentation allows people working on documentation to download just the pod
193 and xml portions of the project.
197 After a git checkout, run the regen.sh shell script to generate a
198 configure script (and a configure-libafs script) and to generate
199 the man pages. The regen.sh script runs the autoconf tools to
200 generate the configure scripts and runs perl to generate the
205 You can skip the generation of the man pages by specifying the '-q'
210 Always run regen.sh again (and then configure) if you change any of the OpenAFS
211 m4 autoconf macros, such as configure.ac or any of the macros under src/cf.
215 The OpenAFS configure script has many options available. Take some time to read
216 the README file and the output of configure --help before running configure the
217 first time. The most common options are introduced below.
221 AFS uses an identifier called a *sysname* to distinguish platforms. configure
222 will automatically detect the sysname of the build system and by default
223 assumes the target system matches. If you are building for a target system
224 which is different than the build system, or if for some reason the sysname
225 detection fails, you will need to manually specify the sysname with the
226 --with-afs-sysname option. See the README file for a complete list of sysnames.
228 The 'sysname' is also used as the name of the destination sub-directory for the
229 binaries created during the build. This sub-directory is automatically created
232 ### Installation Directory Path Modes
234 There are two modes for directory path handling: *Transarc mode* and *default
235 mode*. The mode is selected with the --enable-transarc-paths option.
237 Traditionally, AFS server binaries and configuration files are located in the
238 directory /usr/afs and client binaries and configuration files are located in
239 the directory /usr/vice/etc. This convention is known as *Transarc path mode*
240 because it was the convention adopted by Transarc/IBM in the commercial
241 predecessor of OpenAFS. Use the --enable-transarc-paths configure option to
242 build binaries compatible with the Transarc installation convention.
244 When configure is run without the --enable-transarc-paths option, the build
245 system is configured to be in the *default mode*. This mode builds OpenAFS with
246 installation paths more commonly used in open-source projects, for example
247 /usr/local. The standard configure --prefix option(s) can be used to specify
248 non-default directories. See the README for details on the type of installation
249 directories and the configure options to set the paths.
251 Installation paths are set at build time. Do not mix binaries for the two modes
254 ### Linux Kernel Headers
256 When building on linux, configure will attempt to detect the path to the linux
257 kernel headers. If this path is not found on the build system, you must
258 specify the path with the --with-linux-kernel-headers option. For example,
260 --with-linux-kernel-headers=/usr/src/linux
262 ### Kerberos 5 configuration
264 The 1.6.0 configure scripts should automatically find the kerberos 5
265 libraries and headers.
267 If you need to build 1.4.x, or if the krb5-config file is in a non-standard
268 location, use the --with-krb5-conf option to specify the path to the krb5-config
269 utility (part of the kerberos 5 development package).
271 --with-krb5-conf=/usr/bin/krb5-config
274 ### Debugging Options
276 To enable a debugging build, specify the --enable-debug option on the
277 ./configure command line. This builds with debugging compiler options and
278 disables stripping of binaries.
280 --enable-debug enable compilation of the user space code
281 with debugging information
282 --enable-debug-kernel enable compilation of the kernel module
283 with debugging information
284 --enable-checking Enable compiler warnings when building
285 with gcc and treat compiler warnings
290 There are many configure options for OpenAFS. See the ./configure --help
291 for a complete list and README for more details. Common options are:
293 --enable-bos-restricted-mode enable bosserver restricted mode
294 which disables certain bosserver functionality
295 --enable-bos-new-config enable bosserver pickup of BosConfig.new on restarts
296 --enable-namei-fileserver force compilation of namei fileserver
297 in preference to inode fileserver
298 on systems were inode is the default
299 --enable-supergroups enable support for nested pts groups
300 WARNING: Once you make use of this option
301 by nesting one group inside another,
302 the resulting PTS database cannot be correctly
303 and safely used by a ptserver built
306 ### Configure changes in 1.6.0
308 If you have been building the 1.5.0 freatures branch, note the following configure
309 options have been removed in 1.6.0. Each feature is now always on, except as noted:
312 * --disable-largefile-fileserver
313 * --enable-bos-restricted
314 * --enable-fast-restart (off, but the code is still there)
315 * --disable-full-vos-listvol
316 * --enable-disconnected
317 * --enable-icmp-pmtu-discovery
318 * --enable-demand-attach-fs (see below)
320 In 1.5.x, the demand attach fileserver feature was enabld by the a configure
321 switch. Starting in 1.6.0, both DAFS and legacy binaries are built. The
322 DAFS binaries are prefixed with 'da', expect for the new salvageserver, since
323 salvageserver is new with DAFS.
328 After a successful configure, run make to build OpenAFS. The
329 default target will build all.
336 You can install the OpenAFS binaries outside a package system
337 by copying the binaries. If you built OpenAFS in the default
338 mode (that is without --enable-transarc-paths), run the install
339 target as root to install the binaries.
343 If configure was run with --enable-transarc-paths, then run make to build a
344 binary distribution directory, and then manually copy the files as the root
345 user. To install the server and client binaries,
349 $ sudo mkdir /usr/afs
350 $ sudo mkdir /usr/vice
351 $ sudo mkdir /usr/vice/etc
352 $ sudo cp -p -r root.server/usr/afs/* /usr/afs
353 $ sudo cp -p -r root.client/usr/vice/etc/* /usr/vice/etc
355 See the Quick Start Guide for complete instructions to setup
356 the OpenAFS cache manager and servers.
358 The 'make dest' command places workstation binaries in the sub-directories of
359 <sysname>/dest: bin, etc, man, lib, include. Optionally, copy these to you
360 local filesystem or install them in an appropriate path in AFS. To install
361 these file into your local filesystem:
363 $ sudo mkdir /usr/afsws
364 $ sudo cp -p -r bin /usr/afsws
365 $ sudo cp -p -r etc /usr/afsws
366 $ sudo cp -p -r man /usr/afsws
367 $ sudo cp -p -r lib /usr/afsws
368 $ sudo cp -p -r include /usr/afsws
370 See [Storing AFS Binaries in AFS](http://docs.openafs.org/QuickStartUnix/ch02s29.html) for instructions on
371 how to store the workstation binaries in AFS.
375 Some make targets of interest
377 - make clean - remove build artifacts
378 - make distclean - remove build and configure artifacts
379 - make tests - make the (old) afs test suite
382 ## Building RPM packages
384 A script called makesrpm.pl is provided to build a source RPM package. You can
385 use the generated source RPM to build the binaries and create the RPM packages
386 for your source code tree of OpenAFS.
388 The first step is to create a source tree of OpenAFS. Run the regen.sh script
389 to build the docs and to generate the configure script. Also, use git describe
390 to make a version stamp file which will be used by the packaging process. This
391 example shows how to get a source tree from a remote git repo.
393 $ git clone git://git.openafs.org/openafs.git openafs-<version>
394 $ cd openafs-<version>
395 $ git checkout <tagname>
396 $ git describe >.version
399 The _version_ is the dotted OpenAFS version number, such as 1.6.0,
400 and the _tagname_ is the git tag for the version, such as openafs-stable-1_6_0.
401 The _version_ number for pre-releases are suffixed with pre<number>. For example,
402 to build 1.6.0pre5, create a directory called openafs-1.6.0pre5.
404 Next, create a source RPM file. This requires creating a tar file for the
405 source files and a tar file for the documents. Run the makesrpm program
406 to generate an OpenAFS source RPM.
408 $ cd .. # move out of the source tree
409 $ tar cjf openafs-<version>-src.tar.bz2 openafs-<version> --exclude .git --exclude doc
410 $ tar cjf openafs-<version>-doc.tar.bz2 openafs-<version>/doc
411 $ openafs-<version>/src/packaging/RedHat/makesrpm.pl openafs-<version>-src.tar.bz2 openafs-<version>-doc.tar.bz2
413 At this point you should have a source RPM called openafs-<version>-1.0.src.rpm. See the makesrpm.pl for additional options.
414 The source tree and tar files are no longer needed.
416 Finally, run rpmbuild to build the build binary RPM packages. If all goes well, the final
417 output will show the destination directory and an exit code of zero.
419 $ rpmbuild --rebuild openafs-<version>-1.0.src.rpm
421 + cd /usr/src/redhat/BUILD
422 + rm -rf openafs-<version>
425 Alternatively, the source RPM may be installed, which will place the sources in the
426 rpm SOURCE directory and a spec file in the rpm SPEC directory.