Fedora spec files

There is a similar ApplyOptionalPatch function that will optionally apply a patch if it is not empty and skip it otherwise. This is seldom used. This is the function that is primarily responsible for actually building the kernel and modules. MakeTarget : This is the name of the vmlinux target to build.

This can vary among the architectures. On x86, it is bzImage. On powerpc it is vmlinux. KernelImage : This is the relative path to the final 'MakeTarget' binary that is produced during the build.

Flavour : This is an optional argument the allows us to build multiple kernel flavors for each rpmbuild invocation. InstallName : This is optional and not actually specified anywhere today. The default value of 'vmlinuz' is used. It is the leading portion of the name of the final kernel binary that we install.

The BuildKernel function takes these arguments and builds the kernel and modules via the kernel's makefile system. It generates the correct. It also sets up the proper headers and paths for the kernel-devel and debuginfo packages. Essentially this is where virtually all of the build and installation happens for every rpmbuild. Other tools : Various other tools that are contained within the kernel sources are also built after perf.

Packagers should consider the number of affected directories and packages when determining whether to create artificial filesystem packages, and use their own best judgement to determine if this is necessary or not. Permissions on files MUST be set properly. They MUST be universally readable and executable if appropriate. The default file mode is or Directories should be mode Most well behaved build scripts and rpm will use these defaults. If the directory needs to be group writable, it SHOULD also have the setgid bit set so that files written there are owned by that group.

Guidelines for handling these cases are in a separate document. This is done because:. Whenever possible, Fedora packages should avoid conflicting with each other. Unfortunately, this is not always possible.

The "alternatives" tool provides a means for parallel installation of packages which provide the same functionality by maintaining sets of symlinks. For full details on how to properly use alternatives, see Alternatives. In such situations, use of Environment Modules can avoid conflicts. For full details on how to properly use Environment Modules, see Environment Modules. Any time you create a patch, it is best practice to file it in an upstream bug tracker, and include a link to that in the comment above the patch.

The above is perfectly acceptable; but if you prefer, a brief comment about what the patch does above can be helpful:. It will help others and even you down the line in package maintenance by knowing what patches are likely to appear in a new upstream release.

Storing the files in this way allows people to use standard tools to visualize the changes between revisions of the files and track additions and removals without a layer of indirection as putting them into lookaside would do.

The maintainer MAY deviate from this rule when the upstream of the package provides an extremely large patch or a tarball of patches against a base release. Maintainers and reviewers should be cautious when exercising this exception as shipping an update as a patchset may be a sign that the patchset is not from the actual upstream or that the patches should be reviewed for correctness rather than simply accepted as the upstream code base.

RPM supports a field called "Epoch:", which is a numeric field, that, if set, adds another qualifier for RPM to use in doing package comparisons. Specifically, if set, the Epoch of a package trumps all other comparisons except for a larger Epoch.

If Epoch is not set in a package, RPM treats it the same as if it was set to 0. A package with those definitions would be considered greater than a package with a higher version or a higher release. Since Epoch is confusing to humans and can never be removed from a package once used , it should only be used in Fedora as a last resort to resolve upgrade ordering of a package, and should be avoided wherever possible.

Also, Epoch complicates normal packaging guidelines. For example, if a package being depended upon has an Epoch, this must be listed when adding a versioned dependency:. If a package to be imported is or previously was present in a publicly accessible repository, the packager can optionally include an Epoch tag equal to that of the most recent version of the third-party package.

There are two ways of making a symlink, either as a relative link or an absolute link. In Fedora, neither method is required. Packagers should use their best judgement when deciding which method of symlink creation is appropriate. A relative symlink is a symlink which points to a file or directory relative to the position of the symlink.

For example, this command would create a relative symlink:. Relative symlinks may break or behave unexpectedly when a part of a filesystem is mounted to a custom location. An absolute symlink is a symlink which points to an absolute file or directory path. For example, this command would create an absolute symlink:. In some cases replacing a symlink to a directory requires special handling.

Replacing a directory with any type of file always requires special handling. If you install a sysctl configuration snippet foobar. If you install a binfmt configuration snippet waldo. These have the effect of making the appropriate changes immediately upon package installation instead of requiring a reboot or manual activation. There are specific guidelines for handling tmpfiles. In the event that it becomes necessary to rename or replace an existing package, the new package should make the change transparent to end users to the extent applicable.

