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 building
7 the OpenAFS master branch or the OpenAFS stable releases (currently
14 For the impatient, this section describes how to get a code tree and
15 build it, assuming you have a development environment already setup.
17 The following shows how to download source code tarballs and build the
20 $ wget http://openafs.org/dl/openafs/<version>/openafs-<version>-src.tar.bz2
21 $ wget http://openafs.org/dl/openafs/<version>/openafs-<version>-doc.tar.bz2
22 $ tar xjf openafs-<version>-src.tar.bz2
23 $ tar xjf openafs-<version>-doc.tar.bz2
24 $ cd openafs-<version>
28 See [openafs downloads](http://openafs.org/dl/openafs) for available versions.
30 The following shows how to do a git checkout and build the OpenAFS binaries,
32 $ git clone git://git.openafs.org/openafs.git
34 $ git checkout <branch-or-tag>
39 You will usually want to specify configure options. For example, to enable the
40 traditional Transarc/IBM AFS installation paths, run configure with the
41 --enable-transarc-paths option. (Read on for more information about configure
44 $ ./configure --enable-transarc-paths --enable-checking --enable-debug
48 This will build the binaries and place them in the <platform>/dest
49 directories, that is, the Transarc-style binary distribution directory layout.
51 See [[how to build OpenAFS RPM packages|HowToBuildOpenAFSRpmPackages]] for
52 instructions on how to build RPM packages.
56 Building and packaging OpenAFS is not difficult on current unix-like
57 systems. A small number of fairly common libraries and tools are required. The
58 kernel headers and a compiler capable of building a kernel module is needed to
59 build the OpenAFS kernel module (used by the cache manager and for
60 inode-backend fileservers.) The gnu autoconf and automake tools are used to
61 configure the build system, so should be familiar to most people accustomed to
62 building binaries on unix-like systems.
64 Begin by verifying you have the prerequisite tools and libraries installed on your
65 build host. These are listed in the next section. You will need to obtain the
66 OpenAFS source code, either by downloading a release tar file, or by checking
67 out a version from the git repository.
69 See the README file for details on building OpenAFS and platform specific
70 notes. See src/SOURCE-MAP for a brief description of each source code component.
72 A script called regen.sh is used to build the configure script and to
73 generate the man page documentation from perl pod formatted files.
75 The configure sets up the build system for your platform. Configure will
76 attempt to detect your platform type and capabilities. Configure will generate
77 the makefiles using automake. You may need to specify configure options to
78 enable certain compile-time features. Run ./configure --help to see a
79 complete list of the available configure options.
81 After a successful run of configure, run make in the top level directory to
82 build all the client and server OpenAFS binaries. The server binaries, user and
83 admin tools, and the cache manager can be installed manually if you are not
84 using your systems package manager, for example if you are installing OpenAFS
85 on solaris, or if the target system is being used for testing and development.
86 The installation paths depend on the configure options specified.
88 The process for building rpm packages is actually a bit different than what was
89 just described above. Packaging scripts in the source tree are used to build
90 rpms from a source code tree tar file. You'll need to create two tar files, one
91 of the source and one of the documentation. A script is run to build a source
92 rpm, which can be used to build the various rpm packages. Details are given
93 on the page [[How to build OpenAFS RPM packages|HowToBuildOpenAFSRpmPackages]].
97 The following tools are needed to build OpenAFS from source from a tar file:
106 - perl 5.6 or better (only to build the documention)
108 In addition to the above, the following tools are needed to build OpenAFS
113 - autoconf 2.60 or better
116 The compiler used must be capable of building kernel modules for the target
119 > Note for RHEL users: RedHat Enterprise Linux 5.5 and less shipped with a
120 > version of autoconf too old to generate the OpenAFS configure script.
121 > Fortunately, the recently released RHEL 6.0 shipped with a more up to date
122 > version of autoconf which mets the minimum version needed to generate the
125 The following tools are needed to build OpenAFS RPMS:
130 The following development libraries are needed:
134 - ncurses (optional, needed to build scout/afsmonitor)
138 The ncurses libraries are needed to build the ncurses based admin tools
139 scout and afsmonitor. The kerberos 5 libraries are needed to build kerberos 5
140 support, which is *strongly* recommended.
142 ### Linux Debian Packages ###
144 On a Debian 6, the required packages can be install with the following commands apt-get commands,
146 $ apt-get install git libtool autoconf automake make gcc flex bison
147 $ apt-get install libc6-dev libkrb5-dev libncurses5-dev linux-headers-$(uname -r)
149 ### Linux RPM Packages ###
151 On a RedHat-based linux distributions, all of the required packages can be
152 installed with the following yum commands,
154 $ yum install git-core gcc autoconf automake make flex bison rpm-build
155 $ yum install glibc-devel krb5-devel ncurses-devel pam-devel kernel-devel-$(uname -r)
157 ### Solaris Packages ###
159 [Oracle Solaris Studio][1] can be used to build OpenAFS binaries on the
160 solaris platform. Solaris Studio is freely available for the solaris and linux
161 platforms with a no-cost Oracle Technology Network (OTN) account. Follow the
162 package installer instructions for your platform type and version.
164 [1]: http://www.oracle.com/technetwork/server-storage/solarisstudio
166 The OpenAFS build process requires the `gencat` program. Verify
167 `/usr/bin/gencat` is available, otherwise install the `SUNWloc` package.
169 $ sudo pkg install SUNWloc
171 The [OpenCSW][2] project provides software packages for solaris which can be
172 easily installed. Follow the [OpenCSW getting started][3] instructions to
173 setup the `pkgutil` package manager tool.
175 [2]: http://www.opencsw.org
176 [3]: http://www.opencsw.org/manual/for-administrators/getting-started.html
178 Update your path to include `/opt/csw/bin`.
180 With `pkgutil` installed, install the necessary packages;
182 $ sudo pkgutil -y --install git
183 $ sudo pkgutil -y --install gmake flex bison gsed automake autoconf libtool
184 $ sudo pkgutil -y --install libkrb5_dev libncurses_dev
187 ## Getting the Source Code ##
189 See [[GitDevelopers]] for details on how to use git to fetch OpenAFS source
190 code and to submit source code changes to the OpenAFS project. This is the
191 preferred method to retrieve the source code. Briefly, first create a local
192 clone of the git repository and then checkout a local branch of the version you
193 need to build. For example,
195 $ git clone git://git.openafs.org/openafs.git
197 $ git checkout openafs-stable-<major>-<minor>-<patchlevel>
199 Compressed tar files of the source tree are made available for each stable and
200 development release. The most recent release is located at
201 <http://openafs.org/release/latest.html>. Archives for releases are located at
202 /afs/openafs.org/software/openafs/ and <http://dl.openafs.org/dl>. For example,
203 to download and uncompress version 1.4.14,
205 $ wget http://dl.openafs.org/dl/1.4.14/openafs-1.4.14-src.tar.bz2
206 $ wget http://dl.openafs.org/dl/1.4.14/openafs-1.4.14-doc.tar.bz2
207 $ tar xjf openafs-1.4.14-src.tar.bz2
208 $ tar xjf openafs-1.4.14-doc.tar.bz2
211 The -src archive contains the source code and the -doc archive contains the
212 documentation in xml and pod format. Having a separate archive for
213 documentation allows people working on documentation to download just the pod
214 and xml portions of the project.
218 After a git checkout, run the regen.sh shell script to generate a
219 configure script (and a configure-libafs script) and to generate
220 the man pages. The regen.sh script runs the autoconf tools to
221 generate the configure scripts and runs perl to generate the
226 You can skip the generation of the man pages by specifying the '-q'
231 Always run regen.sh again (and then configure) if you change any of the OpenAFS
232 m4 autoconf macros, such as configure.ac or any of the macros under src/cf.
236 The OpenAFS configure script has many options available. Take some time to read
237 the README file and the output of configure --help before running configure the
238 first time. The most common options are introduced below.
242 AFS uses an identifier called a *sysname* to distinguish platforms. configure
243 will automatically detect the sysname of the build system and by default
244 assumes the target system matches. If you are building for a target system
245 which is different than the build system, or if for some reason the sysname
246 detection fails, you will need to manually specify the sysname with the
247 --with-afs-sysname option. See the README file for a complete list of sysnames.
249 The 'sysname' is also used as the name of the destination sub-directory for the
250 binaries created during the build. This sub-directory is automatically created
253 ### Installation Directory Path Modes
255 There are two modes for directory path handling: *Transarc mode* and *default
256 mode*. The mode is selected with the --enable-transarc-paths option.
258 Traditionally, AFS server binaries and configuration files are located in the
259 directory /usr/afs and client binaries and configuration files are located in
260 the directory /usr/vice/etc. This convention is known as *Transarc path mode*
261 because it was the convention adopted by Transarc/IBM in the commercial
262 predecessor of OpenAFS. Use the --enable-transarc-paths configure option to
263 build binaries compatible with the Transarc installation convention.
265 When configure is run without the --enable-transarc-paths option, the build
266 system is configured to be in the *default mode*. This mode builds OpenAFS with
267 installation paths more commonly used in open-source projects, for example
268 /usr/local. The standard configure --prefix option(s) can be used to specify
269 non-default directories. See the README for details on the type of installation
270 directories and the configure options to set the paths.
272 Installation paths are set at build time. Do not mix binaries for the two modes
275 ### Linux Kernel Headers
277 When building on linux, configure will attempt to detect the path to the linux
278 kernel headers. If this path is not found on the build system, you must
279 specify the path with the --with-linux-kernel-headers option. For example,
281 --with-linux-kernel-headers=/usr/src/linux
283 ### Kerberos 5 configuration
285 The 1.6.0 configure scripts should automatically find the kerberos 5
286 libraries and headers.
288 If you need to build 1.4.x, or if the krb5-config file is in a non-standard
289 location, use the --with-krb5-conf option to specify the path to the krb5-config
290 utility (part of the kerberos 5 development package).
292 --with-krb5-conf=/usr/bin/krb5-config
295 ### Debugging Options ###
297 To enable a debugging build, specify the --enable-debug option on the
298 ./configure command line. This builds with debugging compiler options and
299 disables stripping of binaries.
301 --enable-debug enable compilation of the user space code
302 with debugging information
303 --enable-debug-kernel enable compilation of the kernel module
304 with debugging information
305 --enable-checking Enable compiler warnings when building
306 with gcc and treat compiler warnings
309 ### Feature Options ###
311 There are many configure options for OpenAFS. See the ./configure --help
312 for a complete list and README for more details. Common options are:
314 --enable-bos-restricted-mode enable bosserver restricted mode
315 which disables certain bosserver functionality
316 --enable-bos-new-config enable bosserver pickup of BosConfig.new on restarts
317 --enable-namei-fileserver force compilation of namei fileserver
318 in preference to inode fileserver
319 on systems were inode is the default
320 --enable-supergroups enable support for nested pts groups
321 WARNING: Once you make use of this option
322 by nesting one group inside another,
323 the resulting PTS database cannot be correctly
324 and safely used by a ptserver built
327 ### Configure changes in 1.6.0 ###
329 If you have been building the 1.5.0 freatures branch, note the following configure
330 options have been removed in 1.6.0. Each feature is now always on, except as noted:
333 * --disable-largefile-fileserver
334 * --enable-bos-restricted
335 * --enable-fast-restart (off, but the code is still there)
336 * --disable-full-vos-listvol
337 * --enable-disconnected
338 * --enable-icmp-pmtu-discovery
339 * --enable-demand-attach-fs (see below)
341 In 1.5.x, the demand attach fileserver feature was enabld by the a configure
342 switch. Starting in 1.6.0, both DAFS and legacy binaries are built. The
343 DAFS binaries are prefixed with 'da', expect for the new salvageserver, since
344 salvageserver is new with DAFS.
349 After a successful configure, run make to build OpenAFS. The
350 default target will build all.
357 You can install the OpenAFS binaries outside a package system
358 by copying the binaries. If you built OpenAFS in the default
359 mode (that is, without --enable-transarc-paths), run the install
360 target as root to install the binaries.
364 If configure was run with --enable-transarc-paths, then run make to build a
365 binary distribution directory, and then manually copy the files as the root
366 user. To install the server and client binaries,
370 $ sudo mkdir /usr/afs
371 $ sudo mkdir /usr/vice
372 $ sudo mkdir /usr/vice/etc
373 $ sudo cp -p -r root.server/usr/afs/* /usr/afs
374 $ sudo cp -p -r root.client/usr/vice/etc/* /usr/vice/etc
376 See the Quick Start Guide for complete instructions to setup
377 the OpenAFS cache manager and servers.
379 The 'make dest' command places workstation binaries in the sub-directories of
380 <sysname>/dest: bin, etc, man, lib, include. Optionally, copy these to you
381 local filesystem or install them in an appropriate path in AFS. To install
382 these file into your local filesystem:
384 $ sudo mkdir /usr/afsws
385 $ sudo cp -p -r bin /usr/afsws
386 $ sudo cp -p -r etc /usr/afsws
387 $ sudo cp -p -r man /usr/afsws
388 $ sudo cp -p -r lib /usr/afsws
389 $ sudo cp -p -r include /usr/afsws
391 See [Storing AFS Binaries in AFS](http://docs.openafs.org/QuickStartUnix/ch02s29.html) for instructions on
392 how to store the workstation binaries in AFS.
396 Some make targets of interest
398 - make clean - remove build artifacts
399 - make distclean - remove build and configure artifacts
400 - make tests - make the (old) afs test suite