RFC: Packager's Guide - Content Specification

Petr Kovar pkovar at redhat.com
Wed Mar 12 18:47:47 UTC 2014

Hi all,

This is not really related to the current conversations about playground
repos etc., but I wanted to bring this up anyway.

I put together a content specification of the brand new Packager's Guide
(TM), which we also mention in the PRD:

	Some people prefer to use a single document to learn about concepts
	and tasks rather that browsing through a number of wiki pages. Wiki
	content may not feel qualified and may not invoke the same trust as
	formal documentation. pkovar will be working on a new Packager's
	Guide, to help people getting started with RPM packaging for Fedora
	and EPEL. The goal is to share as much content as possible with
	downstream RHEL/EPEL documentation, using the same format and
	toolchain (DocBook, Publican). The guide will be mostly based on
	the Fedora wiki pages/HOWTOs. It will reference additional
	resources on the wiki (esp. in the Packaging: namespace) and/or
	other content where appropriate. An outdated draft is here:

The content specification is mostly based on
http://fedoraproject.org/wiki/How_to_create_an_RPM_package and intended to
replace the outdated and unmaintained RPM Guide [1]. It will also allow us
to get rid of some rather obsolete packaging HOWTOs on Fedora wiki, such as

But first of all, it will allow people who are getting started with RPM
packaging to find the content they are looking for in one
place, without having to try their luck with searching the somewhat bloated
Fedora wiki.

This guide fills in the gap for RPM formal documentation in Fedora. This
can help people getting started with SCLs, too: the Fedora Software
Collections Guide assumes that the readers already have substantial
knowledge of RPM packaging.

[2] http://fedoraproject.org/wiki/How_to_create_a_GNU_Hello_RPM_package

Please let me know your comments, suggestions or questions. Thanks.

Table of Contents

* Introduction to the RPM Package Manager:
             This chapter introduces the RPM Package Manager, describes the
             RPM package design, defines the basic content of every RPM
             package, and shows how to explore the RPM package structure 

        What Are Packages, and Why Manage Them?

        RPM Design Goals

        What Is in a Package?

        Using rpm2cpio

        Source Package Files and How to Use Them

* Creating and Building RPM Packages:
             This chapter discusses the basics of creating and
             building RPM packages and provides a spec file overview.

        Preparing Your System

        The Basics of Building RPM Packages 
                Creating a Basic spec File
                    spec Templates and Examples
                Building a Package
                Testing a Package
                    Testing a spec File
                    Testing a spec File
                    Testing a Binary Package
                    Testing a Source Package

        spec File Overview
            spec File Sections Explained
            %prep Section
                %prep Section: %setup Command
                %prep Section: %patch Commands
                %prep Section: Unmodified Files
            %build Section
            %install Section
            %check Section
            %files Section
                %files Basics
                %files Prefixes
                %files and Filesystem Hierarchy Standard (FHS)
                %files Example
                Finding Duplicates
            Other Tags
            Dependency Generators

* Distributing RPM Packages:
             This chapter discusses configuring digital signatures and Yum
             repositories to distribute software packaged with RPM. 

        Digital Signatures for RPM Packages
             Generating a GnuPG Keypair
             Signing Packages 

        Yum Repositories for RPM Packages
            Creating a Yum Repository

* Appendix - Eclipse RPM Building:
             This appendix contains information on how to build RPM
             packages in Eclipse Development Environment.

       Eclipse Built-in Specfile Editor

* Appendix - Java Packaging:
             This appendix documents tools and techniques to help
             developers create and maintain Java packages in Fedora. It is
             based on http://sochotni.fedorapeople.org/java-packaging-howto/

      For Packagers
        Example Java Project
        Build System Identification

      For Java Developers Example Java Project
        Java Specifics in Fedora for Users and Developers
        Java Specifics in Fedora for Packagers
            Directory Layout
            JAR File Identification
                Relative Paths
                Artifact Specification
                Compat Versions
            Dependency Handling
            Javadoc Packages
            Core Java Packages

        Generic Java Builds
            add_maven_depmap Macro
            Generating Application Shell Scripts
            Replacing JARs with Symbolic Links Using xmvn-subst


            Packaging a Maven Project
            Macros for Maven Build Configuration
                Installing Additional Artifacts
                Additional Mappings
                Alternative JAR File Names
                Single Artifact Per Package
                Assignment of the Maven Artifacts to the Subpackages
                Modifying XMvn Configuration from within the spec File
            Macros for POM modification
                Macros for pom.xml Modification
                add_maven_depmap Macro
                Replacing JARs with Symbolic Links Using xmvn-subst

        Common Errors

        Integration of Maven and XMvn Tools

* Appendix - Getting More Information:
              Explains where to find more information, including the RPM
              official project site, other RPM books and RPM documentation.


Petr Kovar

More information about the env-and-stacks mailing list