If a package is being renamed without any functional changes, or is a compatible enough replacement to an existing package where "enough" means that it includes only changes of magnitude that are commonly found in version upgrade changes , provide clean upgrade paths and compatibility with:. You usually use macros here because the provides EVR should continue to go up as the renamed package advances in version and release.

If retired packages need to be removed from end user machines because they cause dependency issues which interfere with upgrades or are otherwise harmful, a packager SHOULD request that Obsoletes: be added to fedora-obsolete-packages.

Simply file a bugzilla ticket here. Please include information on which packages need to be obsoleted, the exact versions which need to be obsoleted, and the reasons why they cannot be allowed to remain installed. If the obsoleted package had an Epoch set, it must be preserved in both the Provides: and Obsoletes:. For example, assume foo being renamed to bar, bar is compatible with foo, and the last foo package release being foo The following should be added to bar and similarly for all subpackages as applicable :.

Explicit Provides: need to be aware of whether the package is supplying things that can be used in an arch-independent or arch-specific fashion. In some cases, a package will supply multiple elements, some of which may be consumed only by dependents of an identical arch and some which may be consumed by dependents of any arch. In such cases, both arch-specific and arch-independent Provides: are warranted.

Examples of packages that should explicitly provide only arch-specific Provides: include native code libraries or plug-ins and their associated -devel packages. Packages that should explicitly provide only arch-independent Provides: include most stand-alone programs in addition to all noarch packages. Even though these programs may themselves be arch-specific, clients that run them should not care about their arch in most cases. A package that explicitly provides, for example, both a native code library as well as an interpreted language interface to that library should have both arch-specific for clients of the native code library and arch-independent for clients of the interpreted language interface Provides:.

If there is no standard naming for a package or other long term naming compatibility requirements involved with the rename, the Provides should be assumed to be deprecated and short lived and removed in the distro release after the next one i. Maintainers of affected packages should be notified and encouraged to switch to use the new name.

Forward compatibility Provides: in older distro branches can be considered in order to make it possible for package maintainers to keep same simple specfiles between branches but still switch to the newer name. Note however that the -devel subpackages of lib packages are pulled in as build dependencies using the package name, so adding the Provides is often appropriate there.

A procedure exists for indicating that a package is deprecated and may leave the distribution in the future. See Deprecating Packages. For details on how to package cron files, refer to: CronFiles. If an update to your package resolves a known security concern at the time of the update with a Common Vulnerabilities and Exposures CVE number assigned to it, you should mention the CVE number in the RPM changelog entry.

Packages in the Fedora buildsystem are built in a mock chroot with no access to the internet. If your package introduces build time circular dependencies, you should use this macro to bootstrap your package:.

If your package explicitly Provides: some functionality that is missing when bootstrapped, then that Provides: should look like:. Please note that usage of pre-built binaries in bootstrap still needs an exception from the Packaging Committee as stated in General Exception Policy.

When packaging script files, where the interpreter to be used is specified in the first line of the script the shebang line following! Various checks are also applied to verify that the shebang lines are valid, and the build process can fail as a result of these.

Finally, other language-specific modifications may also be made. It is thus generally unnecessary to manually modify executable scripts to fix env usage as long as this functionality is enabled. The packager can elect to fix the shebang lines manually using patches, scripting via sed, or other similar methods.

The packager can remove the executable permission from the script so that the checks and modifications are not made. If and only if the script needs to remain executable and cannot be modified to pass the checks, then the maintainer MAY elect to disable the checks and modifications. For example, to disable the brp-python-bytecompile script:. For a list of the BRP scripts run by default, invoke:.

For the most part, these guidelines and the application-specific guidelines below cover packaging for both Fedora and EPEL. However, there are necessarily some differences. Some applications, languages and build systems have specific guidelines written for them, located on their own pages:. Want to help? Learn how to contribute to Fedora Docs. Edit this Page. Applicability In general, these guidelines apply to the currently released, non-end-of-life versions of Fedora, as well as the development version of Fedora Rawhide.

General Exception Policy As these guidelines can never cover all possible contingencies, there will always be packages which need exceptions.

Naming You should go through the Naming Guidelines to ensure that your package is named appropriately. Version and Release Documentation covering the proper way to use the Version and Release fields can be found here.

Libraries and Applications Many language- or domain-specific guidelines refer to "libraries", "modules", "plug-ins" or other terms specific to the language or domain. Library or Application? Mixed Use Packages Many packages, regardless of their primary purpose, include both applications and libraries. Spec Files The spec file "spec" is a fundamental element in the packaging workflow. Spec Legibility All spec files MUST be legible and maintained in such a way that the community of packagers is able to understand and work with them.

