devel/HowToBuildOpenAfsRpmPackages.mdwn

   1 # Building RPM packages for OpenAFS
   2
   3 This pages describes how to build OpenAFS client and server packages for RHEL
   4 and CentOS using the contributed RPM spec file available in the OpenAFS source
   5 tree.  Packages may be build from the OpenAFS release tar files or from a clone
   6 of the OpenAFS git repository.  It is recommended to use Fedora `mock` to build
   7 packages, especially if you are building packages for multiple kernel versions.
   8 This page describes how to build packages with and without `mock`.
   9
  10 The general process is:
  11
  12 * Set up the RPM build directories
  13 * Download or extract the RPM sources
  14    - Release Notes
  15    - CellServDB file
  16    - Source code tar file
  17    - Documentation tar file
  18 * Extract the openafs.spec file from the openafs code tree
  19    - Set the OpenAFS version and package release versions
  20 * Run rpmbuild -bs to create a source RPM
  21 * Run rpmbuild with options to create RPM package files
  22
  23 Available resources for building RPM packages:
  24
  25 * The OpenAFS makefile has targets to build the source RPM
  26 * The OpenAFS src/packaging/RedHat/makesrpm.pl script may be used to build the source RPM (This script is used by the makefile)
  27 * The OpenAFS-contrib [afsutil package][1] script will build RPMs in a local git repo, and has options to support building packages with `mock`.
  28
  29
  30 ## How to build release packages from git
  31
  32 The following commands show how to build RPM packages from a git checkout of a
  33 released version of OpenAFS.  The following commands build RPM packages from a
  34 release tag.
  35
  36     $ git clone git://git.openafs.org/openafs.git
  37     $ cd openafs
  38     $ git checkout <openafs-release-tag>  # e.g., openafs-stable-1_8_5
  39
  40     $ ./regen.sh
  41     $ ./configure  # configure options are not required here.
  42     $ make dist    # creates the source distribution in ./packages
  43     $ make srpm    # get the source rpm name from the output
  44
  45     $ rpmbuild --rebuild -ba --define "_topdir $(pwd)/packages/rpmbuild" packages/<name>.src.rpm
  46
  47 The RPM packages will be created in the `packages/rpmbuild/RPMS` directory.  See
  48 the RPM spec file in src/packaging/RedHat for `--define` options for optional
  49 features and packages.
  50
  51 Note: One downside to this method is the RELNOTES and ChangeLog from the
  52 OpenAFS release download page are not included in the build packages.
  53
  54 ## How to build release packages with afsutil
  55
  56 The contributed `afsutil`[1] script can be used to build packages from a git
  57 checkout. This tool is a front-end with various options to support building
  58 client and server packages from release tags as well as non-release commits.
  59 `afsutil` is available on [PyPI][2] and [github][1]
  60
  61
  62     $ pip install afsutil
  63
  64     $ git clone git://git.openafs.org/openafs.git
  65     $ cd openafs
  66     $ git checkout <tag>  # e.g., openafs-stable-1_8_5
  67
  68     $ afsutil package [options]
  69
  70 The RPM packages will be created in the `packages/rpmbuild/RPMS` directory.
  71
  72 Some commonly used `afsutil package` options are:
  73
  74     --version=<custom-version> # for testing or building custom versions
  75     --csdb=<path-to-custom-CellServDB-file>
  76     --spec=<path-to-custom-openafs-spec-file>
  77     --build=<what to build, one of: all, sources, srpm, userspace, kmods>
  78     --kernel-version=<kernel-version> # may be given more than once
  79
  80 See `afsutil package --help` for a complete list of options.
  81
  82 ## How to build release packages from OpenAFS source distributions
  83
  84 The OpenAFS project provides [source code distributions of releases][3]. These
  85 files are, of course, available via AFS3 at
  86 `/afs/grand.central.org/software/openafs` The source RPM file can be built from
  87 the source distribution releases without external tools.
  88
  89 Step 1. Download the source distibution files.
  90
  91 Four files are provided; source tarball, documentation tarball, release notes,
  92 and a change log.
  93
  94     $ wget https://www.openafs.org/dl/openafs/1.8.5/openafs-1.8.5-src.tar.bz2
  95     $ wget https://www.openafs.org/dl/openafs/1.8.5/openafs-1.8.5-doc.tar.bz2
  96     $ wget https://www.openafs.org/dl/openafs/1.8.5/RELNOTES-1.8.5
  97     $ wget https://www.openafs.org/dl/openafs/1.8.5/ChangeLog
  98
  99 Step 2. Extract the packaging files.
 100
 101 The packaging files are contained in the source tarball.
 102
 103     $ tar -x -j -f openafs-1.8.5-src.tar.bz2 openafs-1.8.5/src/packaging/RedHat
 104
 105
 106 Step 3. Set the version strings.
 107
 108 The version being built must be set in the spec file. Replace the following
 109 three version placeholders to create a spec file.
 110
 111     $ sed \
 112       -e s/@PACKAGE_VERSION@/1.8.5/ \
 113       -e s/@LINUX_PKGVER@/1.8.5/ \
 114       -e s/@LINUX_PKGREL@/1/  \
 115       openafs-1.8.5/packaging/RedHat/openafs.spec.in > openafs.spec
 116
 117
 118 Step 4: Download the CellServDB file.
 119
 120 The CellServDB file is maintained at grand.central.org. Download the expected
 121 version specified in the spec file.  The path is set in the spec file as
 122 `Source20` in existing spec files. This could change in the future.
 123
 124      $ grep '^Source20' openafs.spec
 125      Source20: https://www.central.org/dl/cellservdb/CellServDB.2018-05-14
 126
 127      $ wget https://www.central.org/dl/cellservdb/CellServDB.2018-05-14
 128
 129
 130 Step 5. Populate the build directories.
 131
 132     $ mkdir -p rpmbuild/{SOURCES,SPECS,SRPMS}
 133
 134     $ cp openafs.spec rpmbuild/SPECS/
 135
 136     $ cp openafs-1.8.5-src.tar.bz2 rpmbuild/SOURCES/
 137     $ cp openafs-1.8.5-doc.tar.bz2 rpmbuild/SOURCES/
 138     $ cp RELNOTES-1.8.5 rpmbuild/SOURCES/
 139     $ cp ChangeLog rpmbuild/SOURCES/
 140
 141     $ cp CellServDB.2018-05-14 rpmbuild/SOURCES/
 142
 143     $ cp openafs-1.8.5/src/packaging/RedHat/openafs-kvers-is.sh rpmbuild/SOURCES/
 144     $ cp openafs-1.8.5/src/packaging/RedHat/openafs-buildfedora.pl rpmbuild/SOURCES/
 145     $ cp openafs-1.8.5/src/packaging/RedHat/openafs-buildall.sh rpmbuild/SOURCES/
 146     $ cp openafs-1.8.5/src/packaging/RedHat/openafs-kmodtool rpmbuild/SOURCES/
 147
 148 At this point your rpmbuild tree should look like:
 149
 150     rpmbuild
 151     ├── SOURCES
 152     │   ├── CellServDB.2018-05-14
 153     │   ├── ChangeLog
 154     │   ├── openafs-1.8.5-doc.tar.bz2
 155     │   ├── openafs-1.8.5-src.tar.bz2
 156     │   ├── openafs-buildall.sh
 157     │   ├── openafs-buildfedora.pl
 158     │   ├── openafs-kmodtool
 159     │   ├── openafs-kvers-is.sh
 160     │   └── RELNOTES-1.8.5
 161     ├── SPECS
 162     │   └── openafs.spec
 163     └── SRPMS
 164
 165
 166 Step 6: Build the source rpm:
 167
 168     $ rpmbuild -bs --define "_topdir $(pwd)/rpmbuild" rpmbuild/SPECS/openafs.spec
 169     ...
 170     Wrote: /tmp/bs2/rpmbuild/SRPMS/openafs-1.8.5-1.src.rpm
 171
 172 Step 7: Build the rpm packages
 173
 174     $ rpmbuild -ba --define "_topdir $(pwd)/rpmbuild" rpmbuild/SRPMS/openafs-1.8.5-1.src.rpm
 175
 176
 177 ## Version Strings
 178
 179 A note about version strings. RPM packages require a valid version string and
 180 package release number.  If you are building packages for version which is not
 181 a release (or pre-release), for example perhaps you want to make changes and
 182 build packages for testing, perhaps you wish to deploy packages with custom
 183 changes or fixes, you will need to set a customized version string in the spec
 184 file.
 185
 186 In the following examples, set the version string the `.version` to generate a
 187 `openafs.spec` file with your desired version.  If you are using the `afsutil
 188 package` contributed script, use the `--version` option to specify your custom
 189 version.
 190
 191
 192 [1]: https://github.com/openafs-contrib/afsutil
 193 [2]: https://pypi.org/project/afsutil/
 194 [3]: https://www.openafs.org/release/