More rpm building instructions
authorMichael Meffie <mmeffie@sinenomine.net>
Sat, 7 Mar 2020 18:58:22 +0000 (13:58 -0500)
committerMichael Meffie <mmeffie@sinenomine.net>
Sat, 7 Mar 2020 18:58:22 +0000 (13:58 -0500)
Provide the commands to build the source rpm from a source distribution.

Provide examples of the contributed afsutil package script to build from
a git checkout.

devel/HowToBuildOpenAfsRpmPackages.mdwn

index 67643a6..2369310 100644 (file)
 # 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/