Minor grammar fixes
[openafs-wiki.git] / archive / 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 building
7 the OpenAFS master branch or the OpenAFS stable releases (currently
8 the 1.6.x series).
9
10 [[!toc levels=3]]
11
12 # The Short Version #
13
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.
16
17 The following shows how to download source code tarballs and build the
18 OpenAFS binaries:
19
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>
25     $ ./configure
26     $ make
27
28 See [openafs downloads](http://openafs.org/dl/openafs) for available versions.
29
30 The following shows how to do a git checkout and build the OpenAFS binaries,
31
32     $ git clone git://git.openafs.org/openafs.git
33     $ cd openafs
34     $ git checkout <branch-or-tag>
35     $ ./regen.sh
36     $ ./configure
37     $ make
38
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
42 options.)
43
44     $ ./configure --enable-transarc-paths --enable-checking --enable-debug
45     $ make
46     $ make dest
47
48 This will build the binaries and place them in the &lt;platform&gt;/dest
49 directories, that is, the Transarc-style binary distribution directory layout.
50
51 See [[how to build OpenAFS RPM packages|HowToBuildOpenAFSRpmPackages]] for
52 instructions on how to build RPM packages.
53
54 # Building OpenAFS #
55
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.
63
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.
68
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.
71
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.
74
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.
80
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.
87
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]].
94
95 ## Prerequisites ##
96
97 The following tools are needed to build OpenAFS from source from a tar file:
98
99 - make
100 - compiler
101 - assembler
102 - linker
103 - ranlib
104 - lex/yacc
105 - install
106 - perl 5.6 or better (only to build the documention)
107
108 In addition to the above, the following tools are needed to build OpenAFS
109 from a git checkout:
110
111 - git
112 - autoconf 2.60 or better
113 - automake
114 - libtool
115
116 The compiler used must be capable of building kernel modules for the target
117 platform.
118
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
123 > configure script.
124
125 The following tools are needed to build OpenAFS RPMS:
126
127 - perl 5.6 or better
128 - rpmbuild
129
130 The following development libraries are needed:
131
132 - libc
133 - kerberos 5
134 - perl
135 - ncurses (optional, needed to build scout/afsmonitor)
136 - pam (optional)
137 - libfuse (optional)
138 - kernel headers
139
140 The ncurses libraries are needed to build the ncurses based admin tools
141 scout and afsmonitor. The kerberos 5 libraries are needed to build kerberos 5
142 support, which is *strongly* recommended.
143
144 ### Linux Debian Packages ###
145
146 On recent versions of Debian, use the apt-get build-dep command to install the needed
147 build dependencies,
148
149     $ sudo apt-get build-dep openafs
150     $ sudo apt-get install linux-headers-$(uname -r)
151
152 On a Debian 6, the required packages can be install with the following commands apt-get commands,
153
154     $ sudo apt-get install git autoconf automake libtool make gcc flex bison \
155       libc6-dev libkrb5-dev libperl-dev libncurses5-dev libfuse-dev \
156       linux-headers-$(uname -r)
157
158 ### Linux RPM Packages ###
159
160 On a RedHat-based linux distributions, all of the required packages can be
161 installed with the following yum commands,
162
163      $ sudo yum install git-core gcc autoconf automake libtool make flex bison
164      $ sudo yum install glibc-devel krb5-devel perl-devel ncurses-devel pam-devel kernel-devel-$(uname -r)
165      $ sudo yum install perl-devel perl-ExtUtils-Embed
166
167 The following additional packages are needed to [[build RPM packages|HowToBuildOpenAfsRpmPackages]].
168
169      $ sudo yum install wget rpm-build redhat-rpm-config
170
171 ### Solaris Packages ###
172
173 [Oracle Solaris Studio][1] can be used to build OpenAFS binaries on the
174 solaris platform. Solaris Studio is freely available for the solaris and linux
175 platforms with a no-cost Oracle Technology Network (OTN) account.  For recent
176 versions of Solaris, use the `pkg' command to install Solaris Studio.  Follow the
177 package installer instructions on the Solaris Studio download page for
178 your platform type and version. This requires you to create and download a key
179 and certificate using your OTN account.
180
181 [1]: http://www.oracle.com/technetwork/server-storage/solarisstudio
182
183 All the tools and libs needed to build OpenAFS are available with the `pkg`
184 command on Solaris 11.  Earlier versions of Solaris require third party tools
185 and libs.
186
187 #### Solaris 10 and earlier ####
188
189 The [OpenCSW][2] project provides software packages for solaris 10 and earlier
190 which can be easily installed to build OpenAFS.  Follow the [OpenCSW getting started][3]
191 instructions to setup the `pkgutil` package manager tool.
192
193 [2]: http://www.opencsw.org
194 [3]: http://www.opencsw.org/manual/for-administrators/getting-started.html
195
196 Update your path to include `/opt/csw/bin`.
197
198 With `pkgutil` installed, install the necessary packages;
199
200      $ sudo pkgutil -y --install git
201      $ sudo pkgutil -y --install gmake flex bison gsed automake autoconf libtool
202      $ sudo pkgutil -y --install libkrb5_dev libncurses_dev
203
204 Note: Is a perl devel lib needed on solaris?
205
206 #### Solaris 11 ####
207
208 Install [SolarisStudio][1] using the `pkg' command. You will need an SSL
209 certificate and key, which can be created using your OTN account. See the instructions
210 on the Solaris Studio download page.
211
212 (Alternately, install Solaris Studio from the tar file installer, and then find
213 and install any missing dependencies.)
214
215 Use the `pkg` tool to install the other necessary packages:
216
217       $ sudo pkg install git
218       $ sudo pkg install text/locale
219       $ sudo pkg install gnu-coreutils gnu-binutils gnu-sed
220       $ sudo pkg install make flex bison
221       $ sudo pkg install automake autoconf libtool
222       $ sudo pkg install onbld
223
224 If you have dependency issues with automake, try automake-110
225
226 If you have installed Solaris Studio via the tar file, you may need to install
227 the `system/header' package manually:
228
229       $ sudo pkg install system/header
230
231
232 ## Getting the Source Code ##
233
234 See [[GitDevelopers]] for details on how to use git to fetch OpenAFS source
235 code and to submit source code changes to the OpenAFS project. This is the
236 preferred method to retrieve the source code.  Briefly, first create a local
237 clone of the git repository and then checkout a local branch of the version you
238 need to build.  For example,
239
240     $ git clone git://git.openafs.org/openafs.git
241     $ cd openafs
242     $ git checkout openafs-stable-<major>-<minor>-<patchlevel>
243
244 Compressed tar files of the source tree are made available for each stable and
245 development release. The most recent release is located at
246 <http://openafs.org/release/latest.html>.  Archives for releases are located at
247 /afs/openafs.org/software/openafs/ and <http://dl.openafs.org/dl>. For example,
248 to download and uncompress version 1.4.14,
249
250     $ wget http://dl.openafs.org/dl/1.4.14/openafs-1.4.14-src.tar.bz2
251     $ wget http://dl.openafs.org/dl/1.4.14/openafs-1.4.14-doc.tar.bz2
252     $ tar xjf openafs-1.4.14-src.tar.bz2
253     $ tar xjf openafs-1.4.14-doc.tar.bz2
254     $ cd openafs-1.4.14
255
256 The -src archive contains the source code and the -doc archive contains the
257 documentation in xml and pod format. Having a separate archive for
258 documentation allows people working on documentation to download just the pod
259 and xml portions of the project.
260
261 ### Regen
262
263 After a git checkout, run the regen.sh shell script to generate a
264 configure script (and a configure-libafs script) and to generate
265 the man pages. The regen.sh script runs the autoconf tools to
266 generate the configure scripts and runs perl to generate the
267 man pages.
268
269     ./regen.sh
270
271 You can skip the generation of the man pages by specifying the '-q'
272 option to regen.sh.
273
274     ./regen.sh -q
275
276 Always run regen.sh again (and then configure) if you change any of the OpenAFS
277 m4 autoconf macros, such as configure.ac or any of the macros under src/cf.
278
279 ## Configure
280
281 The OpenAFS configure script has many options available. Take some time to read
282 the README file and the output of configure --help before running configure the
283 first time. The most common options are introduced below.
284
285 ### AFS sysname
286
287 AFS uses an identifier called a *sysname* to distinguish platforms. configure
288 will automatically detect the sysname of the build system and by default
289 assumes the target system matches. If you are building for a target system
290 which is different than the build system, or if for some reason the sysname
291 detection fails, you will need to manually specify the sysname with the
292 --with-afs-sysname option.  See the README file for a complete list of sysnames.
293
294 The 'sysname' is also used as the name of the destination sub-directory for the
295 binaries created during the build. This sub-directory is automatically created
296 during the build.
297
298 ### Installation Directory Path Modes
299
300 There are two modes for directory path handling: *Transarc mode* and *default
301 mode*. The mode is selected with the --enable-transarc-paths option.
302
303 Traditionally, AFS server binaries and configuration files are located in the
304 directory /usr/afs and client binaries and configuration files are located in
305 the directory /usr/vice/etc. This convention is known as *Transarc path mode*
306 because it was the convention adopted by Transarc/IBM in the commercial
307 predecessor of OpenAFS.  Use the --enable-transarc-paths configure option to
308 build binaries compatible with the Transarc installation convention.
309
310 When configure is run without the --enable-transarc-paths option, the build
311 system is configured to be in the *default mode*. This mode builds OpenAFS with
312 installation paths more commonly used in open-source projects, for example
313 /usr/local.  The standard configure --prefix option(s) can be used to specify
314 non-default directories.  See the README for details on the type of installation
315 directories and the configure options to set the paths.
316
317 Installation paths are set at build time. Do not mix binaries for the two modes
318 on the same system.
319
320 ### Linux Kernel Headers
321
322 When building on linux, configure will attempt to detect the path to the linux
323 kernel headers.  If this path is not found on the build system, you must
324 specify the path with the --with-linux-kernel-headers option. For example,
325
326     --with-linux-kernel-headers=/usr/src/linux
327
328 ### Kerberos 5 configuration
329
330 The 1.6.0 configure scripts should automatically find the kerberos 5
331 libraries and headers.
332
333 If you need to build 1.4.x, or if the krb5-config file is in a non-standard
334 location, use the --with-krb5-conf option to specify the path to the krb5-config
335 utility (part of the kerberos 5 development package).
336
337     --with-krb5-conf=/usr/bin/krb5-config
338
339
340 ### Debugging Options ###
341
342 To enable a debugging build, specify the --enable-debug option on the
343 ./configure command line.  This builds with debugging compiler options and
344 disables stripping of binaries.
345
346     --enable-debug                enable compilation of the user space code
347                                      with debugging information
348     --enable-debug-kernel         enable compilation of the kernel module
349                                      with debugging information
350     --enable-checking             Enable compiler warnings when building
351                                     with gcc and treat compiler warnings
352                                     as errors
353
354 ### Feature Options ###
355
356 There are many configure options for OpenAFS. See the ./configure --help
357 for a complete list and README for more details.  Common options are:
358
359     --enable-bos-restricted-mode  enable bosserver restricted mode
360                                      which disables certain bosserver functionality
361     --enable-bos-new-config       enable bosserver pickup of BosConfig.new on restarts
362     --enable-namei-fileserver     force compilation of namei fileserver
363                                     in preference to inode fileserver
364                                     on systems were inode is the default
365     --enable-supergroups          enable support for nested pts groups
366                                    WARNING: Once you make use of this option
367                                    by nesting one group inside another,
368                                    the resulting PTS database cannot be correctly
369                                    and safely used by a ptserver built
370                                    without this option.
371
372 ### Configure changes in 1.6.0 ###
373
374 If you have been building the 1.5.0 freatures branch, note the following configure
375 options have been removed in 1.6.0. Each feature is now always on, except as noted:
376
377 * --disable-afsdb
378 * --disable-largefile-fileserver
379 * --enable-bos-restricted
380 * --enable-fast-restart (off, but the code is still there)
381 * --disable-full-vos-listvol
382 * --enable-disconnected
383 * --enable-icmp-pmtu-discovery
384 * --enable-demand-attach-fs (see below)
385
386 In 1.5.x, the demand attach fileserver feature was enabld by the a configure
387 switch. Starting in 1.6.0, both DAFS and legacy binaries are built. The
388 DAFS binaries are prefixed with 'da', expect for the new salvageserver, since
389 salvageserver is new with DAFS.
390
391
392 ## Make
393
394 After a successful configure, run make to build OpenAFS. The
395 default target will build all.
396
397     $ make
398
399
400 ## Install ##
401
402 You can install the OpenAFS binaries outside a package system
403 by copying the binaries. If you built OpenAFS in the default
404 mode (that is, without --enable-transarc-paths), run the install
405 target as root to install the binaries.
406
407     $ sudo make install
408
409 If configure was run with --enable-transarc-paths, then run make to build a
410 binary distribution directory, and then manually copy the files as the root
411 user. To install the server and client binaries,
412
413     $ make dest
414     $ cd <sysname>/dest
415     $ sudo mkdir /usr/afs
416     $ sudo mkdir /usr/vice
417     $ sudo mkdir /usr/vice/etc
418     $ sudo cp -p -r root.server/usr/afs/* /usr/afs
419     $ sudo cp -p -r root.client/usr/vice/etc/* /usr/vice/etc
420
421 See the Quick Start Guide for complete instructions to setup
422 the OpenAFS cache manager and servers.
423
424 The 'make dest' command places workstation binaries in the sub-directories of
425 &lt;sysname&gt;/dest: bin, etc, man, lib, include. Optionally, copy these to you
426 local filesystem or install them in an appropriate path in AFS. To install
427 these file into your local filesystem:
428
429     $ sudo mkdir /usr/afsws
430     $ sudo cp -p -r bin /usr/afsws
431     $ sudo cp -p -r etc /usr/afsws
432     $ sudo cp -p -r man /usr/afsws
433     $ sudo cp -p -r lib /usr/afsws
434     $ sudo cp -p -r include /usr/afsws
435
436 See [Storing AFS Binaries in AFS](http://docs.openafs.org/QuickStartUnix/ch02s29.html) for instructions on
437 how to store the workstation binaries in AFS.
438
439 ## Post build ##
440
441 Some make targets of interest
442
443 - make clean - remove build artifacts
444 - make distclean - remove build and configure artifacts
445 - make tests - make the (old) afs test suite
446
447 ## Out of Tree Builds ##
448
449 You may want to avoid cluttering your source tree with build artifacts, or
450 perhaps your source is in /afs and you want to write build artifacts on a
451 local, fast temporary file system.  No configure hacking is needed to do
452 perform an out of tree build.  If building from a git checkout, first build a
453 configure script as usual, then change the current working directory to your
454 local build directory and run configure and then make.
455
456
457     $ mkdir /tmp/mybuild
458     $ cd /tmp/mybuild
459     $ ( cd /afs/mycell/myfiles/openafs && ./regen.sh )  # if no configure
460     $ /afs/mycell/myfiles/openafs/configure $options
461     $ make
462
463
464