update gerrit list

[openafs-wiki.git] / devel / HowToBuildOpenAFSFromSource.mdwn

This page describes how to build OpenAFS binaries from source code.
The information is specific to unix-like systems. See the
README-WINDOWS file in the root of the OpenAFS source code tree for
instructions and software needed to build OpenAFS on Microsoft Windows.

Unless otherwise noted, the information on this page is for building
the OpenAFS master branch or the OpenAFS stable releases (currently
the 1.6.x series).

[[!toc levels=3]]

# The Short Version #

For the impatient, this section describes how to get a code tree and
build it, assuming you have a development environment already setup.

The following shows how to download source code tarballs and build the
OpenAFS binaries:

    $ wget http://openafs.org/dl/openafs/<version>/openafs-<version>-src.tar.bz2
    $ wget http://openafs.org/dl/openafs/<version>/openafs-<version>-doc.tar.bz2
    $ tar xjf openafs-<version>-src.tar.bz2
    $ tar xjf openafs-<version>-doc.tar.bz2
    $ cd openafs-<version>
    $ ./configure
    $ make

See [openafs downloads](http://openafs.org/dl/openafs) for available versions.

The following shows how to do a git checkout and build the OpenAFS binaries,

    $ git clone git://git.openafs.org/openafs.git
    $ cd openafs
    $ git checkout <branch-or-tag>
    $ ./regen.sh
    $ ./configure
    $ make

You will usually want to specify configure options. For example, to enable the
traditional Transarc/IBM AFS installation paths, run configure with the
--enable-transarc-paths option. (Read on for more information about configure
options.)

    $ ./configure --enable-transarc-paths --enable-checking --enable-debug
    $ make
    $ make dest

This will build the binaries and place them in the &lt;platform&gt;/dest
directories, that is, the Transarc-style binary distribution directory layout.

See [[how to build OpenAFS RPM packages|HowToBuildOpenAFSRpmPackages]] for
instructions on how to build RPM packages.

See [[how to build OpenAFS Debian packages|HowToBuildOpenAFSDebianPackages]]
for instructions on how to build packages for Debian.

# Building OpenAFS #

Building and packaging OpenAFS is not difficult on current unix-like
systems. A small number of fairly common libraries and tools are required. The
kernel headers and a compiler capable of building a kernel module is needed to
build the OpenAFS kernel module (used by the cache manager and for
inode-backend fileservers.) The gnu autoconf and automake tools are used to
configure the build system, so should be familiar to most people accustomed to
building binaries on unix-like systems.

Begin by verifying you have the prerequisite tools and libraries installed on your
build host. These are listed in the next section. You will need to obtain the
OpenAFS source code, either by downloading a release tar file, or by checking
out a version from the git repository.

See the README file for details on building OpenAFS and platform specific
notes. See src/SOURCE-MAP for a brief description of each source code component.

A script called regen.sh is used to build the configure script and to
generate the man page documentation from perl pod formatted files.

The configure sets up the build system for your platform. Configure will
attempt to detect your platform type and capabilities. Configure will generate
the makefiles using automake. You may need to specify configure options to
enable certain compile-time features. Run ./configure --help to see a
complete list of the available configure options.

After a successful run of configure, run make in the top level directory to
build all the client and server OpenAFS binaries. The server binaries, user and
admin tools, and the cache manager can be installed manually if you are not
using your systems package manager, for example if you are installing OpenAFS
on solaris, or if the target system is being used for testing and development.
The installation paths depend on the configure options specified.

The process for building rpm packages is actually a bit different than what was
just described above.  Packaging scripts in the source tree are used to build
rpms from a source code tree tar file. You'll need to create two tar files, one
of the source and one of the documentation. A script is run to build a source
rpm, which can be used to build the various rpm packages.  Details are given
on the page [[How to build OpenAFS RPM packages|HowToBuildOpenAFSRpmPackages]].

## Prerequisites ##

The following tools are needed to build OpenAFS from source from a tar file:

- make
- compiler
- assembler
- linker
- ranlib
- lex/yacc
- install
- perl 5.6 or better (only to build the documention)

In addition to the above, the following tools are needed to build OpenAFS
from a git checkout:

- git
- autoconf 2.60 or better
- automake
- libtool

The compiler used must be capable of building kernel modules for the target
platform.

> Note for RHEL users: RedHat Enterprise Linux 5.5 and less shipped with a
> version of autoconf too old to generate the OpenAFS configure script.
> Fortunately, the recently released RHEL 6.0 shipped with a more up to date
> version of autoconf which mets the minimum version needed to generate the
> configure script.

The following tools are needed to build OpenAFS RPMS:

- perl 5.6 or better
- rpmbuild

The following development libraries are needed:

- libc
- kerberos 5
- perl
- ncurses (optional, needed to build scout/afsmonitor)
- pam (optional)
- libfuse (optional)
- kernel headers

The ncurses libraries are needed to build the ncurses based admin tools
scout and afsmonitor. The kerberos 5 libraries are needed to build kerberos 5
support, which is *strongly* recommended.

### Linux Debian Packages ###

On recent versions of Debian, use the apt-get build-dep command to install the needed
build dependencies,

    $ sudo apt-get build-dep openafs
    $ sudo apt-get install linux-headers-$(uname -r)

On a Debian 6, the required packages can be install with the following commands apt-get commands,

    $ sudo apt-get install git autoconf automake libtool make gcc flex bison \
      libc6-dev libkrb5-dev libperl-dev libncurses5-dev libfuse-dev \
      linux-headers-$(uname -r)

### Linux RPM Packages ###

On a RedHat-based linux distributions, all of the required packages can be
installed with the following yum commands,

     $ sudo yum install git-core gcc autoconf automake libtool make flex bison
     $ sudo yum install glibc-devel krb5-devel perl-devel ncurses-devel pam-devel kernel-devel-$(uname -r)
     $ sudo yum install perl-devel perl-ExtUtils-Embed perl-Test-Simple

The following additional packages are needed to [[build RPM packages|HowToBuildOpenAfsRpmPackages]].

     $ sudo yum install wget rpm-build redhat-rpm-config

### Solaris Packages ###

[Oracle Solaris Studio][1] can be used to build OpenAFS binaries on the
solaris platform. Solaris Studio is freely available for the solaris and linux
platforms with a no-cost Oracle Technology Network (OTN) account.  For recent
versions of Solaris, use the `pkg' command to install Solaris Studio.  Follow the
package installer instructions on the Solaris Studio download page for
your platform type and version. This requires you to create and download a key
and certificate using your OTN account.

[1]: http://www.oracle.com/technetwork/server-storage/solarisstudio

All the tools and libs needed to build OpenAFS are available with the `pkg`
command on Solaris 11.  Earlier versions of Solaris require third party tools
and libs.

#### Solaris 10 and earlier ####

The [OpenCSW][2] project provides software packages for solaris 10 and earlier
which can be easily installed to build OpenAFS.  Follow the [OpenCSW getting started][3]
instructions to setup the `pkgutil` package manager tool.

[2]: http://www.opencsw.org
[3]: http://www.opencsw.org/manual/for-administrators/getting-started.html

Update your path to include `/opt/csw/bin`.

With `pkgutil` installed, install the necessary packages;

     $ sudo pkgutil -y --install git
     $ sudo pkgutil -y --install gmake flex bison gsed automake autoconf libtool
     $ sudo pkgutil -y --install libkrb5_dev libncurses_dev

Note: Is a perl devel lib needed on solaris?

#### Solaris 11 ####

Install [SolarisStudio][1] using the `pkg' command. You will need an SSL
certificate and key, which can be created using your OTN account. See the instructions
on the Solaris Studio download page.

(Alternately, install Solaris Studio from the tar file installer, and then find
and install any missing dependencies.)

Use the `pkg` tool to install the other necessary packages:

      $ sudo pkg install git
      $ sudo pkg install text/locale
      $ sudo pkg install gnu-coreutils gnu-binutils gnu-sed
      $ sudo pkg install make flex bison
      $ sudo pkg install automake autoconf libtool
      $ sudo pkg install onbld

If you have dependency issues with automake, try automake-110

If you have installed Solaris Studio via the tar file, you may need to install
the `system/header' package manually:

      $ sudo pkg install system/header


## Getting the Source Code ##

See [[GitDevelopers]] for details on how to use git to fetch OpenAFS source
code and to submit source code changes to the OpenAFS project. This is the
preferred method to retrieve the source code.  Briefly, first create a local
clone of the git repository and then checkout a local branch of the version you
need to build.  For example,

    $ git clone git://git.openafs.org/openafs.git
    $ cd openafs
    $ git checkout openafs-stable-<major>-<minor>-<patchlevel>

Compressed tar files of the source tree are made available for each stable and
development release. The most recent release is located at
<http://openafs.org/release/latest.html>.  Archives for releases are located at
/afs/openafs.org/software/openafs/ and <http://dl.openafs.org/dl>. For example,
to download and uncompress version 1.4.14,

    $ wget http://dl.openafs.org/dl/1.4.14/openafs-1.4.14-src.tar.bz2
    $ wget http://dl.openafs.org/dl/1.4.14/openafs-1.4.14-doc.tar.bz2
    $ tar xjf openafs-1.4.14-src.tar.bz2
    $ tar xjf openafs-1.4.14-doc.tar.bz2
    $ cd openafs-1.4.14

The -src archive contains the source code and the -doc archive contains the
documentation in xml and pod format. Having a separate archive for
documentation allows people working on documentation to download just the pod
and xml portions of the project.

### Regen

After a git checkout, run the regen.sh shell script to generate a
configure script (and a configure-libafs script) and to generate
the man pages. The regen.sh script runs the autoconf tools to
generate the configure scripts and runs perl to generate the
man pages.

    ./regen.sh

You can skip the generation of the man pages by specifying the '-q'
option to regen.sh.

    ./regen.sh -q

Always run regen.sh again (and then configure) if you change any of the OpenAFS
m4 autoconf macros, such as configure.ac or any of the macros under src/cf.

## Configure

The OpenAFS configure script has many options available. Take some time to read
the README file and the output of configure --help before running configure the
first time. The most common options are introduced below.

### AFS sysname

AFS uses an identifier called a *sysname* to distinguish platforms. configure
will automatically detect the sysname of the build system and by default
assumes the target system matches. If you are building for a target system
which is different than the build system, or if for some reason the sysname
detection fails, you will need to manually specify the sysname with the
--with-afs-sysname option.  See the README file for a complete list of sysnames.

The 'sysname' is also used as the name of the destination sub-directory for the
binaries created during the build. This sub-directory is automatically created
during the build.

### Installation Directory Path Modes

There are two modes for directory path handling: *Transarc mode* and *default
mode*. The mode is selected with the --enable-transarc-paths option.

Traditionally, AFS server binaries and configuration files are located in the
directory /usr/afs and client binaries and configuration files are located in
the directory /usr/vice/etc. This convention is known as *Transarc path mode*
because it was the convention adopted by Transarc/IBM in the commercial
predecessor of OpenAFS.  Use the --enable-transarc-paths configure option to
build binaries compatible with the Transarc installation convention.

When configure is run without the --enable-transarc-paths option, the build
system is configured to be in the *default mode*. This mode builds OpenAFS with
installation paths more commonly used in open-source projects, for example
/usr/local.  The standard configure --prefix option(s) can be used to specify
non-default directories.  See the README for details on the type of installation
directories and the configure options to set the paths.

Installation paths are set at build time. Do not mix binaries for the two modes
on the same system.

### Linux Kernel Headers

When building on linux, configure will attempt to detect the path to the linux
kernel headers.  If this path is not found on the build system, you must
specify the path with the --with-linux-kernel-headers option. For example,

    --with-linux-kernel-headers=/usr/src/linux

### Kerberos 5 configuration

The 1.6.0 configure scripts should automatically find the kerberos 5
libraries and headers.

If you need to build 1.4.x, or if the krb5-config file is in a non-standard
location, use the --with-krb5-conf option to specify the path to the krb5-config
utility (part of the kerberos 5 development package).

    --with-krb5-conf=/usr/bin/krb5-config


### Debugging Options ###

To enable a debugging build, specify the --enable-debug option on the
./configure command line.  This builds with debugging compiler options and
disables stripping of binaries.

    --enable-debug                enable compilation of the user space code
                                     with debugging information
    --enable-debug-kernel         enable compilation of the kernel module
                                     with debugging information
    --enable-checking             Enable compiler warnings when building
                                    with gcc and treat compiler warnings
                                    as errors

### Feature Options ###

There are many configure options for OpenAFS. See the ./configure --help
for a complete list and README for more details.  Common options are:

    --enable-bos-restricted-mode  enable bosserver restricted mode
                                     which disables certain bosserver functionality
    --enable-bos-new-config       enable bosserver pickup of BosConfig.new on restarts
    --enable-namei-fileserver     force compilation of namei fileserver
                                    in preference to inode fileserver
                                    on systems were inode is the default
    --enable-supergroups          enable support for nested pts groups
                                   WARNING: Once you make use of this option
                                   by nesting one group inside another,
                                   the resulting PTS database cannot be correctly
                                   and safely used by a ptserver built
                                   without this option.

### Configure changes in 1.6.0 ###

If you have been building the 1.5.0 freatures branch, note the following configure
options have been removed in 1.6.0. Each feature is now always on, except as noted:

* --disable-afsdb
* --disable-largefile-fileserver
* --enable-bos-restricted
* --enable-fast-restart (off, but the code is still there)
* --disable-full-vos-listvol
* --enable-disconnected
* --enable-icmp-pmtu-discovery
* --enable-demand-attach-fs (see below)

In 1.5.x, the demand attach fileserver feature was enabld by the a configure
switch. Starting in 1.6.0, both DAFS and legacy binaries are built. The
DAFS binaries are prefixed with 'da', expect for the new salvageserver, since
salvageserver is new with DAFS.


## Make

After a successful configure, run make to build OpenAFS. The
default target will build all.

    $ make


## Install ##

You can install the OpenAFS binaries outside a package system
by copying the binaries. If you built OpenAFS in the default
mode (that is, without --enable-transarc-paths), run the install
target as root to install the binaries.

    $ sudo make install

If configure was run with --enable-transarc-paths, then run make to build a
binary distribution directory, and then manually copy the files as the root
user. To install the server and client binaries,

    $ make dest
    $ cd <sysname>/dest
    $ sudo mkdir /usr/afs
    $ sudo mkdir /usr/vice
    $ sudo mkdir /usr/vice/etc
    $ sudo cp -p -r root.server/usr/afs/* /usr/afs
    $ sudo cp -p -r root.client/usr/vice/etc/* /usr/vice/etc

See the Quick Start Guide for complete instructions to setup
the OpenAFS cache manager and servers.

The 'make dest' command places workstation binaries in the sub-directories of
&lt;sysname&gt;/dest: bin, etc, man, lib, include. Optionally, copy these to you
local filesystem or install them in an appropriate path in AFS. To install
these file into your local filesystem:

    $ sudo mkdir /usr/afsws
    $ sudo cp -p -r bin /usr/afsws
    $ sudo cp -p -r etc /usr/afsws
    $ sudo cp -p -r man /usr/afsws
    $ sudo cp -p -r lib /usr/afsws
    $ sudo cp -p -r include /usr/afsws

See [Storing AFS Binaries in AFS](http://docs.openafs.org/QuickStartUnix/ch02s29.html) for instructions on
how to store the workstation binaries in AFS.

## Post build ##

Some make targets of interest

- make clean - remove build artifacts
- make distclean - remove build and configure artifacts
- make tests - make the (old) afs test suite

## Out of Tree Builds ##

You may want to avoid cluttering your source tree with build artifacts, or
perhaps your source is in /afs and you want to write build artifacts on a
local, fast temporary file system.  No configure hacking is needed to do
perform an out of tree build. An out of tree build is done by changing
directory and then specifying the path to the configure script.  When building
from a git checkout and not a source tarball, first build a configure script
with `regen.sh` as usual in the source directory. This requires read-write
access to the source directory.

To do the out of tree build, change the current working directory to your local
build directory and run `configure` and `make`.  For example:

    $ mkdir /tmp/mybuild
    $ cd /tmp/mybuild
    $ /afs/example.com/myfiles/openafs/configure $options
    $ make