From 28fa47f84acbe79407db0dbeda759d5cfe9eb626 Mon Sep 17 00:00:00 2001 From: Miro Hrončok Date: Sep 27 2025 13:25:06 +0000 Subject: Use Cursor AI to convert everything to Semantic Line Breaks Model: gpt-5 Original prompt: > Get familiar with the Semantic Line Breaks principle https://sembr.org/ > > For every adoc document in the project, perform the following 2 steps: > > 1. remove all the nonsemantic line wraps > 2. add new line breaks as defined by https://sembr.org/ > > Never change any code examples within the documents, only prose. > > You must not ever change anything else than newlines and spaces. Later, when the AI tried to write a regex-based Python script for the task: > Do not attempt to write a script for this task. > Go file by file and apply the requested changes manually. > Understanding of the natural language is crucial and an automated scripted approach > that splits lines according to used punctuation is not what I am looking for. Later: > You are merging lines that were already semantically split. > That's not helpful. > You are changing code snippets. You were explicitly told not to. > In Web_Assets.adoc you removed semantic line breaks. > You are trying to put one sentence per line which is not what sembr is about. > For example a semantic line break SHOULD occur after > an independent clause as punctuated by a comma (,), semicolon (;), > colon (:), or em dash (—). > A semantic line break MAY occur after a dependent clause in order > to clarify grammatical structure or satisfy line length constraints. > In SSLCertificateHandling.adoc you added some semantic line breaks, > but you could add more. > The point is to try keeping the lines below 80 characters if possible. > For example, you did not add a line break after semicolon on line 4. > When you wrap lines in lists, could you indent the followup > lines to match the first one? For example, indent line 4 with 4 spaces . > in UnownedDirectories.adoc the continuous indentation in lists seems off > e.g. on line 6 there are far to many spaces > the indentation depends on the alignment of the start of the first line. > e.g. in lists that only have `* ` there will be 2 spaces, > but in lists that have ` 1. ` there will be 4 --- Then I kept saying continue, do more files, etc. At the end, I used: git diff --word-diff | grep -F -- '-]{+' To identify unrelated changes and manually reverted them all. There were mostly valid, but not desired here. --- diff --git a/guidelines/modules/ROOT/pages/Alternatives.adoc b/guidelines/modules/ROOT/pages/Alternatives.adoc index 31a3a87..7b65e49 100644 --- a/guidelines/modules/ROOT/pages/Alternatives.adoc +++ b/guidelines/modules/ROOT/pages/Alternatives.adoc @@ -13,28 +13,28 @@ For more information, see `+update-alternatives(8)+` manpage. Alternatives *MAY* be used to allow parallel installation of software when: * the software can be used as a drop-in replacement -and functions with sufficient similarity -that users and other programs would, within reason, -not need to know which variant is currently installed + and functions with sufficient similarity + that users and other programs would, within reason, + not need to know which variant is currently installed *AND* * the selection of the software is only performed system-wide -by the system administrator -and end users do not have a need to switch between the variants. + by the system administrator + and end users do not have a need to switch between the variants. Inversely, alternatives *MUST NOT* be used when: * The software is not a drop-in replacement. -For instance, if common command line arguments are different -between the two variants, -alternatives *MUST NOT* be used. + For instance, if common command line arguments are different + between the two variants, + alternatives *MUST NOT* be used. *OR* * End users will care which variant they are using. -If a non-root user would gain value by switching between the variants -then alternatives *MUST NOT* be used. + If a non-root user would gain value by switching between the variants + then alternatives *MUST NOT* be used. A good example of using alternatives are the various MTAs which all provide `+/usr/bin/sendmail+` with similar command line arguments. @@ -42,12 +42,12 @@ which all provide `+/usr/bin/sendmail+` with similar command line arguments. Bad examples of using alternatives include: * the various MPI environments where users care -both about which MPI environment they compile against -and which one they run against + both about which MPI environment they compile against + and which one they run against * choice of editor when the user invokes "vi" -where the user will care about feature availability, -compatibility with plugins, etc + where the user will care about feature availability, + compatibility with plugins, etc Cases where parallel installation is desirable but alternatives is unsuitable may be scenarios where diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index 00d1238..674b83f 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -145,9 +145,9 @@ By default, collections ship with all of the files in the repository root, unless they are manually excluded. Therefore, many collections contain development files that are unwanted by users. -Packagers SHOULD exclude these files, which SHOULD be done by patching the -collection's `+galaxy.yml+` to add these files to the `+build_ignore+` -configuration. +Packagers SHOULD exclude these files, +which SHOULD be done by patching the collection's `+galaxy.yml+` +to add these files to the `+build_ignore+` configuration. These files SHOULD NOT be removed with `+rm+`. See the https://docs.ansible.com/ansible/latest/dev_guide/collections_galaxy_meta.html#collection-galaxy-metadata-structure[Ansible documentation] for more information on the `+galaxy.yml+` syntax. diff --git a/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc b/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc index 7060d99..0c2349f 100644 --- a/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc +++ b/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc @@ -8,26 +8,27 @@ The auto requires and provides system contained in RPM is quite useful; however, it sometimes picks up "private" package capabilities that shouldn't be advertised as global, things that are "just wrong", -or things prohibited by policy (e.g. deps from inside `+%{_docdir}+`). +or things prohibited by policy +(e.g. deps from inside `+%{_docdir}+`). For example: * Various "plugin" packages (e.g. Pidgin, Perl, Apache, KDE) are marked as "providing" private shared libraries outside the system path. * Files in `+%{_docdir}+` are routinely scanned, -and can trigger prov/req when this is explicitly forbidden by policy. + and can trigger prov/req when this is explicitly forbidden by policy. This Guideline describes how to filter provides and requires on Fedora. * *MUST:* Packages must not provide RPM dependency information -when that information is not global in nature, -or are otherwise handled (e.g. through a virtual provides system). -e.g. a plugin package containing a binary shared library -must not "provide" that library -unless it is accessible through the system library paths. + when that information is not global in nature, + or are otherwise handled (e.g. through a virtual provides system). + e.g. a plugin package containing a binary shared library + must not "provide" that library + unless it is accessible through the system library paths. * *MUST:* When filtering automatically generated RPM dependency information, -the filtering system implemented by Fedora must be used, -except where there is a compelling reason to deviate from it. + the filtering system implemented by Fedora must be used, + except where there is a compelling reason to deviate from it. == Usage @@ -88,16 +89,16 @@ from the old filtering guidelines but it does not do the same thing. In particular: * The old macro could be invoked multiple times. -This one will only use the regex defined last. + This one will only use the regex defined last. * The old macro advised against anchoring the beginning of the regex -(Using `+^+`). -This macro recommends anchoring -as it doesn't suffer from the compatibility problems of the old one. + (Using `+^+`). + This macro recommends anchoring + as it doesn't suffer from the compatibility problems of the old one. * With the old macro it was common to specify a directory name -to match everything in a directory recursively. -With the new macro you may need to specify `+.*+` -because you should be anchoring your regular expressions. + to match everything in a directory recursively. + With the new macro you may need to specify `+.*+` + because you should be anchoring your regular expressions. === Filtering provides and requires after scanning diff --git a/guidelines/modules/ROOT/pages/BLAS_LAPACK.adoc b/guidelines/modules/ROOT/pages/BLAS_LAPACK.adoc index 3ea9c28..fa3aef9 100644 --- a/guidelines/modules/ROOT/pages/BLAS_LAPACK.adoc +++ b/guidelines/modules/ROOT/pages/BLAS_LAPACK.adoc @@ -20,19 +20,23 @@ Both BLIS and OpenBLAS provide several flavors: a sequential version, a threaded one, and another with OpenMP support (all of them with or without support for 64-bit integers). -Due to implementation differences, it is important that all components of a particular software stack link to the same BLAS/LAPACK implementation. +Due to implementation differences, +it is important that all components of a particular software stack link to the same BLAS/LAPACK implementation. Also, users may want to choose a particular implementation that works best for them at run time. This guideline gives a structure that can enforce the first while allowing the second, -as well as providing a transparent fallback mechanism to Netlib's reference implementation for those symbols not included in the selected backend +as well as providing a transparent fallback mechanism to Netlib's reference implementation +for those symbols not included in the selected backend via https://www.mpi-magdeburg.mpg.de/projects/flexiblas[FlexiBLAS]. === BLAS/LAPACK wrapper https://www.mpi-magdeburg.mpg.de/projects/flexiblas[FlexiBLAS] -is a framework that wraps both BLAS and LAPACK APIs in a single library. +is a framework that wraps both BLAS and LAPACK APIs in a single library. BLAS/LAPACK consumers must link against FlexiBLAS, -and this wrapper is able to redirect calls to a selected optimized backend with negligible overhead. -It also provides transparent fallback to Netlib's reference implementation if a certain symbol is not present in the selected backend. +and this wrapper is able to redirect calls to a selected optimized backend +with negligible overhead. +It also provides transparent fallback to Netlib's reference implementation +if a certain symbol is not present in the selected backend. These are the main features: * Provides a 100% BLAS and LAPACK compatible ABI/API, with interfaces for both 32- and 64-bit integers. @@ -49,15 +53,19 @@ Fedora ships `openblas-openmp` as the system-wide default backend. == Packaging BLAS/LAPACK dependent packages -Consumers of any subset of BLAS and/or LAPACK MUST compile against FlexiBLAS (unless not supported; see below). +Consumers of any subset of BLAS and/or LAPACK MUST compile against FlexiBLAS +(unless not supported; see below). [NOTE] ==== .Exceptions -* Although support for LAPACKE is planned, the few packages using this interface are not yet supported by FlexiBLAS as of v3.1.2. - These packages MUST link against OpenBLAS instead, or `lapack` if the routines used are not supported by this backend. +* Although support for LAPACKE is planned, + the few packages using this interface are not yet supported by FlexiBLAS as of v3.1.2. + These packages MUST link against OpenBLAS instead, + or `lapack` if the routines used are not supported by this backend. Current exceptions of this type include `opencv`, `scamp` and `sextractor`. -* On rare occasions, a package may use an exceptional feature present in a particular backend +* On rare occasions, + a package may use an exceptional feature present in a particular backend and cannot be adapted to FlexiBLAS by any means. In such cases, the package MUST link against this backend. Current exceptions of this type include `julia` (linked against OpenBLAS) and `psfex` (linked against ATLAS). @@ -92,12 +100,14 @@ and configure the proper flags for FlexiBLAS (since CMake v3.19), and no further action will be required from the packager. Unfortunately, many upstream projects present heterogeneous ways of accessing these APIs. -In a best-case scenario, the building framework may define specific options to explicitly set the BLAS and/or LAPACK libraries. +In a best-case scenario, +the building framework may define specific options to explicitly set the BLAS and/or LAPACK libraries. More commonly, the packager MUST ensure that `+%{_includedir}/flexiblas+` and `+%{_libdir}/flexiblas+` (or `+%{_includedir}/flexiblas64+` and `+%{_libdir}/flexiblas64+`) are injected as header and library locations in the proper flags and configuration files, and/or `-lflexiblas` (or `-lflexiblas64`) is provided to the linker. -In rare occasions, hardcoded paths in source files MUST be modified, and patches MAY be required. +In rare occasions, hardcoded paths in source files MUST be modified, +and patches MAY be required. The packager SHOULD work with upstream to standardize the way in which these libraries are detected and configured. [IMPORTANT] diff --git a/guidelines/modules/ROOT/pages/CMake.adoc b/guidelines/modules/ROOT/pages/CMake.adoc index a1da833..ae21c45 100644 --- a/guidelines/modules/ROOT/pages/CMake.adoc +++ b/guidelines/modules/ROOT/pages/CMake.adoc @@ -38,7 +38,8 @@ in project (using `+%__ctest+`). When packaging KDE software, you most likely would replace `+%cmake+` with either `+%cmake_kf5+` -or `+%cmake_kf6+`. For more information, see xref:KDEPackaging.adoc[KDE Packaging Guidelines]. +or `+%cmake_kf6+`. +For more information, see xref:KDEPackaging.adoc[KDE Packaging Guidelines]. It is rarely necessary (but permissible) to use or alter these: diff --git a/guidelines/modules/ROOT/pages/Conflicts.adoc b/guidelines/modules/ROOT/pages/Conflicts.adoc index 38b1179..9d1ffa8 100644 --- a/guidelines/modules/ROOT/pages/Conflicts.adoc +++ b/guidelines/modules/ROOT/pages/Conflicts.adoc @@ -13,13 +13,13 @@ include::{partialsdir}/attributes.adoc[] Users should always be able to install the latest packages from Fedora's repos regardless of what other Fedora packages are installed. Therefore, whenever possible, -the latest Fedora packages of a release -should avoid conflicting with each other. +the latest Fedora packages of a release should avoid conflicting with each other. Conflicts result in a transaction set where the user has to decipher the error message and make some sort of decision. The transaction set doesn't provide information to the user -about why two packages conflict to help them make an informed decision. +about why two packages conflict +to help them make an informed decision. As Fedora packagers, we try to make it so that any subset of latest Fedora's packages @@ -208,8 +208,8 @@ rather than a system administrator. When renaming or putting files into subdirectories, it is a good idea to try to get upstream to rename their conflicting files (for instance if they both had commands named %\{_bindir}/trash). -Doing some research about which has been around longer may be useful -in this case but may or may not be persuasive to upstream. +Doing some research about which has been around longer may be useful in this case +but may or may not be persuasive to upstream. If neither upstream renames, we would then approach other distributions (distributions-list[at]freedesktop.org is a good place to discuss this) diff --git a/guidelines/modules/ROOT/pages/CronFiles.adoc b/guidelines/modules/ROOT/pages/CronFiles.adoc index 716ad98..1f2cd1e 100644 --- a/guidelines/modules/ROOT/pages/CronFiles.adoc +++ b/guidelines/modules/ROOT/pages/CronFiles.adoc @@ -20,7 +20,8 @@ then a custom crontab file should be added to /etc/cron.d (with 0640 permissions). In this case, the cron job file (the script) must be placed in an appropriate system location -(e.g. %\{_bindir}, %\{_libexecdir}), and NOT in /etc/cron.d. +(e.g. %\{_bindir}, %\{_libexecdir}), +and NOT in /etc/cron.d. Both cron job files and crontab definition files installed in any of these directories diff --git a/guidelines/modules/ROOT/pages/D.adoc b/guidelines/modules/ROOT/pages/D.adoc index a7fdc08..3773af9 100644 --- a/guidelines/modules/ROOT/pages/D.adoc +++ b/guidelines/modules/ROOT/pages/D.adoc @@ -2,7 +2,9 @@ == ldc -All D packages depend on ldc to build, so every package must have ldc as BuildRequires. In addition, the ldc package includes some useful macros for D packages. +All D packages depend on ldc to build, +so every package must have ldc as BuildRequires. +In addition, the ldc package includes some useful macros for D packages. === Compiler options @@ -19,11 +21,19 @@ All D packages depend on ldc to build, so every package must have ldc as BuildRe -g _generates debug information_ + -O2 _is the optimisation level_ -Some D packages use Makefiles, which usually use the $DFLAGS variable in the same way that C packages with Makefiles use $CFLAGS. In this case, `+export DFLAGS="%{_d_optflags}"+` is usually appropriate. In other cases, the build script in the D package has an option to pass in `+%{_d_optflags}+`. It is the responsibility of the packager to ensure that `+%{_d_optflags}+` are used with ldc when the package is built. +Some D packages use Makefiles, +which usually use the $DFLAGS variable in the same way that C packages with Makefiles use $CFLAGS. +In this case, +`+export DFLAGS="%{_d_optflags}"+` is usually appropriate. +In other cases, +the build script in the D package has an option to pass in `+%{_d_optflags}+`. +It is the responsibility of the packager to ensure that `+%{_d_optflags}+` are used with ldc when the package is built. === Header Files -D packages contain header files, which end with .d or .di. These header files must be installed into `+%{_d_includedir}/%{name}+`. +D packages contain header files, +which end with .d or .di. +These header files must be installed into `+%{_d_includedir}/%{name}+`. `+%{_d_includedir}+` is defined as: @@ -33,23 +43,34 @@ D packages contain header files, which end with .d or .di. These header files mu == Libraries -At this time, Linux does not support shared libraries for D code (only OSX does). -As a result, D packages are explicitly excluded from the restrictions against packaging static libraries. +At this time, +Linux does not support shared libraries for D code (only OSX does). +As a result, +D packages are explicitly excluded from the restrictions against packaging static libraries. To build static libraries in D, you use the same tools that you would for C, specifically, ar, ranlib, and strip. -If your D package contains static libraries, you must disable debuginfo generation, by adding this line to the top of your spec file: +If your D package contains static libraries, +you must disable debuginfo generation, +by adding this line to the top of your spec file: .... %global debug_package %{nil} .... -Otherwise, it would generate an empty debuginfo package. +Otherwise, +it would generate an empty debuginfo package. -All static libraries must be placed in the *-devel subpackage. When doing this, you must also have +All static libraries must be placed in the *-devel subpackage. +When doing this, +you must also have `+Provides: %{name}-static = %{version}-%{release}+` in the devel package definition. -It is possible that this will leave the root package empty, if this is the case, do not list a %files section for the root package, only for the -devel package. This is illustrated in the example template below. +It is possible that this will leave the root package empty, +if this is the case, +do not list a %files section for the root package, +only for the -devel package. +This is illustrated in the example template below. == Template diff --git a/guidelines/modules/ROOT/pages/Debuginfo.adoc b/guidelines/modules/ROOT/pages/Debuginfo.adoc index 3d706a5..47c682a 100644 --- a/guidelines/modules/ROOT/pages/Debuginfo.adoc +++ b/guidelines/modules/ROOT/pages/Debuginfo.adoc @@ -1,34 +1,69 @@ = Debuginfo packages -This page contains information about debuginfo packages and common pitfalls about them for packagers. For usage information and an explanation why debuginfo packages are important, see https://fedoraproject.org/wiki/StackTraces[StackTraces]. +This page contains information about debuginfo packages and common pitfalls about them for packagers. +For usage information and an explanation why debuginfo packages are important, +see https://fedoraproject.org/wiki/StackTraces[StackTraces]. == Checking your debuginfo package for usefulness -A useful debuginfo package contains stripped symbols from ELF binaries (`+*.debug+` in `+/usr/lib/debug+`) as well as the source code related to them (in `+/usr/src/debug+`). The script that generates the packages is `+/usr/lib/rpm/find-debuginfo.sh+`, read it through to get a basic understanding of how they're generated. If your debuginfo package doesn't contain any files, or is missing the sources or the size of the `+*.debug+` files in it is unexpectedly small (typically `+*.debug+` are larger than the corresponding binary it was stripped from), it's likely that there's a flaw in your package. That's not always the case though, read on. +A useful debuginfo package contains stripped symbols from ELF binaries (`+*.debug+` in `+/usr/lib/debug+`) +as well as the source code related to them (in `+/usr/src/debug+`). +The script that generates the packages is `+/usr/lib/rpm/find-debuginfo.sh+`, +read it through to get a basic understanding of how they're generated. +If your debuginfo package doesn't contain any files, +or is missing the sources +or the size of the `+*.debug+` files in it is unexpectedly small (typically `+*.debug+` are larger than the corresponding binary it was stripped from), +it's likely that there's a flaw in your package. +That's not always the case though, +read on. === Useless or incomplete debuginfo packages due to packaging issues Useless or incomplete debuginfo packages are often a result of packaging flaws. Typical flaws that often manifest themselves as debuginfo packages containing no files: -* The specfile or the package's build routines explicitly strip symbols out of the binaries. Look for invocations of `+strip+`, `+install -s+`, `+ld -s+`, or `+gcc -s+` etc and get rid of them (or the `+-s+` flags). The method how to do that varies, some examples cases include patching, using `+%configure+` or a `+make+` target that prevents the strip from happening, and/or overriding a strip command like for example `+make install STRIP=/bin/true+` +* The specfile or the package's build routines explicitly strip symbols out of the binaries. + Look for invocations of `+strip+`, `+install -s+`, `+ld -s+`, or `+gcc -s+` etc and get rid of them (or the `+-s+` flags). + The method how to do that varies, + some examples cases include patching, + using `+%configure+` or a `+make+` target that prevents the strip from happening, + and/or overriding a strip command like for example `+make install STRIP=/bin/true+` * The package is not marked as `+noarch+`, but does not contain any architecture dependent things (native binaries, architecture dependent paths etc). True `+noarch+` packages contain nothing rpmbuild could strip from them, so it's expected that they're empty if `+BuildArch: noarch+` is missing. If that's the case, make the package `+noarch+`. * `+find-debuginfo.sh+` processes only files that are executable when it's run; for practical purposes one can assume that happens under the hood after the `+%install+` section. Make sure that all ELF binaries (executables, shared libraries, DSO's) are executable at end of `+%install+`. -* `+find-debuginfo.sh+` does not process setuid or setgid binaries. There's a https://bugzilla.redhat.com/117858[bug filed against rpmbuild] about that, but until it is fixed in the distros your package is targeted at, make sure that all your binaries do _not_ have the setuid/setgid bits at end of `+%install+`, and restore them in the `+%files+` section using `+%attr(...) /path/to/file+` +* `+find-debuginfo.sh+` does not process setuid or setgid binaries. + There's a https://bugzilla.redhat.com/117858[bug filed against rpmbuild] about that, + but until it is fixed in the distros your package is targeted at, + make sure that all your binaries do _not_ have the setuid/setgid bits at end of `+%install+`, + and restore them in the `+%files+` section using `+%attr(...) /path/to/file+` Flaws that manifest themselves as unexpectedly small `+*.debug+` in the debuginfo package and/or source files missing: -* The package was built without passing `+-g+` to `+gcc+` or `+g+++`. Without `+-g+`, no or insufficient information for debuginfo packages is generated, make sure that it is being used. -* Note that the default `+CFLAGS+` and `+CXXFLAGS+` of the distro already contain `+-g+`, so if those flags are being honored, it should be already in use. If not, suboptimal debuginfo packages are not the only problem; the package is probably also compiled without the security enhancing options of recent compiler versions. Make sure that `+$RPM_OPT_FLAGS+` is being honored and used. +* The package was built without passing `+-g+` to `+gcc+` or `+g+++`. + Without `+-g+`, no or insufficient information for debuginfo packages is generated, + make sure that it is being used. +* Note that the default `+CFLAGS+` and `+CXXFLAGS+` of the distro already contain `+-g+`, + so if those flags are being honored, + it should be already in use. + If not, suboptimal debuginfo packages are not the only problem; + the package is probably also compiled without the security enhancing options of recent compiler versions. + Make sure that `+$RPM_OPT_FLAGS+` is being honored and used. * `+strip -g+` was used on the binaries; see above for possible remedies. === Useless or incomplete debuginfo packages due to other reasons -Empty debuginfo packages may also be generated in situations where there are no obvious packaging flaws present. Sometimes these are because of limitations of `+find-debuginfo.sh+`, sometimes not. Some usual cases: +Empty debuginfo packages may also be generated in situations where there are no obvious packaging flaws present. +Sometimes these are because of limitations of `+find-debuginfo.sh+`, +sometimes not. +Some usual cases: * Packages whose only architecture dependent binary part is a static library or many of them * R and Mono packages *TODO: people knowledgeable of R and/or Mono, verify these* -If you wish to disable generation of the useless debuginfo package while waiting for improvements to `+find-debuginfo.sh+` or if it's unlikely that it could be enhanced to produce a good debuginfo for your package (for example no architecture dependent files, but package is not noarch because of the installation paths it uses), use `+%global debug_package %{nil}+` in the specfile, and be sure to add a comment next to it explaining why it was done. +If you wish to disable generation of the useless debuginfo package while waiting for improvements to `+find-debuginfo.sh+` +or if it's unlikely that it could be enhanced to produce a good debuginfo for your package +(for example no architecture dependent files, +but package is not noarch because of the installation paths it uses), +use `+%global debug_package %{nil}+` in the specfile, +and be sure to add a comment next to it explaining why it was done. == Missing debuginfo packages @@ -36,11 +71,19 @@ It is normal for noarch package builds to not produce a debuginfo package. If it == Don't obsolete debuginfo packages -In case there is removed subpackage or the subpackage is changed from arch to noarch, the associated -debuginfo package might be left behind. This might be issue, when `+fedora-debuginfo+` repository is enabled during system upgrade. Nevertheless, because the debuginfo packages has no dependencies, they are parallel installable and useful for coredump analysis, don't obsolete them anywhere. +In case there is removed subpackage or the subpackage is changed from arch to noarch, +the associated -debuginfo package might be left behind. +This might be issue, when `+fedora-debuginfo+` repository is enabled during system upgrade. +Nevertheless, because the debuginfo packages has no dependencies, +they are parallel installable and useful for coredump analysis, +don't obsolete them anywhere. == Resources -* debuginfo package listings for Fedora, sorted by size. Most debuginfo packages roughly up to 20kB in size are candidates that should be examined - however significantly larger -debuginfo packages may suffer from the same problems too, esp. in the "missing -g" case. +* debuginfo package listings for Fedora, sorted by size. + Most debuginfo packages roughly up to 20kB in size are candidates that should be examined + - however significantly larger -debuginfo packages may suffer from the same problems too, + esp. in the "missing -g" case. ** Note that due to the split repository, each directory must be examined separately. ** https://dl.fedoraproject.org/pub/fedora/linux/development/rawhide/Everything/x86_64/debug/tree/Packages/a/?C=S;O=A * https://fedoraproject.org/wiki/StackTraces[StackTraces] diff --git a/guidelines/modules/ROOT/pages/DefaultServices.adoc b/guidelines/modules/ROOT/pages/DefaultServices.adoc index eab7c6a..f55bad0 100644 --- a/guidelines/modules/ROOT/pages/DefaultServices.adoc +++ b/guidelines/modules/ROOT/pages/DefaultServices.adoc @@ -2,47 +2,81 @@ == What is a Service? -For the purposes of this document, a "service" is defined as one or more of: +For the purposes of this document, +a "service" is defined as one or more of: * A daemon or process started using a https://www.freedesktop.org/software/systemd/man/systemd.service.html[systemd service unit]. * A daemon or process that is invoked by socket activation, either by using a https://www.freedesktop.org/software/systemd/man/systemd.socket.html[systemd socket unit], https://standards.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html[D-BUS activation] or similar behavior. * A daemon or process that is invoked by hardware activation (i.e. started via a udev rule). * A https://www.freedesktop.org/software/systemd/man/systemd.timer.html[systemd timer unit] that runs periodically. -Note that this includes processes which are not persistent. If something started by a systemd service unit runs for a short period of time and then exits, it is still a service. An example would be `+iptables+`. +Note that this includes processes which are not persistent. +If something started by a systemd service unit runs for a short period of time and then exits, +it is still a service. +An example would be `+iptables+`. This also includes services in the user session (i.e. started per-user by the `systemd --user` manager). == Enabling Services by Default -Only services that meet all criteria below MAY be enabled by default on package installation. +Only services that meet all criteria below +MAY be enabled by default on package installation. === Must not alter other services -Installation of the package providing the unit auto-started by this preset MUST NOT change the behavior of any other service running (or potentially running) on the system. +Installation of the package providing the unit auto-started by this preset +MUST NOT change the behavior of any other service running +(or potentially running) on the system. === Must not require manual configuration to function -The service MUST NOT require configuration before it starts properly. If the end-user/administrator must make some specific configuration change before the service is able to start without error then it MUST NOT be enabled by default. +The service MUST NOT require configuration before it starts properly. +If the end-user/administrator must make some specific configuration change +before the service is able to start without error +then it MUST NOT be enabled by default. === Must not fail under normal operating conditions -The service MUST NOT, under normal operating conditions, exit with an error causing systemd to mark the unit as failed. A service which is started by default is permitted to fail under exceptional conditions. For example, a service could start when appropriate hardware is present, but would still be allowed to fail if that hardware is somehow malfunctioning. Or a service could fail to start with an error if a configuration file has been locally modified to be syntactically incorrect. +The service MUST NOT, under normal operating conditions, +exit with an error causing systemd to mark the unit as failed. +A service which is started by default is permitted to fail under exceptional conditions. +For example, +a service could start when appropriate hardware is present, +but would still be allowed to fail +if that hardware is somehow malfunctioning. +Or a service could fail to start with an error +if a configuration file has been locally modified to be syntactically incorrect. === Must not listen for outside connections -The service MUST NOT listen on a network socket for connections originating on a separate physical or virtual machine. +The service MUST NOT listen on a network socket +for connections originating on a separate physical or virtual machine. D-BUS services and hardware-activated services generally meet this requirement. == Hardware Support Services -Some hardware requires some additional service to be started in order to be useful. This may come in the form of a non-persistent setup process or in the form of a continuously-running service. If the service can be hardware activated to only start when the relevant hardware is present and do nothing when not present, and otherwise it meets the above requirements, then it SHOULD be enabled by default upon package installation. - -If the service cannot be hardware activated, but it is possible to configure it such that it will exit without error and without marking the service as "failed" according to systemd, then it SHOULD be enabled by default upon package installation. This clean exit may be accomplished through https://www.freedesktop.org/software/systemd/man/systemd.unit.html#ConditionArchitecture=[systemd conditionals], by having the service (or a wrapper script) perform hardware detection and exit without indicating an error, or via other similar means. +Some hardware requires some additional service to be started in order to be useful. +This may come in the form of a non-persistent setup process or in the form of a continuously-running service. +If the service can be hardware activated +to only start when the relevant hardware is present +and do nothing when not present, +and otherwise it meets the above requirements, +then it SHOULD be enabled by default upon package installation. + +If the service cannot be hardware activated, +but it is possible to configure it +such that it will exit without error +and without marking the service as "failed" according to systemd, +then it SHOULD be enabled by default upon package installation. +This clean exit may be accomplished through https://www.freedesktop.org/software/systemd/man/systemd.unit.html#ConditionArchitecture=[systemd conditionals], +by having the service (or a wrapper script) perform hardware detection and exit without indicating an error, +or via other similar means. == Approved Exceptions -Some services which are permitted to be enabled by default as specific exceptions. Services that should be enabled by default throughout all of Fedora must be approved by https://pagure.io/fesco[FESCo]. Services that should be enabled or disabled by default only on one or more of the Fedora Editions must be approved by those Editions' https://fedoraproject.org/wiki/Fedora.next#Working_groups[Working Groups]. +Some services which are permitted to be enabled by default as specific exceptions. +Services that should be enabled by default throughout all of Fedora must be approved by https://pagure.io/fesco[FESCo]. +Services that should be enabled or disabled by default only on one or more of the Fedora Editions must be approved by those Editions' https://fedoraproject.org/wiki/Fedora.next#Working_groups[Working Groups]. Example: @@ -58,9 +92,16 @@ Example: == How to enable a service by default -Unit files must correspond to the Fedora Packaging xref:Scriptlets.adoc#_systemd[Guidelines]. Services are enabled or disabled by default through https://www.freedesktop.org/software/systemd/man/systemd.preset.html[systemd preset files]. Preset files can be overridden by a local administrator, but a set of defaults are provided by Fedora. +Unit files must correspond to the Fedora Packaging xref:Scriptlets.adoc#_systemd[Guidelines]. +Services are enabled or disabled by default through https://www.freedesktop.org/software/systemd/man/systemd.preset.html[systemd preset files]. +Preset files can be overridden by a local administrator, +but a set of defaults are provided by Fedora. -If the service should be enabled by default, it must be added to one of the distribution presets files (see above). +If the service should be enabled by default, +it must be added to one of the distribution presets files (see above). -For services which meet one of the conditions listed above, a ticket should be filed in -https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&format=fedora-systemd-request[bugzilla]. If the preset should be changed for versions other than rawhide, indicate that in the ticket. +For services which meet one of the conditions listed above, +a ticket should be filed in +https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&format=fedora-systemd-request[bugzilla]. +If the preset should be changed for versions other than rawhide, +indicate that in the ticket. diff --git a/guidelines/modules/ROOT/pages/DistTag.adoc b/guidelines/modules/ROOT/pages/DistTag.adoc index d4b737b..935739e 100644 --- a/guidelines/modules/ROOT/pages/DistTag.adoc +++ b/guidelines/modules/ROOT/pages/DistTag.adoc @@ -8,7 +8,12 @@ You should consider this document as an addendum to the xref:Naming.adoc[Naming == Purpose of the Dist Tag -There are several uses for a `+%{?dist}+` tag. The original purpose was so that a single spec file could be used for multiple distribution releases. In doing this, there are cases in which BuildRequires: and Requires: will need to be different for different distribution releases. Hence, `+%{?dist}+` does double duty: +There are several uses for a `+%{?dist}+` tag. +The original purpose was so that a single spec file could be used for multiple distribution releases. +In doing this, +there are cases in which BuildRequires: and Requires: +will need to be different for different distribution releases. +Hence, `+%{?dist}+` does double duty: * it differentiates multiple packages which would otherwise have the same `+%{name}-%{version}-%{release}+`, but very different dependencies. @@ -16,7 +21,9 @@ There are several uses for a `+%{?dist}+` tag. The original purpose was so that === Do I Have To Use the Dist Tag? -Yes. It is very useful in maintaining proper ordering between Fedora releases and consistency in release tags is very helpful to the automated tools which are used to perform mass rebuilds. +Yes. +It is very useful in maintaining proper ordering between Fedora releases +and consistency in release tags is very helpful to the automated tools which are used to perform mass rebuilds. == Using +%{?dist}+ @@ -24,9 +31,16 @@ Here is the important information to know: === Possible values for +%{dist}+ -When you run fedpkg commands like `+fedpkg build+`, the values for `+%{dist}+` and its helper variables are assigned according to the git branch that you are working in. You do NOT need to define these variables in your spec file. fedpkg will magically set `+%{?dist}+` for you. +When you run fedpkg commands like `+fedpkg build+`, +the values for `+%{dist}+` and its helper variables are assigned according to the git branch that you are working in. +You do NOT need to define these variables in your spec file. +fedpkg will magically set `+%{?dist}+` for you. -For reference purposes only, these are some possible values for `+%{dist}+`. Note that if `+%{dist}+` is undefined, `+%{?dist}+` simply becomes empty. Also note that Fedora releases use "fc" and not "f" in the tag for historical reasons. +For reference purposes only, +these are some possible values for `+%{dist}+`. +Note that if `+%{dist}+` is undefined, +`+%{?dist}+` simply becomes empty. +Also note that Fedora releases use "fc" and not "f" in the tag for historical reasons. [cols=",",options="header",] |================================================================================== @@ -44,7 +58,8 @@ Development: The development branch takes the disttag of the next major unreleased version of Fedora. -Note the leading period in the definition of `+%{?dist}+`. This is present so that it can easily be used in the release field. +Note the leading period in the definition of `+%{?dist}+`. +This is present so that it can easily be used in the release field. These definitions can be found in common/branches. Note that RHEL dist tags are only defined for EPEL packages. @@ -73,11 +88,13 @@ Release: 2%{?dist} When this package is built in an i386 FC20 buildroot, it generates an rpm named: `+logjam-1.4-2.fc20.i386.rpm+`. -Keep in mind that `+%{?dist}+` should *never* be used in the Name or Version fields, nor in %changelog entries. +Keep in mind that `+%{?dist}+` should *never* be used in the Name or Version fields, +nor in %changelog entries. === Conditionals -Along with `+%{?dist}+`, there are several "helper" variables defined by the buildsystem. These variables are: +Along with `+%{?dist}+`, there are several "helper" variables defined by the buildsystem. +These variables are: `+%{rhel}+`: This variable is only defined on Red Hat Enterprise Linux builds. If defined, it is set to the release number of Red Hat Enterprise Linux present at build time. @@ -90,7 +107,8 @@ Along with `+%{?dist}+`, there are several "helper" variables defined by the bui `+%{el#}+`: This variable is only defined on Red Hat Enterprise Linux builds. For example, on RHEL 7 builds, `+%{el7}+` is defined to 1. All of these variables, if defined, will have a purely numeric value. -With `+%{dist}+` and these additional variables, you can create conditionals in a spec file to handle the differences between distributions. +With `+%{dist}+` and these additional variables, +you can create conditionals in a spec file to handle the differences between distributions. Here are some examples of how to use these variables in conditionals: @@ -116,7 +134,8 @@ Here are some examples of how to use these variables in conditionals: %{?fc22:Requires: baz} .... -Keep in mind that if you are checking for a specific family of distributions, that you need to use: +Keep in mind that if you are checking for a specific family of distributions, +that you need to use: .... %if 0%{?rhel} @@ -128,11 +147,15 @@ and *NOT* %if %{?rhel} .... -Without the extra 0, if `+%{rhel}+` is undefined, the `+%if+` conditional will cease to exist, and the rpm will fail to build. +Without the extra 0, +if `+%{rhel}+` is undefined, +the `+%if+` conditional will cease to exist, +and the rpm will fail to build. === Distribution-specific values -Fedora 37 onwards, a few helper macros are defined to help packagers write distribution-agnostic spec files: +Fedora 37 onwards, +a few helper macros are defined to help packagers write distribution-agnostic spec files: `+%{dist_vendor}+`: The vendor of the distribution. For Fedora, this is `+Fedora+`. @@ -145,8 +168,8 @@ Fedora 37 onwards, a few helper macros are defined to help packagers write distr `+%{dist_debuginfod_url}+`: The URL where the debuginfod server runs (if any). This is used in elfutils.spec. For Fedora, this is `+https://debuginfod.fedoraproject.org/+`. -These values are configured via the `+fedora-release+` package. Downstream distributions of -Fedora are expected to provide their distribution-specific values here. +These values are configured via the `+fedora-release+` package. +Downstream distributions of Fedora are expected to provide their distribution-specific values here. === Things that you cannot use +%{?dist}+ for @@ -160,7 +183,11 @@ Fedora are expected to provide their distribution-specific values here. == Common questions Q: Why don't you just let the buildsystem (or packager) pass the value for dist to rpm, e.g. `+rpm --with dist el7+`? + -A: Actually, we do. The Fedora buildsystem defines the values for dist when you run `+fedpkg+`. +A: Actually, we do. +The Fedora buildsystem defines the values for dist when you run `+fedpkg+`. Q: Why is use of `+%{?dist}+` mandatory? + -A: There are very few packages which didn't use it, the primary very old reason for not using it (sharing large data packages across Fedora releases) is no longer relevant because all Fedora releases are signed with a different key, and having consistent Release: tags simplifies the automated tools which may need to increment them. +A: There are very few packages which didn't use it, +the primary very old reason for not using it (sharing large data packages across Fedora releases) is no longer relevant +because all Fedora releases are signed with a different key, +and having consistent Release: tags simplifies the automated tools which may need to increment them. diff --git a/guidelines/modules/ROOT/pages/Drupal7.adoc b/guidelines/modules/ROOT/pages/Drupal7.adoc index 5717fa2..e4f2f4a 100644 --- a/guidelines/modules/ROOT/pages/Drupal7.adoc +++ b/guidelines/modules/ROOT/pages/Drupal7.adoc @@ -5,7 +5,13 @@ == Naming Scheme -Every package *MUST* be named `+drupal7-+`__`++`. Drupal itself enforces unique machine names for each of its projects and there is a single namespace for all modules, themes, and distributions/profiles. The __`++` *MUST* match the drupal.org project name (i.e. drupal.org/project/__`++`). +Every package *MUST* be named `+drupal7-+`__`++`. +Drupal itself enforces unique machine names for each of its projects +and there is a single namespace for all modules, +themes, +and distributions/profiles. +The __`++` *MUST* match the drupal.org project name +(i.e. drupal.org/project/__`++`). == Macros and Scriptlets diff --git a/guidelines/modules/ROOT/pages/Emacs.adoc b/guidelines/modules/ROOT/pages/Emacs.adoc index 7c760ef..1b493be 100644 --- a/guidelines/modules/ROOT/pages/Emacs.adoc +++ b/guidelines/modules/ROOT/pages/Emacs.adoc @@ -2,11 +2,16 @@ == Purpose -The purpose of this document is to promote good practice in packaging add-ons for GNU Emacs, and to encourage the submission of more Emacs add-on packages to the package collection by providing easy to use spec file templates. +The purpose of this document is to promote good practice +in packaging add-ons for GNU Emacs, +and to encourage the submission of more Emacs add-on packages to the package collection +by providing easy to use spec file templates. == Important notes on these Guidelines -The guidelines in the following sections make extensive use of the macros defined in /usr/lib/rpm/macros.d/macros.emacs which is installed with the emacs-common package. +The guidelines in the following sections +make extensive use of the macros defined in /usr/lib/rpm/macros.d/macros.emacs +which is installed with the emacs-common package. There are two distinct cases where consideration of these guidelines is required: @@ -51,7 +56,8 @@ Package Requires for GNU Emacs add-on (sub-)packages: === Case II -If the package has auxillary files for use with GNU Emacs, the package must have `+Requires: emacs-filesystem >= %{_emacs_version}+` +If the package has auxillary files for use with GNU Emacs, +the package must have `+Requires: emacs-filesystem >= %{_emacs_version}+` == Package BuildRequires diff --git a/guidelines/modules/ROOT/pages/EnvironmentModules.adoc b/guidelines/modules/ROOT/pages/EnvironmentModules.adoc index c348263..fd7455b 100644 --- a/guidelines/modules/ROOT/pages/EnvironmentModules.adoc +++ b/guidelines/modules/ROOT/pages/EnvironmentModules.adoc @@ -2,11 +2,25 @@ == Introduction -When one has multiple programs serving the same purpose (for instance SMTP servers such as sendmail, exim and postfix; or print servers such as lprng and cups), it is usual to wrap these using alternatives. Alternatives provides a clean way to have many types of software serving the same purpose installed at the same time and have the commands such as `+mail+` and `+lpr+` point to the wanted versions. - -However, when there are multiple variants that each serve the needs of some user and thus must be available simultaneously by users, the alternatives system simply isn't enough since it is system-wide. This has been reality on supercomputers and clusters for eons, and multiple implementations of a solution has been developed: http://modules.sourceforge.net/[environment modules] and https://www.tacc.utexas.edu/tacc-projects/lmod[Lmod]. Fedora currently makes use of this primarily for handling switching between different MPI implementations. - -Environment modules are also useful in situations where a package wants to install binaries that use common names and might conflict file in or otherwise pollute /usr/bin. Use must then load an environment module before being able to make use of those programs. +When one has multiple programs serving the same purpose +(for instance SMTP servers such as sendmail, exim and postfix; +or print servers such as lprng and cups), +it is usual to wrap these using alternatives. +Alternatives provides a clean way to have many types of software serving the same purpose installed at the same time +and have the commands such as `+mail+` and `+lpr+` point to the wanted versions. + +However, when there are multiple variants that each serve the needs of some user +and thus must be available simultaneously by users, +the alternatives system simply isn't enough since it is system-wide. +This has been reality on supercomputers and clusters for eons, +and multiple implementations of a solution has been developed: +http://modules.sourceforge.net/[environment modules] +and https://www.tacc.utexas.edu/tacc-projects/lmod[Lmod]. +Fedora currently makes use of this primarily for handling switching between different MPI implementations. + +Environment modules are also useful in situations where a package wants to install binaries that use common names +and might conflict file in or otherwise pollute /usr/bin. +Use must then load an environment module before being able to make use of those programs. == Using environment modules @@ -18,7 +32,12 @@ The upstream documentation for the module command is available https://modules.r == Creating environment modules -To install an environment module, place a module file into `+%{_modulesdir}+`, which should evaluate to `+/usr/share/modulefiles+`. This macro is available in Fedora and EPEL 7+. The directory `+/usr/share/Modules/modulefiles+` is to be used only for internal modules of environment-modules. `+/etc/modulefiles+` is available to local system administrator use. +To install an environment module, +place a module file into `+%{_modulesdir}+`, +which should evaluate to `+/usr/share/modulefiles+`. +This macro is available in Fedora and EPEL 7+. +The directory `+/usr/share/Modules/modulefiles+` is to be used only for internal modules of environment-modules. +`+/etc/modulefiles+` is available to local system administrator use. The module files are plain text with optional tcl syntax, for instance an environment module for 64-bit OpenMPI `+mpi/openmpi-x86_64+`: @@ -44,18 +63,34 @@ setenv MPI_SUFFIX _openmpi setenv MPI_HOME /usr/lib64/openmpi .... -The module file begins with the magic cookie `+#%Module +`, where is the version of the module file used. The current version is 1.0. +The module file begins with the magic cookie `+#%Module +`, +where is the version of the module file used. +The current version is 1.0. -The above commands prepends the path with the bindir of the 64-bit OpenMPI (compiled with GCC) and adds the relevant library path. Then it sets various environment variables. +The above commands prepends the path with the bindir of the 64-bit OpenMPI (compiled with GCC) +and adds the relevant library path. +Then it sets various environment variables. -It is also possible to set `+CFLAGS+` and `+LDFLAGS+` with the above manner, but in the case of MPI compilers it is not necessary since the compilers are invoked with the `+mpicc+`, `+mpicxx+`, `+mpif77+` and `+mpif90+` wrappers that already contain the necessary include and library paths. Also, in the case of development packages an override of `+CFLAGS+` and/or `+LDFLAGS+` is not sane, as it may cause trouble in building RPMs as it overrides `+%{optflags}+`. +It is also possible to set `+CFLAGS+` and `+LDFLAGS+` with the above manner, +but in the case of MPI compilers it is not necessary +since the compilers are invoked with the `+mpicc+`, `+mpicxx+`, `+mpif77+` and `+mpif90+` wrappers +that already contain the necessary include and library paths. +Also, in the case of development packages an override of `+CFLAGS+` and/or `+LDFLAGS+` is not sane, +as it may cause trouble in building RPMs as it overrides `+%{optflags}+`. The upstream documentation for module files is available https://modules.readthedocs.io/en/stable/modulefile.html[here] or with `+man modulefile+`. == Switching between module implementations -Switching between the environment-modules and Lmod implementations is done via alternatives. The shell init scripts /etc/profile.d/modules.\{csh,sh} are links to /etc/alternatives/modules.\{csh.sh} and can be manipulated with the alternatives command. +Switching between the environment-modules and Lmod implementations is done via alternatives. +The shell init scripts /etc/profile.d/modules.\{csh,sh} are links to /etc/alternatives/modules.\{csh.sh} +and can be manipulated with the alternatives command. == Lmod -https://www.tacc.utexas.edu/tacc-projects/lmod[Lmod] is an environment modules implementation written in Lua, and can make use of module files written in Lua as well as Tcl. Such files have a ".lua" extensions. However, such files *must not* be installed /usr/share/modulefiles so as to not cause issues when the environment-modules package is in use. Instead install into %\{_datadir}/lmod/lmod/modulefiles/Core. +https://www.tacc.utexas.edu/tacc-projects/lmod[Lmod] is an environment modules implementation written in Lua, +and can make use of module files written in Lua as well as Tcl. +Such files have a ".lua" extensions. +However, such files *must not* be installed /usr/share/modulefiles +so as to not cause issues when the environment-modules package is in use. +Instead install into %\{_datadir}/lmod/lmod/modulefiles/Core. diff --git a/guidelines/modules/ROOT/pages/Fortran.adoc b/guidelines/modules/ROOT/pages/Fortran.adoc index 50886ea..2b7d287 100644 --- a/guidelines/modules/ROOT/pages/Fortran.adoc +++ b/guidelines/modules/ROOT/pages/Fortran.adoc @@ -2,18 +2,39 @@ == Modules and include files -The fortran modules files, ending in .mod are files describing a fortran 90 (and above) module API and ABI. These are not like C header files describing an API, they are compiler dependent and arch dependent, and not easily readable by a human being. They are nevertheless searched for in the includes directories by gfortran (in directories specified with `+-I+`). - -Due to the ABI specificity, the module directory used must be architecture specific. In addition each gfortran release (e.g. from 4.4 to 4.5) may lead to an incompatible change in the .mod files, therefore mass rebuilds of Fortran packages must take place when gfortran is updated. - -Fortran can also use include files, similar to C headers. Common used filename suffixes are '.inc' and '.h', although '.fh' has been used for files that are designed to function as public headers. +The fortran modules files, ending in .mod are files describing a fortran 90 (and above) module API and ABI. +These are not like C header files describing an API, +they are compiler dependent and arch dependent, +and not easily readable by a human being. +They are nevertheless searched for in the includes directories by gfortran +(in directories specified with `+-I+`). + +Due to the ABI specificity, +the module directory used must be architecture specific. +In addition each gfortran release (e.g. from 4.4 to 4.5) may lead to an incompatible change in the .mod files, +therefore mass rebuilds of Fortran packages must take place when gfortran is updated. + +Fortran can also use include files, similar to C headers. +Common used filename suffixes are '.inc' and '.h', +although '.fh' has been used for files that are designed to function as public headers. == Packaging of Fortran programs -Fortran programs in Fedora MUST be compiled, if possible, using the default Fortran compiler in Fedora, 'gfortran'. As usual, standard Fedora optimization flags `+%{optflags}+` MUST be used in the compilation. +Fortran programs in Fedora MUST be compiled, if possible, +using the default Fortran compiler in Fedora, 'gfortran'. +As usual, standard Fedora optimization flags `+%{optflags}+` MUST be used in the compilation. -Fortran include files MUST be placed in the standard include directory: either directly in `+%{_includedir}+`, or if headers have general names or upstream recommends having an own directory, in e.g. `+%{_includedir}/%{name}+`. +Fortran include files MUST be placed in the standard include directory: +either directly in `+%{_includedir}+`, +or if headers have general names or upstream recommends having an own directory, +in e.g. `+%{_includedir}/%{name}+`. -As Fortran modules are architecture and GCC version specific, they MUST be placed into `+%{_fmoddir}+` (or its package-specific subfolder in case the modules have generic names), which is owned by 'gcc-gfortran'. For directory ownership any packages containing Fortran modules MUST `+Requires: gcc-gfortran%{_isa}+`. +As Fortran modules are architecture and GCC version specific, +they MUST be placed into `+%{_fmoddir}+` +(or its package-specific subfolder in case the modules have generic names), +which is owned by 'gcc-gfortran'. +For directory ownership any packages containing Fortran modules MUST `+Requires: gcc-gfortran%{_isa}+`. -To use the modules in the Fortran module directory, one needs to add `+-I%{_fmoddir}+` to the compiler flags (this is already included in `+FFLAGS+` used by `+%configure+`). +To use the modules in the Fortran module directory, +one needs to add `+-I%{_fmoddir}+` to the compiler flags +(this is already included in `+FFLAGS+` used by `+%configure+`). diff --git a/guidelines/modules/ROOT/pages/GAP.adoc b/guidelines/modules/ROOT/pages/GAP.adoc index 1793add..e46bb30 100644 --- a/guidelines/modules/ROOT/pages/GAP.adoc +++ b/guidelines/modules/ROOT/pages/GAP.adoc @@ -158,14 +158,14 @@ then invoke the macro without arguments in `+%install+`. For special cases, two optional arguments can be given: * `+-d directory+`: -for cases where the documentation directory is not named `doc`, -or there are multiple documentation directories + for cases where the documentation directory is not named `doc`, + or there are multiple documentation directories * `+-n package+`: -the installed add-on directory name is assumed -to be available from a macro `+%pkgname+`. - If that is not the case, -use this macro to give the main add-on directory name. + the installed add-on directory name is assumed + to be available from a macro `+%pkgname+`. + If that is not the case, + use this macro to give the main add-on directory name. == Documentation @@ -186,14 +186,14 @@ Other RPM macros that may be useful for GAP add-on spec files include the following: * `+%gap_version+`: -the version of the main GAP package; e.g., 4.12.0. + the version of the main GAP package; e.g., 4.12.0. * `+%gap_archdir+`: - parent directory for arch-specific GAP add-ons, -currently `+%{_libdir}/gap+`. + parent directory for arch-specific GAP add-ons, + currently `+%{_libdir}/gap+`. * `+%gap_libdir+`: - the root directory of the GAP installation, currently `+%{_datadir}/gap+`. + the root directory of the GAP installation, currently `+%{_datadir}/gap+`. * `+%gap_arch+`: - the GAP name for the build architecture; e.g., `x86_64-redhat-linux-gnu`. + the GAP name for the build architecture; e.g., `x86_64-redhat-linux-gnu`. diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index c1969d9..3c25380 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -1,8 +1,8 @@ = Golang Packaging Guidelines :last-reviewed: 2019-06-19 -This document details best practices for packaging Golang packages. Most of it -is automated by an extensive use of macros. +This document details best practices for packaging Golang packages. +Most of it is automated by an extensive use of macros. == go2rpm @@ -12,17 +12,17 @@ before attempting to write a SPEC by hand. == Import Path -In Golang, packages are referenced by full URLs. Since this URL is -referenced in several places throughout the rpmspec, set the -base import path as a global define at the top of the spec file +In Golang, packages are referenced by full URLs. +Since this URL is referenced in several places throughout the rpmspec, +set the base import path as a global define at the top of the spec file [source,rpm-spec] ---- %global goipath github.com/kr/pretty ---- -All macros, including package name, source URL, will be computed from this -value. +All macros, including package name, source URL, +will be computed from this value. [NOTE] ==== diff --git a/guidelines/modules/ROOT/pages/Golang_advanced.adoc b/guidelines/modules/ROOT/pages/Golang_advanced.adoc index f9272e9..8c7e4ab 100644 --- a/guidelines/modules/ROOT/pages/Golang_advanced.adoc +++ b/guidelines/modules/ROOT/pages/Golang_advanced.adoc @@ -3,8 +3,8 @@ == Shipping additional files -If you need to ship additional files in your source code packages, you can use -the following macros in the preamble: +If you need to ship additional files in your source code packages, +you can use the following macros in the preamble: * `+%global goextensions+` A space separated list of extensions that should be included in the devel package in addition to @@ -24,9 +24,10 @@ For example, if you have glide files to ship: == Additional header declarations -Use `+%godevelheader+` to add specific subpackage declarations. For example, you -might want to require the main package containing the binaries, or -Obsoletes/Provides another package in case of renaming. +Use `+%godevelheader+` to add specific subpackage declarations. +For example, +you might want to require the main package containing the binaries, +or Obsoletes/Provides another package in case of renaming. [source,rpm-spec] ---- @@ -39,14 +40,17 @@ Provides: == Dealing with cyclic dependencies -In many cases, you'll encounter packages that depend on each other, also known -as cyclic dependencies, making it difficult to build either package. - -Typically, when you have a problematic requires, it is only used in specific -project subpackages, and most project dependents do not need those subpackages -directly or indirectly. The idea is then to affect the goipaths associated with -the problematic subpackages to a separate -devel rpm package, to simplify -your dependency graph. +In many cases, +you'll encounter packages that depend on each other, +also known as cyclic dependencies, +making it difficult to build either package. + +Typically, when you have a problematic requires, +it is only used in specific project subpackages, +and most project dependents do not need those subpackages directly or indirectly. +The idea is then to affect the goipaths associated with the problematic subpackages +to a separate -devel rpm package, +to simplify your dependency graph. Let's take for example the following packages: `+cloud.google.com/go+` and `+golang.org/x/oauth2+`. diff --git a/guidelines/modules/ROOT/pages/Initial_Service_Setup.adoc b/guidelines/modules/ROOT/pages/Initial_Service_Setup.adoc index 7872411..6e82b65 100644 --- a/guidelines/modules/ROOT/pages/Initial_Service_Setup.adoc +++ b/guidelines/modules/ROOT/pages/Initial_Service_Setup.adoc @@ -1,10 +1,19 @@ = First-time Service Setup -Many system services require some amount of initial setup before they can run properly for the first time. Common examples are the generation of private keys and certificates or a unique, system-specific identifier. - -Traditionally, this was done by RPM scriptlets as part of the installation or upgrade of a package. This was sensible for a time when the majority of installations were performed by attended or unattended installers (such as anaconda and kickstart). - -Today we see an increased reliance on generating virtual machine images for use in both traditional and cloud-computing environments. In those cases, having system-specific data created at package installation time is problematic. It means that the production of such images need to have significant care applied to remove any system-specific information about them and then additional tools written to apply the corrected information post-deployment. *The goal of this guideline is to ensure that if a system clean-up service such as virt-sysprep is run on the system and then the machine is rebooted, any service that requires first-time configuration will re-run it.* The mechanism by which we will accomplish this is to remove such first-time configuration from RPM scriptlets (e.g. `+%post+`) and instead execute this configuration as part of service startup with systemd. +Many system services require some amount of initial setup before they can run properly for the first time. +Common examples are the generation of private keys and certificates +or a unique, system-specific identifier. + +Traditionally, this was done by RPM scriptlets as part of the installation or upgrade of a package. +This was sensible for a time when the majority of installations were performed by attended or unattended installers (such as anaconda and kickstart). + +Today we see an increased reliance on generating virtual machine images for use in both traditional and cloud-computing environments. +In those cases, having system-specific data created at package installation time is problematic. +It means that the production of such images need to have significant care applied to remove any system-specific information about them +and then additional tools written to apply the corrected information post-deployment. +*The goal of this guideline is to ensure that if a system clean-up service such as virt-sysprep is run on the system and then the machine is rebooted, any service that requires first-time configuration will re-run it.* +The mechanism by which we will accomplish this is to remove such first-time configuration from RPM scriptlets (e.g. `+%post+`) +and instead execute this configuration as part of service startup with systemd. This guideline describes a mechanism that can be used for both traditional and cloud-based deployment styles. diff --git a/guidelines/modules/ROOT/pages/Java.adoc b/guidelines/modules/ROOT/pages/Java.adoc index 2d4a7d4..c57e37f 100644 --- a/guidelines/modules/ROOT/pages/Java.adoc +++ b/guidelines/modules/ROOT/pages/Java.adoc @@ -1,16 +1,14 @@ = Java Packaging Guidelines :last-reviewed: 2022-07-01 -This page represents Fedora guidelines -for packaging libraries and applications -written in Java and related languages +This page represents Fedora guidelines for packaging libraries and applications written in Java and related languages that use the Java Virtual Machine as a bytecode interpreter. It does not aim to extensively describe packaging techniques and tips. RPM macros and commands used here are documented in man pages. -Furthermore, a separate https://fedora-java.github.io/howto/latest/[Java Packaging HOWTO] -describes Java packaging techniques in detail -and includes examples, templates and documentation aimed at packagers and Java developers +Furthermore, a separate https://fedora-java.github.io/howto/latest/[Java Packaging HOWTO] describes Java packaging techniques in detail +and includes examples, templates and documentation +aimed at packagers and Java developers who are taking their first steps in Java RPM packaging. Fedora Java packaging is originally based on the https://web.archive.org/web/20191223234327/http://www.jpackage.org/[JPackage Project] standards. diff --git a/guidelines/modules/ROOT/pages/JavaScript.adoc b/guidelines/modules/ROOT/pages/JavaScript.adoc index 8673aa5..dce586f 100644 --- a/guidelines/modules/ROOT/pages/JavaScript.adoc +++ b/guidelines/modules/ROOT/pages/JavaScript.adoc @@ -20,11 +20,14 @@ Node.js xref:Node.js.adoc[have their own guidelines], and software like GNOME which embeds JavaScript for extensions have their own directories and policies as well. -Packages containing JavaScript should make the best effort to regenerate any precompiled/minimized JS wherever possible, +Packages containing JavaScript should make the best effort to regenerate +any precompiled/minimized JS wherever possible, as this leads to more maintainable packages. Where this would result in a significant hardship, -the bundled pregenerated JS may be shipped with a specfile comment explaining the decision. -This does not eliminate the requirement to validate licenses of bundled code. +the bundled pregenerated JS may be shipped +with a specfile comment explaining the decision. +This does not eliminate the requirement +to validate licenses of bundled code. == Naming Guidelines diff --git a/guidelines/modules/ROOT/pages/KDEPackaging.adoc b/guidelines/modules/ROOT/pages/KDEPackaging.adoc index e4484fd..b58f6e3 100644 --- a/guidelines/modules/ROOT/pages/KDEPackaging.adoc +++ b/guidelines/modules/ROOT/pages/KDEPackaging.adoc @@ -2,11 +2,13 @@ :last-reviewed: 2024-01-02 -This document outlines the best practices for packaging software using the KDE frameworks, for use in Fedora. +This document outlines the best practices for packaging software using the KDE frameworks, +for use in Fedora. == Build Dependencies -If using cmake, the following BuildRequires are a *MUST*: +If using cmake, +the following BuildRequires are a *MUST*: [source, rpm-spec] ---- @@ -15,11 +17,14 @@ BuildRequires: gcc-c++ BuildRequires: kf6-rpm-macros ---- -`kf6-rpm-macros` needs to be changed to `kf5-rpm-macros` if building for Plasma 5 instead of Plasma 6. +`kf6-rpm-macros` needs to be changed to `kf5-rpm-macros` +if building for Plasma 5 instead of Plasma 6. == Available Macros -The following macros are used in the building of KDE packages. Note that the version of macros (i.e. `%cmake_kf5` and `%cmake_kf6`) can be changed depending on which version of Plasma you are building for. +The following macros are used in the building of KDE packages. +Note that the version of macros (i.e. `%cmake_kf5` and `%cmake_kf6`) can be changed +depending on which version of Plasma you are building for. `+%cmake_kf6+`:: Not unlike `+%cmake+`, this macro defines CFLAGS, LDFLAGS, etc. and calls `+%__cmake+` @@ -42,9 +47,12 @@ This macro is sometimes used instead of `+%find_lang+` in packages using languag [#kde-file-macros] == Macros for paths set and used by build systems -The following table lists macros which are widely used in fedora `.spec` files. Those macros are provided by the `kf5-rpm-macros` (For Plasma 5) and `kf6-rpm-macros` (For Plasma 6) packages. +The following table lists macros which are widely used in fedora `.spec` files. +Those macros are provided by the `kf5-rpm-macros` (For Plasma 5) and `kf6-rpm-macros` (For Plasma 6) packages. -For Plasma 5, the following macros can simply have their version number changed to reflect the Plasma 5 version (For example, `+%{_kf6_datadir}+` would become `+%{_kf5_datadir}+`). +For Plasma 5, +the following macros can simply have their version number changed to reflect the Plasma 5 version +(For example, `+%{_kf6_datadir}+` would become `+%{_kf5_datadir}+`). [cols="20%m,30%m,50%",options="header"] |================================= diff --git a/guidelines/modules/ROOT/pages/Langpacks.adoc b/guidelines/modules/ROOT/pages/Langpacks.adoc index a3abafb..4e76fd5 100644 --- a/guidelines/modules/ROOT/pages/Langpacks.adoc +++ b/guidelines/modules/ROOT/pages/Langpacks.adoc @@ -1,10 +1,26 @@ = Language packages -The idea behind "langpacks" is to separate translations or language specific content into subpackages in the case that the size of the files is huge or the package is part of a core image that should be minimal. +The idea behind "langpacks" is to separate translations +or language specific content into subpackages +in the case that the size of the files is huge +or the package is part of a core image that should be minimal. -Subpackages that exist solely to contain additional language translations or content must be named in the form -langpack-, where is the name of the package that the langpacks belong to and is a valid language code from _/usr/share/xml/iso-codes/iso_639_3.xml_ or from _/usr/share/i18n/locales/_. Specifically, the langcode value used in the package name must agree with the langcode identifier used in the directory path by upstream for the translation or language files. +Subpackages that exist solely to contain additional language translations or content +must be named in the form -langpack-, +where is the name of the package that the langpacks belong to +and is a valid language code +from _/usr/share/xml/iso-codes/iso_639_3.xml_ +or from _/usr/share/i18n/locales/_. +Specifically, +the langcode value used in the package name must agree with the langcode identifier +used in the directory path by upstream +for the translation or language files. -The langpack ecosystem does not need any procedural logic in the form of plugins. Instead it takes advantage of the weak and rich dependency features provided by RPM. The necessary dependencies are computed by the package manager (DNF or PackageKit) so it is essential to include the following `+Supplements:+` tag relation in the langpack package definition in the spec file: +The langpack ecosystem does not need any procedural logic in the form of plugins. +Instead it takes advantage of the weak and rich dependency features provided by RPM. +The necessary dependencies are computed by the package manager (DNF or PackageKit) +so it is essential to include the following `+Supplements:+` tag relation +in the langpack package definition in the spec file: `+Supplements: (%{name} = %{version}-%{release} and langpacks-)+` @@ -18,7 +34,13 @@ Suppose you have a package with following spec file: `+/usr/share/pear-data/Horde_Perms/locale/+` + `+...+` -In order to create langpacks for each language (_/usr/share/pear-data/Horde_Perms/locale//LC_MESSAGES/Horde_Perms.mo_ translations), you would need to define a new subpackage for each package. The snippet below shows a macro for automating the definition of langpacks, along with the definition of langpacks for _bs_ and _cs_ languages. This would replace the lines shown above. Note that this macro definition is specific to the example package; you will need to modify it as appropriate for your package. +In order to create langpacks for each language (_/usr/share/pear-data/Horde_Perms/locale//LC_MESSAGES/Horde_Perms.mo_ translations), +you would need to define a new subpackage for each package. +The snippet below shows a macro for automating the definition of langpacks, +along with the definition of langpacks for _bs_ and _cs_ languages. +This would replace the lines shown above. +Note that this macro definition is specific to the example package; +you will need to modify it as appropriate for your package. `+Name: php-horde-Horde-Perms+` + `+...+` + diff --git a/guidelines/modules/ROOT/pages/LibreOfficeExtensions.adoc b/guidelines/modules/ROOT/pages/LibreOfficeExtensions.adoc index 8fb57fc..b593c53 100644 --- a/guidelines/modules/ROOT/pages/LibreOfficeExtensions.adoc +++ b/guidelines/modules/ROOT/pages/LibreOfficeExtensions.adoc @@ -1,11 +1,25 @@ = LibreOffice extension rpm guidelines -1. Extensions *Must* be installed unpacked under %\{_libdir}/libreoffice/share/extensions. These are termed bundled extensions. Extensions should not be installed as shared extensions i.e. via unopkg --shared + -2. An extension should normally just be able to Require: an appropriate LibreOffice component e.g. libreoffice-core, without a specific n-v-r as extensions use the stable UNO ABI which rarely changes, and then only to add extra APIs. So unless you require a specific feature of a LibreOffice release there is no need to require a specific n-v-r and force a rebuild on every n-v-r of libreoffice. + +1. Extensions *Must* be installed unpacked under %\{_libdir}/libreoffice/share/extensions. + These are termed bundled extensions. + Extensions should not be installed as shared extensions i.e. via unopkg --shared + +2. An extension should normally just be able to Require: an appropriate LibreOffice component e.g. libreoffice-core, + without a specific n-v-r as extensions use the stable UNO ABI which rarely changes, + and then only to add extra APIs. + So unless you require a specific feature of a LibreOffice release there is no need to require a specific n-v-r and force a rebuild on every n-v-r of libreoffice. + 3. Extensions *Must* be named libreoffice-FOO. + -4. Extensions are similar to e.g. xorg video drivers in that there exist proprietary or binary only extensions, but of course normal Fedora rules apply to what extensions can be packaged, i.e. see normal packaging licensing etc. rules. The license *Must* be acceptable, and the package *Must* be built from source. + -5. Extensions can be written in any language that has an uno binding, e.g. C++, python, java or StarBasic. Consider the additional packaging guidelines of the language that the extension is written in if such guidelines exists. + -6. Many extensions are actually architecture independent, but cannot be noarch packages due to libreoffice limitations. Such packages will generate empty debuginfo sub-packages. If this is the case, add '%global debug_package %\{nil}' to the package. +4. Extensions are similar to e.g. xorg video drivers in that there exist proprietary or binary only extensions, + but of course normal Fedora rules apply to what extensions can be packaged, + i.e. see normal packaging licensing etc. rules. + The license *Must* be acceptable, + and the package *Must* be built from source. + +5. Extensions can be written in any language that has an uno binding, + e.g. C++, python, java or StarBasic. + Consider the additional packaging guidelines of the language that the extension is written in if such guidelines exists. + +6. Many extensions are actually architecture independent, + but cannot be noarch packages due to libreoffice limitations. + Such packages will generate empty debuginfo sub-packages. + If this is the case, add '%global debug_package %\{nil}' to the package. .. + An example is... + diff --git a/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc b/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc index 42400ff..cd6b2d9 100644 --- a/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc +++ b/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc @@ -15,8 +15,8 @@ https://www.gnu.org/philosophy/license-list.html#GPLCompatibleLicenses[Free Soft https://opensource.org/licenses/[OSI] and consultation with Red Hat Legal. -For more details on the criteria for allowed -and not-allowed licenses, processes related to licensing, +For more details on the criteria for allowed and not-allowed licenses, +processes related to licensing, or other guidance related to Fedora licensing, see xref:legal::index.adoc[Licensing in Fedora]. diff --git a/guidelines/modules/ROOT/pages/Lisp.adoc b/guidelines/modules/ROOT/pages/Lisp.adoc index 8016db4..a8bf144 100644 --- a/guidelines/modules/ROOT/pages/Lisp.adoc +++ b/guidelines/modules/ROOT/pages/Lisp.adoc @@ -7,11 +7,21 @@ This document does _not_ describe conventions and customs for application progra 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. -The Common Lisp community currently rallies around a common packaging and deployment technology called asdf (Another System Definition Format). Projects deployed using asdf include a system definition file. These files include information about project dependencies, licensing, and the authors. Projects don't typically distribute binaries, but rather depend on the asdf utilities to compile the Lisp source code on demand. When you run program that depends on a library managed by asdf, the asdf system will automatically compile the dependent Lisp code on demand and cache the results. - -The Debian Lisp community have developed tools and guidelines for packaging and maintaining asdf managed libraries on Linux systems. Their tool is called common-lisp-controller and, combined with asdf, it ensures that .fasl files are managed properly on the system. For instance, when a Common Lisp implementation is upgraded, the .fasl files for all of the packages built using the old implementation are deleted so that new ones may be generated on demand. - -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. +The Common Lisp community currently rallies around a common packaging and deployment technology called asdf (Another System Definition Format). +Projects deployed using asdf include a system definition file. +These files include information about project dependencies, licensing, and the authors. +Projects don't typically distribute binaries, +but rather depend on the asdf utilities to compile the Lisp source code on demand. +When you run program that depends on a library managed by asdf, +the asdf system will automatically compile the dependent Lisp code on demand and cache the results. + +The Debian Lisp community have developed tools and guidelines for packaging and maintaining asdf managed libraries on Linux systems. +Their tool is called common-lisp-controller and, combined with asdf, it ensures that .fasl files are managed properly on the system. +For instance, when a Common Lisp implementation is upgraded, +the .fasl files for all of the packages built using the old implementation are deleted so that new ones may be generated on demand. + +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 diff --git a/guidelines/modules/ROOT/pages/Lua.adoc b/guidelines/modules/ROOT/pages/Lua.adoc index 941362a..ae19f50 100644 --- a/guidelines/modules/ROOT/pages/Lua.adoc +++ b/guidelines/modules/ROOT/pages/Lua.adoc @@ -13,10 +13,11 @@ To learn Lua, read https://www.lua.org/pil/contents.html[Programming in Lua]. == Spec Template for a Lua Package -Many Lua packages use http://luarocks.org/[Lua-rocks] for packaging. It is helpful -to examine the `+.rockspec+` specification as a guide in writing your spec file. -Some packages require compilation of C programs, but others may be pure Lua. Both -will have very similar install locations. +Many Lua packages use http://luarocks.org/[Lua-rocks] for packaging. +It is helpful to examine the `+.rockspec+` specification as a guide in writing your spec file. +Some packages require compilation of C programs, +but others may be pure Lua. +Both will have very similar install locations. .... Summary: Lua integration with libev @@ -75,9 +76,9 @@ lua -e 'ev = require "ev"; print(ev.version())' == Naming Lua add-on packages generally follow the naming scheme of `+lua-modulename+` --- e.g. `+lua-filesystem+`, `+lua-lpeg+`, `+lua-moonscript+`. If the module name -makes it clear that it is an add-on for Lua, though, the module name -itself is sufficient. e.g. `+lutok+`. +-- e.g. `+lua-filesystem+`, `+lua-lpeg+`, `+lua-moonscript+`. +If the module name makes it clear that it is an add-on for Lua, though, +the module name itself is sufficient. e.g. `+lutok+`. Use your judgement -- e.g. the second `+l+` in `+lua-lpeg+` already stands for Lua, but it might not be seen as unambiguous enough. diff --git a/guidelines/modules/ROOT/pages/MPI.adoc b/guidelines/modules/ROOT/pages/MPI.adoc index 9a488fd..960029b 100644 --- a/guidelines/modules/ROOT/pages/MPI.adoc +++ b/guidelines/modules/ROOT/pages/MPI.adoc @@ -2,12 +2,31 @@ == Introduction -Message Passing Interface (MPI) is an API for parallelization of programs across multiple nodes and has been around since 1994 https://en.wikipedia.org/wiki/Message_Passing_Interface[1]. MPI can also be used for parallelization on SMP machines and is considered very efficient in it too (close to 100% scaling on parallelizable code as compared to ~80% commonly obtained with threads due to unoptimal memory allocation on NUMA machines). Before MPI, about every manufacturer of supercomputers had their own programming language for writing programs; MPI made porting software easy. - -There are many MPI implementations available, such as https://www.open-mpi.org/[Open MPI] (the default MPI compiler in Fedora and the MPI compiler used in RHEL), https://www.mpich.org/[MPICH] (in Fedora and RHEL) and -https://mvapich.cse.ohio-state.edu/[MVAPICH1 and MVAPICH2] (in RHEL but not yet in Fedora). - -As some MPI libraries work better on some hardware than others, and some software works best with some MPI library, the selection of the library used must be done in user level, on a session specific basis. Also, people doing high performance computing may want to use more efficient compilers than the default one in Fedora (gcc), so one must be able to have many versions of the MPI compiler each compiled with a different compiler installed at the same time. This must be taken into account when writing spec files. +Message Passing Interface (MPI) is an API for parallelization of programs across multiple nodes +and has been around since 1994 https://en.wikipedia.org/wiki/Message_Passing_Interface[1]. +MPI can also be used for parallelization on SMP machines +and is considered very efficient in it too +(close to 100% scaling on parallelizable code as compared to ~80% commonly obtained with threads +due to unoptimal memory allocation on NUMA machines). +Before MPI, about every manufacturer of supercomputers had their own programming language for writing programs; +MPI made porting software easy. + +There are many MPI implementations available, +such as https://www.open-mpi.org/[Open MPI] +(the default MPI compiler in Fedora and the MPI compiler used in RHEL), +https://www.mpich.org/[MPICH] (in Fedora and RHEL) +and https://mvapich.cse.ohio-state.edu/[MVAPICH1 and MVAPICH2] +(in RHEL but not yet in Fedora). + +As some MPI libraries work better on some hardware than others, +and some software works best with some MPI library, +the selection of the library used must be done in user level, +on a session specific basis. +Also, people doing high performance computing may want to use more efficient compilers +than the default one in Fedora (gcc), +so one must be able to have many versions of the MPI compiler +each compiled with a different compiler installed at the same time. +This must be taken into account when writing spec files. == Packaging of MPI compilers @@ -24,7 +43,12 @@ The files of MPI compilers MUST be installed in the following directories: |Config files |`+%{_sysconfdir}/%{name}-%{_arch}+` |=================================================================== -As include files and manual pages are bound to overlap between different MPI implementations, they MUST also placed outside normal directories. It is possible that some man pages or include files (either those of the MPI compiler itself or of some MPI software installed in the compiler's directory) are architecture specific (e.g. a definition on a 32-bit arch differs from that on a 64-bit arch), the directories that MUST be used are as follows: +As include files and manual pages are bound to overlap between different MPI implementations, +they MUST also placed outside normal directories. +It is possible that some man pages or include files +(either those of the MPI compiler itself or of some MPI software installed in the compiler's directory) +are architecture specific (e.g. a definition on a 32-bit arch differs from that on a 64-bit arch), +the directories that MUST be used are as follows: [cols=",",options="header",] |================================================ @@ -35,11 +59,16 @@ As include files and manual pages are bound to overlap between different MPI imp Architecture independent parts (except headers which go into `+-devel+`) MUST be placed in a `+-common+` subpackage that is `+BuildArch: noarch+`. -The runtime of MPI compilers (mpirun, the libraries, the manuals etc) MUST be packaged into %\{name}, and the development headers and libraries into %\{name}-devel. +The runtime of MPI compilers (mpirun, the libraries, the manuals etc) +MUST be packaged into %\{name}, +and the development headers and libraries into %\{name}-devel. -As the compiler is installed outside `+PATH+`, one needs to load the relevant variables before being able to use the compiler or run MPI programs. This is done using xref:EnvironmentModules.adoc[environment modules]. +As the compiler is installed outside `+PATH+`, +one needs to load the relevant variables before being able to use the compiler or run MPI programs. +This is done using xref:EnvironmentModules.adoc[environment modules]. -The module file MUST be installed under `+%{_sysconfdir}/modulefiles/mpi+`. This allows as user with only one mpi implementation installed to load the module with: +The module file MUST be installed under `+%{_sysconfdir}/modulefiles/mpi+`. +This allows as user with only one mpi implementation installed to load the module with: .... module load mpi @@ -53,7 +82,8 @@ conflict mpi to prevent concurrent loading of multiple mpi modules. -The module file MUST prepend `+$MPI_BIN+` into the user's `+PATH+` and prepend `+$MPI_LIB+` to `+LD_LIBRARY_PATH+`. +The module file MUST prepend `+$MPI_BIN+` into the user's `+PATH+` +and prepend `+$MPI_LIB+` to `+LD_LIBRARY_PATH+`. The module file MUST also set some helper variables (primarily for use in spec files): [cols=",,",options="header",] @@ -71,13 +101,20 @@ The module file MUST also set some helper variables (primarily for use in spec f |`+MPI_SUFFIX+` |`+_%{name}+` |The suffix used for programs compiled against the MPI stack |========================================================================================== -As these directories may be used by software using the MPI stack, the MPI runtime package MUST own all of them. +As these directories may be used by software using the MPI stack, +the MPI runtime package MUST own all of them. -MUST: By default, NO files are placed in `+/etc/ld.so.conf.d+`. If the packager wishes to provide alternatives support, it MUST be placed in a subpackage along with the ld.so.conf.d file so that alternatives support does not need to be installed if not wished for. +MUST: By default, NO files are placed in `+/etc/ld.so.conf.d+`. +If the packager wishes to provide alternatives support, +it MUST be placed in a subpackage along with the ld.so.conf.d file +so that alternatives support does not need to be installed if not wished for. -MUST: If the maintainer wishes for the environment module to load automatically by use of a scriptlet in /etc/profile.d or by some other mechanism, this MUST be done in a subpackage. +MUST: If the maintainer wishes for the environment module to load automatically +by use of a scriptlet in /etc/profile.d or by some other mechanism, +this MUST be done in a subpackage. -MUST: The MPI compiler package MUST provide an RPM macro that makes loading and unloading the support easy in spec files, e.g. by placing the following in `+/etc/rpm/macros.openmpi+` +MUST: The MPI compiler package MUST provide an RPM macro that makes loading and unloading the support easy in spec files, +e.g. by placing the following in `+/etc/rpm/macros.openmpi+` .... %_openmpi_load \ @@ -91,19 +128,36 @@ MUST: The MPI compiler package MUST provide an RPM macro that makes loading and loading and unloading the compiler in spec files is as easy as `+%{_openmpi_load}+` and `+%{_openmpi_unload}+`. -Automatic setting of the module loading path in python interpreters is done using a `+.pth+` file placed in one of the directories normally searched for modules (`+%{python2_sitearch}+`, `+%{python3_sitearch}+`). Those `+.pth+` files should append the directory specified with $MPI_PYTHON2_SITEARCH or $MPI_PYTHON3_SITEARCH environment variable, depending on the interpreter version, to `+sys.path+`, and do nothing if those variables are unset. Module files MUST NOT set PYTHONPATH directly, since it cannot be set for both Python versions at the same time. +Automatic setting of the module loading path in python interpreters is done using a `+.pth+` file placed in one of the directories normally searched for modules (`+%{python2_sitearch}+`, `+%{python3_sitearch}+`). +Those `+.pth+` files should append the directory specified with $MPI_PYTHON2_SITEARCH or $MPI_PYTHON3_SITEARCH environment variable, +depending on the interpreter version, +to `+sys.path+`, +and do nothing if those variables are unset. +Module files MUST NOT set PYTHONPATH directly, +since it cannot be set for both Python versions at the same time. -If the environment module sets compiler flags such as `+CFLAGS+` (thus overriding the ones exported in `+%configure+`, the RPM macro MUST make them use the Fedora optimization flags `+%{optflags}+` once again (as in the example above in which the openmpi-%\{_arch} module sets CFLAGS). +If the environment module sets compiler flags such as `+CFLAGS+` +(thus overriding the ones exported in `+%configure+`, +the RPM macro MUST make them use the Fedora optimization flags `+%{optflags}+` once again +(as in the example above in which the openmpi-%\{_arch} module sets CFLAGS). == Packaging of MPI software -Software that supports MPI MUST be packaged also in serial mode [i.e. no MPI], if it is supported by upstream. (for instance: `+foo+`). +Software that supports MPI MUST be packaged also in serial mode [i.e. no MPI], +if it is supported by upstream. +(for instance: `+foo+`). -If possible, the packager MUST package versions for each MPI compiler in Fedora (e.g. if something can only be built with mpich and mvapich2, then mvapich1 and openmpi packages do not need to be made). +If possible, the packager MUST package versions for each MPI compiler in Fedora +(e.g. if something can only be built with mpich and mvapich2, +then mvapich1 and openmpi packages do not need to be made). MPI implementation specific files MUST be installed in the directories used by the used MPI compiler (`+$MPI_BIN+`, `+$MPI_LIB+` and so on). -The binaries MUST be suffixed with `+$MPI_SUFFIX+` (e.g. _openmpi for Open MPI, _mpich for MPICH and _mvapich2 for MVAPICH2). This is for two reasons: the serial version of the program can still be run when an MPI module is loaded and the user is always aware of the version s/he is running. This does not need to hurt the use of shell scripts: +The binaries MUST be suffixed with `+$MPI_SUFFIX+` +(e.g. _openmpi for Open MPI, _mpich for MPICH and _mvapich2 for MVAPICH2). +This is for two reasons: the serial version of the program can still be run when an MPI module is loaded +and the user is always aware of the version s/he is running. +This does not need to hurt the use of shell scripts: .... # Which MPI implementation do we use? @@ -122,15 +176,29 @@ mpirun -np 4 bar${MPI_SUFFIX} -process bar -collect .... -The MPI enabled bits MUST be placed in a subpackage with the suffix denoting the MPI compiler used (for instance: `+foo-openmpi+` for Open MPI [the traditional MPI compiler in Fedora] or `+foo-mpich+` for MPICH). For directory ownership and to guarantee the pickup of the correct MPI runtime, the MPI subpackages MUST require the correct MPI compiler's runtime package. - -Each MPI build of shared libraries SHOULD have a separate -libs subpackage for the libraries (e.g. foo-mpich-libs). As in the case of MPI compilers, library configuration (in `+/etc/ld.so.conf.d+`) MUST NOT be made. - -In case the headers are the same regardless of the compilation method and architecture (e.g. 32-bit serial, 64-bit Open MPI, MPICH), they MUST be split into a separate `+-headers+` subpackage (e.g. 'foo-headers'). Fortran modules are architecture specific and as such are placed in the (MPI implementation specific) `+-devel+` package (foo-devel for the serial version and foo-openmpi-devel for the Open MPI version). - -Each MPI build MUST have a separate -devel subpackage (e.g. foo-mpich-devel) that includes the development libraries and `+Requires: %{name}-headers+` if such a package exists. The goal is to be able to install and develop using e.g. 'foo-mpich-devel' without needing to install e.g. openmpi or the serial version of the package. - -Files must be shared between packages as much as possible. Compiler independent parts, such as data files in `+%{_datadir}/%{name}+` and man files MUST be put into a `+-common+` subpackage that is required by all of the binary packages (the serial package and all of the MPI packages). +The MPI enabled bits MUST be placed in a subpackage with the suffix denoting the MPI compiler used +(for instance: `+foo-openmpi+` for Open MPI [the traditional MPI compiler in Fedora] or `+foo-mpich+` for MPICH). +For directory ownership and to guarantee the pickup of the correct MPI runtime, +the MPI subpackages MUST require the correct MPI compiler's runtime package. + +Each MPI build of shared libraries SHOULD have a separate -libs subpackage for the libraries (e.g. foo-mpich-libs). +As in the case of MPI compilers, library configuration (in `+/etc/ld.so.conf.d+`) MUST NOT be made. + +In case the headers are the same regardless of the compilation method and architecture +(e.g. 32-bit serial, 64-bit Open MPI, MPICH), +they MUST be split into a separate `+-headers+` subpackage (e.g. 'foo-headers'). +Fortran modules are architecture specific and as such are placed in the (MPI implementation specific) `+-devel+` package +(foo-devel for the serial version and foo-openmpi-devel for the Open MPI version). + +Each MPI build MUST have a separate -devel subpackage (e.g. foo-mpich-devel) +that includes the development libraries and `+Requires: %{name}-headers+` if such a package exists. +The goal is to be able to install and develop using e.g. 'foo-mpich-devel' +without needing to install e.g. openmpi or the serial version of the package. + +Files must be shared between packages as much as possible. +Compiler independent parts, +such as data files in `+%{_datadir}/%{name}+` and man files MUST be put into a `+-common+` subpackage +that is required by all of the binary packages (the serial package and all of the MPI packages). === A sample spec file diff --git a/guidelines/modules/ROOT/pages/Meson.adoc b/guidelines/modules/ROOT/pages/Meson.adoc index 8f2f2cd..6b1875c 100644 --- a/guidelines/modules/ROOT/pages/Meson.adoc +++ b/guidelines/modules/ROOT/pages/Meson.adoc @@ -1,6 +1,14 @@ = Meson Packaging Guidelines -This document provides best practices for the usage of https://mesonbuild.com/[the Meson build system] in Fedora packages. Meson is a build system (similar to automake) which can generate code for other lower-level build systems. For example, it can generate code for https://ninja-build.org/[ninja]. When packaging software which builds using Meson it's important to use the `+%meson+` macros instead of `+%ninja+` or other lower-level build system macros directly. The backend used by Meson could change. +This document provides best practices for the usage of +https://mesonbuild.com/[the Meson build system] +in Fedora packages. +Meson is a build system (similar to automake) +which can generate code for other lower-level build systems. +For example, it can generate code for https://ninja-build.org/[ninja]. +When packaging software which builds using Meson it's important to use the `+%meson+` macros +instead of `+%ninja+` or other lower-level build system macros directly. +The backend used by Meson could change. == Build Dependencies diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index 6c09a84..1a854ab 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -2,21 +2,18 @@ == 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. - -The targets Win32 and Win64 are supported with the MSVCRT runtime. The target -Win64 with the UCRT runtime is also supported, however, only for the base -toolchain. Builds for UCRT are not enabled for packages above the toolchain -at this time. +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. + +The targets Win32 and Win64 are supported with the MSVCRT runtime. +The target Win64 with the UCRT runtime is also supported, however, +only for the base toolchain. +Builds for UCRT are not enabled for packages above the toolchain at this time. == Separate vs integrated MinGW source packages diff --git a/guidelines/modules/ROOT/pages/Mono.adoc b/guidelines/modules/ROOT/pages/Mono.adoc index 454f402..83914af 100644 --- a/guidelines/modules/ROOT/pages/Mono.adoc +++ b/guidelines/modules/ROOT/pages/Mono.adoc @@ -2,11 +2,21 @@ == File Locations and Architectures -For a while, Fedora considered mono packages to be architecture-specific, and installed assemblies to %\{_libdir}. However, after discussions with upstream, we now consider mono packages to be architecture (and platform) independent. This means that mono packages should be correctly installed into the GAC in in %\{_monogacdir} or installed into /usr/lib/PACKAGENAME. - -As a notable exception, any ELF binary libraries generated in a mono package must be correctly installed into %\{_libdir}, because these files are architecture-specific. - -Also, even though we consider mono packages to be architecture independent, they must not be marked as "noarch". Although the assemblies are the same, the files may differ due to strings referring to the build architecture. +For a while, Fedora considered mono packages to be architecture-specific, +and installed assemblies to %\{_libdir}. +However, after discussions with upstream, +we now consider mono packages to be architecture (and platform) independent. +This means that mono packages should be correctly installed into the GAC in in %\{_monogacdir} +or installed into /usr/lib/PACKAGENAME. + +As a notable exception, +any ELF binary libraries generated in a mono package must be correctly installed into %\{_libdir}, +because these files are architecture-specific. + +Also, even though we consider mono packages to be architecture independent, +they must not be marked as "noarch". +Although the assemblies are the same, +the files may differ due to strings referring to the build architecture. In addition, because some architectures simply do not support mono, every mono package (either a library or a mono-using application) must include @@ -43,13 +53,23 @@ gacutil format == RPMS and source -Don't build RPMS against built from source versions of mono. It will work for you but probably not for other users! +Don't build RPMS against built from source versions of mono. +It will work for you +but probably not for other users! -While you may get away with recompiling the source for part of the overall package (such as gnome-panel is part of gnome or evolution-data-server is part of evolution) for other programs, you should not attempt this with Mono. +While you may get away with recompiling the source for part of the overall package +(such as gnome-panel is part of gnome or evolution-data-server is part of evolution) +for other programs, +you should not attempt this with Mono. If you're going to use the source, you *MUST* remove the RPMS first. -Compiling mono is not a trivial matter and may not even work (when you download the source, you must also _make get-monolite-latest_ which grabs a version of the corelib and mcs which are need for compiling the main C# compilers - the monolite-latest does not always work and you end up without a working copy of Mono. +Compiling mono is not a trivial matter and may not even work +(when you download the source, +you must also _make get-monolite-latest_ +which grabs a version of the corelib and mcs which are need for compiling the main C# compilers - +the monolite-latest does not always work +and you end up without a working copy of Mono. == rpmlint and mono packages diff --git a/guidelines/modules/ROOT/pages/Node.js.adoc b/guidelines/modules/ROOT/pages/Node.js.adoc index 6749664..8f15e52 100644 --- a/guidelines/modules/ROOT/pages/Node.js.adoc +++ b/guidelines/modules/ROOT/pages/Node.js.adoc @@ -1,6 +1,10 @@ = Node.js Packaging Guidelines -The upstream Node.js stance on https://nodejs.org/en/blog/npm/npm-1-0-global-vs-local-installation/[global library packages] is that they are ".. best avoided if not needed." In Fedora, we take the same stance with our nodejs packages. You can provide a package that uses nodejs, but you should bundle all the nodejs libraries that are needed. +The upstream Node.js stance on https://nodejs.org/en/blog/npm/npm-1-0-global-vs-local-installation/[global library packages] +is that they are ".. best avoided if not needed." +In Fedora, we take the same stance with our nodejs packages. +You can provide a package that uses nodejs, +but you should bundle all the nodejs libraries that are needed. == What to Package @@ -116,15 +120,30 @@ These tarballs store the contents of the module inside a `+package+` directory, == Using tarballs for bundling -It is prefered to use tarballs for bundling node module dependencies. These tarballs should be independent from the main package source. There should be two tarballs. One for the binary, runtime package. One for testing while the package builds. This creates a smaller installed package. +It is prefered to use tarballs for bundling node module dependencies. +These tarballs should be independent from the main package source. +There should be two tarballs. +One for the binary, runtime package. +One for testing while the package builds. +This creates a smaller installed package. -These tarballs store the bundled modules in a directory called node_modules_prod, and node_modules_dev. +These tarballs store the bundled modules in a directory called node_modules_prod, +and node_modules_dev. -If your packages does not need one of the tarballs, then change these instructions accordingly. If it does not need the prod tarball, remove `+Source1+` plus the `+%build+` and `+%install+` sections. If it does not need the dev tarball, remove `+Source2+` and the `+%check+` section. +If your packages does not need one of the tarballs, +then change these instructions accordingly. +If it does not need the prod tarball, +remove `+Source1+` plus the `+%build+` and `+%install+` sections. +If it does not need the dev tarball, +remove `+Source2+` and the `+%check+` section. -Note1: The setup of the prod and dev tarballs will soon become a macro. At the time of this writting, they are not. +Note1: The setup of the prod and dev tarballs will soon become a macro. +At the time of this writting, they are not. -Note2: The tarball with the dev dependencies needs to be unpacked in +%check+ and not in +%prep+ to avoid accidentally bundling the unpackaged dependencies that are only needed for testing. +Note2: The tarball with the dev dependencies needs to be unpacked in +%check+ +and not in +%prep+ +to avoid accidentally bundling the unpackaged dependencies +that are only needed for testing. .... ... @@ -175,8 +194,13 @@ Many node modules contain JavaScript that can be used both client-side and serve == Automatic Requires and Provides -The _nodejs_ package includes an automatic Requires and Provides generator that automatically adds versioned dependencies based on the information provided in a module's and bundled dependencies _package.json_ file. Additional Requires are added to native (binary) modules to protect against ABI breaks in Node or the V8 JavaScript runtime. Additional Provides: bundled() line is added for e - +The _nodejs_ package includes an automatic Requires and Provides generator +that automatically adds versioned dependencies +based on the information provided in a module's +and bundled dependencies _package.json_ file. +Additional Requires are added to native (binary) modules +to protect against ABI breaks in Node or the V8 JavaScript runtime. +Additional Provides: bundled() line is added for e === Provides npm diff --git a/guidelines/modules/ROOT/pages/OCaml.adoc b/guidelines/modules/ROOT/pages/OCaml.adoc index 02b2e9b..26db926 100644 --- a/guidelines/modules/ROOT/pages/OCaml.adoc +++ b/guidelines/modules/ROOT/pages/OCaml.adoc @@ -1,7 +1,10 @@ = OCaml Packaging Guidelines -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. +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 diff --git a/guidelines/modules/ROOT/pages/Octave.adoc b/guidelines/modules/ROOT/pages/Octave.adoc index 1208121..c40fb48 100644 --- a/guidelines/modules/ROOT/pages/Octave.adoc +++ b/guidelines/modules/ROOT/pages/Octave.adoc @@ -6,13 +6,15 @@ The definition from https://www.octave.org/[website] says: _"GNU Octave is a high-level language, primarily intended for numerical computations. It provides a convenient command line interface for solving linear and nonlinear problems numerically, and for performing other numerical experiments using a language that is mostly compatible with Matlab. It may also be used as a batch-oriented language."_ -If you are interested in packaging Octave packages, you should check here for upstream sources: +If you are interested in packaging Octave packages, +you should check here for upstream sources: * https://octave.sourceforge.io/[The Octave Forge website] == RPM macros -The following macros are defined in /etc/rpm/macros.octave in the octave 3.4.0 (Fedora 15+) package for help in packaging: +The following macros are defined in /etc/rpm/macros.octave in the octave 3.4.0 (Fedora 15+) package +for help in packaging: .... # Octave binary API provided @@ -46,7 +48,11 @@ The following macros are defined in /etc/rpm/macros.octave in the octave 3.4.0 ( === Naming of Octave packages -Packages of Octave packages have their own naming scheme. They should take into account the upstream name of the package. This makes a package name format of `+octave-$NAME+`. When in doubt, use the name of the module that you type to import it in octave. +Packages of Octave packages have their own naming scheme. +They should take into account the upstream name of the package. +This makes a package name format of `+octave-$NAME+`. +When in doubt, +use the name of the module that you type to import it in octave. '''Examples: ''' @@ -55,20 +61,26 @@ octave-java (Octave package named java) octave-gsl (Octave package named gsl) .... -Limitations in the pkg function of octave (pkg.m) means that versioning of octave packages requires that the package version must have a MAJOR.MINOR.MICRO format. Failing to use this format results in octave not recognising binary package components in %prefix/libexec. +Limitations in the pkg function of octave (pkg.m) means that versioning of octave packages requires that the package version must have a MAJOR.MINOR.MICRO format. +Failing to use this format results in octave not recognising binary package components in %prefix/libexec. === Updating the octave package database -Octave maintains a list of installed packages in /usr/share/octave/octave_packages that needs to be updated on package install and removal. This file is in an octave plain-text format. +Octave maintains a list of installed packages in /usr/share/octave/octave_packages +that needs to be updated on package install and removal. +This file is in an octave plain-text format. -The contents of the /usr/share/octave/packages/ directory are scanned for the following files when performing a pkg('rebuild') from within octave. +The contents of the /usr/share/octave/packages/ directory are scanned for the following files +when performing a pkg('rebuild') from within octave. * /usr/share/octave/packages/_NAMEOFPACKAGE_/packinfo/COPYING * /usr/share/octave/packages/_NAMEOFPACKAGE_/packinfo/DESCRIPTION -If these files are not present in any given _NAMEOFPACKAGE_ directory, then octave will silently skip the folder and fail to index it correctly. +If these files are not present in any given _NAMEOFPACKAGE_ directory, +then octave will silently skip the folder and fail to index it correctly. -Octave will use the contents of octave_packages to modify its path at startup, allowing octave to find plugins. +Octave will use the contents of octave_packages to modify its path at startup, +allowing octave to find plugins. === Documentation files diff --git a/guidelines/modules/ROOT/pages/PHP.adoc b/guidelines/modules/ROOT/pages/PHP.adoc index 8842f70..5e215d1 100644 --- a/guidelines/modules/ROOT/pages/PHP.adoc +++ b/guidelines/modules/ROOT/pages/PHP.adoc @@ -5,7 +5,8 @@ Fedora Packaging Guidelines for PHP addon modules [#types] == Different types of PHP packages -There are basically 4 different kinds of PHP modules, which are packaged for Fedora: +There are basically 4 different kinds of PHP modules, +which are packaged for Fedora: * https://pecl.php.net[PECL] (PHP Extension Community Library) modules, which are PHP modules usually written in C @@ -94,7 +95,8 @@ Please make sure that a pure PHP package (PEAR, packagist...) is correctly being built for `+noarch+`. As for other packages, -name should only use lowercase, underscore and slash replaced by dash. +name should only use lowercase, +underscore and slash replaced by dash. The `+PECLPackageName+` and the `+PEARPackageName+` should be consistent with the upstream naming scheme. diff --git a/guidelines/modules/ROOT/pages/PatchUpstreamStatus.adoc b/guidelines/modules/ROOT/pages/PatchUpstreamStatus.adoc index 6c5efdc..6d038ba 100644 --- a/guidelines/modules/ROOT/pages/PatchUpstreamStatus.adoc +++ b/guidelines/modules/ROOT/pages/PatchUpstreamStatus.adoc @@ -2,14 +2,20 @@ == 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: +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: .... # https://bugzilla.gnome.org/show_bug.cgi?id=12345 Patch: gnome-panel-fix-frobnicator.patch .... -The above is perfectly acceptable; but if you prefer, a brief comment about what the patch does above can be helpful: +The above is perfectly acceptable; +but if you prefer, +a brief comment about what the patch does above can be helpful: .... # Don't crash with frobnicator applet @@ -17,7 +23,8 @@ The above is perfectly acceptable; but if you prefer, a brief comment about what Patch: 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 https://docs.fedoraproject.org/en-US/package-maintainers/Staying_Close_to_Upstream_Projects/[Staying Close to Upstream Projects]). 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. +Sending patches upstream and adding this comment will help ensure that Fedora is acting as a good FLOSS citizen (see https://docs.fedoraproject.org/en-US/package-maintainers/Staying_Close_to_Upstream_Projects/[Staying Close to Upstream Projects]). +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 @@ -35,7 +42,8 @@ Patch: foobar-fix-the-baz.patch === Fedora-specific (or rejected upstream) patches -It may be that some patches truly are Fedora-specific; in that case, say so: +It may be that some patches truly are Fedora-specific; +in that case, say so: .... # This patch is temporary until we land the long term System.loadLibrary fix in OpenJDK diff --git a/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc b/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc index 1be3b02..a34f1fd 100644 --- a/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc +++ b/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc @@ -1,17 +1,20 @@ = Per-product Configuration Packaging In the Fedora.next world, -we have a set of curated Fedora Products as well as the availability of classic Fedora. +we have a set of curated Fedora Products +as well as the availability of classic Fedora. Historically, we have maintained a single set of configuration defaults for all Fedora installs, but different target use-cases have different needs. -The goal of this document -is to set out the guidelines for creating per-Product configuration defaults. +The goal of this document is to set out the guidelines +for creating per-Product configuration defaults. We want to ensure that all packages have sensible defaults for whichever Product on which they are installed, -while also avoiding situations where users would have some packages installed -with one Product's defaults and some packages with another. +while also avoiding situations +where users would have some packages installed +with one Product's defaults +and some packages with another. == Requirements diff --git a/guidelines/modules/ROOT/pages/Perl.adoc b/guidelines/modules/ROOT/pages/Perl.adoc index 831a54d..1a8767a 100644 --- a/guidelines/modules/ROOT/pages/Perl.adoc +++ b/guidelines/modules/ROOT/pages/Perl.adoc @@ -10,7 +10,8 @@ See https://docs.fedoraproject.org/en-US/legal/license-field/#_perl_packages[Lic == Directory Ownership -As specified in the xref:index.adoc#_file_and_directory_ownership[general Packaging Guidelines], Perl packages are expected to share ownership of certain directories. +As specified in the xref:index.adoc#_file_and_directory_ownership[general Packaging Guidelines], +Perl packages are expected to share ownership of certain directories. In general, a noarch Perl package must own: @@ -29,35 +30,65 @@ In general, a noarch Perl package must own: == Build Dependencies -As stated in xref:index.adoc#buildrequires[Packaging Guidelines: Build-Time Dependencies (BuildRequires)], a package must explicitly indicate its build dependencies (using `+BuildRequires:+`) outside of the minimal set required for RPM to build packages. This includes any dependency on Perl. While Perl may have been in the default buildroot at one time, this is not currently the case. +As stated in xref:index.adoc#buildrequires[Packaging Guidelines: Build-Time Dependencies (BuildRequires)], +a package must explicitly indicate its build dependencies (using `+BuildRequires:+`) +outside of the minimal set required for RPM to build packages. +This includes any dependency on Perl. +While Perl may have been in the default buildroot at one time, +this is not currently the case. Below is a list of Perl-related build dependencies you may need. -* `+perl-generators+` – Automatically generates run-time Requires and Provides for installed Perl files. Whenever you install a Perl script or a Perl module, you must include a build dependency on this package. +* `+perl-generators+` – Automatically generates run-time Requires and Provides for installed Perl files. + Whenever you install a Perl script or a Perl module, + you must include a build dependency on this package. -* `+perl-interpreter+` – The Perl interpreter must be listed as a build dependency if it is called in any way, either explicitly via `+perl+` or `+%__perl+`, or as part of your package's build system. +* `+perl-interpreter+` – The Perl interpreter must be listed as a build dependency if it is called in any way, + either explicitly via `+perl+` or `+%__perl+`, + or as part of your package's build system. -* `+perl-devel+` - Provides Perl header files. If building architecture-specific code which links to `+libperl.so+` library (e.g. an XS Perl module), you must include `+BuildRequires: perl-devel+`. +* `+perl-devel+` - Provides Perl header files. + If building architecture-specific code which links to `+libperl.so+` library (e.g. an XS Perl module), + you must include `+BuildRequires: perl-devel+`. -If a specific Perl module is required at build time, use `perl(__MODULE__)` syntax as documented above. This applies to so called _core_ modules as well, since they may move in and out of the base Perl package over time. +If a specific Perl module is required at build time, +use `perl(__MODULE__)` syntax as documented above. +This applies to so called _core_ modules as well, +since they may move in and out of the base Perl package over time. -If you need to limit your package to a specific Perl version, use `+perl(:VERSION)+` dependency with desired version constraint (e.g. `+perl(:VERSION) >= 5.22+`). Do not use a comparison against the version of the `+perl+` package because it includes an epoch number, which makes version comparisons tricky. +If you need to limit your package to a specific Perl version, +use `+perl(:VERSION)+` dependency with desired version constraint (e.g. `+perl(:VERSION) >= 5.22+`). +Do not use a comparison against the version of the `+perl+` package because it includes an epoch number, +which makes version comparisons tricky. == Perl Requires and Provides -Perl packages use the virtual `+perl(Foo)+` naming to indicate a given Perl module. Packages should use this methodology, and not require the package name directly. For example, a package requiring the Perl module Readonly should not explicitly require `+perl-Readonly+`, but rather `+perl(Readonly)+`, which the `+perl-Readonly+` package provides. +Perl packages use the virtual `+perl(Foo)+` naming to indicate a given Perl module. +Packages should use this methodology, and not require the package name directly. +For example, a package requiring the Perl module Readonly should not explicitly require `+perl-Readonly+`, +but rather `+perl(Readonly)+`, which the `+perl-Readonly+` package provides. It is recommended to include explicit dependencies for core modules, because they can move between sub-packages or disappear from core Perl. === Versioned MODULE_COMPAT_ Requires or `+perl-libs+` -Packages with Perl modules installed in %\{perl_vendorarch}, %\{perl_vendorlib}, %\{perl_privlib} or %\{perl_archlib} will automatically gain dependency on `+perl-libs+` for pure Perl modules or a dependency on `+perl(:MODULE_COMPAT_)+` for libraries with compiled code. The dependency is handled by `+perl-generators+`. +Packages with Perl modules installed in %\{perl_vendorarch}, %\{perl_vendorlib}, %\{perl_privlib} or %\{perl_archlib} +will automatically gain dependency on `+perl-libs+` for pure Perl modules +or a dependency on `+perl(:MODULE_COMPAT_)+` for libraries with compiled code. +The dependency is handled by `+perl-generators+`. -Packages that require the Perl interpreter or `+libperl.so+` but do not install modules to the aforementioned directories or explicitly link to `+libperl.so.+` need to handle the dependency manually. +Packages that require the Perl interpreter or `+libperl.so+` +but do not install modules to the aforementioned directories +or explicitly link to `+libperl.so.+` +need to handle the dependency manually. === Filtering Requires and Provides -RPM's dependency generator can often throw in additional dependencies and will often think packages provide functionality contrary to reality. To fix this, the dependency generator needs to be overridden so that the additional dependencies can be filtered out. Please see xref:AutoProvidesAndRequiresFiltering.adoc#_perl[Packaging Guidelines: Automatic Filtering of Provides and Requires - Perl] for information. +RPM's dependency generator can often throw in additional dependencies +and will often think packages provide functionality contrary to reality. +To fix this, the dependency generator needs to be overridden +so that the additional dependencies can be filtered out. +Please see xref:AutoProvidesAndRequiresFiltering.adoc#_perl[Packaging Guidelines: Automatic Filtering of Provides and Requires - Perl] for information. === Manual Requires and Provides @@ -71,7 +102,9 @@ use base 'Class::Accessor::Fast'; use base 'Class::Accessor'; .... -A tell-tale sign of this particular construct is that the package contains a dependency on `+perl(base)+`, but this is not the only situation in which dependencies can be missed. This package needed additional dependencies as follows: +A tell-tale sign of this particular construct is that the package contains a dependency on `+perl(base)+`, +but this is not the only situation in which dependencies can be missed. +This package needed additional dependencies as follows: .... Requires: perl(Class::Accessor), perl(Class::Accessor::Fast) @@ -88,7 +121,10 @@ use autouse 'Date::Calc' => qw(Delta_DHMS Decode_Date_EU Decode_Date_US); use autouse 'Date::Manip' => qw(ParseDate Date_Init); .... -Similarly, it possible to miss Provides:, as was the case in https://bugzilla.redhat.com/167797[Bug #167797] , where the `+perl-DBD-Pg+` package failed to Provide: `+perl(DBD::Pg)+` due to the following construct in `+DBD::Pg+` version 1.43: +Similarly, it possible to miss Provides:, +as was the case in https://bugzilla.redhat.com/167797[Bug #167797] , +where the `+perl-DBD-Pg+` package failed to Provide: `+perl(DBD::Pg)+` +due to the following construct in `+DBD::Pg+` version 1.43: .... { package DBD::Pg; diff --git a/guidelines/modules/ROOT/pages/Pkcs11Support.adoc b/guidelines/modules/ROOT/pages/Pkcs11Support.adoc index a7022ae..9355c6a 100644 --- a/guidelines/modules/ROOT/pages/Pkcs11Support.adoc +++ b/guidelines/modules/ROOT/pages/Pkcs11Support.adoc @@ -1,10 +1,26 @@ = PKCS#11 / Smart-Card Support Guidelines -These guidelines are relevant to maintainers of packages with smart cards drivers (PKCS#11 modules), or smart card related tooling. Its purpose is to bring a consistency in smart card handling on the OS; for background and motivation see the https://fedoraproject.org/wiki/User:Nmav/Pkcs11Status[current status of PKCS#11 in Fedora]. +These guidelines are relevant to maintainers of packages with smart cards drivers (PKCS#11 modules), +or smart card related tooling. +Its purpose is to bring a consistency in smart card handling on the OS; +for background and motivation see the https://fedoraproject.org/wiki/User:Nmav/Pkcs11Status[current status of PKCS#11 in Fedora]. == Registering the modules system-wide -Any package in Fedora containing a PKCS#11 provider module, intended to be used outside this package, MUST be registered with https://p11-glue.github.io/p11-glue/[p11-kit]. For example, the https://github.com/OpenSC/OpenSC/wiki[OpenSC] module 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. The appropriate place in Fedora can be obtained with `+pkg-config p11-kit-1 --variable p11_module_configs+` or `+%{_datadir}/p11-kit/modules/+`. The dropped file should have the `.module` suffix and should contain something similar to the contents below (which is the opensc example). +Any package in Fedora containing a PKCS#11 provider module, +intended to be used outside this package, +MUST be registered with https://p11-glue.github.io/p11-glue/[p11-kit]. +For example, +the https://github.com/OpenSC/OpenSC/wiki[OpenSC] module 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. +The appropriate place in Fedora can be obtained with `+pkg-config p11-kit-1 --variable p11_module_configs+` +or `+%{_datadir}/p11-kit/modules/+`. +The dropped file should have the `.module` suffix +and should contain something similar to the contents below +(which is the opensc example). # This file describes how to load the opensc module # See: https://p11-glue.freedesktop.org/doc/p11-kit/config.html @@ -15,7 +31,9 @@ Any package in Fedora containing a PKCS#11 provider module, intended to be used # 32-bit and 64-bit and make them parallel installable module: opensc-pkcs11.so -The provider module, as mentioned in the example below should be installed at `+%{_libdir}/pkcs11/+`. +The provider module, +as mentioned in the example below +should be installed at `+%{_libdir}/pkcs11/+`. Once a module is registered the tokens/HSMs provided by it should be listed in the `p11tool` output using the following command: @@ -27,19 +45,37 @@ The packages SHOULD NOT provide the package config `*.pc` files for the PKCS#11 [#registered] == How applications take advantage of registered provider modules -Packages which can potentially 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. That can be done by applications using the p11-kit library to get the list of modules, or by applications defaulting to the p11-kit proxy module (`+%{_libdir}/p11-kit-proxy.so+`), if no PKCS#11 provider module was specified by the user. The proxy module, is a single module wrapping all available registered modules. +Packages which can potentially 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. +That can be done by applications using the p11-kit library to get the list of modules, +or by applications defaulting to the p11-kit proxy module (`+%{_libdir}/p11-kit-proxy.so+`), +if no PKCS#11 provider module was specified by the user. +The proxy module, +is a single module wrapping all available registered modules. [#specify-card] == How to specify a specific smart card/HSM -https://tools.ietf.org/html/rfc7512[RFC7512] defines a 'PKCS#11 URI' as a standard way to identify tokens and objects. Fedora follows this standard and applications which refer to tokens such as smart cards or HSMs, must use -RFC7512 to refer to them. Note that an application must not require the '''module-name''' and '''module-path''' URI elements. Compliant with this policy applications should resolve URIs which do not contain these elements based [[#Registered|on the registered provider modules]]. Applications must not require the "slot" attribute, nor print it, since it is an esoteric PKCS#11 module implementation information that has no meaning for the end-user, and in several modules its value is not guaranteed to be unique (and may change for example after system reboot). +https://tools.ietf.org/html/rfc7512[RFC7512] defines a 'PKCS#11 URI' as a standard way to identify tokens and objects. +Fedora follows this standard and applications which refer to tokens such as smart cards or HSMs, +must use RFC7512 to refer to them. +Note that an application must not require the '''module-name''' and '''module-path''' URI elements. +Compliant with this policy applications should resolve URIs which do not contain these elements based [[#Registered|on the registered provider modules]]. +Applications must not require the "slot" attribute, +nor print it, +since it is an esoteric PKCS#11 module implementation information that has no meaning for the end-user, +and in several modules its value is not guaranteed to be unique +(and may change for example after system reboot). [#specify-object] == How to specify an object stored in a smart card/HSM -https://tools.ietf.org/html/rfc7512[RFC7512] defines a 'PKCS#11 URI' as a standard way to identify tokens and objects. Fedora follows this standard and applications which refer to objects stored in smart cards or HSMs, must use RFC7512 to refer to certificates and private keys. +https://tools.ietf.org/html/rfc7512[RFC7512] defines a 'PKCS#11 URI' as a standard way to identify tokens and objects. +Fedora follows this standard and applications which refer to objects stored in smart cards or HSMs, +must use RFC7512 to refer to certificates and private keys. -In particular when PKCS#11 objects are specified in a textual form which is visible to the user ''(e.g. on the command line or in a config file)'', objects SHOULD be specified in the form of a PKCS#11 URI as as described in https://tools.ietf.org/html/rfc7512[RFC7512]. +In particular when PKCS#11 objects are specified in a textual form which is visible to the user ''(e.g. on the command line or in a config file)'', +objects SHOULD be specified in the form of a PKCS#11 URI as as described in https://tools.ietf.org/html/rfc7512[RFC7512]. -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'`. +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'`. diff --git a/guidelines/modules/ROOT/pages/PkgConfigBuildRequires.adoc b/guidelines/modules/ROOT/pages/PkgConfigBuildRequires.adoc index 22ba4e9..541bbd8 100644 --- a/guidelines/modules/ROOT/pages/PkgConfigBuildRequires.adoc +++ b/guidelines/modules/ROOT/pages/PkgConfigBuildRequires.adoc @@ -1,16 +1,26 @@ = BuildRequires: pkgconfig(foo) vs. foo-devel -Fedora packages which use `+pkg-config+` to build against a library (e.g. 'foo') on which they depend, *SHOULD* express their build dependency correctly as `+pkgconfig(foo)+`. +Fedora packages which use `+pkg-config+` to build against a library (e.g. 'foo') on which they depend, +*SHOULD* express their build dependency correctly as `+pkgconfig(foo)+`. == Rationale -The build infrastructure for a given package will often locate and use required libraries by using `+pkg-config+`. +The build infrastructure for a given package will often locate and use required libraries +by using `+pkg-config+`. -Thus, `+pkgconfig(foo)+` is the true statement of the build dependency, and is how it should be expressed in the spec file. +Thus, `+pkgconfig(foo)+` is the true statement of the build dependency, +and is how it should be expressed in the spec file. -For historical reasons, many packages seem to have a hard-coded "`+BuildRequires: foo-devel+`", with the name of the package which _currently_ provides the required pkgconfig module. This is fragile and less portable than simply expressing the real dependency. Where package names change, and/or a required pkgconfig module is later provided by a _different_ package, these hard-coded dependencies break. +For historical reasons, +many packages seem to have a hard-coded "`+BuildRequires: foo-devel+`", +with the name of the package which _currently_ provides the required pkgconfig module. +This is fragile and less portable than simply expressing the real dependency. +Where package names change, +and/or a required pkgconfig module is later provided by a _different_ package, +these hard-coded dependencies break. -Note that it shall still be acceptable to require specific packages by name if they are required for some reason _other_ than a `+pkg-config+` module that they provide. +Note that it shall still be acceptable to require specific packages by name +if they are required for some reason _other_ than a `+pkg-config+` module that they provide. == Example @@ -26,4 +36,8 @@ BuildRequires: pkgconfig(libproxy-1.0) BuildRequires: libproxy-devel .... -This way, if the `+libproxy-1.0.pc+` pkgconfig module is ever provided from a differently-named package (such as by PacRunner once its integration is complete, or by a '`+libproxy1+`' backward-compatibility package as has happened to a number of other libraries in the past), the dependency will continue to be correct. +This way, +if the `+libproxy-1.0.pc+` pkgconfig module is ever provided from a differently-named package +(such as by PacRunner once its integration is complete, +or by a '`+libproxy1+`' backward-compatibility package as has happened to a number of other libraries in the past), +the dependency will continue to be correct. diff --git a/guidelines/modules/ROOT/pages/Python_Appendix.adoc b/guidelines/modules/ROOT/pages/Python_Appendix.adoc index 01d4631..1eb6713 100644 --- a/guidelines/modules/ROOT/pages/Python_Appendix.adoc +++ b/guidelines/modules/ROOT/pages/Python_Appendix.adoc @@ -1,7 +1,8 @@ = Additional Python Guidelines :last-reviewed: 2020-01-01 -Here are some additional Python-related guidelines, moved here in order to keep the main page manageable. +Here are some additional Python-related guidelines, +moved here in order to keep the main page manageable. [#manual-bytecompilation] == Manual byte compilation @@ -10,7 +11,11 @@ NOTE: This section only applies for the 201x-era guidelines. In the new guidelines, see the xref:Python.adoc#manual-bytecompilation[Manual byte compilation] section. -When byte compiling a .py file, python embeds a magic number in the byte compiled files that correspond to the runtime. Files in `+%{python?_sitelib}+` and `+%{python?_sitearch}+` MUST correspond to the runtime for which they were built. For instance, a pure Python module compiled for the 3.4 runtime MUST be below `+%{_usr}/lib/python3.4/site-packages+` +When byte compiling a .py file, +python embeds a magic number in the byte compiled files that correspond to the runtime. +Files in `+%{python?_sitelib}+` and `+%{python?_sitearch}+` MUST correspond to the runtime for which they were built. +For instance, +a pure Python module compiled for the 3.4 runtime MUST be below `+%{_usr}/lib/python3.4/site-packages+` The `+brp-python-bytecompile+` script tries to figure this out for you. The script determines which interpreter to use when byte compiling the module @@ -26,7 +31,8 @@ and you require those files to be byte compiled (e.g. it's an importable Python module) you MUST compile them explicitly using the `+%py_byte_compile+` macro. Note that not all Python files are importable Python modules; -when in doubt, grep the sources for the appropriate import statement. +when in doubt, +grep the sources for the appropriate import statement. An example for a package that has both Python versions: @@ -53,15 +59,26 @@ the macro will recursively byte compile any *.py file in the directory. == Manual byte compilation for EPEL 6 and 7 -The script interpreter defined in `+%{__python}+` is used to compile the modules outside of `+/usr/lib(64)?/pythonX.Y/+` directories. This defaults to `+/usr/bin/python+` (that's Python 2.6 or on EPEL 6 and 2.7 on EPEL 7). If you need to compile the modules for python3, set it to `+/usr/bin/python3+` instead: +The script interpreter defined in `+%{__python}+` is used to compile the modules outside of `+/usr/lib(64)?/pythonX.Y/+` directories. +This defaults to `+/usr/bin/python+` (that's Python 2.6 or on EPEL 6 and 2.7 on EPEL 7). +If you need to compile the modules for python3, +set it to `+/usr/bin/python3+` instead: .... %global __python %{python3} .... -Doing this is useful when you have a python3 application that's installing a private module into its own directory. For instance, if the foobar application installs a module for use only by the command line application in `+%{_datadir}/foobar+`. Since these files are not in one of the python3 library paths (i.e., `+/usr/lib/python3.6+`) you have to override `+%{__python}+` to tell `+brp-python-bytecompile+` to use the python3 interpreter for byte compiling. +Doing this is useful when you have a python3 application that's installing a private module into its own directory. +For instance, +if the foobar application installs a module for use only by the command line application in `+%{_datadir}/foobar+`. +Since these files are not in one of the python3 library paths (i.e., `+/usr/lib/python3.6+`) +you have to override `+%{__python}+` to tell `+brp-python-bytecompile+` to use the python3 interpreter for byte compiling. -These settings are enough to properly byte compile any package that builds Python modules in `+%{python?_sitelib}+` or `+%{python?_sitearch}+` or builds for only a single Python interpreter. However, if the application you're packaging needs to build with both python2 and python3 and install into a private module directory (perhaps because it provides one utility written in python2 and a second utility written in python3) then you need to do this manually. Here's a sample spec file snippet that shows what to do: +These settings are enough to properly byte compile any package that builds Python modules in `+%{python?_sitelib}+` or `+%{python?_sitearch}+` or builds for only a single Python interpreter. +However, if the application you're packaging needs to build with both python2 and python3 and install into a private module directory +(perhaps because it provides one utility written in python2 and a second utility written in python3) +then you need to do this manually. +Here's a sample spec file snippet that shows what to do: .... # Turn off the brp-python-bytecompile script @@ -92,11 +109,14 @@ For two Python files with the exact same content and metadata, byte compilation might produce different results. The resulting `.pyc` files are functionally identical but are not bit-by-bit identical. In most cases, -internal Python reference counter is here to blame because it might have a different internal state during each byte compilation. +internal Python reference counter is here to blame +because it might have a different internal state during each byte compilation. If you want a deeper explanation, take a look at https://bugzilla.redhat.com/show_bug.cgi?id=1686078#c2[this Bugzilla comment]. -This inconvenience might cause a problem in Koji where noarch packages built as a part of an arch build might be rejected because they have different content. +This inconvenience might cause a problem in Koji +where noarch packages built as a part of an arch build +might be rejected because they have different content. To work around this issue, BuildRequire marshalparser `BuildRequires: /usr/bin/marshalparser` diff --git a/guidelines/modules/ROOT/pages/R.adoc b/guidelines/modules/ROOT/pages/R.adoc index 2b470b2..012b73d 100644 --- a/guidelines/modules/ROOT/pages/R.adoc +++ b/guidelines/modules/ROOT/pages/R.adoc @@ -6,9 +6,11 @@ The definition from https://www.r-project.org/[The R-Project website] says that _" R is a language and environment for statistical computing and graphics."_ -R is a GNU project, very similar to the S language developed by Bell Laboratories. +R is a GNU project, +very similar to the S language developed by Bell Laboratories. -This language is heavily used in research as it provides a lot of statistical and graphical tools. +This language is heavily used in research +as it provides a lot of statistical and graphical tools. It is also a well developed language for data manipulation. If you are looking for more information on R, you can go to: @@ -16,7 +18,9 @@ If you are looking for more information on R, you can go to: * https://www.r-project.org/[The R-Project website] * https://cran.r-project.org/doc/manuals/R-intro.html[An introduction to R] -If you are interested in packaging R modules, or if you are looking for R libraries, you should check here for upstream sources: +If you are interested in packaging R modules, +or if you are looking for R libraries, +you should check here for upstream sources: * https://www.bioconductor.org/[The bioconductor website] * https://cran.r-project.org/[The CRAN website] @@ -27,7 +31,8 @@ If you are interested in packaging R modules, or if you are looking for R librar There are two types of R packages: arch-specific and noarch. The following template shows how to package an arch-specific R package; -there are very minor differences for noarch packages, which are noted below the template. +there are very minor differences for noarch packages, +which are noted below the template. .... %global packname foo @@ -85,17 +90,23 @@ rm -f %{buildroot}%{rlibdir}/R.css * Noarch packages set `+BuildArch: noarch+`. * Noarch packages install into `+%{_datadir}/R/library/%{packname}+`; arch-specific packages install into `+%{_libdir}/R/library/%{packname}+`. + - Change the `+%global rlibdir+` at the top of the file to use `+%{_datadir}+` instead of `+%{_libdir}+`. + Change the `+%global rlibdir+` at the top of the file + to use `+%{_datadir}+` instead of `+%{_libdir}+`. === R2spec -R2spec is an excellent little tool to assist in creating Fedora-compliant packages for R libraries. Using it as a starting point is recommended (but certainly not mandated). +R2spec is an excellent little tool to assist in creating Fedora-compliant packages +for R libraries. +Using it as a starting point is recommended +(but certainly not mandated). More information here : https://pagure.io/r2spec/ == Automatically generated dependencies -All R packages that depend on `+R-devel+` will automatically produce Provides, Requires, Suggests, and Enhances via a generator in `+R-rpm-macros+`. -This generator uses upstream metadata in `+DESCRIPTION+` files to determine what the package should depend on. +All R packages that depend on `+R-devel+` will automatically produce Provides, Requires, Suggests, and Enhances +via a generator in `+R-rpm-macros+`. +This generator uses upstream metadata in `+DESCRIPTION+` files +to determine what the package should depend on. === Provides with a standardized name @@ -134,7 +145,11 @@ _and_ you need to escape said backslash for RPM. === Naming of R packages -Packages of R modules (thus they rely on R as a parent) have their own naming scheme. They should take into account the upstream name of the R module. This makes a package name format of `+R-$NAME+`. When in doubt, use the name of the module that you type to import it in R. +Packages of R modules (thus they rely on R as a parent) have their own naming scheme. +They should take into account the upstream name of the R module. +This makes a package name format of `+R-$NAME+`. +When in doubt, +use the name of the module that you type to import it in R. ==== Examples @@ -146,9 +161,13 @@ R-waveslim (R module named waveslim) === R version -Many R packages contain '-' in their version. Usually, the versioning used is a sequence of at least two (and usually three) non-negative integers separated by single '.' or '-' characters. +Many R packages contain '-' in their version. +Usually, the versioning used is a sequence of at least two (and usually three) +non-negative integers +separated by single '.' or '-' characters. -To be consistent with the versioning system used in Fedora, you should simply replace dashes with dots. +To be consistent with the versioning system used in Fedora, +you should simply replace dashes with dots. ==== Example @@ -159,11 +178,19 @@ Fedora Version: 0.5.8 === Empty %build section -Unlike normal Fedora packages, there is normally no separate `+%build+` actions (e.g. `+%configure+`)that need to be taken for an R package. However, it is important that all R module packages include an empty `+%build+` section, as shown in the spec templates. +Unlike normal Fedora packages, +there is normally no separate `+%build+` actions +(e.g. `+%configure+`) +that need to be taken for an R package. +However, it is important that all R module packages include an empty `+%build+` section, +as shown in the spec templates. === Installing the R addon bits -Instead of calling make install, to install the R addon components, you need to run `+R CMD INSTALL -l %{buildroot}%{_datadir}/R/library %{packname}+` (noarch) or `+R CMD INSTALL -l %{buildroot}%{_libdir}/R/library %{packname}+` (arch-specific). Proper `+%install+` sections for Fedora R packages are demonstrated in the spec templates. +Instead of calling make install, to install the R addon components, +you need to run `+R CMD INSTALL -l %{buildroot}%{_datadir}/R/library %{packname}+` (noarch) +or `+R CMD INSTALL -l %{buildroot}%{_libdir}/R/library %{packname}+` (arch-specific). +Proper `+%install+` sections for Fedora R packages are demonstrated in the spec templates. === Deleting the R.css file @@ -174,7 +201,9 @@ You must delete this file, and do not include it in your package. === Cleaning the R directory of binaries -It is important to clean the R directory of binary files (`+*.o *.so+`) before running `+R CMD CHECK+`. Otherwise, the CHECK command will throw a warning about finding binaries in the source dir. This is accomplished by running (in `+%install+`): +It is important to clean the R directory of binary files (`+*.o *.so+`) before running `+R CMD CHECK+`. +Otherwise, the CHECK command will throw a warning about finding binaries in the source dir. +This is accomplished by running (in `+%install+`): .... test -d %{packname}/src && (cd %{packname}/src; rm -f *.o *.so) @@ -191,23 +220,44 @@ Most (if not all) R addon modules come with a built-in check. This can be trigge %{_bindir}/R CMD check %{packname} .... -Note that frequently, R packages have circular dependency loops when running `+R CMD check+`. If you hit such a case, you can comment out the check to break the dependency loop, and leave a comment explaining the circular dependency problem. +Note that frequently, +R packages have circular dependency loops when running `+R CMD check+`. +If you hit such a case, +you can comment out the check to break the dependency loop, +and leave a comment explaining the circular dependency problem. === Documentation files -The `+R CMD INSTALL+` operation will install all of the files, including documentation files. The doc, html and NEWS files/directories need to be marked as `+%doc+`. -Note that other files, such as DESCRIPTION, INDEX, NAMESPACE, and help/ are not `+%doc+`, since proper R functionality depends on their presence. Be careful not to duplicate `+%doc+` files in the package, the spec templates provide good examples on how to package the R addon files without duplications. +The `+R CMD INSTALL+` operation will install all of the files, +including documentation files. +The doc, html and NEWS files/directories need to be marked as `+%doc+`. +Note that other files, +such as DESCRIPTION, INDEX, NAMESPACE, and help/ are not `+%doc+`, +since proper R functionality depends on their presence. +Be careful not to duplicate `+%doc+` files in the package, +the spec templates provide good examples on how to package the R addon files +without duplications. ==== R documentation -R documentation is written in TeX. rpmlint sometimes complains that these TeX files are not utf-8 files, but the encoding is normally specified in the file when needed, so this error is safe to ignore (and you should not try to re-encode the files). +R documentation is written in TeX. +rpmlint sometimes complains that these TeX files are not utf-8 files, +but the encoding is normally specified in the file when needed, +so this error is safe to ignore (and you should not try to re-encode the files). === Optimization flags -R packages inherit their optimization flags from the main R package, which stores them in `+%{_libdir}/R/etc/Makeconf+`. The design of R is such that all R addon library modules use the same optimization flags that the main R package was built with. Accordingly, this is why R addon packages do not pass `+%{optflags}+`. Also, there is no simple way to pass special optimization flags to `+R CMD INSTALL+`. +R packages inherit their optimization flags from the main R package, +which stores them in `+%{_libdir}/R/etc/Makeconf+`. +The design of R is such that all R addon library modules use the same optimization flags +that the main R package was built with. +Accordingly, this is why R addon packages do not pass `+%{optflags}+`. +Also, there is no simple way to pass special optimization flags to `+R CMD INSTALL+`. === R headers -R packages usually expect to find their header files in `+%{_libdir}/R/library/*/+`. rpmlint will complain that these files are misplaced, but this is safe to ignore. +R packages usually expect to find their header files in `+%{_libdir}/R/library/*/+`. +rpmlint will complain that these files are misplaced, +but this is safe to ignore. You should still separate these header files into a -devel subpackage. diff --git a/guidelines/modules/ROOT/pages/RPMMacros.adoc b/guidelines/modules/ROOT/pages/RPMMacros.adoc index 65293ef..075defc 100644 --- a/guidelines/modules/ROOT/pages/RPMMacros.adoc +++ b/guidelines/modules/ROOT/pages/RPMMacros.adoc @@ -5,12 +5,14 @@ RPM provides a rich set of macros to make package maintenance simpler and consistent across packages. -For example, it includes a list of default path definitions +For example, +it includes a list of default path definitions which are used by the build system macros, and definitions for RPM package build specific directories. They usually should be used instead of hard-coded directories. It also provides the default set of compiler flags as macros, -which should be used when compiling manually and not relying on a build system. +which should be used when compiling manually +and not relying on a build system. == Getting and setting Macros on the command line diff --git a/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc b/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc index 8942283..34481b3 100644 --- a/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc +++ b/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc @@ -53,7 +53,9 @@ for i in $(cat %{SOURCE1000}) ; do done .... -where `+Source1000: subdirs-kde-l10n+` is a list provided by upstream of all the languages supported, -and there are ~50 `+SourceN:+` tags, which can vary from version from version, +where `+Source1000: subdirs-kde-l10n+` is a list provided by upstream +of all the languages supported, +and there are ~50 `+SourceN:+` tags, +which can vary from version from version, but match the languages listed in `+Source1000+`, for the tarballs provided by upstream. diff --git a/guidelines/modules/ROOT/pages/Ruby.adoc b/guidelines/modules/ROOT/pages/Ruby.adoc index c1ddbc3..bddc980 100644 --- a/guidelines/modules/ROOT/pages/Ruby.adoc +++ b/guidelines/modules/ROOT/pages/Ruby.adoc @@ -1,15 +1,13 @@ = Ruby Packaging Guidelines NOTE: *JRuby Gems*: -Although Fedora has fully functioning JRuby -integrated with system RubyGems, +Although Fedora has fully functioning JRuby integrated with system RubyGems, we have decided to not include the JRuby specific packaging guidelines here, as they need some more work. They will appear here as soon as we feel that we've got everything covered properly. You can contact us on https://lists.fedoraproject.org/archives/list/ruby-sig@lists.fedoraproject.org/[Ruby-SIG mailing list] -in case of any questions -about the prepared JRuby packaging guidelines. +in case of any questions about the prepared JRuby packaging guidelines. There are three basic categories of ruby packages: <>, @@ -40,7 +38,10 @@ Requires: ruby(release) >= 1.9.1 NOTE: *Alternate interpreters*: Alternate Ruby interpreters (currently JRuby) also `Provide: ruby(release)`. -This implies, that pure RubyGems packages (these are shared among interpreters) SHOULD NOT have `Requires: ruby` or `Requires: jruby` to have their dependencies satisfied by any of these interpreters. +This implies, +that pure RubyGems packages (these are shared among interpreters) +SHOULD NOT have `Requires: ruby` or `Requires: jruby` +to have their dependencies satisfied by any of these interpreters. WARNING: *Over specified ruby(release) versioning*: Please note that if the `ruby(release)` version requirement is too specific, diff --git a/guidelines/modules/ROOT/pages/SSLCertificateHandling.adoc b/guidelines/modules/ROOT/pages/SSLCertificateHandling.adoc index c73badc..ef449ec 100644 --- a/guidelines/modules/ROOT/pages/SSLCertificateHandling.adoc +++ b/guidelines/modules/ROOT/pages/SSLCertificateHandling.adoc @@ -1,11 +1,23 @@ = Certificate Handling Guidelines -These guidelines are relevant to maintainers of packages which utilize smart cards for loading certificate or private key. Its purpose is to bring a consistency in smart card handling on the OS; for background and motivation see the link:https://fedoraproject.org/wiki/User:Nmav/Pkcs11Status[current status of PKCS#11 in Fedora]. +These guidelines are relevant to maintainers of packages which utilize smart cards for loading certificate or private key. +Its purpose is to bring a consistency in smart card handling on the OS; +for background and motivation see the +link:https://fedoraproject.org/wiki/User:Nmav/Pkcs11Status[current status of PKCS#11 in Fedora]. == How to specify a certificate or private key stored in a smart card or HSM -In April 2015, link:https://tools.ietf.org/html/rfc7512[RFC7512] defined a 'PKCS#11 URI' as a standard way to identify objects stored in smart cards or HSMs. That form should be understood by programs when specified in place of a certificate file. For non-interactive applications which get information on the command line or configuration file, there should not be a separate configuration option to load keys and certificates stored in smart cards, the same option accepting files, should additionally accept PKCS#11 URIs. +In April 2015, +link:https://tools.ietf.org/html/rfc7512[RFC7512] +defined a 'PKCS#11 URI' as a standard way to identify objects stored in smart cards or HSMs. +That form should be understood by programs when specified in place of a certificate file. +For non-interactive applications which get information on the command line or configuration file, +there should not be a separate configuration option to load keys and certificates stored in smart cards, +the same option accepting files, +should additionally accept PKCS#11 URIs. == How to specify a specific PKCS#11 provider module for the certificate or key -Packages which can potentially 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. See xref:Pkcs11Support.adoc[the PKCS#11 packaging page] for more information. +Packages which can potentially 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. +See xref:Pkcs11Support.adoc[the PKCS#11 packaging page] for more information. diff --git a/guidelines/modules/ROOT/pages/ScriptletsGConf.adoc b/guidelines/modules/ROOT/pages/ScriptletsGConf.adoc index b7e6c10..c4bc6a5 100644 --- a/guidelines/modules/ROOT/pages/ScriptletsGConf.adoc +++ b/guidelines/modules/ROOT/pages/ScriptletsGConf.adoc @@ -29,7 +29,8 @@ with the gconf daemon on installation and unregister them on removal. Due to the ordering of the scriptlets, this is a four step process. -Disabling the GConf installation during the package creation can be done like so: +Disabling the GConf installation during the package creation can be done +like so: [source,rpm-spec] ---- @@ -108,7 +109,8 @@ that the package currently installs just like `+%gconf_schema_prepare+`. Behind the scenes, it does the actual work of registering the new version of the schema and deregistering the old version. -The last section is for unregistering schemas when a package is removed: +The last section is for unregistering schemas +when a package is removed: [source,rpm-spec] ---- diff --git a/guidelines/modules/ROOT/pages/SourceURL.adoc b/guidelines/modules/ROOT/pages/SourceURL.adoc index 28903e8..5c67e37 100644 --- a/guidelines/modules/ROOT/pages/SourceURL.adoc +++ b/guidelines/modules/ROOT/pages/SourceURL.adoc @@ -1,7 +1,8 @@ = Referencing Source One of the design goals of rpm is to cleanly separate upstream source from vendor modifications. -For the Fedora packager, this means that sources used to build a package should be the vanilla sources available from upstream. +For the Fedora packager, +this means that sources used to build a package should be the vanilla sources available from upstream. To help reviewers and QA scripts verify this, the packager needs to indicate where a reviewer can find the source that was used to make the rpm. @@ -26,16 +27,16 @@ This ensures the smallest source rpm to save space on the mirrors and downloads == Using Forges (Hosted Revision Control) -Any software publishing website, permitting the download of source archives via normalized URLs, -that can be deduced from a project root URL and version, commit, tag, scm, extension… values is a _“forge”_ -that can be supported by the `redhat-rpm-config` `+%{forgemeta}+` macro. +Any software publishing website, +permitting the download of source archives via normalized URLs, +that can be deduced from a project root URL and version, commit, tag, scm, extension… values +is a _“forge”_ that can be supported by the `redhat-rpm-config` `+%{forgemeta}+` macro. Common Forge examples are _GitLab_ and _GitHub_. `+%{forgemeta}+` centralizes and abstracts our knowledge about those forges, so packagers do not have to handle download quirks manually. `+%{forgemeta}+` makes it easy to switch from release to tag to commit source archives. -Using `+%{forgemeta}+`, -forge download URLs or guideline changes are propagated to spec files without manual refactoring. +Using `+%{forgemeta}+`, forge download URLs or guideline changes are propagated to spec files without manual refactoring. When those changes result in a different naming or structure of the source archive, the source file needs to be uploaded to the build system before rebuilding existing spec files. @@ -87,7 +88,8 @@ include::{examplesdir}/spectemplate-forge-multi.spec[] In some cases you may want to pull sources from upstream's revision control system because there have been many changes since the last release -and you think that a tarball that you generate from there will more accurately show how the package relates to upstream's development. +and you think that a tarball that you generate from there will more accurately show +how the package relates to upstream's development. Here's how you can use a comment to show where the source came from: .... @@ -106,7 +108,8 @@ In particular, check the section on xref:Versioning.adoc#_complex_versioning[Com == When Upstream uses Prohibited Code Some upstream packages include patents or trademarks that we are not allowed to ship even as source code. -In these cases you have to modify the source tarball to remove this code before you even upload it to the build system. +In these cases you have to modify the source tarball to remove this code +before you even upload it to the build system. Here's an example of using a script to document how you went from the upstream tarball to the one included in the package: From the spec: diff --git a/guidelines/modules/ROOT/pages/SugarActivityGuidelines.adoc b/guidelines/modules/ROOT/pages/SugarActivityGuidelines.adoc index 0c3559c..21478fb 100644 --- a/guidelines/modules/ROOT/pages/SugarActivityGuidelines.adoc +++ b/guidelines/modules/ROOT/pages/SugarActivityGuidelines.adoc @@ -1,6 +1,7 @@ = Sugar Activity Packaging Guidelines -These guidelines are for packaging Sugar activities. http://wiki.laptop.org/go/Sugar[Sugar] is the core of the OLPC Human Interface. +These guidelines are for packaging Sugar activities. +http://wiki.laptop.org/go/Sugar[Sugar] is the core of the OLPC Human Interface. == Macros @@ -20,7 +21,9 @@ Architecture Dependent: == Necessary BuildRequires -All Sugar Activities use setup.py, which is dependant upon sugar-toolkit. Accordingly, all activities need to: +All Sugar Activities use setup.py, +which is dependant upon sugar-toolkit. +Accordingly, all activities need to: .... BuildRequires: sugar-toolkit @@ -32,7 +35,8 @@ All activities *MUST* be named `+sugar-+`. == Architecture-specific Activities -All activities containing compiled code (thus, architecture-specific) must be built in the %build section. Any architecture-specific bits must either go in `+%{_bindir}+` `+%{_libdir}+` or `+%{sugarlibdir}+` as appropriate. +All activities containing compiled code (thus, architecture-specific) must be built in the %build section. +Any architecture-specific bits must either go in `+%{_bindir}+` `+%{_libdir}+` or `+%{sugarlibdir}+` as appropriate. == Runtime Dependencies diff --git a/guidelines/modules/ROOT/pages/Systemd.adoc b/guidelines/modules/ROOT/pages/Systemd.adoc index fb2cf08..4111b46 100644 --- a/guidelines/modules/ROOT/pages/Systemd.adoc +++ b/guidelines/modules/ROOT/pages/Systemd.adoc @@ -306,7 +306,8 @@ 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 xref:Scriptlets.adoc#_systemd[systemd scriptlets]. These services should never be enabled by the package +and are installed by the normal xref:Scriptlets.adoc#_systemd[systemd scriptlets]. +These services should never be enabled by the package as they will be enabled by udev. [#activation_socket] diff --git a/guidelines/modules/ROOT/pages/Tcl.adoc b/guidelines/modules/ROOT/pages/Tcl.adoc index 8b2dc4a..6fb93fb 100644 --- a/guidelines/modules/ROOT/pages/Tcl.adoc +++ b/guidelines/modules/ROOT/pages/Tcl.adoc @@ -1,10 +1,16 @@ = Tcl packaging guidelines -These conventions apply to Tcl packages in Fedora 9 and later. There are some aspects of Tcl in Fedora 7 and Fedora 8 that will conflict with these guidelines. +These conventions apply to Tcl packages in Fedora 9 and later. +There are some aspects of Tcl in Fedora 7 and Fedora 8 +that will conflict with these guidelines. == Naming Conventions -The name for all Tcl/Tk extensions must be prefixed with `+tcl-+`. This rule applies even for Tcl/Tk packages that are already prefixed with `+tcl+` in the name (see examples below). An optional `+Provides: foo+` is recommended to allow selecting the package based on the upstream name, as long as the upstream name is not excessively generic and does not conflict with an existing package name. Tk extensions have the option of adding additional Provides: with the prefix `+tk-+`. + +The name for all Tcl/Tk extensions must be prefixed with `+tcl-+`. +This rule applies even for Tcl/Tk packages that are already prefixed with `+tcl+` in the name (see examples below). +An optional `+Provides: foo+` is recommended to allow selecting the package based on the upstream name, +as long as the upstream name is not excessively generic and does not conflict with an existing package name. +Tk extensions have the option of adding additional Provides: with the prefix `+tk-+`. + Examples: .... @@ -25,7 +31,12 @@ The exception to this naming rule are existing packages that provide both an ext == Applications -Tcl and Tk applications *must* use a non-versioned interpreter name in shebang line. This is to prevent any unnecessary dependency on the version of the interpreter being used. Most dependencies are with specific Tcl extensions, not the command line applications. Nevertheless, if an application does require a specific version of Tcl, it should use the standard Tcl package system to express this, as well as an explicit `+Requires: tcl(abi) = 8.x+` in the spec file. +Tcl and Tk applications *must* use a non-versioned interpreter name in shebang line. +This is to prevent any unnecessary dependency on the version of the interpreter being used. +Most dependencies are with specific Tcl extensions, not the command line applications. +Nevertheless, if an application does require a specific version of Tcl, +it should use the standard Tcl package system to express this, +as well as an explicit `+Requires: tcl(abi) = 8.x+` in the spec file. Bad: @@ -44,7 +55,12 @@ The same rules apply for Tk applications. The non-versioned `+wish+` interpreter == Extensions -Since Fedora 9, `+%{_libdir}+` and `+%{_datadir}+` have been removed from the search path to optimize package loading times. Instead, Tcl extension packages *must* be installed in `+%{_datadir}/tcl8.x+` if they are noarch packages containing only Tcl code, or `+%{_libdir}/tcl8.x+` if they are arch-specific extensions containing shared libraries. Note that most Tcl extensions are not configured do install in these directories out of the box, and may need to use additional configure switches, patches, or script code in `+%install+` to move the files to the correct location. +Since Fedora 9, `+%{_libdir}+` and `+%{_datadir}+` have been removed from the search path to optimize package loading times. +Instead, Tcl extension packages *must* be installed in `+%{_datadir}/tcl8.x+` if they are noarch packages containing only Tcl code, +or `+%{_libdir}/tcl8.x+` if they are arch-specific extensions containing shared libraries. +Note that most Tcl extensions are not configured do install in these directories out of the box, +and may need to use additional configure switches, patches, +or script code in `+%install+` to move the files to the correct location. Both arch-specific and `+noarch+` Tcl extensions *must* use @@ -52,7 +68,15 @@ Both arch-specific and `+noarch+` Tcl extensions *must* use 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 version 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. +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 version 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 @@ -63,15 +87,22 @@ The following macros *must* be used at the top of the spec file to determine the %{!?tcl_sitelib: %global tcl_sitelib %{_datadir}/tcl%{tcl_version}} .... -In order for the macros to work, the package must also `+BuildRequires: tcl+` either directly, or indirectly with `+BuildRequires: tcl-devel+` +In order for the macros to work, +the package must also `+BuildRequires: tcl+` either directly, +or indirectly with `+BuildRequires: tcl-devel+` -Merely adding the `+%{tcl_sitearch}+` and `+%{tcl_sitelib}+` is not enough to ensure that the packages get installed into the correct location. Most Tcl extensions will install into `+%{_libdir}+` by default. There are two ways to change this. For most `+noarch+` packages, you can use the `+--libdir+` and `+--datadir+` configure switches to change the installation directory: +Merely adding the `+%{tcl_sitearch}+` and `+%{tcl_sitelib}+` is not enough to ensure that the packages get installed into the correct location. +Most Tcl extensions will install into `+%{_libdir}+` by default. +There are two ways to change this. +For most `+noarch+` packages, +you can use the `+--libdir+` and `+--datadir+` configure switches to change the installation directory: .... %configure --libdir=%{tcl_sitelib} --datadir=%{tcl_sitelib} .... -For `+noarch+` packages that aren't fixed by using `+--libdir+`, you can simply move the installation directory in the `+%install+` section of the spec file. +For `+noarch+` packages that aren't fixed by using `+--libdir+`, +you can simply move the installation directory in the `+%install+` section of the spec file. .... %install @@ -81,7 +112,8 @@ install -d $RPM_BUILD_ROOT%{tcl_sitelib} mv $RPM_BUILD_ROOT%{_datadir}/foobar%{version} $RPM_BUILD_ROOT%{tcl_sitelib}/foobar%{version} .... -It may also be acceptable 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. +It may also be acceptable 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 @@ -92,7 +124,9 @@ The following macros *must* be used at the top of the spec file to determine the %{!?tcl_sitearch: %global tcl_sitearch %{_libdir}/tcl%{tcl_version}} .... -In order for the macros to work, the package must also `+BuildRequires: tcl+` either directly, or indirectly with `+BuildRequires: tcl-devel+` +In order for the macros to work, +the package must also `+BuildRequires: tcl+` either directly, +or indirectly with `+BuildRequires: tcl-devel+` While `+%{tcl_sitearch}+` is a symlink to `+%{tcl_sitelib}+` in Fedora 8 and earlier, in Fedora 9 it is an actual directory. @@ -103,7 +137,10 @@ The `+--libdir+` flag for the configure script can often be used to set the corr %configure --libdir=%{tcl_sitearch} .... -For most arch-specific packages, the `+--libdir+` flag for the configure script is also used to locate tclConfig.sh. Some of these arch-specific packages will break if `+--libdir+` is redirected to `+%{tcl_sitearch}+`. For packages that can't handle alternate values for `+--libdir+`, you can simply move the installation directory in the `+%install+` section of the spec file: +For most arch-specific packages, the `+--libdir+` flag for the configure script is also used to locate tclConfig.sh. +Some of these arch-specific packages will break if `+--libdir+` is redirected to `+%{tcl_sitearch}+`. +For packages that can't handle alternate values for `+--libdir+`, +you can simply move the installation directory in the `+%install+` section of the spec file: .... %install @@ -115,15 +152,39 @@ mv $RPM_BUILD_ROOT%{_libdir}/foobar%{version} $RPM_BUILD_ROOT%{tcl_sitearch}/foo Arch-specific packages can be generally grouped into three categories: those that provide a shell, those that provide a fooConfig.sh file and a shared library for linking, and those that only provide a shared library for dlopen(). *No shells:* -Very few Tcl extension packages provide a shell. Providing a shell for an extension is frowned upon. The extension's shared library can be dynamically loaded into a Tcl interpreter through the standard `+package require ...+` mechanism without providing a shell that automatically loads the shared library. The exceptions to this rule are the shells that are commonly expected to be present on a system, including Tk (wish) and Expect (expect, expectk). +Very few Tcl extension packages provide a shell. +Providing a shell for an extension is frowned upon. +The extension's shared library can be dynamically loaded into a Tcl interpreter through the standard `+package require ...+` mechanism without providing a shell that automatically loads the shared library. +The exceptions to this rule are the shells that are commonly expected to be present on a system, +including Tk (wish) and Expect (expect, expectk). *-devel subpackage for fooConfig.sh:* -Some arch-specific Tcl extensions provide a shared library and a corresponding `+fooConfig.sh+` file with instructions for linking against the library. The shared library for such packages *must* be installed into %\{_libdir} so that it can be found at runtime by applications that link against it. Unfortunately, the pkgIndex.tcl file in the package directory often references the shared library with a relative path. There are two ways to fix this. First, the maintainer can choose to keep the installation directory as %\{_libdir}, and make a symlink to %\{tcl_sitearch}. Second, the maintainer can choose to patch the pkgIndex.tcl file to contain an appropriate path to the shared library. Either solution is acceptible. - -`+fooConfig.sh+` files must be placed in a -devel subpackage. This may require some sed magic to modify `+fooConfig.sh+` so that the paths to the libraries and headers are still correct. +Some arch-specific Tcl extensions provide a shared library and a corresponding `+fooConfig.sh+` file with instructions for linking against the library. +The shared library for such packages *must* be installed into %\{_libdir} +so that it can be found at runtime by applications that link against it. +Unfortunately, the pkgIndex.tcl file in the package directory often references the shared library with a relative path. +There are two ways to fix this. +First, the maintainer can choose to keep the installation directory as %\{_libdir}, +and make a symlink to %\{tcl_sitearch}. +Second, the maintainer can choose to patch the pkgIndex.tcl file to contain an appropriate path to the shared library. +Either solution is acceptible. + +`+fooConfig.sh+` files must be placed in a -devel subpackage. +This may require some sed magic to modify `+fooConfig.sh+` so that the paths to the libraries and headers are still correct. *No dlopen()'d libraries in %\{_libdir}:* -If the extension does *not* provide a `+fooConfig.sh+` file, then the shared library *must not* be installed directly in `+%{_libdir}+`, but in the package-specific installation directory in `+%{tcl_sitearch}+` instead. This may require a patch to update the extension's `+pkgIndex.tcl+` file to look for the shared library in the correct location. +If the extension does *not* provide a `+fooConfig.sh+` file, +then the shared library *must not* be installed directly in `+%{_libdir}+`, +but in the package-specific installation directory in `+%{tcl_sitearch}+` instead. +This may require a patch to update the extension's `+pkgIndex.tcl+` file to look for the shared library in the correct location. *Stubs are ok if put in -devel subpackage:* -Some Tcl extensions provide a static 'stub' library. Stub libraries are a Tcl-ism to provide version-independent dynamic linking on a variety of platforms. These are not normal static libraries that provide the library's actual functionality, but instead provide a level of indirection pointing to the shared library. These stub libraries do not have the same static linking issues that are generally frowned upon in Fedora, and thus are acceptable. If a package provides such a stub library, it must be placed in a -devel subpackage. More information on stubs can be found on the Tcl wiki: https://wiki.tcl-lang.org/page/Stubs +Some Tcl extensions provide a static 'stub' library. +Stub libraries are a Tcl-ism to provide version-independent dynamic linking on a variety of platforms. +These are not normal static libraries that provide the library's actual functionality, +but instead provide a level of indirection pointing to the shared library. +These stub libraries do not have the same static linking issues that are generally frowned upon in Fedora, +and thus are acceptable. +If a package provides such a stub library, +it must be placed in a -devel subpackage. +More information on stubs can be found on the Tcl wiki: https://wiki.tcl-lang.org/page/Stubs diff --git a/guidelines/modules/ROOT/pages/Tmpfiles.d.adoc b/guidelines/modules/ROOT/pages/Tmpfiles.d.adoc index 93032b8..af91c7d 100644 --- a/guidelines/modules/ROOT/pages/Tmpfiles.d.adoc +++ b/guidelines/modules/ROOT/pages/Tmpfiles.d.adoc @@ -2,13 +2,28 @@ == Overview -tmpfiles.d is a service for managing temporary files and runtime directories for daemons. In this guideline we mainly concentrate on how it is used to populate `+/run+` and `+/run/lock+`. Since `+/run+` is a `+tmpfs+` filesystem, it and its contents must be recreated on every reboot. For files intended to be created there, this should normally not pose any problems. However, directories will often need to be created ahead of time. This is best done using the tmpfiles.d mechanism. +tmpfiles.d is a service for managing temporary files and runtime directories for daemons. +In this guideline we mainly concentrate on how it is used to populate `+/run+` +and `+/run/lock+`. +Since `+/run+` is a `+tmpfs+` filesystem, +it and its contents must be recreated on every reboot. +For files intended to be created there, +this should normally not pose any problems. +However, directories will often need to be created ahead of time. +This is best done using the tmpfiles.d mechanism. == tmpfiles.d configuration -Asking the tmpfiles.d mechanism to create directories for you just involves dropping a file into `+%{_tmpfilesdir}+`. You will need a build dependency on systemd-rpm-macros in order to make use of this macro. +Asking the tmpfiles.d mechanism to create directories for you +just involves dropping a file into `+%{_tmpfilesdir}+`. +You will need a build dependency on systemd-rpm-macros +in order to make use of this macro. -For example, if the package needs a few directories to be created in `+/run+` in order for it to run, the packager needs to create a file named `+%{name}.conf+` that is installed as `+%{_tmpfilesdir}/%{name}.conf+`. The file has one or more lines of the following format: +For example, +if the package needs a few directories to be created in `+/run+` in order for it to run, +the packager needs to create a file named `+%{name}.conf+` +that is installed as `+%{_tmpfilesdir}/%{name}.conf+`. +The file has one or more lines of the following format: .... d /run/NAME PERM USER GROUP - @@ -16,12 +31,20 @@ d /run/NAME PERM USER GROUP - The format of the line is as follows: -* `+d+` specifies that a directory is to be created if it doesn't exist. You can use a different type specifier if you need it. See `+man tmpfiles.d+` for possible values. +* `+d+` specifies that a directory is to be created if it doesn't exist. + You can use a different type specifier if you need it. + See `+man tmpfiles.d+` for possible values. * `+/run/NAME+` is the filesystem path to create. -* `+PERM+` are the permissions (in the 4-digit octal format) to apply to the directory when it is created. +* `+PERM+` are the permissions (in the 4-digit octal format) + to apply to the directory when it is created. * `+USER+` is the name of the owner of the directory. * `+GROUP+` is the name of the group of the directory. -* `+-+` specifies that aging should not be applied to the contents of the directory. Aging is a mechanism for automated cleanup of files that were not used for a specified length of time. This is mostly useful for directories such as /tmp and is seldom used by packages. Feel free to use aging if it is appropriate for your directory. +* `+-+` specifies that aging should not be applied to the contents of the directory. + Aging is a mechanism for automated cleanup of files + that were not used for a specified length of time. + This is mostly useful for directories such as /tmp + and is seldom used by packages. + Feel free to use aging if it is appropriate for your directory. An example: @@ -29,11 +52,15 @@ An example: d /run/mysqld 0755 mysql mysql - .... -Information on other options is available on the https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html[tmpfiles.d man page] should you need to do something more advanced. +Information on other options is available on the +https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html[tmpfiles.d man page] +should you need to do something more advanced. == Example spec file -In the spec file, the packager needs to install the tmpfiles.d conf file into the `+%{_tmpfilesdir}+` directory and also make sure the directory is included in the rpm. +In the spec file, +the packager needs to install the tmpfiles.d conf file into the `+%{_tmpfilesdir}+` directory +and also make sure the directory is included in the rpm. [source, rpm-spec] ---- @@ -65,23 +92,46 @@ chmod 0644 %{buildroot}/run/%{name}.pid %{_tmpfilesdir}/%{name}.conf ---- -`+%{_tmpfilesdir}+` expands to `+%{_prefix}/lib/tmpfiles.d+` which is the location that the package's default tmpfile creation scripts should install into. `+%{_tmpfilesdir}/%{name}.conf+` is *not* marked as a `+%config+` file because it is not supposed to be edited by administrators. Administrators can override the package's `+%{name}.conf+` by placing an identically named file in `+/etc/tmpfiles.d/+`, but this should very rarely be needed. - -Files (*not directories*) that the program places directly into `+/run+` are listed in the `+%files+` section as `+%verify(not size mtime md5)+` so that rpm knows the file must exist as part of this package but will not complain when the file contents change. Files placed in the subdirectories may be listed the same way or omitted entirely as the files will be cleaned up on every reboot. +`+%{_tmpfilesdir}+` expands to `+%{_prefix}/lib/tmpfiles.d+` +which is the location that the package's default tmpfile creation scripts should install into. +`+%{_tmpfilesdir}/%{name}.conf+` is *not* marked as a `+%config+` file +because it is not supposed to be edited by administrators. +Administrators can override the package's `+%{name}.conf+` +by placing an identically named file in `+/etc/tmpfiles.d/+`, +but this should very rarely be needed. + +Files (*not directories*) that the program places directly into `+/run+` +are listed in the `+%files+` section as `+%verify(not size mtime md5)+` +so that rpm knows the file must exist as part of this package +but will not complain when the file contents change. +Files placed in the subdirectories may be listed the same way or omitted entirely +as the files will be cleaned up on every reboot. == Why not create the directories with XXXXXX instead? -There are multiple ways to try creating the directories but most suffer some disadvantage that tmpfiles.d addresses: +There are multiple ways to try creating the directories +but most suffer some disadvantage that tmpfiles.d addresses: === Have the daemon create the directory when it starts up -Many times, daemons run as an unprivileged user who would not be allowed to create new directories directly into `+/run+`. -If the daemon does not drop privileges, then you can patch it to create the files and directories when the daemon starts and submit the patch upstream. +Many times, daemons run as an unprivileged user +who would not be allowed to create new directories directly into `+/run+`. +If the daemon does not drop privileges, +then you can patch it to create the files and directories when the daemon starts +and submit the patch upstream. === Have the init script create the directory when it starts up the daemon -Since the init script is run by root, before the daemon drops privileges, why not create the directories there? - -* This code would need to be implemented in every init script packaged. Using tmpfiles.d we can cut down on the number of places we have to put code like this. -* Having to add the mkdir to the systemd unit files when tmpfiles.d is already in place introduces the need to run shell code for that init script. Systemd is no longer able to handle starting the daemon by itself which slows things down. The shell code also introduces imperative constructs into the otherwise declarative structure which is nice to avoid. -* Properly labelling the created directories is done automatically by the tmpfiles.d mechanism but would have to be manually done by the init script. +Since the init script is run by root, +before the daemon drops privileges, +why not create the directories there? + +* This code would need to be implemented in every init script packaged. + Using tmpfiles.d we can cut down on the number of places we have to put code like this. +* Having to add the mkdir to the systemd unit files when tmpfiles.d is already in place + introduces the need to run shell code for that init script. + Systemd is no longer able to handle starting the daemon by itself which slows things down. + The shell code also introduces imperative constructs into the otherwise declarative structure + which is nice to avoid. +* Properly labelling the created directories is done automatically by the tmpfiles.d mechanism + but would have to be manually done by the init script. diff --git a/guidelines/modules/ROOT/pages/Tree-sitter.adoc b/guidelines/modules/ROOT/pages/Tree-sitter.adoc index fafe34c..297dbcb 100644 --- a/guidelines/modules/ROOT/pages/Tree-sitter.adoc +++ b/guidelines/modules/ROOT/pages/Tree-sitter.adoc @@ -2,8 +2,7 @@ == Macros -The macros in package `tree-sitter-srpm-macros` can do most of the work -for you. +The macros in package `tree-sitter-srpm-macros` can do most of the work for you. === Specifying the build system @@ -28,9 +27,9 @@ Generate `%package` and `%files` sections for the subpackages built from your pa %{tree_sitter -l language-name} ---- -Here, _language-name_ is the human-friendly name(s) of the Language -parser(s) provided by this package, to be mentioned in the package -summaries and descriptions. +Here, +_language-name_ is the human-friendly name(s) of the Language parser(s) provided by this package, +to be mentioned in the package summaries and descriptions. == Example spec file diff --git a/guidelines/modules/ROOT/pages/UnownedDirectories.adoc b/guidelines/modules/ROOT/pages/UnownedDirectories.adoc index b322c01..948bed8 100644 --- a/guidelines/modules/ROOT/pages/UnownedDirectories.adoc +++ b/guidelines/modules/ROOT/pages/UnownedDirectories.adoc @@ -1,10 +1,14 @@ = Unowned Directories -The term "unowned directory" (or "orphaned directory") refers to a packaging mistake where these three things happen: +The term "unowned directory" (or "orphaned directory") refers to a packaging mistake +where these three things happen: -* a package includes files within a directory it creates, but *not* the directory itself +* a package includes files within a directory it creates, + but *not* the directory itself * none of the package's dependencies provide the directory either -* the directory belongs to your package and does not belong to any core package or base filesystem package that is considered essential/fundamental to any Fedora System. +* the directory belongs to your package + and does not belong to any core package or base filesystem package + that is considered essential/fundamental to any Fedora System. == Issues @@ -12,36 +16,67 @@ Unowned directories can cause the following problems. === Inaccessible Directories -A restrictive superuser umask during package installation can create inaccessible directories when installed using the RPM Package Manager older than 4.4.2.3. Fedora 9 and RHEL 5.3 are the first to use RPM 4.4.2.3 which sets umask 0022 always. On platforms with older versions of RPM if the superuser does this: +A restrictive superuser umask during package installation can create inaccessible directories +when installed using the RPM Package Manager older than 4.4.2.3. +Fedora 9 and RHEL 5.3 are the first to use RPM 4.4.2.3 +which sets umask 0022 always. +On platforms with older versions of RPM +if the superuser does this: `+ umask 077+` + `+ yum update+` + `+ [or]+` + `+ rpm -ivh PACKAGE+` -Unowned directories within the updated or installed packages will only be readable and executable by root. This prevents other users from using the files within those directories. +Unowned directories within the updated or installed packages +will only be readable and executable by root. +This prevents other users from using the files within those directories. -This causes run-time problems for users. For example, unreadable subdirs below %_libdir disable plugins. Unreadable subdirs below %_datadir prevent application data, help texts, and graphics from being accessed. +This causes run-time problems for users. +For example, +unreadable subdirs below %_libdir disable plugins. +Unreadable subdirs below %_datadir prevent application data, +help texts, +and graphics from being accessed. -Several sorts of users fix such permission problems with chmod instead of taking the time to report it as a bug. It is common belief that such bugs are so obvious they would be found by the package maintainer or will be reported by other users. +Several sorts of users fix such permission problems with chmod +instead of taking the time to report it as a bug. +It is common belief that such bugs are so obvious +they would be found by the package maintainer +or will be reported by other users. === Directories not Removed -Upon uninstalling the package (or upgrading to another version), the old directory is not removed from the file system because it does not belong in the package in the RPM database. +Upon uninstalling the package (or upgrading to another version), +the old directory is not removed from the file system +because it does not belong in the package in the RPM database. -Especially if directories contain a version number, they clutter up the file system with every update which doesn't remove old directories. +Especially if directories contain a version number, +they clutter up the file system +with every update which doesn't remove old directories. === Directories cannot be Verified -Unowned/orphaned directories cannot be checked with rpm -V and not with rpm -qf either. +Unowned/orphaned directories cannot be checked with rpm -V +and not with rpm -qf either. === ./configure Scripts can Fail -Upstream source tarball configuration can fail, because it detects the presence of an old but empty versioned header directories or because it is trying to use multiple versioned directories instead of just the latest valid one. +Upstream source tarball configuration can fail, +because it detects the presence of an old but empty versioned header directories +or because it is trying to use multiple versioned directories +instead of just the latest valid one. == Tools to Help -It's easy to find unowned directories with `+rpmls+` from rpmdevtools or `+rpm -qlv+`. Just a bit of carefulness is needed to not include core filesystem directories, such as %_bindir, %_libdir (and obvious others, e.g. from the "filesystem" pkg) which don't belong into your package. +It's easy to find unowned directories with `+rpmls+` from rpmdevtools +or `+rpm -qlv+`. +Just a bit of carefulness is needed +to not include core filesystem directories, +such as %_bindir, +%_libdir (and obvious others, +e.g. from the "filesystem" pkg) +which don't belong into your package. == Common Mistakes diff --git a/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc b/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc index 0686479..d6f4510 100644 --- a/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc +++ b/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc @@ -23,15 +23,15 @@ There are a few conditions that need to exist in which DSOs are allowed to remain unversioned. * The DSO ``MUST NOT`` be visible -to the dynamic linker -(i.e. the DSO does not show up in ``ldconfig -p`` output) + to the dynamic linker + (i.e. the DSO does not show up in ``ldconfig -p`` output) * The DSO ``MUST`` be located in a private directory -(i.e. not located directly in /usr/lib[64] or in another directory listed as a library path for the linker) + (i.e. not located directly in /usr/lib[64] or in another directory listed as a library path for the linker) * The DSO ``MUST NOT`` be linked against and is loaded at runtime -by the implementing application -(i.e. ``dlopen()``) + by the implementing application + (i.e. ``dlopen()``) If these conditions are met, the unversioned DSOs @@ -61,18 +61,18 @@ and are a special exception. Drivers have the following requirements: * The DSO ``SHOULD`` be located in a private directory in /usr/lib[64] -(i.e. `+%{_libdir}/%{name}/driver+`) + (i.e. `+%{_libdir}/%{name}/driver+`) * The directory ``SHOULD`` be added to the loader path using a ``ld.conf.d`` configuration -(i.e. `+%{_sysconfdir}/ld.conf.d/%{name}.conf+` definition) + (i.e. `+%{_sysconfdir}/ld.conf.d/%{name}.conf+` definition) Vulkan Layers are loaded by configuration as defined by the Vulkan Loader specification. Layers have the following requirements: * The DSO ``MUST`` be located in a private directory in /usr/lib[64] -(i.e. `+%{_libdir}/%{name}/layer+`) -and loaded by configuration + (i.e. `+%{_libdir}/%{name}/layer+`) + and loaded by configuration === OpenXR @@ -89,18 +89,18 @@ OpenXR Runtimes are loaded by configuration as defined by the OpenXR Loader spec Runtimes have the following requirements: * The DSO ``MUST`` be located in a private directory in /usr/lib[64] -(i.e. `+%{_libdir}/%{name}/runtime+`) + (i.e. `+%{_libdir}/%{name}/runtime+`) * The directory ``SHOULD`` be added to the loader path using a ``ld.conf.d`` configuration -(i.e. `+%{_sysconfdir}/ld.conf.d/%{name}.conf+` definition) + (i.e. `+%{_sysconfdir}/ld.conf.d/%{name}.conf+` definition) OpenXR Layers are loaded by configuration as defined by the OpenXR Loader specification. Layers have the following requirements: * The DSO ``MUST`` be located in a private directory in /usr/lib[64] -(i.e. `+%{_libdir}/%{name}/layer+`) -and loaded by configuration + (i.e. `+%{_libdir}/%{name}/layer+`) + and loaded by configuration === Other Cases diff --git a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc index 6dc7b87..b1b358a 100644 --- a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc +++ b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc @@ -164,11 +164,12 @@ manual creation of users and groups is required. The sysusers file must be a separate `Source` file. -In the specfile, add a BuildRequires for systemd-rpm-macros, install the sysusers file, +In the specfile, add a BuildRequires for systemd-rpm-macros, +install the sysusers file, use the `%sysusers_create_compat` macro to consume it in the `%pre` section -(in this example the sysusers config file is `Source3` of the specfile), and the -`%sysusers_requires_compat` macro to specify the runtime dependencies for the `%pre` -section: +(in this example the sysusers config file is `Source3` of the specfile), +and the `%sysusers_requires_compat` macro +to specify the runtime dependencies for the `%pre` section: ``` [...] BuildRequires: systemd-rpm-macros diff --git a/guidelines/modules/ROOT/pages/Versioning.adoc b/guidelines/modules/ROOT/pages/Versioning.adoc index 3decde2..7873e53 100644 --- a/guidelines/modules/ROOT/pages/Versioning.adoc +++ b/guidelines/modules/ROOT/pages/Versioning.adoc @@ -74,10 +74,12 @@ Release: %autorelease As described in https://fedora-infra.github.io/rpmautospec-docs/autorelease.html[%autorelease documentation], the build machinery will -replace the macro with the number of builds since the last commit that changed the `+Version+` field, +replace the macro with the number of builds since the last commit +that changed the `+Version+` field, suffixed with the `%{?dist}` tag. This means that a commit that changes `+Version+` automatically gets `Release: 1%{?dist}`, -and commits after that get `Release: 2%{?dist}`, `Release: 3%{?dist}`, and so on. +and commits after that get `Release: 2%{?dist}`, +`Release: 3%{?dist}`, and so on. Alternatively, the `+Release:+` field **may** be updated manually. See xref:Versioning.adoc#traditional-versioning[Traditional versioning @@ -124,18 +126,22 @@ in a particular situation: * More than one of the above may apply (lucky you). Follow all of the relevant recommendations below together. -This subsection describes how to modify the upstream project version to be suitable for the `+Version+` field. +This subsection describes how to modify the upstream project version +to be suitable for the `+Version+` field. Use of `Release: +%autorelease+` remains unchanged. === Handling non-sorting versions with tilde, dot, and caret -The tilde symbol ('`+~+`') is used before a version component which must sort *earlier* than any non-tilde component. -It is used for any pre-release versions which wouldn't otherwise sort appropriately. +The tilde symbol ('`+~+`') is used before a version component +which must sort *earlier* than any non-tilde component. +It is used for any pre-release versions +which wouldn't otherwise sort appropriately. For example, with upstream releases `+0.4.0+`, `+0.4.1+`, `+0.5.0-rc1+`, `+0.5.0-rc2+`, `+0.5.0+`, the two "release candidates" should use `+0.5.0~rc1+` and `+0.5.0~rc2+` in the `+Version:+` field. -Bugfix or "patchlevel" releases that some upstream make should be handled using simple versioning. +Bugfix or "patchlevel" releases that some upstream make +should be handled using simple versioning. The separator used by upstream may need to be replaced by a dot or dropped. For example, if the same upstream released `+0.5.0-post1+` as a bugfix version, diff --git a/guidelines/modules/ROOT/pages/WeakDependencies.adoc b/guidelines/modules/ROOT/pages/WeakDependencies.adoc index 6c88b5d..26edcb1 100644 --- a/guidelines/modules/ROOT/pages/WeakDependencies.adoc +++ b/guidelines/modules/ROOT/pages/WeakDependencies.adoc @@ -2,11 +2,12 @@ == Introduction -Weak dependencies are basically variants of the `+Requires:+` tag and -are matched against (virtual) `+Provides:+` and package names using -`+Epoch-Version-Release+` range comparisons, just like regular -`+Requires:+`. They come in two strengths: "weak" and "hint" and two -directions "forward" (analogous to `+Requires:+`) and "backwards" +Weak dependencies are basically variants of the `+Requires:+` tag +and are matched against (virtual) `+Provides:+` and package names +using `+Epoch-Version-Release+` range comparisons, +just like regular `+Requires:+`. +They come in two strengths: "weak" and "hint" +and two directions "forward" (analogous to `+Requires:+`) and "backwards" (which has no analog in the previous dependency system). [cols=",,",] @@ -16,29 +17,33 @@ directions "forward" (analogous to `+Requires:+`) and "backwards" |Hint |Suggests: |Enhances: |=============================== -Weak dependencies allow smaller minimal installations while keeping the default -installation feature rich. They also allow packages to specify preferences for -specific providers while maintaining the flexibility of virtual provides, for -example, preferring ruby vs jruby or community-mysql vs mariadb. +Weak dependencies allow smaller minimal installations +while keeping the default installation feature rich. +They also allow packages to specify preferences for specific providers +while maintaining the flexibility of virtual provides, for example, +preferring ruby vs jruby or community-mysql vs mariadb. == Weak dependencies -Weak dependencies are by default treated similarly to regular -`+Requires:+`. Matching packages are added to the dnf transaction. If -adding the package would lead to an error dnf will by default ignore the -dependency. This allows users to exclude packages that would be added by weak -dependencies or remove them later. To skip installing weak dependencies, pass -`--setopt=install_weak_deps=False` to `dnf`. +Weak dependencies are by default treated similarly to regular `+Requires:+`. +Matching packages are added to the dnf transaction. +If adding the package would lead to an error +dnf will by default ignore the dependency. +This allows users to exclude packages that would be added by weak dependencies +or remove them later. +To skip installing weak dependencies, pass `--setopt=install_weak_deps=False` to `dnf`. -As with regular dependencies, weak dependencies MUST be satisfiable within the official Fedora repositories. +As with regular dependencies, +weak dependencies MUST be satisfiable within the official Fedora repositories. Weak dependencies may only be used in a package if the package still functions -without the dependency present. It is acceptable, however, to create packages -that have very limited functionality without adding any of its weak -requirements. Weak dependencies should be used where possible to minimize the -installation for reasonable use cases, especially for building virtual machines -or containers that have a single purpose only and do not require the full -feature set of the package. +without the dependency present. +It is acceptable, however, to create packages that have very limited functionality +without adding any of its weak requirements. +Weak dependencies should be used where possible to minimize the installation +for reasonable use cases, +especially for building virtual machines or containers that have a single purpose only +and do not require the full feature set of the package. Typical use cases for weak dependencies are: @@ -52,27 +57,28 @@ Typical use cases for weak dependencies are: == Hints -Hints are by default ignored by dnf. They may be used by GUI tools to offer -add-on packages that are not installed by default but might be useful in -combination with the installed packages. The requirements of the main use cases -of a package should not merely be referenced by hints but included by strong or -weak dependencies. +Hints are by default ignored by dnf. +They may be used by GUI tools to offer add-on packages +that are not installed by default but might be useful in combination with the installed packages. +The requirements of the main use cases of a package should not merely be referenced by hints +but included by strong or weak dependencies. == Package Preference -dnf (or more precisely libsolv) will use weak dependencies and hints to decide -which package to use if there is a choice between multiple equally valid -packages. In these cases packages that are pointed at by dependencies from -installed or to be installed packages are preferred. Note, that this does not -alter the normal rules of dependency resolution. For example, weak -dependencies cannot enforce a older version of a package to be chosen. - -If there are multiple (typically virtual) providers for a dependency the -requiring package may add a Suggests: to provide a hint to the dependency -resolver as to which option is preferred. `+Enhances:+` should only -be used for the rare occasion when the main package and other providers agree -that adding the hint to the required package is for some reason the cleaner -solution. +dnf (or more precisely libsolv) will use weak dependencies and hints +to decide which package to use +if there is a choice between multiple equally valid packages. +In these cases +packages that are pointed at by dependencies from installed or to be installed packages are preferred. +Note, +that this does not alter the normal rules of dependency resolution. +For example, weak dependencies cannot enforce a older version of a package to be chosen. + +If there are multiple (typically virtual) providers for a dependency +the requiring package may add a Suggests: +to provide a hint to the dependency resolver as to which option is preferred. +`+Enhances:+` should only be used for the rare occasion when the main package and other providers agree +that adding the hint to the required package is for some reason the cleaner solution. === Real life example @@ -90,21 +96,24 @@ If you want to prefer mariadb over community-mysql -> add `+Suggests:+` == Forward vs Backward Dependencies -Forward dependencies are, as Requires, evaluated for packages that are being -installed. The best of the matching (fulfilling) packages are also installed. -For reverse dependencies the packages containing the dependency are installed if -a matching package is getting installed also. - -In general forward dependencies should be used. Add the dependency to the -package getting the other package added to the system. - -Reverse dependencies are mainly designed for 3rd party vendors who can attach -their plug-ins/add-ons/extensions to distribution or other 3rd party packages. -Within Fedora the control over which packages a package requires should stay -with the package maintainer. There are, however, cases when it is easier for -the requiring package not needing to care about all add-ons. In this cases -reverse dependencies may be used with the agreement of the package maintainer of -the targeted package. +Forward dependencies are, as Requires, +evaluated for packages that are being installed. +The best of the matching (fulfilling) packages are also installed. +For reverse dependencies the packages containing the dependency are installed +if a matching package is getting installed also. + +In general forward dependencies should be used. +Add the dependency to the package getting the other package added to the system. + +Reverse dependencies are mainly designed for 3rd party vendors +who can attach their plug-ins/add-ons/extensions +to distribution or other 3rd party packages. +Within Fedora +the control over which packages a package requires should stay with the package maintainer. +There are, however, cases when it is easier for the requiring package +not needing to care about all add-ons. +In this cases reverse dependencies may be used +with the agreement of the package maintainer of the targeted package. Note, that EPEL or other third party repositories may have (and are encouraged to have) a different policy. diff --git a/guidelines/modules/ROOT/pages/WordPress_plugin_packaging_guidelines.adoc b/guidelines/modules/ROOT/pages/WordPress_plugin_packaging_guidelines.adoc index f5523ae..679f221 100644 --- a/guidelines/modules/ROOT/pages/WordPress_plugin_packaging_guidelines.adoc +++ b/guidelines/modules/ROOT/pages/WordPress_plugin_packaging_guidelines.adoc @@ -1,5 +1,7 @@ = WordPress plugins Packaging Guidelines -https://wordpress.org/plugins/[WordPress plugins] are packaged for Fedora so that the plugin can be used for both and without requiring both. +https://wordpress.org/plugins/[WordPress plugins] are packaged for Fedora +so that the plugin can be used for both +and without requiring both. == Requirements for packaging diff --git a/guidelines/modules/ROOT/pages/deprecating-packages.adoc b/guidelines/modules/ROOT/pages/deprecating-packages.adoc index 3dbb9ea..1cbb9b7 100644 --- a/guidelines/modules/ROOT/pages/deprecating-packages.adoc +++ b/guidelines/modules/ROOT/pages/deprecating-packages.adoc @@ -1,12 +1,24 @@ = Deprecating Packages -Sometimes a package is intended to be https://docs.fedoraproject.org/en-US/package-maintainers/Package_Retirement_Process/[removed from Fedora], but it is kept in Fedora for some additional (often indeterminate) time for various reasons including maintaining backwards compatibility. In order to prevent new packages from depending on such a package, it can be marked as *deprecated*. +Sometimes a package is intended to be https://docs.fedoraproject.org/en-US/package-maintainers/Package_Retirement_Process/[removed from Fedora], +but it is kept in Fedora for some additional (often indeterminate) time +for various reasons including maintaining backwards compatibility. +In order to prevent new packages from depending on such a package, +it can be marked as *deprecated*. == Prerequisites for deprecation -If nothing in Fedora depends on a package, a maintainer may deprecate it at their leisure. A maintainer (or collection of maintainers) may also deprecate a set of packages together if no package in that set is a dependency of any package outside of that set. +If nothing in Fedora depends on a package, +a maintainer may deprecate it at their leisure. +A maintainer (or collection of maintainers) may also deprecate a set of packages together +if no package in that set is a dependency of any package outside of that set. -If a package is a dependency of other packages in the distribution (which are not to be deprecated) then deprecation requires a https://fedoraproject.org/wiki/Changes/Policy[FESCo approved Fedora change]. A packager SHOULD communicate package deprecation to other maintainers, preferably via the https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel] or https://lists.fedoraproject.org/archives/list/devel-announce@lists.fedoraproject.org/[devel-announce] mailing lists. +If a package is a dependency of other packages in the distribution (which are not to be deprecated) +then deprecation requires a https://fedoraproject.org/wiki/Changes/Policy[FESCo approved Fedora change]. +A packager SHOULD communicate package deprecation to other maintainers, +preferably via the https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel] +or https://lists.fedoraproject.org/archives/list/devel-announce@lists.fedoraproject.org/[devel-announce] +mailing lists. == Marking a package deprecated @@ -16,7 +28,9 @@ In order to mark a package deprecated, a special virtual provides is added: Provides: deprecated() .... -If the package has subpackages and the packager intends to deprecate the package as a whole, packager MUST mark all subpackages as being deprecated. +If the package has subpackages +and the packager intends to deprecate the package as a whole, +packager MUST mark all subpackages as being deprecated. .... Name:      mainpackage @@ -48,8 +62,23 @@ If a date for the final removal of the package from the distribution is known, i Provides:  deprecated() = YYYYMMDD .... -The special `+deprecated()+` provide MUST NOT be added in any released branch of Fedora. It is acceptable to deprecate packages in rawhide (the master branch), the branch for an upcoming Fedora release (if one exists) up until the time of the https://fedoraproject.org/wiki/Schedule[Final Freeze], and to EPEL branches (at any time). Also note that because packages may exist in a deprecated state for some time, those packages can eventually enter release branches. The restriction is on the initial addition of the `+deprecated()+` tag. +The special `+deprecated()+` provide MUST NOT be added in any released branch of Fedora. +It is acceptable to deprecate packages in rawhide (the master branch), +the branch for an upcoming Fedora release (if one exists) up until the time of the +https://fedoraproject.org/wiki/Schedule[Final Freeze], +and to EPEL branches (at any time). +Also note that because packages may exist in a deprecated state for some time, +those packages can eventually enter release branches. +The restriction is on the initial addition of the `+deprecated()+` tag. == Consequences of a package being deprecated -Technically, nothing changes; a deprecated package works and behaves as before. However, other packages in Fedora MUST NOT add a dependency on a deprecated package (that includes Requires, BuildRequires, Recommends, Suggests, etc.). This applies both for updates of existing packages and new packages added to Fedora. Those submitting new packages, along with package reviewers, MUST check to see if any dependencies of the package they are submitting or reviewing have been deprecated. (It is, however, acceptable for a deprecated package to be renamed.) +Technically, nothing changes; a deprecated package works and behaves as before. +However, other packages in Fedora MUST NOT add a dependency on a deprecated package +(that includes Requires, BuildRequires, Recommends, Suggests, etc.). +This applies both for updates of existing packages +and new packages added to Fedora. +Those submitting new packages, along with package reviewers, +MUST check to see if any dependencies of the package they are submitting or reviewing +have been deprecated. +(It is, however, acceptable for a deprecated package to be renamed.) diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index ed3f58e..12ebc56 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -145,9 +145,11 @@ or use the generic-logos package. Many language- or domain-specific guidelines refer to "libraries", "modules", "plug-ins" or other terms specific to the language or -domain. This is specifically important to package -naming. Some applications may include libraries, and some libraries -may include applications, so the distinction is not always clear. +domain. +This is specifically important to package naming. +Some applications may include libraries, +and some libraries may include applications, +so the distinction is not always clear. === Library or Application? diff --git a/guidelines/modules/ROOT/pages/manual-changelog.adoc b/guidelines/modules/ROOT/pages/manual-changelog.adoc index 24494d6..291882f 100644 --- a/guidelines/modules/ROOT/pages/manual-changelog.adoc +++ b/guidelines/modules/ROOT/pages/manual-changelog.adoc @@ -1,11 +1,13 @@ = Manual Changelog -This describes the traditional method of managing changelogs that provides a -separate text log of user-visible changes independently of the git commit messages. +This describes the traditional method of managing changelogs +that provides a separate text log of user-visible changes +independently of the git commit messages. This is an alternative for the recommended method with `+%autochangelog+` described in xref:index.adoc#changelogs[Changelogs]. -_Every time_ you make changes, that is, +_Every time_ you make changes, +that is, whenever you increment the E-V-R of a package, add a changelog entry in the `+%changelog+` section. diff --git a/guidelines/modules/ROOT/pages/what-can-be-packaged.adoc b/guidelines/modules/ROOT/pages/what-can-be-packaged.adoc index 38cca68..84f56fa 100644 --- a/guidelines/modules/ROOT/pages/what-can-be-packaged.adoc +++ b/guidelines/modules/ROOT/pages/what-can-be-packaged.adoc @@ -3,11 +3,24 @@ :legal-team: https://fedoraproject.org/wiki/Legal:Main[Legal Team] :kernel-team: https://fedoraproject.org/wiki/Kernel[Kernel Team] -Not everything can be packaged in Fedora. Most things considered to be "free software" or "open source software" are permitted, but definitions of these are not always consistent and Fedora has a few specific requirements and exceptions. This is an overview of some specific requirements and exceptions, but it is not intended to be exhaustive. If questions arise, the {packaging-committee} and the {legal-team} are the primary places to receive answers. +Not everything can be packaged in Fedora. +Most things considered to be "free software" or "open source software" are permitted, +but definitions of these are not always consistent +and Fedora has a few specific requirements and exceptions. +This is an overview of some specific requirements and exceptions, +but it is not intended to be exhaustive. +If questions arise, +the {packaging-committee} and the {legal-team} +are the primary places to receive answers. == Legal Issues -Some software (or in some cases, portions of that software) cannot be packaged for legal reasons. This includes issues related to licensing, patents, trademark law, etc. +Some software (or in some cases, portions of that software) +cannot be packaged for legal reasons. +This includes issues related to licensing, +patents, +trademark law, +etc. See the following pages for various examples. @@ -18,27 +31,43 @@ See the following pages for various examples. == Impermissible Content It is important to make distinction between computer executable code and content. -While code is permitted (assuming, of course, that it has an open source compatible license, is not legally questionable, etc.), only some kinds of content are permissible. +While code is permitted (assuming, of course, that it has an open source compatible license, is not legally questionable, etc.), +only some kinds of content are permissible. The rule is this: -If the content enhances the OS user experience, then the content is OK to be packaged in Fedora. This means, for example, that things like: fonts, themes, clipart, and wallpaper are OK. - -Content still has to be reviewed for inclusion. It must have an open source compatible license, must not be legally questionable. In addition, there are several additional restrictions for content: - -* Content must not be pornographic, or contain nudity, whether animated, simulated, or photographed. There are better places on the Internet to get porn. -* Content should not be offensive, discriminatory, or derogatory. If you're not sure if a piece of content is one of these things, it probably is. -* All content is subject to review by FESCo, who has the final say on whether or not it can be included. +If the content enhances the OS user experience, +then the content is OK to be packaged in Fedora. +This means, for example, +that things like: fonts, themes, clipart, and wallpaper are OK. + +Content still has to be reviewed for inclusion. +It must have an open source compatible license, +must not be legally questionable. +In addition, there are several additional restrictions for content: + +* Content must not be pornographic, + or contain nudity, + whether animated, simulated, or photographed. + There are better places on the Internet to get porn. +* Content should not be offensive, discriminatory, or derogatory. + If you're not sure if a piece of content is one of these things, + it probably is. +* All content is subject to review by FESCo, + who has the final say on whether or not it can be included. Some examples of content which is permissible: * Package documentation or help files. * Clipart for use in office suites. -* Background images (non-offensive, discriminatory, with permission to freely redistribute). +* Background images (non-offensive, discriminatory, + with permission to freely redistribute). * Fonts (under an open source license, with no ownership/legal concerns). * Game levels are not considered content, since games without levels would be non functional. * Sound or graphics included with the source tarball that the program or theme uses (or the documentation uses) are acceptable. -* Game music or audio content is permissible, as long as the content is freely distributable without restriction, and the format is not patent encumbered. +* Game music or audio content is permissible, + as long as the content is freely distributable without restriction, + and the format is not patent encumbered. * Example files included with the source tarball are not considered content. Some examples of content which are not permissible: @@ -47,28 +76,44 @@ Some examples of content which are not permissible: * Religious texts * Files in patent-encumbered media formats -If you are unsure if something is considered approved content, ask the {packaging-committee} or, if your question is of a legal nature, {legal-team}. +If you are unsure if something is considered approved content, +ask the {packaging-committee} or, if your question is of a legal nature, {legal-team}. == Packages which are not useful without external code -Some software is not functional or useful without the presence of external code dependencies in the runtime operating system environment. When those external code dependencies are non-free, legally unacceptable, or binary-only (with the exception of permissible firmware), then the dependent software is not acceptable for inclusion in Fedora. If the code dependencies are acceptable for Fedora, then they should be packaged and included in Fedora as a pre-requisite for inclusion of the dependent software. Software which downloads code bundles from the internet in order to be functional or useful is not acceptable for inclusion in Fedora (regardless of whether the downloaded code would be acceptable to be packaged in Fedora as a proper dependency). +Some software is not functional or useful without the presence of external code dependencies in the runtime operating system environment. +When those external code dependencies are non-free, +legally unacceptable, +or binary-only (with the exception of permissible firmware), +then the dependent software is not acceptable for inclusion in Fedora. +If the code dependencies are acceptable for Fedora, +then they should be packaged and included in Fedora as a pre-requisite for inclusion of the dependent software. +Software which downloads code bundles from the internet in order to be functional or useful +is not acceptable for inclusion in Fedora +(regardless of whether the downloaded code would be acceptable +to be packaged in Fedora as a proper dependency). This also means that packages which are not functional or useful without code or packages from third-party sources are not acceptable for inclusion in Fedora. == Only one kernel package -Fedora allows only a single kernel package; packages containing alternate kernels are not allowed in the distribution. If there are kernel features which would be generally useful, please communicate with the {kernel-team}. +Fedora allows only a single kernel package; packages containing alternate kernels are not allowed in the distribution. +If there are kernel features which would be generally useful, +please communicate with the {kernel-team}. == No external kernel modules -Fedora does not allow kernel modules to be packaged outside of the main kernel package. You should communicate with the {kernel-team} regarding enabling additional kernel modules. +Fedora does not allow kernel modules to be packaged outside of the main kernel package. +You should communicate with the {kernel-team} regarding enabling additional kernel modules. [#prebuilt-binaries-or-libraries] == No inclusion of pre-built binaries or libraries -All program binaries and program libraries included in Fedora packages must be built from the source code that is included in the source package. This is a requirement for the following reasons: +All program binaries and program libraries included in Fedora packages must be built from the source code that is included in the source package. +This is a requirement for the following reasons: -* Security: Pre-packaged program binaries and program libraries not built from the source code could contain parts that are malicious, dangerous, or just broken. Also, these are functionally impossible to patch. +* Security: Pre-packaged program binaries and program libraries not built from the source code could contain parts that are malicious, dangerous, or just broken. + Also, these are functionally impossible to patch. * Compiler Flags: Pre-packaged program binaries and program libraries not built from the source code were probably not compiled with standard Fedora compiler flags for security and optimization. Content binaries (such as .pdf, .png, .ps files) are _not_ required to be rebuilt from the source code. @@ -79,11 +124,13 @@ If you are in doubt as to whether something is considered a program binary or a * Does it contain a `+.so+`, `+.so.#+`, or `+.so.#.#.#+` extension? If so, it is probably a program library. * If in doubt, ask your reviewer. If the reviewer is not sure, they should ask the Fedora Packaging Committee. -Packages which require non-open source components to build are also not permitted (e.g. proprietary compiler required). +Packages which require non-open source components to build are also not permitted +(e.g. proprietary compiler required). When you encounter prebuilt binaries in a package you *MUST*: -* Remove all pre-built program binaries and program libraries in %prep prior to the building of the package. Examples include, but are not limited to, `+*.class+`, `+*.dll+`, `+*.DS_Store+`, `+*.exe+`, `+*.jar+`, `+*.o+`, `+*.pyc+`, `+*.pyo+`, `+*.egg+`, `+*.so+`, `+*.swf+` files. +* Remove all pre-built program binaries and program libraries in %prep prior to the building of the package. + Examples include, but are not limited to, `+*.class+`, `+*.dll+`, `+*.DS_Store+`, `+*.exe+`, `+*.jar+`, `+*.o+`, `+*.pyc+`, `+*.pyo+`, `+*.egg+`, `+*.so+`, `+*.swf+` files. * Ask upstream to remove the binaries in their next release. === Exceptions @@ -97,7 +144,10 @@ When you encounter prebuilt binaries in a package you *MUST*: Often a package will contain code which was itself generated by other code. This often takes the form of configure files or parsing code generated by bison/yacc or lex/flex. -It is required that the original source files from which the code was generated be included in the source package. Generally these files are part of the source archive supplied by upstream, but it may be necessary to fetch those files from an upstream source repository and include them in the source package as separate Source: entries. +It is required that the original source files from which the code was generated be included in the source package. +Generally these files are part of the source archive supplied by upstream, +but it may be necessary to fetch those files from an upstream source repository +and include them in the source package as separate Source: entries. It is preferred, but not required, that the tools used to generate such code be free software and included in Fedora.