Reorg how to build packages
[openafs-wiki.git] / 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 an OpenAFS source distribution
31
32 The OpenAFS project provides a source code distributions of [releases][3]. A
33 source RPM (src.rpm) file can be built from a source distribution release,
34 which can then be used to build rpm packages.
35
36 Step 1. Download the source distribution files.
37
38 Four files are provided; source tarball, documentation tarball, release notes,
39 and a change log.
40
41     $ wget https://www.openafs.org/dl/openafs/1.8.5/openafs-1.8.5-src.tar.bz2
42     $ wget https://www.openafs.org/dl/openafs/1.8.5/openafs-1.8.5-doc.tar.bz2
43     $ wget https://www.openafs.org/dl/openafs/1.8.5/RELNOTES-1.8.5
44     $ wget https://www.openafs.org/dl/openafs/1.8.5/ChangeLog
45
46 Step 2. Extract the packaging files.
47
48 Extract packaging files contained in the source tarball.
49
50     $ tar xf openafs-1.8.5-src.tar.bz2 openafs-1.8.5/src/packaging/RedHat
51
52 Step 3. Run the `makesrpm.pl` script to build the source rpm.
53
54     $ ./openafs-1.8.5/src/packaging/RedHat/makesrpm.pl \
55       openafs-1.8.5-src.tar.bz2 \
56       openafs-1.8.5-doc.tar.bz2 \
57       RELNOTES-1.8.5 \
58       ChangeLog
59     ...
60     SRPM is openafs-1.8.5-1.src.rpm
61
62 Step 4: Build the rpm packages.
63
64     $ rpmbuild --rebuild -bb --define "_topdir $(pwd)/rpmbuild" openafs-1.8.5-1.src.rpm
65
66
67 ## How to build release packages from git
68
69 The following commands show how to build RPM packages from a git checkout of a
70 released version of OpenAFS.  The following commands build RPM packages from a
71 release tag.
72
73     $ git clone git://git.openafs.org/openafs.git
74     $ cd openafs
75     $ git checkout <openafs-release-tag>  # e.g., openafs-stable-1_8_5
76
77     $ ./regen.sh
78     $ ./configure  # configure options are not required here.
79     $ make dist    # creates the source distribution in ./packages
80     $ make srpm    # get the source rpm name from the output
81
82     $ rpmbuild --rebuild -ba --define "_topdir $(pwd)/packages/rpmbuild" packages/<name>.src.rpm
83
84 The RPM packages will be created in the `packages/rpmbuild/RPMS` directory.  See
85 the RPM spec file in src/packaging/RedHat for `--define` options for optional
86 features and packages.
87
88 Note: One downside to this method is the RELNOTES and ChangeLog from the
89 OpenAFS release download page are not included in the build packages.
90
91 ## How to build release packages with afsutil
92
93 The contributed `afsutil`[1] script can be used to build packages from a git
94 checkout. This tool is a front-end with various options to support building
95 client and server packages from release tags as well as non-release commits.
96 `afsutil` is available on [PyPI][2] and [github][1]
97
98
99     $ pip install afsutil
100
101     $ git clone git://git.openafs.org/openafs.git
102     $ cd openafs
103     $ git checkout <tag>  # e.g., openafs-stable-1_8_5
104
105     $ afsutil package [options]
106
107 The RPM packages will be created in the `packages/rpmbuild/RPMS` directory.
108
109 Some commonly used `afsutil package` options are:
110
111     --version=<custom-version> # for testing or building custom versions
112     --csdb=<path-to-custom-CellServDB-file>
113     --spec=<path-to-custom-openafs-spec-file>
114     --build=<what to build, one of: all, sources, srpm, userspace, kmods>
115     --kernel-version=<kernel-version> # may be given more than once
116
117 See `afsutil package --help` for a complete list of options.
118
119
120 ## Version Strings
121
122 A note about version strings. RPM packages require a valid version string and
123 package release number.  If you are building packages for version which is not
124 a release (or pre-release), for example perhaps you want to make changes and
125 build packages for testing, perhaps you wish to deploy packages with custom
126 changes or fixes, you will need to set a customized version string in the spec
127 file.
128
129 In the following examples, set the version string the `.version` to generate a
130 `openafs.spec` file with your desired version.  If you are using the `afsutil
131 package` contributed script, use the `--version` option to specify your custom
132 version.
133
134
135 [1]: https://github.com/openafs-contrib/afsutil
136 [2]: https://pypi.org/project/afsutil/
137 [3]: https://www.openafs.org/release/