Spec File Encoding Unless you need to use characters outside the ASCII repertoire , you will not need to be concerned about the encoding of the spec file. Obtaining the Correct Keys The verification method requires an OpenPGP keyring file with one or more public keys from the upstream project.

Exceptions If the upstream tarball of a package needs to be modified, for example because it contains forbidden items, then the tarball cannot be verified as part of the build process. Help If you need help getting your package compliant to this guideline, or if you do not know what to do if a build fails on a signature verification, then you should seek help on the Fedora devel mailing list before circumventing the check, to make sure that you do not build compromised software.

Architecture Support All Fedora packages must successfully compile and build into binary rpms on at least one supported primary architecture, except where the package is useful only on a secondary architecture such as an architecture-specific boot utility, microcode loader, or hardware configuration tool.

Architecture Build Failures If a Fedora package does not successfully compile, build or work on an architecture, then those architectures should be listed in the spec in ExcludeArch. Noarch with Unported Dependencies Sometimes you are working on a noarch package that can only run in locations that a different, arched package builds on. Arch-Specific Runtime and Build-Time Dependencies You can limit both the architectures used to build a noarch package, and the repositories to which the built noarch package will be added, by using either the ExcludeArch: or ExclusiveArch: tags:.

Filesystem Layout Fedora follows the Filesystem Hierarchy Standard with regards to filesystem layout, with exceptions noted below. Distributions must take care not to remove locally placed files in these directories without administrator permission.

In addition, no Fedora package can contain files or directories or modify files under:. Use rpmlint Run rpmlint on binary and source rpms to examine them for common errors, and fix them unless rpmlint is wrong, which can happen, too. File and Directory Dependencies RPM gives you the ability to depend on arbitrary files or directories instead of packages. Explicit Requires Explicit Requires are Requires added manually by the packager in the spec file. The automatic dependency on libfubar.

Build-Time Dependencies BuildRequires It is important that your package list all necessary build dependencies using the BuildRequires: tag.

BuildRequires Based on pkg-config Fedora packages which use pkg-config to build against a library e. Conditional Build-Time Dependencies If the spec file contains conditional dependencies selected based on presence of optional --with out foo arguments to rpmbuild , build the source RPM to be submitted with the default options, i. Summary and Description The summary should be a short and concise description of the package. Trademarks in Summary or Description Packagers should be careful how they use trademarks in Summary or Description.

Documentation Any relevant documentation included in the source distribution should be included in the package in the proper documentation directory. Changelogs Every time you make changes, that is, whenever you increment the E-V-R of a package, add a changelog entry. Multiple Changelog Entries per Release In some situations, it may be useful for packagers to have multiple changelog entries in the spec file, but not increment the release field for each one.

Updating and replacing the existing date line In this situation, you have added this changelog entry, but have not built the package yet:. Please remember that this is only acceptable if 1.

Repeat the old version release with a new entry In this situation, you have added this changelog entry, but have not built the package yet:. Compiler Fedora packages should default to using gcc as the compiler for all languages that gcc supports or clang if upstream does not support building with gcc. The default compiler cannot build a package correctly. The default compiler takes significantly longer to build a package. The default compiler is missing a feature that would benefit the package.

Compiler Flags Compilers used to build packages must honor the applicable compiler flags set in the system rpm configuration. In Fedora, PIE is enabled by default. To disable it in your spec, add:. Your package has suid binaries, or binaries with capabilities. Your package runs as root.

Debuginfo Packages Packages should produce useful -debuginfo packages, or explicitly disable them when it is not possible to generate a useful one but rpmbuild would do it anyway.

Devel Packages Fedora packages must be designed with a logical separation of files. Header files foo. There are some notable exceptions to this packaging model, specifically:. Pkgconfig Files foo. Requiring Base Package Subpackages are often extensions for their base package and in that case they should require their base package. There are two scenarios in which static libraries are packaged: Static libraries and shared libraries. The 3mux package. The 3proxy rpms. The 4diac-forte package.

The 4Pane rpms. The 4th package. The 4ti2 rpms. The 5minute package. The 64tass rpms. The open-source version of Seven Kingdoms: Ancient Adversaries 7kaa. The 8Kingdoms rpms.

The 8sync package. The Second-Portraits package. The resolution rpms. The 99soft-oss-parent rpms. Defining Spec File Macros 9. Built-in macros 9.

Spec file-specific macros 9. Defining new macros 9. Specifying parameters to macros 9. 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. 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. 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.

Reading Spec Files.