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