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