# Building RPM packages for OpenAFS

This pages describes how to build OpenAFS client and server packages for RHEL
and CentOS using the contributed RPM spec file available in the OpenAFS source
tree.  Packages may be build from the OpenAFS release tar files or from a clone
of the OpenAFS git repository.  It is recommended to use Fedora `mock` to build
packages, especially if you are building packages for multiple kernel versions.
This page describes how to build packages with and without `mock`.

The general process is:

* Set up the RPM build directories
* Download or extract the RPM sources
   - Release Notes
   - CellServDB file
   - Source code tar file
   - Documentation tar file
* Extract the openafs.spec file from the openafs code tree
   - Set the OpenAFS version and package release versions
* Run rpmbuild -bs to create a source RPM
* Run rpmbuild with options to create RPM package files

Available resources for building RPM packages:

* The OpenAFS makefile has targets to build the source RPM
* The OpenAFS src/packaging/RedHat/makesrpm.pl script may be used to build the source RPM (This script is used by the makefile)
* The OpenAFS-contrib [afsutil package][1] script will build RPMs in a local git repo, and has options to support building packages with `mock`.


## How to build release packages from git

The following commands show how to build RPM packages from a git checkout of a
released version of OpenAFS.  The following commands build RPM packages from a
release tag.

    $ git clone git://git.openafs.org/openafs.git
    $ cd openafs
    $ git checkout <openafs-release-tag>  # e.g., openafs-stable-1_8_5

    $ ./regen.sh
    $ ./configure  # configure options are not required here.
    $ make dist    # creates the source distribution in ./packages
    $ make srpm    # get the source rpm name from the output

    $ rpmbuild --rebuild -ba --define "_topdir $(pwd)/packages/rpmbuild" packages/<name>.src.rpm

The RPM packages will be created in the `packages/rpmbuild/RPMS` directory.  See
the RPM spec file in src/packaging/RedHat for `--define` options for optional
features and packages.

Note: One downside to this method is the RELNOTES and ChangeLog from the
OpenAFS release download page are not included in the build packages.

## How to build release packages with afsutil

The contributed `afsutil`[1] script can be used to build packages from a git
checkout. This tool is a front-end with various options to support building
client and server packages from release tags as well as non-release commits.
`afsutil` is available on [PyPI][2] and [github][1]


    $ pip install afsutil

    $ git clone git://git.openafs.org/openafs.git
    $ cd openafs
    $ git checkout <tag>  # e.g., openafs-stable-1_8_5

    $ afsutil package [options]

The RPM packages will be created in the `packages/rpmbuild/RPMS` directory.

Some commonly used `afsutil package` options are:

    --version=<custom-version> # for testing or building custom versions
    --csdb=<path-to-custom-CellServDB-file>
    --spec=<path-to-custom-openafs-spec-file>
    --build=<what to build, one of: all, sources, srpm, userspace, kmods>
    --kernel-version=<kernel-version> # may be given more than once

See `afsutil package --help` for a complete list of options.

## How to build release packages from OpenAFS source distributions

The OpenAFS project provides [source code distributions of releases][3]. These
files are, of course, available via AFS3 at
`/afs/grand.central.org/software/openafs` The source RPM file can be built from
the source distribution releases without external tools.

Step 1. Download the source distribution files.

Four files are provided; source tarball, documentation tarball, release notes,
and a change log.

    $ wget https://www.openafs.org/dl/openafs/1.8.5/openafs-1.8.5-src.tar.bz2
    $ wget https://www.openafs.org/dl/openafs/1.8.5/openafs-1.8.5-doc.tar.bz2
    $ wget https://www.openafs.org/dl/openafs/1.8.5/RELNOTES-1.8.5
    $ wget https://www.openafs.org/dl/openafs/1.8.5/ChangeLog

Step 2. Extract the packaging files.

The packaging files are contained in the source tarball.

    $ tar -x -j -f openafs-1.8.5-src.tar.bz2 openafs-1.8.5/src/packaging/RedHat


Step 3. Set the version strings.

The version being built must be set in the spec file. Replace the following
three version placeholders to create a spec file.

    $ sed \
      -e s/@PACKAGE_VERSION@/1.8.5/ \
      -e s/@LINUX_PKGVER@/1.8.5/ \
      -e s/@LINUX_PKGREL@/1/  \
      openafs-1.8.5/packaging/RedHat/openafs.spec.in > openafs.spec


Step 4: Download the CellServDB file.

The CellServDB file is maintained at grand.central.org. Download the expected
version specified in the spec file.  The path is set in the spec file as
`Source20` in existing spec files. This could change in the future.

     $ grep '^Source20' openafs.spec
     Source20: https://www.central.org/dl/cellservdb/CellServDB.2018-05-14

     $ wget https://www.central.org/dl/cellservdb/CellServDB.2018-05-14


Step 5. Populate the build directories.

    $ mkdir -p rpmbuild/{SOURCES,SPECS,SRPMS}

    $ cp openafs.spec rpmbuild/SPECS/

    $ cp openafs-1.8.5-src.tar.bz2 rpmbuild/SOURCES/
    $ cp openafs-1.8.5-doc.tar.bz2 rpmbuild/SOURCES/
    $ cp RELNOTES-1.8.5 rpmbuild/SOURCES/
    $ cp ChangeLog rpmbuild/SOURCES/

    $ cp CellServDB.2018-05-14 rpmbuild/SOURCES/

    $ cp openafs-1.8.5/src/packaging/RedHat/openafs-kvers-is.sh rpmbuild/SOURCES/
    $ cp openafs-1.8.5/src/packaging/RedHat/openafs-buildfedora.pl rpmbuild/SOURCES/
    $ cp openafs-1.8.5/src/packaging/RedHat/openafs-buildall.sh rpmbuild/SOURCES/
    $ cp openafs-1.8.5/src/packaging/RedHat/openafs-kmodtool rpmbuild/SOURCES/

At this point your rpmbuild tree should look like:

    rpmbuild
    ├── SOURCES
    │   ├── CellServDB.2018-05-14
    │   ├── ChangeLog
    │   ├── openafs-1.8.5-doc.tar.bz2
    │   ├── openafs-1.8.5-src.tar.bz2
    │   ├── openafs-buildall.sh
    │   ├── openafs-buildfedora.pl
    │   ├── openafs-kmodtool
    │   ├── openafs-kvers-is.sh
    │   └── RELNOTES-1.8.5
    ├── SPECS
    │   └── openafs.spec
    └── SRPMS


Step 6: Build the source rpm:

    $ rpmbuild -bs --define "_topdir $(pwd)/rpmbuild" rpmbuild/SPECS/openafs.spec
    ...
    Wrote: /tmp/bs2/rpmbuild/SRPMS/openafs-1.8.5-1.src.rpm

Step 7: Build the rpm packages

    $ rpmbuild -ba --define "_topdir $(pwd)/rpmbuild" rpmbuild/SRPMS/openafs-1.8.5-1.src.rpm


## Version Strings

A note about version strings. RPM packages require a valid version string and
package release number.  If you are building packages for version which is not
a release (or pre-release), for example perhaps you want to make changes and
build packages for testing, perhaps you wish to deploy packages with custom
changes or fixes, you will need to set a customized version string in the spec
file.

In the following examples, set the version string the `.version` to generate a
`openafs.spec` file with your desired version.  If you are using the `afsutil
package` contributed script, use the `--version` option to specify your custom
version.


[1]: https://github.com/openafs-contrib/afsutil
[2]: https://pypi.org/project/afsutil/
[3]: https://www.openafs.org/release/