home *** CD-ROM | disk | FTP | other *** search
/ Hackers Toolkit v2.0 / Hackers_Toolkit_v2.0.iso / HTML / archive / Unix / HOWTOs / RPM-HOWT < prev    next >
Text File  |  1999-11-04  |  33KB  |  850 lines
  1.   RPM HOWTO (RPM at Idle)
  2.   Donnie Barnes, djb@redhat.com
  3.   v2.0, 8 April 1997
  4.  
  5.   1.  Introduction
  6.  
  7.   RPM is the Red Hat Package Manager.  While it does contain Red Hat in
  8.   the name, it is completely intended to be an open packaging system
  9.   available for anyone to use.  It allows users to take source code for
  10.   new software and package it into source and binary form such that
  11.   binaries can be easily installed and tracked and source can be rebuilt
  12.   easily.  It also maintains a database of all packages and their files
  13.   that can be used for verifying packages and querying for information
  14.   about files and/or packages.
  15.  
  16.   Red Hat Software encourages other distribution vendors to take the
  17.   time to look at RPM and use it for their own distributions.  RPM is
  18.   quite flexible and easy to use, though it provides the base for a very
  19.   extensive system.  It is also completely open and available, though we
  20.   would appreciate bug reports and fixes.   Permission is granted to use
  21.   and distribute RPM royalty free under the GPL.
  22.  
  23.   More complete documentation is available on RPM in the book by Ed
  24.   Bailey, Maximum RPM.  That book is available for download or purchase
  25.   at www.redhat.com <http://www.redhat.com>.
  26.  
  27.   2.  Overview
  28.  
  29.   First, let me state some of the philosophy behind RPM.  One design
  30.   goal was to allow the use of ``pristine'' sources.  With RPP (our
  31.   former packaging system of which none of RPM is derived), our source
  32.   packages were the ``hacked'' sources that we built from.
  33.   Theoretically, one could install a source RPP and then make it with no
  34.   problems.  But the sources were not the original ones, and there was
  35.   no reference as to what changes we had to make to get it to build.
  36.   One had to download the pristine sources separately.  With RPM, you
  37.   have the pristine sources along with a patch that we used to compile
  38.   from.  We see this as a big advantage.  Why?  Several reasons.  For
  39.   one, if a new version of a program comes out, you don't necessarily
  40.   have to start from scratch to get it to compile under RHL.  You can
  41.   look at the patch to see what you might need to do.  All the compile-
  42.   in defaults are easily visible this way.
  43.  
  44.   RPM is also designed to have powerful querying options.  You can do
  45.   searches through your entire database for packages or just certain
  46.   files.  You can also easily find out what package a file belongs to
  47.   and where it came from.  The RPM files themselves are compressed
  48.   archives, but you can query individual packages easily and quickly
  49.   because of a custom binary header added to the package with everything
  50.   you could possibly need to know contained in uncompressed form.  This
  51.   allows for fast querying.
  52.  
  53.   Another powerful feature is the ability to verify packages.  If you
  54.   are worried that you deleted an important file for some package, just
  55.   verify it.  You will be notified of any anomalies.  At that point, you
  56.   can reinstall the package if necessary.  Any config files that you had
  57.   are preserved as well.
  58.  
  59.   We would like to thank the folks from the BOGUS distribution for many
  60.   of their ideas and concepts that are included in RPM.  While RPM was
  61.   completely written by Red Hat Software, its operation is based on code
  62.   written by BOGUS (PM and PMS).
  63.  
  64.   3.  General Information
  65.  
  66.   3.1.  Acquiring RPM
  67.  
  68.   The best way to get RPM is to install Red Hat Linux.  If you don't
  69.   want to do that, you can still get and use RPM.  It can be acquired
  70.   from ftp.redhat.com <ftp://ftp.redhat.com/pub/redhat/code/rpm>.
  71.  
  72.   3.2.  RPM Requirements
  73.  
  74.   The main requirement to run RPM is cpio 2.4.2 or greater.  While this
  75.   system is intended for use with Linux, it may very well be portable to
  76.   other Unix systems.  It has, in fact, been compiled on SunOS, Solaris,
  77.   AIX, Irix, AmigaOS, and others.  Be warned, the binary packages
  78.   generated on a different type of Unix system will not be compatible.
  79.  
  80.   Those are the minimal requirements to install RPMs.  To build RPMs
  81.   from source, you also need everything normally required to build a
  82.   package, like gcc, make, etc.
  83.  
  84.   4.  Using RPM
  85.  
  86.   In its simplest form, RPM can be used to install packages:
  87.  
  88.                rpm -i foobar-1.0-1.i386.rpm
  89.  
  90.   The next simplest command is to uninstall a package:
  91.  
  92.                rpm -e foobar
  93.  
  94.   One of the more complex but highly useful commands allows you to
  95.   install packages via FTP.  If you are connected to the net and want to
  96.   install a new package, all you need to do is specify the file with a
  97.   valid URL, like so:
  98.  
  99.                rpm -i ftp://ftp.pht.com/pub/linux/redhat/rh-2.0-beta/RPMS/foobar-1.0-1.i386.rpm
  100.  
  101.   Please note, that RPM will now query and/or install via FTP.
  102.  
  103.   While these are simple commands, rpm can be used in a multitude of
  104.   ways as seen from the Usage message:
  105.  
  106.   RPM version 2.3.9
  107.   Copyright (C) 1997 - Red Hat Software
  108.   This may be freely redistributed under the terms of the GNU Public License
  109.  
  110.   usage: rpm {--help}
  111.          rpm {--version}
  112.          rpm {--initdb}   [--dbpath <dir>]
  113.          rpm {--install -i} [-v] [--hash -h] [--percent] [--force] [--test]
  114.                           [--replacepkgs] [--replacefiles] [--root <dir>]
  115.                           [--excludedocs] [--includedocs] [--noscripts]
  116.                           [--rcfile <file>] [--ignorearch] [--dbpath <dir>]
  117.                           [--prefix <dir>] [--ignoreos] [--nodeps]
  118.                           [--ftpproxy <host>] [--ftpport <port>]
  119.                           file1.rpm ... fileN.rpm
  120.          rpm {--upgrade -U} [-v] [--hash -h] [--percent] [--force] [--test]
  121.                           [--oldpackage] [--root <dir>] [--noscripts]
  122.                           [--excludedocs] [--includedocs] [--rcfile <file>]
  123.                           [--ignorearch]  [--dbpath <dir>] [--prefix <dir>]
  124.                           [--ftpproxy <host>] [--ftpport <port>]
  125.                           [--ignoreos] [--nodeps] file1.rpm ... fileN.rpm
  126.          rpm {--query -q} [-afpg] [-i] [-l] [-s] [-d] [-c] [-v] [-R]
  127.                           [--scripts] [--root <dir>] [--rcfile <file>]
  128.                           [--whatprovides] [--whatrequires] [--requires]
  129.                           [--ftpuseport] [--ftpproxy <host>] [--ftpport <port>]
  130.                           [--provides] [--dump] [--dbpath <dir>] [targets]
  131.          rpm {--verify -V -y} [-afpg] [--root <dir>] [--rcfile <file>]
  132.                           [--dbpath <dir>] [--nodeps] [--nofiles] [--noscripts]
  133.                           [--nomd5] [targets]
  134.          rpm {--setperms} [-afpg] [target]
  135.          rpm {--setugids} [-afpg] [target]
  136.          rpm {--erase -e} [--root <dir>] [--noscripts] [--rcfile <file>]
  137.                           [--dbpath <dir>] [--nodeps] [--allmatches]
  138.                           package1 ... packageN
  139.          rpm {-b|t}[plciba] [-v] [--short-circuit] [--clean] [--rcfile  <file>]
  140.                           [--sign] [--test] [--timecheck <s>] specfile
  141.          rpm {--rebuild} [--rcfile <file>] [-v] source1.rpm ... sourceN.rpm
  142.          rpm {--recompile} [--rcfile <file>] [-v] source1.rpm ... sourceN.rpm
  143.          rpm {--resign} [--rcfile <file>] package1 package2 ... packageN
  144.          rpm {--addsign} [--rcfile <file>] package1 package2 ... packageN
  145.          rpm {--checksig -K} [--nopgp] [--nomd5] [--rcfile <file>]
  146.                              package1 ... packageN
  147.          rpm {--rebuilddb} [--rcfile <file>] [--dbpath <dir>]
  148.          rpm {--querytags}
  149.  
  150.   You can find more details on what those options do in the RPM man
  151.   page.
  152.  
  153.   5.  Now what can I really do with RPM?
  154.  
  155.   RPM is a very useful tool and, as you can see, has several options.
  156.   The best way to make sense of them is to look at some examples.  I
  157.   covered simple install/uninstall above, so here are some more
  158.   examples:
  159.  
  160.   ╖  Let's say you delete some files by accident, but you aren't sure
  161.      what you deleted.  If you want to verify your entire system and see
  162.      what might be missing, you would do:
  163.  
  164.        rpm -Va
  165.  
  166.   ╖  Let's say you run across a file that you don't recognize.  To find
  167.      out which package owns it, you would do:
  168.  
  169.        rpm -qf /usr/X11R6/bin/xjewel
  170.  
  171.   The output would be:
  172.  
  173.        xjewel-1.6-1
  174.  
  175.   ╖  You find a new koules RPM, but you don't know what it is.  To find
  176.      out some information on it, do:
  177.  
  178.        rpm -qpi koules-1.2-2.i386.rpm
  179.  
  180.   The output would be:
  181.  
  182.        Name        : koules                      Distribution: Red Hat Linux Colgate
  183.        Version     : 1.2                               Vendor: Red Hat Software
  184.        Release     : 2                             Build Date: Mon Sep 02 11:59:12 1996
  185.        Install date: (none)                        Build Host: porky.redhat.com
  186.        Group       : Games                         Source RPM: koules-1.2-2.src.rpm
  187.        Size        : 614939
  188.        Summary     : SVGAlib action game with multiplayer, network, and sound support
  189.        Description :
  190.        This arcade-style game is novel in conception and excellent in execution.
  191.        No shooting, no blood, no guts, no gore.  The play is simple, but you
  192.        still must develop skill to play.  This version uses SVGAlib to
  193.        run on a graphics console.
  194.  
  195.   ╖  Now you want to see what files the koules RPM installs.  You would
  196.      do:
  197.  
  198.        rpm -qpl koules-1.2-2.i386.rpm
  199.  
  200.   The output is:
  201.  
  202.   /usr/doc/koules
  203.   /usr/doc/koules/ANNOUNCE
  204.   /usr/doc/koules/BUGS
  205.   /usr/doc/koules/COMPILE.OS2
  206.   /usr/doc/koules/COPYING
  207.   /usr/doc/koules/Card
  208.   /usr/doc/koules/ChangeLog
  209.   /usr/doc/koules/INSTALLATION
  210.   /usr/doc/koules/Icon.xpm
  211.   /usr/doc/koules/Icon2.xpm
  212.   /usr/doc/koules/Koules.FAQ
  213.   /usr/doc/koules/Koules.xpm
  214.   /usr/doc/koules/README
  215.   /usr/doc/koules/TODO
  216.   /usr/games/koules
  217.   /usr/games/koules.svga
  218.   /usr/games/koules.tcl
  219.   /usr/man/man6/koules.svga.6
  220.  
  221.   These are just several examples.  More creative ones can be thought of
  222.   really easy once you are familiar with RPM.
  223.  
  224.   6.  Building RPMs
  225.  
  226.   Building RPMs is fairly easy to do, especially if you can get the
  227.   software you are trying to package to build on its own.
  228.  
  229.   The basic procedure to build an RPM is as follows:
  230.  
  231.   ╖  Make sure your /etc/rpmrc is setup for your system.
  232.  
  233.   ╖  Get the source code you are building the RPM for to build on your
  234.      system.
  235.  
  236.   ╖  Make a patch of any changes you had to make to the sources to get
  237.      them to build properly.
  238.  
  239.   ╖  Make a spec file for the package.
  240.  
  241.   ╖  Make sure everything is in its proper place.
  242.  
  243.   ╖  Build the package using RPM.
  244.  
  245.   Under normal operation, RPM builds both binary and source packages.
  246.  
  247.   6.1.  The rpmrc File
  248.  
  249.   Right now, the only configuration of RPM is available via the
  250.   /etc/rpmrc file.  An example one looks like:
  251.  
  252.   require_vendor: 1
  253.   distribution: I roll my own!
  254.   require_distribution: 1
  255.   topdir: /usr/src/me
  256.   vendor: Mickiesoft
  257.   packager:  Mickeysoft Packaging Account <packages@mickiesoft.com>
  258.  
  259.   optflags: i386 -O2 -m486 -fno-strength-reduce
  260.   optflags: alpha -O2
  261.   optflags: sparc -O2
  262.  
  263.   signature: pgp
  264.   pgp_name: Mickeysoft Packaging Account
  265.   pgp_path: /home/packages/.pgp
  266.  
  267.   tmppath: /usr/tmp
  268.  
  269.   The require_vendor line causes RPM to require that it find a vendor
  270.   line.  This can come from the /etc/rpmrc or from the header of the
  271.   spec file itself.  To turn this off, change the number to 0.  The same
  272.   holds true for the require_distribution and require_group lines.
  273.  
  274.   The next line is the distribution line.  You can define that here or
  275.   later in the header of the spec file.  When building for a particular
  276.   distribution, it's a good idea to make sure this line is correct, even
  277.   though it is not required.  The vendor  line works much the same way,
  278.   but can be anything (ie. Joe's Software and Rock Music Emporium).
  279.  
  280.   RPM also now has support for building packages on multiple
  281.   architectures.  The rpmrc file can hold an ``optflags'' variable for
  282.   building things that require architecture specific flags when
  283.   building.  See later sections for how to use this variable.
  284.  
  285.   In addition to the above macros, there are several more.  You can use:
  286.  
  287.        rpm --showrc
  288.  
  289.   to find out how your tags are set and what all the available flags
  290.   are.
  291.  
  292.   6.2.  The Spec File
  293.  
  294.   We'll begin with discussion of the spec file.  Spec files are required
  295.   to build a package.  The spec file is a description of the software
  296.   along with instructions on how to build it and a file list for all the
  297.   binaries that get installed.
  298.  
  299.   You'll want to name your spec file according to a standard convention.
  300.   It should be the package name-dash-version number-dash-release number-
  301.   dot-spec.
  302.  
  303.   Here is a small spec file (vim-3.0-1.spec):
  304.  
  305.   Summary: ejects ejectable media and controls auto ejection
  306.   Name: eject
  307.   Version: 1.4
  308.   Release: 3
  309.   Copyright: GPL
  310.   Group: Utilities/System
  311.   Source: sunsite.unc.edu:/pub/Linux/utils/disk-management/eject-1.4.tar.gz
  312.   Patch: eject-1.4-make.patch
  313.   Patch1: eject-1.4-jaz.patch
  314.   %description
  315.   This program allows the user to eject media that is autoejecting like
  316.   CD-ROMs, Jaz and Zip drives, and floppy drives on SPARC machines.
  317.  
  318.   %prep
  319.   %setup
  320.   %patch -p1
  321.   %patch1 -p1
  322.  
  323.   %build
  324.   make RPM_OPT_FLAGS="$RPM_OPT_FLAGS"
  325.  
  326.   %install
  327.   install -s -m 755 -o 0 -g 0 eject /usr/bin/eject
  328.   install -m 644 -o 0 -g 0 eject.1 /usr/man/man1
  329.  
  330.   %files
  331.   %doc README COPYING ChangeLog
  332.  
  333.   /usr/bin/eject
  334.   /usr/man/man1/eject.1
  335.  
  336.   6.3.  The Header
  337.  
  338.   The header has some standard fields in it that you need to fill in.
  339.   There are a few caveats as well.  The fields must be filled in as
  340.   follows:
  341.  
  342.   ╖  Summary: This is a one line description of the package.
  343.  
  344.   ╖  Name: This must be the name string from the rpm filename you plan
  345.      to use.
  346.  
  347.   ╖  Version: This must be the version string from the rpm filename you
  348.      plan to use.
  349.  
  350.   ╖  Release: This is the release number for a package of the same
  351.      version (ie. if we make a package and find it to be slightly broken
  352.      and need to make it again, the next package would be release number
  353.      2).
  354.  
  355.   ╖  Icon: This is the name of the icon file for use by other high level
  356.      installation tools (like Red Hat's ``glint'').  It must be a gif
  357.      and resides in the SOURCES directory.
  358.  
  359.   ╖  Source: This line points at the HOME location of the pristine
  360.      source file.  It is used if you ever want to get the source again
  361.      or check for newer versions.  Caveat:  The filename in this line
  362.      MUST match the filename you have on your own system (ie. don't
  363.      download the source file and change its name).  You can also
  364.      specify more than one source file using lines like:
  365.  
  366.   Source0: blah-0.tar.gz
  367.   Source1: blah-1.tar.gz
  368.   Source2: fooblah.tar.gz
  369.  
  370.   These files would go in the SOURCES directory. (The directory struc¡
  371.   ture is discussed in a later section, "The Source Directory Tree".)
  372.  
  373.   ╖  Patch: This is the place you can find the patch if you need to
  374.      download it again.  Caveat:  The filename here must match the one
  375.      you use when you make YOUR patch.  You may also want to note that
  376.      you can have multiple patch files much as you can have multiple
  377.      sources.  ] You would have something like:
  378.  
  379.        Patch0: blah-0.patch
  380.        Patch1: blah-1.patch
  381.        Patch2: fooblah.patch
  382.  
  383.   These files would go in the SOURCES directory.
  384.  
  385.   ╖  Copyright: This line tells how a package is copyrighted.  You
  386.      should use something like GPL, BSD, MIT, public domain,
  387.      distributable, or commercial.
  388.  
  389.   ╖  BuildRoot: This line allows you to specify a directory as the
  390.      ``root'' for building and installing the new package.  You can use
  391.      this to help test your package before having it installed on your
  392.      machine.
  393.  
  394.   ╖  Group: This line is used to tell high level installation programs
  395.      (such as Red Hat's ``glint'') where to place this particular
  396.      program in its hierarchical structure.  The group tree currently
  397.      looks something like this:
  398.  
  399.   Applications
  400.       Communications
  401.       Editors
  402.           Emacs
  403.       Engineering
  404.       Spreadsheets
  405.       Databases
  406.       Graphics
  407.       Networking
  408.       Mail
  409.       Math
  410.       News
  411.       Publishing
  412.           TeX
  413.   Base
  414.       Kernel
  415.   Utilities
  416.       Archiving
  417.       Console
  418.       File
  419.       System
  420.       Terminal
  421.       Text
  422.   Daemons
  423.   Documentation
  424.   X11
  425.       XFree86
  426.           Servers
  427.       Applications
  428.           Graphics
  429.           Networking
  430.       Games
  431.           Strategy
  432.           Video
  433.       Amusements
  434.       Utilities
  435.       Libraries
  436.       Window Managers
  437.   Libraries
  438.   Networking
  439.       Admin
  440.       Daemons
  441.       News
  442.       Utilities
  443.   Development
  444.       Debuggers
  445.       Libraries
  446.           Libc
  447.       Languages
  448.           Fortran
  449.           Tcl
  450.       Building
  451.       Version Control
  452.       Tools
  453.   Shells
  454.   Games
  455.  
  456.   ╖  %description  It's not really a header item, but should be
  457.      described with the rest of the header.  You need one description
  458.      tag per package and/or subpackage.  This is a multi-line field that
  459.      should be used to give a comprehensive description of the package.
  460.  
  461.   6.4.  Prep
  462.  
  463.   This is the second section in the spec file.  It is used to get the
  464.   sources ready to build.  Here you need to do anything necessary to get
  465.   the sources patched and setup like they need to be setup to do a make.
  466.  
  467.   One thing to note:  Each of these sections is really just a place to
  468.   execute shell scripts.  You could simply make an sh script and put it
  469.   after the %prep tag to unpack and patch your sources.  We have made
  470.   macros to aid in this, however.
  471.  
  472.   The first of these macros is the %setup macro.  In its simplest form
  473.   (no command line options), it simply unpacks the sources and cd's into
  474.   the source directory.  It also takes the following options:
  475.  
  476.   ╖  -n name will set the name of the build directory to the listed
  477.      name.  The default is $NAME-$VERSION.  Other possibilities include
  478.      $NAME, ${NAME}${VERSION}, or whatever the main tar file uses.
  479.      (Please note that these ``$'' variables are not real variables
  480.      available within the spec file.  They are really just used here in
  481.      place of a sample name.  You need to use the real name and version
  482.      in your package, not a variable.)
  483.  
  484.   ╖  -c will create and cd to the named directory before doing the
  485.      untar.
  486.  
  487.   ╖  -b # will untar Source# before cd'ing into the directory (and this
  488.      makes no sense with -c so don't do it).  This is only useful with
  489.      multiple source files.
  490.  
  491.   ╖  -a # will untar Source# after cd'ing into the directory.
  492.  
  493.   ╖  -T This option overrides the default action of untarring the Source
  494.      and requires a -b 0 or -a 0 to get the main source file untarred.
  495.      You need this when there are secondary sources.
  496.  
  497.   ╖  -D Do not delete the directory before unpacking.  This is only
  498.      useful where you have more than one setup macro.  It should only be
  499.      used in setup macros after the first one (but never in the first
  500.      one).
  501.  
  502.   The next of the available macros is the %patch macro.  This macro
  503.   helps automate the process of applying patches to the sources.  It
  504.   takes several options, listed below:
  505.  
  506.   ╖  # will apply Patch# as the patch file.
  507.  
  508.   ╖  -p # specifies the number of directories to strip for the patch(1)
  509.      command.
  510.  
  511.   ╖  -P The default action is to apply Patch (or Patch0).  This flag
  512.      inhibits the default action and will require a 0 to get the main
  513.      source file untarred.  This option is useful in a second (or later)
  514.      %patch macro that required a different number than the first macro.
  515.  
  516.   ╖  You can also do %patch# instead of doing the real command: %patch #
  517.      -P
  518.  
  519.   That should be all the macros you need.  After you have those right,
  520.   you can also do any other setup you need to do via sh type scripting.
  521.   Anything you include up until the %build macro (discussed in the next
  522.   section) is executed via sh.  Look at the example above for the types
  523.   of things you might want to do here.
  524.  
  525.   6.5.  Build
  526.  
  527.   There aren't really any macros for this section.  You should just put
  528.   any commands here that you would need to use to build the software
  529.   once you had untarred the source, patched it, and cd'ed into the
  530.   directory.  This is just another set of commands passed to sh, so any
  531.   legal sh commands can go here (including comments).  Your current
  532.   working directory is reset in each of these sections to the toplevel
  533.   of the source directory, so keep that in mind.  You can cd into
  534.   subdirectories if necessary.
  535.  
  536.   6.6.  Install
  537.  
  538.   There aren't really any macros here, either.  You basically just want
  539.   to put whatever commands here that are necessary to install.  If you
  540.   have make install available to you in the package you are building,
  541.   put that here.  If not, you can either patch the makefile for a make
  542.   install and just do a make install here, or you can hand install them
  543.   here with sh commands.  You can consider your current directory to be
  544.   the toplevel of the source directory.
  545.  
  546.   6.7.  Optional pre and post Install/Uninstall Scripts
  547.  
  548.   You can put scripts in that get run before and after the installation
  549.   and uninstallation of binary packages.  A main reason for this is to
  550.   do things like run ldconfig after installing or removing packages that
  551.   contain shared libraries.  The macros for each of the scripts is as
  552.   follows:
  553.  
  554.   ╖  %pre is the macro to do pre-install scripts.
  555.  
  556.   ╖  %post is the macro to do post-install scripts.
  557.  
  558.   ╖  %preun is the macro to do pre-uninstall scripts.
  559.  
  560.   ╖  %postun is the macro to do post-uninstall scripts.
  561.  
  562.   The contents of these sections should just be any sh style script,
  563.   though you do not need the #!/bin/sh.
  564.  
  565.   6.8.  Files
  566.  
  567.   This is the section where you must list the files for the binary
  568.   package.  RPM has no way to know what binaries get installed as a
  569.   result of make install.  There is NO way to do this.  Some have
  570.   suggested doing a find before and after the package install.  With a
  571.   multiuser system, this is unacceptable as other files may be created
  572.   during a package building process that have nothing to do with the
  573.   package itself.
  574.  
  575.   There are some macros available to do some special things as well.
  576.   They are listed and described here:
  577.  
  578.   ╖  %doc is used to mark documentation in the source package that you
  579.      want installed in a binary install.  The documents will be
  580.      installed in /usr/doc/$NAME-$VERSION-$RELEASE.  You can list
  581.      multiple documents on the command line with this macro, or you can
  582.      list them all separately using a macro for each of them.
  583.  
  584.   ╖  %config is used to mark configuration files in a package.  This
  585.      includes files like sendmail.cf, passwd, etc.  If you later
  586.      uninstall a package containing config files, any unchanged files
  587.      will be removed and any changed files will get moved to their old
  588.      name with a .rpmsave appended to the filename.  You can list
  589.      multiple files with this macro as well.
  590.  
  591.   ╖  %dir marks a single directory in a file list to be included as
  592.      being owned by a package.  By default, if you list a directory name
  593.      WITHOUT a %dir macro, EVERYTHING in that directory is included in
  594.      the file list and later installed as part of that package.
  595.  
  596.   ╖  %files -f <filename> will allow you to list your files in some
  597.      arbitrary file within the build directory of the sources.  This is
  598.      nice in cases where you have a package that can build it's own
  599.      filelist.  You then just include that filelist here and you don't
  600.      have to specifically list the files.
  601.  
  602.   The biggest caveat in the file list is listing directories.  If you
  603.   list /usr/bin by accident, your binary package will contain every file
  604.   in /usr/bin on your system.
  605.  
  606.   6.9.  Building It
  607.  
  608.   6.9.1.  The Source Directory Tree
  609.  
  610.   The first thing you need is a properly configured build tree.  This is
  611.   configurable using the /etc/rpmrc file.  Most people will just use
  612.   /usr/src.
  613.  
  614.   You may need to create the following directories to make a build tree:
  615.  
  616.   ╖  BUILD is the directory where all building occurs by RPM.  You don't
  617.      have to do your test building anywhere in particular, but this is
  618.      where RPM will do it's building.
  619.  
  620.   ╖  SOURCES is the directory where you should put your original source
  621.      tar files and your patches.  This is where RPM will look by
  622.      default.
  623.  
  624.   ╖  SPECS is the directory where all spec files should go.
  625.  
  626.   ╖  RPMS is where RPM will put all binary RPMs when built.
  627.  
  628.   ╖  SRPMS is where all source RPMs will be put.
  629.  
  630.   6.9.2.  Test Building
  631.  
  632.   The first thing you'll probably want to to is get the source to build
  633.   cleanly without using RPM.  To do this, unpack the sources, and change
  634.   the directory name to $NAME.orig.  Then unpack the source again.  Use
  635.   this source to build from.  Go into the source directory and follow
  636.   the instructions to build it.  If you have to edit things, you'll need
  637.   a patch.  Once you get it to build, clean the source directory.  Make
  638.   sure and remove any files that get made from a configure script.  Then
  639.   cd back out of the source directory to its parent.  Then you'll do
  640.   something like:
  641.  
  642.                diff -uNr dirname.orig dirname > ../SOURCES/dirname-linux.patch
  643.  
  644.   This will create a patch for you that you can use in your spec file.
  645.   Note that the ``linux'' that you see in the patch name is just an
  646.   identifier.  You might want to use something more descriptive like
  647.   ``config'' or ``bugs'' to describe why you had to make a patch.  It's
  648.   also a good idea to look at the patch file you are creating before
  649.   using it to make sure no binaries were included by accident.
  650.  
  651.   6.9.3.  Generating the File List
  652.  
  653.   Now that you have source that will build and you know how to do it,
  654.   build it and install it.  Look at the output of the install sequence
  655.   and build your file list from that to use in the spec file.  We
  656.   usually build the spec file in parallel with all of these steps.  You
  657.   can create the initial one and fill in the easy parts, and then fill
  658.   in the other steps as you go.
  659.  
  660.   6.9.4.  Building the Package with RPM
  661.  
  662.   Once you have a spec file, you are ready to try and build your
  663.   package.  The most useful way to do it is with a command like the
  664.   following:
  665.  
  666.                rpm -ba foobar-1.0.spec
  667.  
  668.   There are other options useful with the -b switch as well:
  669.  
  670.   ╖  p means just run the prep section of the specfile.
  671.  
  672.   ╖  l is a list check that does some checks on %files.
  673.  
  674.   ╖  c do a prep and compile.  This is useful when you are unsure of
  675.      whether your source will build at all.  It seems useless because
  676.      you might want to just keep playing with the source itself until it
  677.      builds and then start using RPM, but once you become accustomed to
  678.      using RPM you will find instances when you will use it.
  679.  
  680.   ╖  i do a prep, compile, and install.
  681.  
  682.   ╖  b prep, compile, install, and build a binary package only.
  683.  
  684.   ╖  a build it all (both source and binary packages).
  685.  
  686.      There are several modifiers to the -b switch.  They are as follows:
  687.  
  688.   ╖  --short-circuit will skip straight to a specified stage (can only
  689.      be used with c and i).
  690.  
  691.   ╖  --clean removes the build tree when done.
  692.  
  693.   ╖  --keep-temps will keep all the temp files and scripts that were
  694.      made in /tmp.  You can actually see what files were created in /tmp
  695.      using the -v option.
  696.  
  697.   ╖  --test does not execute any real stages, but does keep-temp.
  698.  
  699.   6.10.  Testing It
  700.  
  701.   Once you have a source and binary rpm for your package, you need to
  702.   test it.  The easiest and best way is to use a totally different
  703.   machine from the one you are building on to test.  After all, you've
  704.   just done a lot of make install's on your own machine, so it should be
  705.   installed fairly well.
  706.  
  707.   You can do an rpm -u packagename on the package to test, but that can
  708.   be deceiving because in building the package, you did a make install.
  709.   If you left something out of your file list, it will not get
  710.   uninstalled.  You'll then reinstall the binary package and your system
  711.   will be complete again, but your rpm still isn't.  Make sure and keep
  712.   in mind that just because you do a rpm -ba package, most people
  713.   installing your package will just be doing the rpm -i package.  Make
  714.   sure you don't do anything in the build or install sections that will
  715.   need to be done when the binaries are installed by themselves.
  716.  
  717.   6.11.  What to do with your new RPMs
  718.  
  719.   Once you've made your own RPM of something (assuming its something
  720.   that hasn't already been RPM'ed), you can contribute your work to
  721.   others (also assuming you RPM'ed something freely distributable).  To
  722.   do so, you'll want to upload it to ftp.redhat.com
  723.   <ftp://ftp.redhat.com>.
  724.  
  725.   6.12.  What Now?
  726.  
  727.   Please see the above sections on Testing and What to do with new RPMs.
  728.   We want all the RPMs available we can get, and we want them to be good
  729.   RPMs.  Please take the time to test them well, and then take the time
  730.   to upload them for everyone's benefit.  Also, please make sure you are
  731.   only uploading freely available software.  Commercial software and
  732.   shareware should not be uploaded unless they have a copyright
  733.   expressly stating that this is allowed.  This includes Netscape
  734.   software, ssh, pgp, etc.
  735.  
  736.   7.  Multi-architectural RPM Building
  737.  
  738.   RPM can now be used to build packages for the Intel i386, the Digital
  739.   Alpha running Linux, and the Sparc.  It has been reported to work on
  740.   SGI's and HP workstations as well.  There are several features that
  741.   make building packages on all platforms easy.  The first of these is
  742.   the ``optflags'' directive in the /etc/rpmrc.  It can be used to set
  743.   flags used when building software to architecture specific values.
  744.   Another feature is the ``arch'' macros in the spec file.  They can be
  745.   used to do different things depending on the architecture you are
  746.   building on.  Another feature is the ``Exclude'' directive in the
  747.   header.
  748.  
  749.   7.1.  Sample spec File
  750.  
  751.   The following is part of the spec file for the ``fileutils'' package.
  752.   It is setup to build on both the Alpha and the Intel.
  753.  
  754.   Summary: GNU File Utilities
  755.   Name: fileutils
  756.   Version: 3.16
  757.   Release: 1
  758.   Copyright: GPL
  759.   Group: Utilities/File
  760.   Source0: prep.ai.mit.edu:/pub/gnu/fileutils-3.16.tar.gz
  761.   Source1: DIR_COLORS
  762.   Patch: fileutils-3.16-mktime.patch
  763.  
  764.   %description
  765.   These are the GNU file management utilities.  It includes programs
  766.   to copy, move, list, etc, files.
  767.  
  768.   The ls program in this package now incorporates color ls!
  769.  
  770.   %prep
  771.   %setup
  772.  
  773.   %ifarch alpha
  774.   %patch -p1
  775.   autoconf
  776.   %endif
  777.   %build
  778.   configure --prefix=/usr --exec-prefix=/
  779.   make CFLAGS="$RPM_OPT_FLAGS" LDFLAGS=-s
  780.  
  781.   %install
  782.   rm -f /usr/info/fileutils*
  783.   make install
  784.   gzip -9nf /usr/info/fileutils*
  785.  
  786.   7.2.  Optflags
  787.  
  788.   In this example, you see how the ``optflags'' directive is used from
  789.   the /etc/rpmrc.  Depending on which architecture you are building on,
  790.   the proper value is given to RPM_OPT_FLAGS.  You must patch the
  791.   Makefile for your package to use this variable in place of the normal
  792.   directives you might use (like -m486 and -O2).  You can get a better
  793.   feel for what needs to be done by installing this source package and
  794.   then unpacking the source and examine the Makefile.  Then look at the
  795.   patch for the Makefile and see what changes must be made.
  796.  
  797.   7.3.  Macros
  798.  
  799.   The %ifarch macro is very important to all of this.  Most times you
  800.   will need to make a patch or two that is specific to one architecture
  801.   only.  In this case, RPM will allow you to apply that patch to just
  802.   one architecture only.
  803.  
  804.   In the above example, fileutils has a patch for 64 bit machines.
  805.   Obviously, this should only be applied on the Alpha at the moment.
  806.   So, we add an %ifarch macro around the 64 bit patch like so:
  807.  
  808.        %ifarch axp
  809.        %patch1 -p1
  810.        %endif
  811.  
  812.   This will insure that the patch is not applied on any architecture
  813.   except the alpha.
  814.  
  815.   7.4.  Excluding Architectures from Packages
  816.  
  817.   So that you can maintain source RPMs in one directory for all
  818.   platforms, we have implemented the ability to ``exclude'' packages
  819.   from being built on certain architectures.  This is so you can still
  820.   do things like
  821.  
  822.        rpm --rebuild /usr/src/SRPMS/*.rpm
  823.  
  824.   and have the right packages build.  If you haven't yet ported an
  825.   application to a certain platform, all you have to do is add a line
  826.   like:
  827.  
  828.        ExcludeArch: axp
  829.  
  830.   to the header of the spec file of the source package.  Then rebuild
  831.   the package on the platform that it does build on.  You'll then have a
  832.   source package that builds on an Intel and can easily be skipped on an
  833.   Alpha.
  834.  
  835.   7.5.  Finishing Up
  836.  
  837.   Using RPM to make multi-architectural packages is usually easier to do
  838.   than getting the package itself to build both places.  As more of the
  839.   hard packages get built this is getting much easier, however.  As
  840.   always, the best help when you get stuck building an RPM is to look a
  841.   similar source package.
  842.  
  843.   8.  Copyright Notice
  844.  
  845.   This document and its contents are copyright protected.
  846.   Redistribution of this document is permitted as long as the content
  847.   remains completely intact and unchanged.  In other words, you may
  848.   reformat and reprint or redistribute only.
  849.  
  850.