From Fedora Project Wiki

No edit summary
 
Line 64: Line 64:


== Sections ==
== Sections ==
Though sections look like (and technically are) macros, they they cannot be surrounded by braces as macros can.


Except for %changelog, all sections should be followed by two blank lines.
Except for %changelog, all sections should be followed by two blank lines.
Though sections look like (and technically are) macros, they they cannot be surrounded by braces as macros can.
Sections which are present MUST appear in the following order:
Sections which are present MUST appear in the following order:



Latest revision as of 23:34, 20 February 2017

Warning.png
Draft
This document is only a draft! It shouldn't actively harm anything to follow what's presented here, please don't yet take it as anything official. It is in a very early state, such that it's just one person's opinion, and some of the choices are completely arbitrary. You will almost certainly find something here with which you disagree.

The Packaging Guidelines provide a wealth of information about what should and should not be present in a spec file, but they don't specify everything. In some cases that's because there is no point in prescribing every detail of packaging, and in some cases there simply is no agreement about how something should be done (and no will to fight about it endlessly).

This document attempts to fill in some of those gaps, so that new package maintainers aren't left to invent their own styles or copy and paste from existing (and perhaps poorly maintained) specs.

For now this will purposefully leave out everything which is covered by the packaging guidelines. This may result in odd things such as this document telling you where Summary: goes in the spec and whether it can be indented, but not that it doesn't end in a period. As this document is fleshed out, things may end up being moved between it and the guidelines. It might even be subsumed entirely into the guidelines.

Spaces/Tabs/Indentation

Use the following spacing rules:

  • The default indent MUST be four spaces.
  • Tabs MUST not be used.
  • Trailing whitespace MUST NOT be present.

Tags

Tags are the colon-terminated strings which go near the beginning of the spec and which are required by RPM to occur before the first section (except in the case of subpackage declarations).

Ordering of Tags

Tags SHOULD occur in roughly the following order. This improves readability.

  • The initial set, which provide the most basic information about the spec. These should be as close to the top of the spec as possible, such that they at least appear on the first page when viewed in an average terminal window.
    1. Name:
    2. Version:
    3. Release:
    4. Summary:
  • A blank line, to set these off from the rest.
  • Further important information:
    1. License:
    2. URL:
    3. SourceN: lines
    4. PatchN: lines
    5. BuildArch:
  • A blank line
  • Dependency information
    1. BuildRequires:
    2. Requires: (manually listed dependencies)
    3. Requires(pre/post/preun/postun): (manually listed scriptlet dependencies)
  • A single blank line to end the set of tags and offset it from %description

Spacing and Indentation of Tags

The various sets of tags (see above) SHOULD be separated by single blank lines to enable them to be easily found by the eye. Additional space MAY be inserted to set large groups of tags apart, which can be useful in the case of a package with many sources, patches, or build dependencies.

Tags and their values MUST be separated by at least one space. Additional whitespace MAY be inserted between the tag and its value to line up the values visually, though this is not required. As some of the tags can be long, this indentation SHOULD NOT extend beyond the 16th column, which is sufficient space to indent BuildRequires: tags. Too much indentation makes it difficult to visually line up tags and values.

Sources

If more than one source tag is present, all source tags SHOULD carry a number. It is easy to become confused between Source:, Source0: and Source1:.

Some source file naming is of course dictated by upstream. Files which will be installed directly into the buildroot SHOULD if possible carry the name they will have in the final package. This makes constructs such as install -p -m 755 %SOURCE5 %buildroot/%__bindir possible.

There are not really any reasonable guidelines to give for other source files.

Patches

If more than one patch tag is present, all patch tags SHOULD carry a number. It is easy to become confused between Patch:, Patch0: and Patch1:.

Sadly RPM does not allow patches to be stored in a subdirectory. If multiple patches are present, their filenames SHOULD be prefixed identically, so that they appear together in a directory listing. It is not necessary to prefix them with the name of the package, or with the package and version, though this is OK if the maintainers find it to be useful.

Sections

Though sections look like (and technically are) macros, they they cannot be surrounded by braces as macros can.

Except for %changelog, all sections should be followed by two blank lines. Though sections look like (and technically are) macros, they they cannot be surrounded by braces as macros can.

Sections which are present MUST appear in the following order:

  1. %description
  2. Any subpackage declarations
  3. %prep
  4. %build
  5. %install
  6. %check
  7. scriptlets
  8. file triggers
  9. %files
  10. %changelog

Scriptlets SHOULD appear in the following order, which is approximately the order in which RPM will execute them:

  1. %pretrans
  2. %pre
  3. %post
  4. %triggerin
  5. %preun
  6. %postun
  7. %triggerpostun
  8. %posttrans

File triggers SHOULD appear in the following order:

  1. %filetriggerin
  2. %filetriggerun
  3. %filetriggerpostun
  4. %transfiletriggerin
  5. %transfiletriggerun
  6. %transfiletriggerpostun