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