# Building RPM packages for OpenAFS
-The OpenAFS source tree contains an RPM spec file for building RPM packages.
-Recent versions of OpenAFS have makefile targets to build the source
-distribution tarballs and a source RPM package (srpm). After creating these
-files, run the `rpmbuild` tool to create create the binary RPM packages.
+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 following commands show how to build RPM packages from a git checkout. The
-tools will create RPM packages from annotated git tags. Checkout a tag for the
-desired version, then generated the source rpm, then run rpmbuild to build the
-binaries RPM package files.
+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 <tag>
+ $ git checkout <openafs-release-tag> # e.g., openafs-stable-1_8_5
+
$ ./regen.sh
- $ ./configure # no configure options required
- $ make dist
- $ make srpm
+ $ ./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 packages will be created in the `packages/rpmbuild/RPMS` directory. See
+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 distibution 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 4. 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/
git://git.openafs.org / openafs-wiki.git / blobdiff