From a1b83649c9219ff3867d7148fa9157bbc8b19157 Mon Sep 17 00:00:00 2001 From: Igor Gnatenko Date: Sep 22 2018 06:50:12 +0000 Subject: trivial: fix markup errors Signed-off-by: Igor Gnatenko --- diff --git a/guidelines/modules/ROOT/pages/AppData.adoc b/guidelines/modules/ROOT/pages/AppData.adoc index fa692b4..8c55d06 100644 --- a/guidelines/modules/ROOT/pages/AppData.adoc +++ b/guidelines/modules/ROOT/pages/AppData.adoc @@ -6,7 +6,7 @@ If a package contains an add-on for GUI application, then it SHOULD also install The AppData files MUST correctly validate using `appstream-util validate-relax`. -=== .appdata.xml file creation +== .appdata.xml file creation If the package doesn't already include and install its own `.appdata.xml` file, you can make your own and sending it upstream. Benefits of sending the file upstream is that upstream can translate the file using the existing translation resources and can also modify the screenshots and descriptions as the application changes over time. You can do this by including a `.appdata.xml` file you create as a Source: (e.g. Source3: %\{name}.appdata.xml) or generating it in the spec file. Here is the contents of a sample `.appdata.xml` file (comical.appdata.xml): @@ -53,7 +53,7 @@ If the package doesn't already include and install its own `.appdata.xml` file, The AppData file MUST be named with the same root as the .desktop file, so if the .desktop file is named `org.gnome.SomeApp.desktop` then the AppData file MUST be called `org.gnome.SomeApp.appdata.xml`. -=== .metainfo.xml file creation +== .metainfo.xml file creation If the add-on package doesn't already include and install its own `.metainfo.xml` file, you can make your own and sending it upstream. You can do this by including a `.metainfo.xml` file you create as a Source: (e.g. Source4: %\{name}.metainfo.xml) or generating it in the spec file. Here is the contents of a sample `.metainfo.xml` file (gedit-bookmarks.metainfo.xml): @@ -73,7 +73,7 @@ If the add-on package doesn't already include and install its own `.metainfo.xml You can use anything as the but it needs to be unique and sensible and also match the `.metainfo.xml` filename prefix. -=== app-data-validate usage +== app-data-validate usage Although you can just include the .appdata.xml or .metainfo.xml files in the package, you MUST run `appstream-util validate-relax` (in `%check` or `%install`) and have `BuildRequires: libappstream-glib`, to help ensure the validity and safety of the appdata files you're installing. An example: diff --git a/guidelines/modules/ROOT/pages/C_and_C++.adoc b/guidelines/modules/ROOT/pages/C_and_C++.adoc index 9101d1e..39f94d1 100644 --- a/guidelines/modules/ROOT/pages/C_and_C++.adoc +++ b/guidelines/modules/ROOT/pages/C_and_C++.adoc @@ -1,10 +1,10 @@ -= Introduction +== Introduction The C and C++ languages and runtimes are one of the most common development frameworks for packages in fedora. As such there is a wide variety of quality, style, and convention in all of those packages. The follow document provides best practice for certain aspects of C and C++ packaging. -= Packaging +== Packaging -== BuildRequires and Requires +=== BuildRequires and Requires If your application is a C or C++ application you must list a `BuildRequires` against `gcc`, `gcc-c++` or `clang`. Those packages will include everything that is required to build a standards conforming C or C++ application. @@ -16,7 +16,7 @@ You need not include a `BuildRequires` or `Requires` on `glibc-headers`, or any Please refer to https://fedoraproject.org/wiki/Packaging:Guidelines#Compiler[Packaging:Guidelines Compiler] for the list of supported compilers for C and C++ compilers. -== Packaging Q&A +=== Packaging Q&A Q: Do I need a `Requires: glibc` to ensure I have the C runtime installed for my application? @@ -26,13 +26,13 @@ Q: Do I need to include a `Requires: libgcc`? A: If you are using an API from `libgcc` directly, then yes, you must have a `Requires: libgcc`. In general though `glibc` requires `libgcc`, so it is always installed. -= Libraries +== Libraries Libraries should have unique shared object names (SONAMEs via `-Wl,-soname=libfoo.so`) that do not conflict with other library SONAMEs used in the distribution. For example there should be only one `libfoo.so` in the distribution. The exception is when there are multiple implementations of the same library `libfoo.so` provided by different authors and each conflicts with the other. In this case both `libfoo.so` must provide exactly the same interface, but with a different implementation. Having two `libfoo.so` each with a different API is bad practice and makes it harder to package and distribute those packages. Libraries should version all of their symbols using a version script. Versioning allows the library to avoid changing the SONAME when the API changes and instead compatibility functions can be written to provide backwards compatibility for older applications. -= Applications +== Applications No additional suggestions are provided for applications at this time. diff --git a/guidelines/modules/ROOT/pages/FontsPolicy.adoc b/guidelines/modules/ROOT/pages/FontsPolicy.adoc index 5bc5b94..9e6cb16 100644 --- a/guidelines/modules/ROOT/pages/FontsPolicy.adoc +++ b/guidelines/modules/ROOT/pages/FontsPolicy.adoc @@ -1,23 +1,23 @@ -== Legal considerations +=== Legal considerations The FLOSS font scene is still too young to have evolved common licensing conventions. As a result packaging fonts will often require more legal work than packaging your average FLOSS app. Before you continue, check our link:Legal_considerations_for_fonts[ legal page]. + + -== Package layout for fonts +=== Package layout for fonts -1. Fonts released upstream in separate archives *MUST* be packaged in separate source packages (_src.rpm_), unless they belong to the same font family. -2. Packagers *SHOULD* ask upstream to release each font family in a separate versioned archive, when it bundles in a common release archive: -1. fonts with other material such as application code, or -2. different font families. +. Fonts released upstream in separate archives *MUST* be packaged in separate source packages (_src.rpm_), unless they belong to the same font family. +. Packagers *SHOULD* ask upstream to release each font family in a separate versioned archive, when it bundles in a common release archive: +.. fonts with other material such as application code, or +.. different font families. * As an exception, when a project is the upstream of several font families, which are all licensed the same way, and released on the same date, with the same version, the use of a common release archive is tolerated. -3. Packagers *MUST* package each font family in a separate (_noarch.rpm_) (sub)package, notwithstanding on how they applied the previous source package (_src.rpm_) rules. The only admitted exceptions are: -1. source packages that only include one font family and no other code or content (font documentation excepted), in which case a simple package is fine, -2. font families which are designed to extend other font families with larger Unicode coverage (for example _Arial Unicode_, _Droid Sans Fallback_), in which case grouping the font family and its extension in a single (sub)package is acceptable. +. Packagers *MUST* package each font family in a separate (_noarch.rpm_) (sub)package, notwithstanding on how they applied the previous source package (_src.rpm_) rules. The only admitted exceptions are: +.. source packages that only include one font family and no other code or content (font documentation excepted), in which case a simple package is fine, +.. font families which are designed to extend other font families with larger Unicode coverage (for example _Arial Unicode_, _Droid Sans Fallback_), in which case grouping the font family and its extension in a single (sub)package is acceptable. * such cases should be notified to the fontconfig maintainer and the Fedora link:Fonts_SIG_mailing_lists[fonts list], so the font family split can be eventually hidden from users. -3. fonts that use a format that bundles different font families in a single file. -4. On the other hand, the different faces of a font family *MUST* be packaged together in a common (_noarch.rpm_) (sub)package, and not spread over different (sub)packages +.. fonts that use a format that bundles different font families in a single file. +. On the other hand, the different faces of a font family *MUST* be packaged together in a common (_noarch.rpm_) (sub)package, and not spread over different (sub)packages *Rationale:* @@ -29,11 +29,11 @@ The functional font unit for users is the font family. Users don't understand pa Lastly, multi-font packages unnecessarily complexify font auto-installation.. -== Naming +=== Naming Fedora font packages are named *[foundryname-]projectname[-fontfamilyname]-fonts*, in lowercase. -=== Clarifications +==== Clarifications 1. For Fedora purposes a “foundry” is an entity that publishes a set of fonts with consistent font QA rules. Thus a generic hosting service such as http://www.sf.net[Sourceforge] is not a foundry, but the http://openfontlibrary.org/[Open Font Library] is. 2. It is good practice to contract _foundryname-_ in a short prefix. @@ -48,7 +48,7 @@ Fedora font packages are named *[foundryname-]projectname[-fontfamilyname]-fonts When in doubt, ask the link:Fonts_SIG_mailing_lists[mailing list] for clarification. -=== Examples +==== Examples .Font package naming examples [cols=",,",options="header",] @@ -96,11 +96,11 @@ When in doubt, ask the link:Fonts_SIG_mailing_lists[mailing list] for clarificat (cooked up example, this page is not a TEX naming guideline) |======================================================================================================================== -== Building from sources +=== Building from sources Fonts *SHOULD* be built from source whenever upstream provides them in a source formatfootnote:[As documented in our general link:Packaging/Guidelines#SourceRequirementExceptions[packaging guidelines].]. Automating the build ensures we'll be able to fix the fonts when problems are reported and upstream is not responsive. Sometimes that means working with upstream to sanitize its build processes. -== Technical implementation +=== Technical implementation Creating font packages or subpackages in Fedora is done using the _fontpackages-devel_ packagefootnote:[Built from the pkgdb:fontpackages[fontpackages] srpm.]. Its sources are published on http://pagure.io/[Pagure] in https://pagure.io/fontpackages[archive] and git (https://pagure.io/fontpackages.git) formats. @@ -113,7 +113,7 @@ While this package has been created by Fedora for Fedora, its content should be _fontpackages_ evolutions can be discussed on the Fonts SIG link:Fonts_SIG_mailing_lists[mailing list]. -== Install-time dependencies +=== Install-time dependencies Font packages in a generic format (TTF, OTF) are resources and *MUST NOT* force the installation of a particular font handler through direct or indirect _Requires_. Fonts can be used by many different software stacks, including outside an X11 context, you should not choose one of them in the stead of users. @@ -121,15 +121,15 @@ Execution of stack-specific helpers in scriptlets is allowed, as long as it's co Likewise, installation of stack-specific configuration files is allowed, if they have no effect in the absence of this software stack, and are auto-discovered on installation of the software stack package. -== Grouping +=== Grouping -== Licensing Information in Metadata +=== Licensing Information in Metadata The "copyright notice" field (tag #0) of the "name" table of TTF and OTF files *MUST* be populated and contain accurate information. Additionally, if information is provided in the "license description" (#13) or "license info URL" (#14) fields are populated, the information contained therein must also be accurate. You can use User:Patches/ttname[`ttname`] to review the metadata included with the font to check it for accuracy. If the metadata is incorrect, packagers should work with upstream to ensure the metadata is properly populated there, so all users of the font can benefit from the corrections. If upstream is non-responsive or you are waiting on a new release for the corrections, you can also use `ttname` in `%prep` to correct the metadata for the Fedora package. -=== Checking the metadata with ttname +==== Checking the metadata with ttname To view the contents of the entire name table of a font, just run: @@ -137,7 +137,7 @@ To view the contents of the entire name table of a font, just run: ttname -a font.ttf .... -=== Correcting the metadata with ttname +==== Correcting the metadata with ttname You can also use ttname to set the fields if upstream is nonresponsive to your requests to correct it. @@ -147,7 +147,7 @@ For example, you could run this in `%prep` to populate all the relevant fields w ttname -a --copyright="$(head -n1 LICENSE)" --license="$(cat LICENSE)" --license-url="http://scripts.sil.org/OFL" font.ttf .... -== Core fonts +=== Core fonts Once upon a time every Linux GUI application used the so-called _Core fonts_ server-side X11 backendfootnote:[Fonts accessed through the original _core_ X protocol, using tools like _mkfontdir_, _xfs_, _/etc/X11/fontpath.d/_, _XLFD_ strings, etc. See also this http://keithp.com/~keithp/talks/xtc2001/paper/[paper] written shortly before projects massively migrated to client-side fonts.]. It was riddled with problems. The FLOSS developers finally gave up on it, declared it legacy and broken by design, and moved to client-side font handling (_fontconfig_). Nowadays almost no modern Linux GUI application uses the _Core fonts_ backend. Few (if any) people are willing to fix its remaining bugs. @@ -155,6 +155,6 @@ Therefore, unless your font has previously been registered in _Core fonts_, and The users of this legacy backend won't thank you for destabilizing it with new fonts. They value stability. Otherwise they'd have moved to _fontconfig_ like everyone else a long time ago. -== Notes +=== Notes Category:Fonts_packaging[Packaging policy] Category:Packaging_guidelines[Category:Packaging guidelines] diff --git a/guidelines/modules/ROOT/pages/Lisp.adoc b/guidelines/modules/ROOT/pages/Lisp.adoc index 940e77d..b1a5eba 100644 --- a/guidelines/modules/ROOT/pages/Lisp.adoc +++ b/guidelines/modules/ROOT/pages/Lisp.adoc @@ -1,9 +1,9 @@ -= Lisp Packaging Guidelines +== Lisp Packaging Guidelines This document seeks to document the conventions and customs surrounding the proper packaging of Common Lisp implementations and libraries in Fedora. This document does _not_ describe conventions and customs for application programs that are written in Common Lisp. -= Introduction +== Introduction Most Common Lisp implementations provide a compiler to generate their own binary representation of source. These binary files typically end in .fasl (for Fast Load). These .fasl files are not compatible across Common Lisp implementations, or even between different versions of the same implementation. This unique property calls for special support on the packaging front. @@ -13,23 +13,23 @@ The Debian Lisp community have developed tools and guidelines for packaging and The rest of this packaging guideline aims to describe how to package Common Lisp implementations, libraries and programs to take advantage of asdf and the common-lisp-controller. -= Guidelines for Libraries and Programs written in Common Lisp +== Guidelines for Libraries and Programs written in Common Lisp -== Naming +=== Naming Lisp libraries should have their package names prefixed with "cl-", except in the case where the library name already starts with "cl-". Rationale: There is some overlap between Lisp library names and existing Fedora packages. Creating a special name space for Lisp libraries should simplify life for everybody. -== -devel sub-package +=== -devel sub-package Pure lisp libraries do not require -devel sub-packages, as they install source code by default. -== Use of asdf +=== Use of asdf Libraries should be managed by asdf, a packaging format for Common Lisp libraries (see the cl-asdf package for details). Most modern Lisp libraries already ship with asdf system definition files (with names typically ending in ".asd"). If none exist, then one will have to be written. The contents of these files is not all that different from an RPM .spec file, so this should not be too difficult for a Lisp-savvy packager. The ASDF manual describing how to write .asd files is available here: http://constantly.at/lisp/asdf/ . -== Install location and hooking into the common-lisp-controller +=== Install location and hooking into the common-lisp-controller Libraries should depend on the common-lisp-controller package. Lisp source should be installed in %\{_datadir}/common-lisp/source/. @@ -39,7 +39,7 @@ The %post section should call "%\{_sbindir}/register-common-lisp-source ". The %preun section should call "%\{_sbindir}/unregister-common-lisp-source " These scripts are provided by common-lisp-controller. -== Spec file template +=== Spec file template .... Name: # see normal package guidelines @@ -101,21 +101,21 @@ done %changelog .... -= Guidelines for Common Lisp implementations +== Guidelines for Common Lisp implementations -== Naming +=== Naming There are no special requirements here. Common Lisp implementations should be packaged using their normal project name. -== -devel sub-package +=== -devel sub-package Common Lisp implementations do not require -devel sub-packages, and they necessarily include all development tools by default. -== Use of asdf +=== Use of asdf Common Lisp implementations should be able to load asdf by simply entering "(require 'asdf)" at the Lisp Read-Eval-Print loop (REPL). This may involve modifying search paths or related changes at build time. -== Install location and hooking into the common-lisp-controller +=== Install location and hooking into the common-lisp-controller Common Lisp implementations should depend on the common-lisp-controller package. @@ -128,7 +128,7 @@ These scripts, and the %\{_libdir}/common-lisp/bin directory are provided and ow All implementations should be modified to load common-lisp-controller's %\{_sysconfdir}/lisp-config.lisp on startup. -= Further reading +== Further reading See http://www.cliki.net/common-lisp-controller and http://common-lisp.net/project/asdf/ for more details on common-lisp-controller and asdf. diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index 8b8e6cf..7bcc067 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -1,23 +1,23 @@ -= Packaging Guidelines for MinGW Cross Compilers +== Packaging Guidelines for MinGW Cross Compilers -= Introduction +== Introduction The Fedora MinGW project's mission is to provide an excellent development environment for Fedora users who wish to cross-compile their programs to run on Windows, minimizing the need to use Windows at all. In the past developers have had to port and compile all of the libraries and tools they have needed, and this huge effort has happened independently many times over. We aim to eliminate duplication of work for application developers by providing a range of libraries and development tools which have already been ported to the MinGW cross-compiler environment. This means that developers will not need to recompile the application stack themselves, but can concentrate just on the changes needed to their own application. As of Fedora 17 a set of RPM macros and packages have been introduced which help packagers compile binaries for multiple targets. The targets Win32 and Win64 are supported. -= Track Fedora native package versions +== Track Fedora native package versions In general terms, cross-compiled MinGW versions of packages which are already natively available in Fedora, should follow the native Fedora package as closely as possible. This means they should stay at the same version, include all the same patches as the native Fedora package, and be built with the same configuration options. The MinGW SIG have written an RPM comparison tool which makes it possible to compare cross compiled MinGW packages with the Fedora native packages, in order to determine whether versions, patches and configuration are aligned. -= Follow Fedora policy +== Follow Fedora policy Cross compiled MinGW packages must follow Fedora policy, except where noted in this document. Cross compiled packages go through the same review process, GIT admin process etc as other Fedora packages. -= Package naming +== Package naming MinGW packages require special naming to denote the appropriate CPU architecture the binaries have been built for. There should *never* be a package prefixed with `mingw-` output during a build. The `mingw-` prefix is exclusive for RPM spec file names and the source RPM file name. The CPU architecture specific packages are created by sections with `%files -n mingw32-foo` or `%files -n mingw64-foo`. @@ -28,7 +28,7 @@ MinGW packages require special naming to denote the appropriate CPU architecture |`mingw64-` |Used for packages which are built for Win64 |======================================================= -= Base packages +== Base packages The base packages provide a root filesystem, base libraries, binutils (basic programs like 'strip', 'ld' etc), the compiler (gcc) and the Win32/Win64 API. Packages may need to depend on one or more of these. In particular, almost all packages should BuildRequire `mingw32-filesystem`, `mingw64-filesystem`, `mingw32-gcc` and `mingw64-gcc`. The correct Requires flags will get added automatically when the `%{?mingw_package_header}` macro is mentioned in the spec file (as will be described later on in these guidelines) @@ -41,7 +41,7 @@ The base packages provide a root filesystem, base libraries, binutils (basic pro |`mingw32-headers` / `mingw64-headers` |Win32 and Win64 API. A free (public domain) reimplementation of the header files required to link to the Win32 and Win64 API. No direct equivalent in base Fedora - glibc-devel is closest |================================================================================================================================================================================================================================= -= Build for multiple targets +== Build for multiple targets The goal of the MinGW framework is to provide an easy way for package maintainers to build their packages for multiple targets using one .spec file. To aid developers in this several RPM macros have been developed which are part of the mingw-filesystem package. These RPM macros will be explained later on in these guidelines. @@ -56,7 +56,7 @@ When a package can only be built for either one of these targets this can be ind |`%global mingw_build_win64 0` |Don't build for the Win64 target |=============================================================== -= One source RPM, separate binary RPMs per-target +== One source RPM, separate binary RPMs per-target Each cross compiled MinGW package which builds binaries for a specific target should put the binaries for that target in a separate subpackage. So if a package `foo` builds binaries for the Win32 and Win64 targets, then the source RPM should provide two subpackages named `mingw32-foo` and `mingw64-foo`. @@ -81,7 +81,7 @@ These file lists can be included in the %files section for the targets: %files -n mingw64-foo -f mingw64-foo.lang .... -= Filesystem layout +== Filesystem layout `[root]` + `  |` + @@ -145,7 +145,7 @@ These file lists can be included in the %files section for the targets: `              |` + `              +- man` -= Filenames of the cross-compilers and binutils +== Filenames of the cross-compilers and binutils The MinGW cross-compilers and binutils are Fedora binaries and are therefore placed in `%{_bindir}` (ie. `/usr/bin`) according to the FHS and Fedora guidelines. @@ -175,7 +175,7 @@ name, ie: The same also applies for the x86_64 target. This target uses 'x86_64-w64-mingw32' as prefix instead of 'i686-w64-mingw32' -= Naming of the root filesystem +== Naming of the root filesystem The root filesystem contains Windows executables and DLLs and any other Windows-only files. It is necessary both because we need to store Windows libraries in order to link further libraries which depend on them, and also because MinGW requires a root filesystem location. @@ -191,12 +191,12 @@ And the Win64 target is provided by the macro: %{mingw64_sysroot} %{_prefix}/x86_64-w64-mingw32/sys-root .... -= Standard mingw RPM macros +== Standard mingw RPM macros The `mingw-filesystem` package provides a number of convenience macros for the cross compiled sysroot directories, and toolchain. It is mandatory to use these macros in all MinGW cross compiled packages submitted to Fedora. -== Toolchain macros +=== Toolchain macros The following macros are for the %build and %install section of the spec @@ -271,7 +271,7 @@ mingw64-filesystem | Value |Explanation |mingw64_target |>= 95 |x86_64-w64-mingw32 |Target platform for build |=================================================================================================================================================== -== Filesystem location macros +=== Filesystem location macros The following macros are for use in %build, %install and %files sections of the RPM spec @@ -311,7 +311,7 @@ For the Win64 target: |mingw64_sysroot |%\{_prefix}/x86_64-w64-mingw32/sys-root |Windows system root. |=================================================================================================== -= Compilation of binaries +== Compilation of binaries In order to build binaries for multiple targets we have to call commands like `./configure` and `make` multiple times (once for each target). If one has to write this all out in a spec file then it will lead to duplicate code. @@ -355,7 +355,7 @@ The environment variable MINGW_BUILDDIR_SUFFIX can also be used here Some packages require some custom instructions before the files are ready to be packaged. Such code can remain as is. However, you may need to duplicate these instructions multiple times (for all configured targets). -= Dependencies +== Dependencies If a package contains binaries which depend on a DLL provided by another package, these dependencies should be expressed in the form: @@ -383,7 +383,7 @@ and any other BuildRequires that they need. The `minimum-version` must be at least 95 or any later version which provides the functionality you need -= Build architecture +== Build architecture All packages should have: @@ -391,7 +391,7 @@ All packages should have: unless they contain Fedora native executables. -= Libraries (DLLs) +== Libraries (DLLs) All libraries must be built as DLLs. @@ -405,14 +405,14 @@ the `%{mingw32_libdir}` directory. For example, for a library called `foo` there The `foo.dll` file is the main library, `foo.dll.a` is a stub linked to applications so they can find the library at runtime. All of these files are required in those locations in order to link successfully. The `.dll` may contain a version number although not always (eg. `foo-0.dll`). -== Do not use %\{mingw32_bindir}/* or %\{mingw32_libdir}/* in %files section +=== Do not use %\{mingw32_bindir}/* or %\{mingw32_libdir}/* in %files section The `%files` section must list DLLs and import libraries separately. Packages must NOT use `%{mingw32_bindir}/*` or `%{mingw32_libdir}/*` The reason for this is that libtool is very fragile and will give up on building a DLL very easily. Therefore we force the name of the DLL to be listed explicitly in the `%files` section in order to catch this during RPM builds. -== Stripping +=== Stripping Libraries and executables should be stripped. This is done correctly and automatically if the spec file starts with this line: @@ -420,7 +420,7 @@ Libraries and executables should be stripped. This is done correctly and automat %{?mingw_package_header} .... -== Debuginfo subpackage +=== Debuginfo subpackage Most binaries contain debugging symbols when the package gets built. To split the debugging symbols to a separate debuginfo package (as is done with native Fedora packages) the spec file must include these lines: @@ -432,14 +432,14 @@ Most binaries contain debugging symbols when the package gets built. To split th The `%{?mingw_debug_package}` line must be placed after the `%description tag`. Otherwise spectool and other RPM tools may fail to function -= Executables (EXEs) +== Executables (EXEs) Most libraries also provide executables. These can include executables which can be used to test or showcase the library in question (for example gtk3-demo.exe in mingw-gtk3). Other examples are helper executables which are used by the library itself internally (for example gspawn-win32-helper.exe in mingw-glib2). Executables which are required for proper functionality of the libraries must be packaged in the matching mingw32/mingw64 subpackage. All other executables are discouraged, but may be packaged in optional (dependent) subpackages at a packager's discretion. -= Files which are already part of native packages +== Files which are already part of native packages There are various types of files which are simply duplicates of equivalent files found in Fedora native packages. These files should not be packaged in the MinGW package. The following files don't need to be packaged in the MinGW package when their native counterpart already contains them: @@ -450,7 +450,7 @@ The following files don't need to be packaged in the MinGW package when their na * Autoconf files (`%{mingw32_datadir}/aclocal` / `%{mingw64_datadir}/aclocal`) * gtk-doc files (`%{mingw32_datadir}/gtk-doc` / `%{mingw64_datadir}/gtk-doc`) -= Example Specfile +== Example Specfile .... %{?mingw_package_header} diff --git a/guidelines/modules/ROOT/pages/OCaml.adoc b/guidelines/modules/ROOT/pages/OCaml.adoc index f4b2c2a..54ae787 100644 --- a/guidelines/modules/ROOT/pages/OCaml.adoc +++ b/guidelines/modules/ROOT/pages/OCaml.adoc @@ -1,6 +1,6 @@ This document seeks to document the conventions and customs surrounding the proper packaging of ocaml modules in Fedora. It does not intend to cover all situations, but to codify those practices which have served the Fedora ocaml community well. -= Naming +== Naming The base OCaml compiler is called ocaml. @@ -10,11 +10,11 @@ This naming does not apply to applications written in OCaml, which can be given Rationale: this is how they are named in other distros (Debian, PLD) and this is consistent with perl / php / python naming. -= Packaging libraries +== Packaging libraries image:Packaging_OCaml_ocaml-foolib.spec[Packaging_OCaml_ocaml-foolib.spec,title="fig:Packaging_OCaml_ocaml-foolib.spec"] - An example specfile for an imaginary OCaml library called _foolib_. -== Main package +=== Main package In order to allow OCaml scripts and the toplevel to use a library, the main package should contain only files matching: @@ -35,7 +35,7 @@ The packager should check the META file[[FootNote(http://www.ocaml-programming.d Rationale: OCaml does not support dynamic linking of binaries, and even if it did with the current module hash system for expressing strict typing requirements almost any conceivable change to a library would require the binary to be recompiled. OCaml scripts are the closest we come to dynamic linking, in as much as they do not usually depend on a specific version of a library (albeit this only works because the scripts are recompiled each time they run). -== -devel subpackage +=== -devel subpackage The -devel subpackage of a library should contain all other files required to allow development with the library. Normally these would be: @@ -56,17 +56,17 @@ The -devel subpackage should require the exact name-version-release of the main Rationale for inclusion of all cmx files: [*.cmx files] are needed even for module included in .cmxa libraries in order to enable cross-module optimizations (inlining, constant propagation and direct function calls). The .o files are not needed. [From a private email from Alain Frisch] -== -doc subpackage +=== -doc subpackage If the documentation files are very large they may be placed in a separate -doc subpackage, as per normal Fedora guidelines. -== -data subpackage +=== -data subpackage If the package contains excessively large data files, they may be placed in a separate -data subpackage, as per normal Fedora guidelines. -== Requires and provides +=== Requires and provides For each module that library A uses from another library B, library A must have a Requires of the form: ocaml(Modulename) = MD5hash @@ -85,13 +85,13 @@ There are two scripts in the base ocaml package which automatically calculate th Rationale: OCaml does not offer binary compatibility between releases of the compiler (even between bugfixes). Furthermore the module system uses a hash over the interface and some internals of a module which basically means a library or program must be linked against the identical modules it was compiled with. The Requires and Provides lines express the module name and hash so that RPM enforces the same requirements as the OCaml linker itself. Please see the further reading at the end of this page for more details. -= Packaging binaries +== Packaging binaries The rules for packaging OCaml binaries are not significantly different from packaging ordinary programs (see ["Packaging/Guidelines"] ). However if the OCaml package also contains a library, then you should follow the rules above for packaging libraries as well. -== Stripping binaries +=== Stripping binaries Binaries should be stripped, as per ordinary Fedora packaging guidelines. @@ -99,11 +99,11 @@ There is one exception where a binary should not be stripped. If the package was Rationale: http://bugs.debian.org/256900 -== Providing best possible binaries +=== Providing best possible binaries The packager should attempt to ship native code compiled binaries in preference to bytecode compiled binaries, where this is possible. -= Bytecode-only architectures +== Bytecode-only architectures The OCaml native code compiler (ocamlopt) contains code generators for popular architectures, but not for every architecture that Fedora might support. On such architectures, the spec file should still build bytecode libraries and binaries. @@ -127,7 +127,7 @@ To test that your spec file will work on such an architecture, temporarily remov Rationale: Debian packaging policy section 2.3 does the same thing. -= Unnecessary files +== Unnecessary files The following files should not normally be distributed: @@ -135,13 +135,13 @@ The following files should not normally be distributed: * *.o for corresponding *.cmx. Exception: see above. * *.ml sources. Exception: see above. -= Security issues in OCaml libraries +== Security issues in OCaml libraries If a security issue arises in an OCaml library, then all libraries and binaries which depend on it must be recompiled. OCaml scripts do not need to be changed (unless resolving the security issue requires changing the public interface to the library and the script is broken by the change). This is because OCaml scripts are recompiled each time they run. -= Further reading +== Further reading * http://pkg-ocaml-maint.alioth.debian.org/ocaml_packaging_policy.txt - Debian packaging policy document. * http://docs.pld-linux.org/ocaml.html diff --git a/guidelines/modules/ROOT/pages/PatchUpstreamStatus.adoc b/guidelines/modules/ROOT/pages/PatchUpstreamStatus.adoc index 54720f1..4fa3d12 100644 --- a/guidelines/modules/ROOT/pages/PatchUpstreamStatus.adoc +++ b/guidelines/modules/ROOT/pages/PatchUpstreamStatus.adoc @@ -1,4 +1,4 @@ -== All patches should have an upstream bug link or comment +=== All patches should have an upstream bug link or comment All patches in Fedora spec files *SHOULD* have a comment above them about their upstream status. 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. For example: @@ -17,7 +17,7 @@ Patch0: gnome-panel-fix-frobnicator.patch Sending patches upstream and adding this comment will help ensure that Fedora is acting as a good FLOSS citizen (see link:PackageMaintainers/WhyUpstream[ Why Upstream?] ). 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. -=== If upstream doesn't have a bug tracker +==== If upstream doesn't have a bug tracker You can indicate that you have sent the patch upstream and any known status: @@ -31,7 +31,7 @@ Patch0: foobar-fix-the-bar.patch Patch0: foobar-fix-the-baz.patch .... -=== Fedora-specific (or rejected upstream) patches +==== Fedora-specific (or rejected upstream) patches It may be that some patches truly are Fedora-specific; in that case, say so: @@ -40,7 +40,7 @@ It may be that some patches truly are Fedora-specific; in that case, say so: Patch0: jna-jni-path.patch .... -= Why upstream? +== Why upstream? Refer link:PackageMaintainers/WhyUpstream[ Why Upstream?] diff --git a/guidelines/modules/ROOT/pages/SSLCertificateHandling.adoc b/guidelines/modules/ROOT/pages/SSLCertificateHandling.adoc index aefdb03..e00f300 100644 --- a/guidelines/modules/ROOT/pages/SSLCertificateHandling.adoc +++ b/guidelines/modules/ROOT/pages/SSLCertificateHandling.adoc @@ -1,6 +1,6 @@ -= Background +== Background -== X.509 / SSL certificates +=== X.509 / SSL certificates X.509 certificates are used for authentication in TLS and other protocols. It's an X.509 certificate which lets you trust, when you connect to https://fedoraproject.org/, that you really are talking to the Fedora server and not an imposter. @@ -18,7 +18,7 @@ If a key is stored in a file on the file system, it's common to use a _passphras A much more secure option is to keep the key in a separate hardware 'crypto token'. This will never just _give up_ the key; instead it will perform (sign, encrypt, etc.) operations _using_ the key. So you know the key can never really be stolen. -== PKCS#11 +=== PKCS#11 PKCS#11 is the API standard for cryptographic tokens. It covers hardware crypto devices as mentioned above, and there are also implementations of PKCS#11 "providers" in pure software — for example the NSS (Firefox) certificate store, GNOME keyring, and SoftHSM. @@ -26,7 +26,7 @@ For our purposes, PKCS#11 mostly just provides an object store for keys and cert For security reasons as described above, it's very useful to be able to import keys into a PKCS#11 token and use them from there — even if it's just a software token like the one provided by gnome-keyring — instead of just having them stored in a file in a user's home directory. That's exactly what you're doing when you import a certificate into something like Firefox, Thunderbird or Evolution. There are plans to make NetworkManager always behave this way too: https://wiki.gnome.org/Projects/NetworkManager/PKCS11 -= Problem statement +== Problem statement Although the use of PKCS#11 is very desirable, it can be very hard to use because each application does things differently. There has historically been no consistent way to specify which certificate to use, from which PKCS#11 provider. @@ -38,9 +38,9 @@ With wpa_supplicant it's different again, as shown at http://w1.fi/cgit/hostap/p There are two parts to the problem — there's the question of which PKCS#11 provider module(s) should be loaded, and the question of how to identify the certificate you want to use from it. And there are two parts to the solution... -= Solution +== Solution -== Which provider to load? +=== Which provider to load? In Fedora _(as with most other modern Linux and *NIX systems)_ this question is answered by http://p11-glue.freedesktop.org/[p11-kit]. A Fedora package containing a PKCS#11 provider module, such as the https://github.com/OpenSC/OpenSC/wiki[OpenSC] one which supports most major hardware smart cards, will automatically drop a config file into the appropriate place and then its module will automatically appear in well-behaved software which is integrated with the platform and uses p11-kit properly. @@ -48,15 +48,15 @@ Applications can either link against `libp11-kit` and use its functionality for If you have an application which is already capable of using PKCS#11 but which doesn't know about p11-kit, it will mostly _need_ a PKCS#11 provider module to be explicitly specified. All you need to do is make it use `p11-kit-proxy.so` if the user didn't specify anything else, and it should Do The Right Thing. -== How to specify a certificate? +=== How to specify a certificate? In April 2015, https://tools.ietf.org/html/rfc7512[RFC7512] defined a 'PKCS#11 URI' as a standard way to identify such objects. This form is already accepted by some programs such as the OpenConnect VPN client. The certificate used in the above examples can be simply used as a client authentication certificate by adding the command-line option `-c '`pkcs11:manufacturer=piv_II;id=%01[`pkcs11:manufacturer=piv_II;id=%01`]`'`. -= Proposal +== Proposal -== Client and server applications +=== Client and server applications * Packages which use SSL certificates/keys from a file or elsewhere SHOULD also support using certs/keys from PKCS#11 tokens. @@ -64,31 +64,31 @@ This form is already accepted by some programs such as the OpenConnect VPN clien * Packages which can use PKCS#11 tokens SHOULD automatically use the tokens which are present in the system's p11-kit configuration, rather than needing to have a PKCS#11 provider explicitly specified. -== PKCS#11 Providers +=== PKCS#11 Providers * Packages providing a PKCS#11 module DSO file SHOULD also provide a corresponding http://p11-glue.freedesktop.org/doc/p11-kit/pkcs11-conf.html#config-module[module configuration file] in the directory specified by `pkg-config p11-kit-1 --variable p11_module_configs` _(currently `/usr/share/p11-kit/modules`)_ so that the new module is automatically visible in well-behaved applications. `Packages providing PKCS#11 module DSO file SHOULD also provide a corresponding module configuration file` -= Rationale +== Rationale By consistently using p11-kit for token configuration, and PKCS#11 URIs for specifying objects, we make things a lot simpler for Fedora users. If I want to use a certain certificate from my Yubikey, I should be able to use the URI pkcs11:manufacturer=piv_II;id=%01[`pkcs11:manufacturer=piv_II;id=%01`] consistently in *all* applications within Fedora and expect it to work. -= Examples +== Examples -== OpenVPN +=== OpenVPN To fix OpenVPN, we first https://community.openvpn.net/openvpn/ticket/490[fixed it] to load `p11-kit-proxy.so` by default _(thus making the correct tokens visible)_, And then we fixed its "serialisation" format for how it identifies objects. This was actually in the pkcs11-helper library, and is fixed https://github.com/OpenSC/pkcs11-helper/pull/4[here]. -== OpenSSL engine_pkcs11 +=== OpenSSL engine_pkcs11 Similar https://github.com/OpenSC/engine_pkcs11/pull/9[fixes] were submitted to engine_pkcs11 (now in F22+) to make it load `p11-kit-proxy.so` as its default provider if none is specified, and to make it accept the RFC7512 standard object URIs in place of its own legacy format. -== wpa_supplicant +=== wpa_supplicant Since wpa_supplicant uses engine_pkcs11, much of the work was already done. All that remained was to make it automatically use the PKCS#11 engine when it detected a "filename" starting with '`pkcs11:`'. (http://w1.fi/cgit/hostap/commit/?id=01b0d1d5c1d5598fc92580f2804507d61faf0453[sample commit]) -= Expectations +== Expectations Obviously, packagers are not always expected to be proficient coders in the language their packages are written in. We don't necessarily expect packagers to fix software for themselves, although it's great when they can. @@ -110,7 +110,7 @@ With that in mind, what we ask of packagers is this: If there are things which need to be fixed, it's helpful also to file a bug in Fedora bugzilla and make it block the https://bugzilla.redhat.com/showdependencytree.cgi?id=1173546&hide_resolved=1[PKCS#11 Sanity Tracker bug]. Do include a reference to the upstream bug. -= Help +== Help There's a lot of confusing terminology here, but really what we're asking for is quite simple: If your application can use a certificate from a file, then we would _also_ like it to be able to use a certificate from PKCS#11. diff --git a/guidelines/modules/ROOT/pages/Systemd.adoc b/guidelines/modules/ROOT/pages/Systemd.adoc index 0e8625c..b7ea2a9 100644 --- a/guidelines/modules/ROOT/pages/Systemd.adoc +++ b/guidelines/modules/ROOT/pages/Systemd.adoc @@ -1,8 +1,8 @@ -= Fedora systemd Services +== Fedora systemd Services This document describes the guidelines for systemd services, for use and inclusion in Fedora packages. -== Definitions +=== Definitions Since systemd includes some concepts which are extensions of previous concepts, the following definitions may be useful: @@ -13,7 +13,7 @@ Socket-activated Service: A service which is waiting for traffic across a socket D-Bus service: A service which activates in response to a message from the D-Bus system bus. + Unit file: The systemd equivalent of a SysV initscript. + -== Unit Files +=== Unit Files Each package that contains software that wants/needs to start a traditional service at boot MUST have a systemd unit file. @@ -24,7 +24,7 @@ systemd files you prepare in the upstream sources. Information for developers on how to integrate systemd support best with their build system you may find on http://0pointer.de/public/systemd-man/daemon.html -=== Naming +==== Naming Unit files for traditional services have a naming scheme of foobar.service. When considering what basename to use, keep in mind that we'd like to use the same service names for software across distributions. We'd also like to ship the `.service` files in the upstream packages. These desires create a few guides for naming a unit file: @@ -34,9 +34,9 @@ Unit files for traditional services have a naming scheme of foobar.service. When For backwards compatibility you may also want to create a symlink from an older, name to the new name. In the above example, for instance, Fedora has always used `httpd` for the service. When creating the new `apache-httpd.service` file, also create a symlink named `httpd.service` that points at `apache-httpd.service`. Then end users that are used to using `service httpd` will have it continue to work. -=== Basic format +==== Basic format -==== [Unit] +===== [Unit] Every `.service` file must begin with a `[Unit]` section: @@ -48,11 +48,11 @@ Documentation=man:foo.service(8) man:foo.conf(5) http://www.foo.org/docs/ The `Description=` line must not exceed 80 characters, and must describe the service, and not the `.service` file. For example, "Apache Web Server" is a good description, but "Starts and Stops the Apache Web Server" is a bad one. -===== Documentation field +====== Documentation field Systemd in Fedora 17+ has support for defining documentation in unit files via the Documentation= field (it is ignored in older releases, so it is safe to keep one systemd unit file across all branches). System administrators will be looking at the contents of the Documentation= field to determine what the service is, how to configure it, and where to locate additional documentation relating to the service. Accordingly, packagers are strongly encouraged to include any available sources in the Documentation= field which provide this information. If a man page or info page is present in the package, refer to it using "man:manpage" or "info:infofile" respectively. If the documentation is in plaintext, use "​file://path/to/file". Lastly, if no local documentation exists in the package, but it exists at a url, use the URL (with ​http://) in this field. Multiple URIs can be added to the Documentation= field, as a space separated list. For details on URI definitions and formatting, please refer to the uri(7) manpage (man uri). -==== [Service] +===== [Service] Next, the `.service` file must have a `[Service]` section: @@ -79,7 +79,7 @@ omit the `Type` line altogether. `ExecReload=` should be specified for all services supporting reload. It is highly recommended to add code here that synchronously reloads the configuration file here (i.e. `/bin/kill -HUP $MAINPID` is usually a poor choice, due to its asynchronous nature). Omit this option if your service does not support reloading. -==== [Install] +===== [Install] Finally, the `.service` file should have an `[Install]` section: @@ -92,7 +92,7 @@ The recommended parameters for `WantedBy=` are either `graphical.target` (servic For more information regarding these options see http://0pointer.de/public/systemd-man/systemd.unit.html and http://0pointer.de/public/systemd-man/systemd.service.html -=== EnvironmentFiles and support for /etc/sysconfig files +==== EnvironmentFiles and support for /etc/sysconfig files The `EnvironmentFiles=` line in the `[Service]` section of `.service` files is used to support loading environment variables that can be used in unit files. For instance, if your sysv-initscript used a file in /etc/sysconfig to set command line options, you can use `EnvironmentFiles=` like so: @@ -114,7 +114,7 @@ multiple words) The "-" on the `EnvironmentFile=` line ensures that no error messages is generated if the environment file does not exist. Since many of these files were optional in sysvinit, you should include the "-" when using this directive. -=== Fields to avoid +==== Fields to avoid For most services, we do not want to use requirement dependencies in the `[Unit]` section, such as `Requires=` or @@ -148,7 +148,7 @@ We want to keep our service files short. Unit files should avoid using `StandardOutput=` or `StandardError=`. The default is the right choice for almost all cases, and using the default allows users to change global defaults in /etc/systemd/system.conf. -=== Example Unit file +==== Example Unit file This is an example systemd unit `.service` file for ABRT: @@ -165,15 +165,15 @@ ExecStart=/usr/sbin/abrtd -d -s WantedBy=multi-user.target .... -== Activation +=== Activation Systemd allows for three forms of activated services: link:#Hardware_activation[#Hardware activation], link:#Socket_activation[#Socket activation], and link:#DBus_activation[#DBus activation]. -=== Hardware activation +==== Hardware activation Hardware activation occurs when a service is installed but only turns on if a certain type of hardware is installed. Enabling of the service is normally done with a udev rule. At this time we do not have further guidance on how to write those udev rules. The service itself installs its `.service` files in the normal places and are installed by the normal Packaging:ScriptletSnippets#Systemd[ systemd scriptlets]. These services should never be enabled by the package as they will be enabled by udev. -=== Socket activation +==== Socket activation Socket activation occurs when a service allows systemd to listen for connections to a specific socket and, when systemd receives a connection on @@ -189,7 +189,7 @@ However, socket activation can also be used to allow parallel startup of service Note that certain socket activated services (notably network listening ones) require FESCo approval - see Packaging:DefaultServices for details. Once you have permission, you can package the `.socket` file and use the systemd scriptlets that enable the service by default. You need to also check the `.service` file to make sure it has a `Wants=` entry on the `.socket` file as that ensures that starting the service will also inform systemd of the socket. -=== Timer activation +==== Timer activation All packages with timed execution which already depend on systemd (for example because they contain systemd units) must use timer units instead of cron jobs, @@ -199,7 +199,7 @@ Packages which do not already depend or require systemd must not use timer units but instead depend and have requirement on crontabs, to avoid introducing unnecessary new dependencies on systemd directly. -=== DBus activation +==== DBus activation In order to allow parallel startup of a D-Bus service and its consumers it is essential that D-Bus services can be bus activated and the D-Bus activation request is forwarded from the D-Bus system bus to systemd so that you end up with only a single instance of the service, even if a service is triggered by both boot-up and activation. If historically your D-Bus service was not bus-activated but started via a SysV init script, it should be updated to use bus activation. This may be implemented by dropping a D-Bus `.service` file in `/usr/share/dbus-1/system-services/` and use the `SystemdService=` directive therein to redirect the activation to systemd. @@ -288,7 +288,7 @@ In general, it is also recommended to supply native systemd units for all servic See the D-Bus documentation for more information about bus activation: http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-starting-services -== Automatic restarting +=== Automatic restarting If you package a long-running service, please consider enabling systemd's automatic restart feature for it, to improve reliability by making sure the system automatically attempts recovering a failing daemon. Please use @@ -310,7 +310,7 @@ in your unit's `.service` file for this. The former will tell systemd to restart the daemon as soon as it fails regardless of the precise reason. It's a good choice for most long-running services. Some daemons require a way to escape constant restarting by exiting with any non-zero exit code. For those services use `Restart=on-abnormal`, which will still restart the daemon when it fails "abnormally", on unclean signal, core dump, timeout or watchdog exits, but not on unclean exit codes. It is recommended to to enable automatic restarts for all long-running services, but which setting is the right one, and whether it is useful at all depends on the specific service. Please consult the `systemd.service(5)` man page for more information on the various settings. -== Private devices and networking +=== Private devices and networking If you package a long-running system service, please consider enabling systemd's `PrivateDevices=` and `PrivateNetwork=` settings for it, in order to improve security and minimize the attack surface. @@ -336,9 +336,9 @@ Note that `PrivateNetwork=yes` should not be used for: For further details see the systemd.exec(5) man page. -= Packaging +== Packaging -== Filesystem locations +=== Filesystem locations Packages with systemd unit files *must* put them into `%{_unitdir}`. `%{_unitdir}` evaluates to /lib/systemd/system on all Fedora systems (F-15+). Unit files are architecture independent (hence, not `%{_lib}`) and needed early in the boot process. @@ -348,19 +348,19 @@ Please note that in order for the `%{_unitdir}` macro to exist, your package mus BuildRequires: systemd .... -== %files section +=== %files section Systemd unit `.service` files must not be marked as `%config` files. -== Unit files in spec file scriptlets +=== Unit files in spec file scriptlets Information on proper handling of unit files in spec file scriptlets can be found here: :Packaging:Scriptlets#Systemd -== Tmpfiles.d +=== Tmpfiles.d tmpfiles.d is a service provided systemd in Fedora 15 and later for managing temporary files and directories for daemons. For more information on how to use Tmpfiles.d in Fedora Packages, please see: :Packaging:Tmpfiles.d -== Why don't we.... +=== Why don't we.... * Start the service after installation? diff --git a/guidelines/modules/ROOT/pages/Tcl.adoc b/guidelines/modules/ROOT/pages/Tcl.adoc index fe356ff..47f9e6d 100644 --- a/guidelines/modules/ROOT/pages/Tcl.adoc +++ b/guidelines/modules/ROOT/pages/Tcl.adoc @@ -54,7 +54,7 @@ Requires: tcl(abi) = 8.6 to indicate which Tcl version (8.5 in F19 and F20, 8.6 in F21+) they were built against. This is necessary because the guidelines below require extensions to be installed into tcl-versioned directories, which are only used by a single verison of Tcl. This does impose an inconvenience that all arch-specific and noarch extensions will need to be rebuilt for a new minor version of Tcl, but since new Tcl minor versions only appear once every few years, this should not be such a problematic inconvenience. -==== noarch packages +=== noarch packages The following macros *must* be used at the top of the spec file to determine the correct installation paths: @@ -83,7 +83,7 @@ mv $RPM_BUILD_ROOT%{_datadir}/foobar%{version} $RPM_BUILD_ROOT%{tcl_sitelib}/foo It may also be acceptible to patch upstream's `configure` script and `Makefile` to add additional flexibility for the install directory, but the packager is not required to do this. -==== arch-specific packages +=== arch-specific packages The following macros *must* be used at the top of the spec file to determine the correct installation paths: