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