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