rpm-guide rpm-guide-specfiles-en.xml,NONE,1.1

[Stuart Ellis (elliss)]

Author: elliss

Update of /cvs/docs/rpm-guide
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv2636

Added Files:
	rpm-guide-specfiles-en.xml 
Log Message:



--- NEW FILE rpm-guide-specfiles-en.xml ---
<!-- $Id: --> 
<chapter id="ch-specfiles">
<title>Working with Spec Files</title>

  <para>
    Copyright (c) 2005 by Eric Foster-Johnson. This material may be
    distributed only subject to the terms and conditions set forth in
    the Open Publication License, v1.0 or later (the latest version is
    presently available at http://www.opencontent.org/openpub/).
  </para>

  <para/>

  <para>
    In This Chapter
  </para>

  <para>
    *Writing spec files
  </para>

  <para>
    *Defining package information
  </para>

  <para>
    *Controlling the build
  </para>

  <para>
    *Listing the files in the package
  </para>

  <para>
    *Defining spec file macros
  </para>

  <para>
    The previous chapter introduces the concepts of how to build RPMs,
    and briefly covered the spec file, which controls how RPM packages
    are built and installed. This chapter delves into how to create spec
    files and the next chapter covers advanced spec file topics such as
    using conditional commands and making relocatable packages.
  </para>

  <para>
    A spec file defines all the commands and values that are required
    for creating a package, everything from the name and version number
    to the actual commands used to build the program you are packaging.
  </para>

  <para>
    This chapter covers the spec file syntax and how to write spec
    files. In goes in depth into defining information about your
    package, controlling how the software will be built, defining what
    exactly should go into the package, and customizing your build with
    RPM macros.
  </para>

  <sect1>
    <title>Reading Spec Files</title>
    <para>
      The first step to learning more about spec files is to read
      through some of the huge number of spec files for the source RPMs
      that come with your Linux distribution. Looking at these files
      will show two things right away:
    </para>
    <para>
      *You will see that the spec file syntax is not really as
      complicated as it appears.
    </para>
    <para>
      *You will see how many others have solved problems similar to
      those you need to solve.
    </para>
    <para>
      I’ve used real-world examples throughout this book, to show how
      the RPMs you need to deal with actually work. Some of the more
      interesting packages include anything that has a client and a
      server component, anything with networking or e-mail, and anything
      that installs a system service. All these types of packages solve
      problems that you will commonly face. Some useful spec files to
      look at are those for anonftp, telnet, vnc, and sendmail. To get
      these spec files, you need to install the corresponding source
      RPMs for each of these packages.
    </para>
    <para>
      As you read through spec files, you’ll start to see common
      patterns in how packages are defined, named, the macros used, and
      common elements in the build sections of the spec files. You’ll
      also see how network services are installed on Linux, as well as
      example install and uninstall scripts. The next sections provide
      more information on the things to look for within spec files.
    </para>
    <para>
      Furthermore, even with the plethora of options RPM provides, if
      you know shell scripting basics and something about how C programs
      are normally built, with configure scripts and make commands, you
      will find most spec files relatively easy to understand.
    </para>
    <para>
      The following sections go into the details of writing your own
      spec files. Keep your example spec files handy as you read through
      these sections.
    </para>
  </sect1>

  <sect1>
    <title>Writing Spec Files</title>
    <para>
      Spec files are text files containing RPM directives. These
      directives use a simple syntax of a tag name, a colon, and a
      value:
    </para>
    <para>
      TagName: value
    </para>
    <para>
      For example:
    </para>
    <para>
      Version: 1.15
    </para>
    <para>
      This example sets the package version to 1.15. The name of the
      item is not case sensitive, so tag names of version, Version, or
      VERSION all set the same value. This syntax works for most
      settings, including Name, Release, and so on.
    </para>
    <para>
      In addition to this directive syntax, you can define macros using
      the RPM %define syntax. For example:
    </para>
    <para>
      %define major 2
    </para>
    <para>
      This example defines a macro named major with a value of 2. Once
      defined, you can access macros using the %{macro_name} or just
      %macro_name syntaxes. For example:
    </para>
    <para>
      source: %{name}-%{version}.tar.gz
    </para>
    <para>
      See the section "Defining Spec File Macros" later in this chapter
      for more options for macros.
    </para>
    <para>
      Major sections in the spec file are also delimited with % markers.
      For example, the build section starts with %build on a line by
      itself.
    </para>
    <para>
      Note
    </para>
    <para>
      The multiple uses of the % sign aren’t really that confusing in
      practice. Read through some spec files and you should find most of
      the commands are easily understood.
    </para>
    <para>
      Blank lines separate sections in the spec file, which makes sense
      for readability as well.
    </para>
    <sect2>
      <title>Comments</title>
      <para>
        To help document your work, you can include comments (to
        yourself and others reading the spec file). Any line starting
        with a hash character, #, holds a comment. RPM will ignore
        comments.
      </para>
      <para>
        # This is a comment.
      </para>
      <para>
        In spec files, comments are mostly to help explain your syntax
        choices to yourself should you view the spec file later.
        Comments are a good thing. You should comment heavily,
        especially for any choice that deviates from the norm. For
        example, if you provide special C compiler options for building
        the package, add comments to describe why you picked the options
        and how necessary they are. Such comments help immensely should
        you need to port the RPM to another architecture or modify how
        it was built.
      </para>
      <para>
        Tip
      </para>
      <para>
        Avoid single percent signs, %, in comments. For example:
      </para>
      <para>
        # Added new commands to %prep
      </para>
      <para>
        The rpmbuild command may report an error of a second %prep
        section. To get around this problem, use two percent signs, such
[...2526 lines suppressed...]
    <para>
      <require name="make" />
    </para>
    <para>
      </buildrequires>
    </para>
    <para/>
    <para>
      <!-- packages -->
    </para>
    <para>
      <package group="System/Base" autoreqprov="no">
    </para>
    <para>
      <requires>
    </para>
    <para>
      <require name="glibc" />
    </para>
    <para>
      </requires>
    </para>
    <para>
      <summary>The Bash package contains the bash
      program.</summary>
    </para>
    <para>
      <description>%{summary}
    </para>
    <para>
      Bash is the Bourne-Again SHell, which is a widely used command
      interpreter
    </para>
    <para>
      on Unix systems. Bash is a program that reads from standard input,
      the
    </para>
    <para>
      keyboard. A user types something and the program will evaluate
      what he has
    </para>
    <para>
      typed and do something with it, like running a
      program.</description>
    </para>
    <para>
      <files list="%{name}.files.lst" />
    </para>
    <para>
      </package>
    </para>
    <para/>
    <para>
      <package name="bash-doc" group="Documentation/System/Base"
      autoreqprov="no">
    </para>
    <para>
      <requires>
    </para>
    <para>
      <require name="%{name}" />
    </para>
    <para>
      </requires>
    </para>
    <para>
      <summary>Documentation for the bash package.</summary>
    </para>
    <para>
      <description>%{summary}</description>
    </para>
    <para>
      <pre script="%{name}-doc.pre.sh" />
    </para>
    <para>
      <files list="%{name}-doc.files.lst" />
    </para>
    <para>
      </package>
    </para>
    <para/>
    <para>
      <!-- scripts to create the package -->
    </para>
    <para>
      <prep script="%{name}.prep.sh">
    </para>
    <para>
      <setup />
    </para>
    <para>
      <script>echo &quot;Prep
      completed&quot;</script>
    </para>
    <para>
      </prep>
    </para>
    <para>
      <build script="%{name}.build.sh" />
    </para>
    <para>
      <install script="%{name}.install.sh" />
    </para>
    <para>
      <clean script="%{name}.clean.sh" />
    </para>
    <para/>
    <para>
      <!-- changelog -->
    </para>
    <para>
      <changelog>
    </para>
    <para>
      <changes date="Mon Aug 26 2002" version="2.05a-02test"
    </para>
    <para>
      author="" author-email="">
    </para>
    <para>
      <change>Added setup macro to extract files</change>
    </para>
    <para>
      <change>Initial version ready for jbj</change>
    </para>
    <para>
      </changes>
    </para>
    <para>
      </changelog>
    </para>
    <para>
      </spec>
    </para>
    <para>
      Note
    </para>
    <para>
      XML spec files are a very experimental feature. Future releases of
      RPM will likely provide more support for XML spec files. The
      format will likely change.
    </para>
  </sect1>

  <sect1>
    <title>Summary</title>
    <para>
      This chapter covers spec files, the files that define how to build
      packages. Start your spec file by defining package information,
      such as the name, version, and release number. You can also add a
      detailed description to help administrators decide whether to
      install your packages.
    </para>
    <para>
      You need to name all of the source and patch files used to build
      the package. In most cases, the source files are compressed tar
      archives. After naming all the sources and patches, you need to
      control how the rpmbuild command should build your package. This
      comes in four sections.
    </para>
    <para>
      The %prep section prepares for the build by extracting the source
      files and applying patches. The %build section defines the
      commands to build the software, normally something as simple as
      running a configure script and then the make command. The %install
      section contains the commands for installing the software. And,
      the %clean section provides commands to clean up after the build.
    </para>
    <para>
      For these sections, you can use handy RPM macros for common tasks,
      such as running the configure script or the make install command.
      You can also define scripts the rpm command should run before and
      after installing, as well as before and after removing the
      package.
    </para>
    <para>
      Spec files contain a listing of all the files that should go into
      the package, as well as where those files should be placed on the
      user’s hard disk.
    </para>
    <para>
      You can define RPM macros in your spec files to make commands that
      can work with different directory structures as well as simplify
      common commands.
    </para>
    <para>
      While it may seem that this chapter described a great many options
      for making spec files, there’s more to come. The next chapter
      covers advanced spec file topics such as triggers, conditional
      builds, and specifying dependencies.
    </para>
  </sect1>
</chapter>
<!--
Local variables:
mode: xml
sgml-parent-document:("rpm-guide-en.xml" "book" "chapter")
fill-column: 72
End:
-->