--- /dev/null
+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 <platform>/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.
+
+# 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
+
+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
+<sysname>/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. If building from a git checkout, first build a
+configure script as usual, then change the current working directory to your
+local build directory and run configure and then make.
+
+
+ $ mkdir /tmp/mybuild
+ $ cd /tmp/mybuild
+ $ ( cd /afs/mycell/myfiles/openafs && ./regen.sh ) # if no configure
+ $ /afs/mycell/myfiles/openafs/configure $options
+ $ make
+
+
+
git://git.openafs.org / openafs-wiki.git / blobdiff