source: trunk/server/doc/package-build-howto @ 2838

Last change on this file since 2838 was 2832, checked in by andersk, 7 years ago
server/doc/package-build-howto: minor fixes (Can you tell that these are test commits?)
File size: 7.8 KB
Line 
1This document is a how-to for building new packaages for scripts.mit.edu.
2
3Prerequisites
4=============
5
6  * A trusted scripts.mit.edu server
7  * A scripts-build account on that server (but that was created when it
8    was installed, or something's wrong)
9  * A set of personal credentials for the scripts svn repo
10
11Directions
12==========
13
14  * Log into the server as root
15
16  * /bin/su scripts-build # It's a bad idea to build as root.  This is
17                          # less urgent than it used to be, because you'll
18                          # be building using mock in a chroot, but it's
19                          # still good habit.  Also, if you work in
20                          # /srv/repository as root, scripts-build won't
21                          # be able to change some of the resulting files
22
23  * cd /srv/repository
24
25  * svn up  # Important both to build with current code, and because the
26            # svn revision becomes part of the package release number,
27            # and you can infer whether changes in the code were made
28            # before or after a particular build by looking at the package
29            # and svn release/revision.
30
31  * cd server/fedora
32
33  * # Look in the .dload directory.  If you want to build with a newer
34    # version of any upstream packages that are there, then
35    * rm .dload/[OLD-PACKAGES].src.rpm # It's fine to delete all SRPMs here
36    * rm download_stamp
37
38  * make [PACKAGE-YOU-WANT] # e.g. 'make httpd' builds Apache with our patches
39    # Note that openafs-devel is a build-dependency of accountadm, so if
40    # this is a new Fedora release being bootstrapped, you'll have to
41    # build openafs and install its -devel package before building accountadm
42
43  * # If the build succeeds, the mock logs, build log, binary and SRPMs
44    # will be in /var/lib/mock/fedora-[RELEASE]-{x86_64|i386}/result (note that
45    # this will be cleared out each time you start a new build, so if
46    # you're building several packages in succession, copy the results
47    # somewhere safe after each build to preserve them)
48    # Add the packages to the repository by using a trusted machine and
49    krootscp root@[BUILD-SERVER]:/var/lib/mock/fedora-[RELEASE]-{x86_64|i386}/result/*.rpm /mit/scripts/yum-repos/rpm-fc[RELEASE]
50
51    # There has been some historic discussion about whether SRPMs should be
52    # added to the repository. At this point, the standard is to include them.
53
54  * # Rebuild the repo metadata to include the new packages.
55    cd /mit/scripts/yum-repos/rpm-fc[RELEASE]
56    # If you have a trusted machine:
57    createrepo -d .
58    # Otherwise, on a scripts server, as root:
59    mkdir /root/repodata-YYYYMMDD # Or any suitable temp directory
60    createrepo -d -o /root/repodata-YYYYMMDD .
61    # Then from your trusted machine
62    krootscp -r root@[BUILD-SERVER]:/root/repodata-YYYYMMDD /mit/scripts/yum-repos/rpm-fc[RELEASE]
63    # Sanity check the files, and then replace the current repodata directory
64    # with the one in repodata-YYYYMMDD.
65
66    # The sbin/scripts-createrepo script in the locker automates this
67    # metadata rebuild dance.
68
69Patching packages
70=================
71
72  * To make changes to the packages that we are the upstream maintainers
73    of (that is, the packages that the Scripts Team wrote):
74    * The authoritative source lives in server/common/oursrc/[PACKAGE]
75    * The RPM spec file is server/fedora/specs/[PACAKGE].spec
76    * You directly make the relevant changes to those files, commit to
77      svn, and then rebuild the package as above to include the new changes.
78
79  * To make changes to the upstream packages that we "scriptsify":
80
81    * If we haven't previously scriptsified this package, you'll need
82      to add it to the upstream_yum line in SVN/server/fedora/Makefile,
83      and remove the download_stamp file so that it gets fetched next
84      time you run 'make [PACKAGE]'.
85
86    * The authoritative upstream source comes from the SRPM in the upstream
87      yum repo, or in odd cases like openafs, from some other URL.  When
88      you 'make [PACKAGE]' in SVN/server/fedora, if download_stamp has
89      been removed, the SRPMs are all refetched into
90      SVN/server/fedora/.dload, and then installed with 'rpm -i'.  This
91      results in the source patches, and tarballs landing in ~/rpmbuild/SOURCES
92      and the spec files landing in ~/rpmbuild/SPECS.  You can also
93      manually get individual SRPMs for a package by doing this (these
94      steps work fine as a mortal user, including the 'rpm -i'):
95      * yumdownloader --source [PACKAGE]
96        # That deposits [PACKAGE]-[VER]-[RELEASE].src.rpm in the current dir
97      * rpm -i [PACAKGE]-[VER]-[RELEASE].src.rpm
98        # That unpacks the SRPM, placing the source tarball and patches in
99        # ~/rpmbuild/SOURCES and the spec file in ~/rpmbuild/SPECS; it
100        # does *not* globally install anything, and doesn't require root
101      If you prefer to not install the file, you can simply extract it
102      into a directory by running:
103      * /mit/ghudson/scripts/rpmx [PACKAGE]-[VER]-[RELEASE].src.rpm
104
105    * If you develop a patch to the upstream source, you should save a
106      diff with your changes and add it to the repo as
107      SVN/server/common/patches/[PACKAGE]-[SHORT_DESCRIPTIVE_STRING].patch
108
109    * To cause your patch to be applied when the package is built, you
110      will need to save a copy of the original spec file for the upstream
111      package, then modify it to add a line like:
112        Patch[NUM]: [PACKAGE]-[SHORT_DESCRIPTOVE_STRING].patch
113        # This should generally go after the last existing Patch line
114        # in the file, and [NUM] should be significantly larger than
115        # the upstream Fedora patches, to avoid conflicts later.  This
116        # line tells rpmbuild where the contents of the patch live.
117      You also add a line like:
118        %patch[NUM] -p1 -b .[SHORT_DESCRIPTIVE_STRING]
119        # This should generally go after the last existing %patch line
120        # in the file, [NUM] should be the same as in the Patch line, and
121        # tells rpmbuild that this is the point at which to actually apply
122        # the patch
123
124    * The Release tag in the spec file should have ".scripts.%{scriptsversion}
125      inserted into it just before %{?dist}, or at the end of the release
126      if %{?dist} is unused.
127      # e.g.          Release: 1%{?dist}
128      # changes to    Release: 1.scripts.%{scriptsversion}%{?dist}
129      This causes the package version to include the string "scripts"
130      and our SVN revision number (which is set by the Makefile) for
131      easy identification (this version will also be greater than the
132      upstream version, so the system will prefer to update to it).
133
134    * If the scriptsified version of the package needs to be installed
135      on the servers, and a new upstream version would break scripts
136      without our changes, add a line like this:
137        Provides: scripts-[PACKAGE]
138      and correspondingly, add "scripts-[PACKAGE]" to the Requires line
139      in SVN/server/fedora/specs/scripts-base.spec (and remember to
140      build, upload, and deploy a new scripts-base package)
141
142    * Though we're not always good about it, do feel encouraged to add
143      an entry at the top of the %changelog section near the bottom of
144      the spec file explaining your modifications
145
146    * When you're finished with the updates to the upstream spec file,
147      create a diff from the upstream spec file to your new version,
148      and add it to the SVN repo as
149        SVN/server/fedora/specs/[PACKAGE].spec.patch
150      Make sure to copy it there before you try to build the package,
151      since if you don't mock will use the original specfile (and
152      overwrite any changes you made in place).
153
154Replacing the source of packages
155===============================
156
157    * Patch the specfile to have an alternate Source0 (or SourceX) URL
158      pointing to the updated source of the package.  You will then
159      need to add a spectool line to the Makefile to ensure this new
160      source gets downloaded on build:
161        spectool -g -R $(specs)/PACKAGE-NAME.spec
162
163Tips
164====
165
166    * Don't try to build a 32-bit package without building the 64-bit
167      package as well.
Note: See TracBrowser for help on using the repository browser.