From 0d72dd50c658fd2dbcc0e62eff1754688a049046 Mon Sep 17 00:00:00 2001 From: Frank Dana (FeRD) Date: Apr 12 2022 00:18:01 +0000 Subject: Tag specfile example source Enable syntax-highlighting of .spec file snippets by tagging them as source code in the 'rpm-spec' language. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 6faf292..40cbb35 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -329,7 +329,8 @@ while the keyring must be committed directly to the package SCM. The following format must be used: -.... +[source, rpm-spec] +---- Source0: ftp://ftp.example.com/pub/foo/%{name}-%{version}.tar.gz Source1: ftp://ftp.example.com/pub/foo/%{name}-%{version}.tar.gz.asc Source2: https://www.example.com/gpgkey-0123456789ABCDEF0123456789ABCDEF.gpg @@ -338,7 +339,7 @@ BuildRequires: gnupg2 … %prep %{gpgverify} --keyring='%{SOURCE2}' --signature='%{SOURCE1}' --data='%{SOURCE0}' -.... +---- The first source is the actual tarball, the second one is the signature from upstream, @@ -374,7 +375,8 @@ but distributing a compressed version, then the verification step must be adjusted accordingly, for example: -.... +[source, rpm-spec] +---- Source0: ftp://ftp.example.com/pub/foo/%{name}-%{version}.tar.xz Source1: ftp://ftp.example.com/pub/foo/%{name}-%{version}.tar.asc Source2: https://www.example.com/gpgkey-0123456789ABCDEF0123456789ABCDEF.gpg @@ -383,7 +385,7 @@ BuildRequires: gnupg2 xz … %prep xzcat '%{SOURCE0}' | %{gpgverify} --keyring='%{SOURCE2}' --signature='%{SOURCE1}' --data=- -.... +---- Packages that are vital during bootstrapping of Fedora may use a <> @@ -453,11 +455,12 @@ You can limit both the architectures used to build a noarch package, and the repositories to which the built noarch package will be added, by using either the `+ExcludeArch:+` or `+ExclusiveArch:+` tags: -.... +[source, rpm-spec] +---- BuildArch: noarch # List the arches that the dependent package builds on below ExclusiveArch: %{ix86} %{arm} x86_64 noarch -.... +---- Sometimes a language runtime you are packaging for will provide a macro for the arches it's available on, for instance, @@ -474,11 +477,12 @@ Packages MUST NOT have `+Source:+` or `+Patch:+` tags which are conditionalized on architecture. For example, this is forbidden: -.... +[source, rpm-spec] +---- %ifarch ppc64 Patch0: build-fix-for-ppc64.patch %endif -.... +---- Conditionalizing `+Source:+` or `+Patch:+` tags by architecture causes the contents of the source package to differ @@ -494,13 +498,14 @@ and to use the `+%patch+` macro to apply each patch using `+%ifarch+` or `+%ifnarch+` as appropriate. For example: -.... +[source, rpm-spec] +---- %prep %setup -q %ifarch s390x %patch0 -p1 %endif -.... +---- == Filesystem Layout @@ -669,10 +674,11 @@ rpm file dependencies don't work according to what's on the filesystem, they work according to the path specified in the rpm `+%files+` section. So an rpm which specified: -.... +[source, rpm-spec] +---- %files /bin/sh -.... +---- would be able to satisfy a file dependency for `+/bin/sh+` but not for `+/usr/bin/sh+`. @@ -690,12 +696,13 @@ as to which directory a program is placed in, you can use a Virtual Provides to list the alternate path. For instance: -.... +[source, rpm-spec] +---- Provides: %{_sbindir}/ifconfig [...] %files /sbin/ifconfig -.... +---- If you are a packager who uses file dependencies to Require the proper dependencies @@ -792,15 +799,17 @@ A dependency is made arch-specific by appending the macro `+%{?_isa}+` to the package name. For example: -.... +[source, rpm-spec] +---- Requires: foo -.... +---- becomes: -.... +[source, rpm-spec] +---- Requires: foo%{?_isa} -.... +---- If the foo-devel package has a foo-config script, you can try doing a foo-config --libs and foo-config --cflags @@ -897,11 +906,12 @@ explicit library dependencies should typically be arch-specific (unless the packages involved are noarch) and there should be a spec file comment justifying it: -.... +[source, rpm-spec] +---- # The automatic dependency on libfubar.so.1 is insufficient, # as we strictly need at least the release that fixes two segfaults. Requires: libfubar%{?_isa} >= 0:1.2.3-7 -.... +---- Packagers should revisit an explicit dependency as appropriate to avoid it becoming inaccurate and superfluous. @@ -937,10 +947,11 @@ The arch ends up in the built SRPM but SRPMs need to be architecture independent. For instance, if you did this: -.... +[source, rpm-spec] +---- # Example of what *not* to do BuildRequires: foo%{?_isa} >= 3.3 -.... +---- Then the SRPM that is built in Fedora would have one of these Requirements depending on what builder the SRPM was created on: @@ -1091,28 +1102,36 @@ to easily spot the changes that you make. If a particular change is related to a Bugzilla bug, include the bug ID in the changelog entry for easy reference, e.g. -.... +[source, rpm-spec] +---- +%changelog * Wed Jun 14 2003 Joe Packager - 1.0-2 - Added README file (#42). -.... +---- You must use one of the following formats: -.... +[source, rpm-spec] +---- +%changelog * Fri Jun 23 2006 Jesse Keating - 0.6-4 - And fix the link syntax. -.... +---- -.... +[source, rpm-spec] +---- +%changelog * Fri Jun 23 2006 Jesse Keating 0.6-4 - And fix the link syntax. -.... +---- -.... +[source, rpm-spec] +---- +%changelog * Fri Jun 23 2006 Jesse Keating - 0.6-4 - And fix the link syntax. -.... +---- Changelog entries should provide a brief summary of the changes done to the package between releases, @@ -1139,21 +1158,25 @@ There are two supported methods for doing this: In this situation, you have added this changelog entry, but have not built the package yet: -.... +[source, rpm-spec] +---- +%changelog * Nov 12 2010 Toshio Kuratomi - 1.0-1 - Fix spelling errors in package description -.... +---- The next day, you make additional changes to the spec, and need to add a new changelog line, then you would update the existing date line for 1.0-1, and append any new notes, making the changelog look like this: -.... +[source, rpm-spec] +---- +%changelog * Nov 13 2010 Toshio Kuratomi - 1.0-1 - Fix spelling errors in package description - Add a patch to fix compilation problems on F15 -.... +---- Please remember that this is only acceptable if 1.0-1 has not yet been built. @@ -1168,23 +1191,27 @@ as described in <>. In this situation, you have added this changelog entry, but have not built the package yet: -.... +[source, rpm-spec] +---- +%changelog * Nov 12 2010 Toshio Kuratomi - 1.0-1 - Fix spelling errors in package description -.... +---- The next day, you make additional changes to the spec, and need to add a new changelog line. Now, you can add an additional changelog item with the new date, but the same Version-Release, so your new changelog looks like this: -.... +[source, rpm-spec] +---- +%changelog * Nov 13 2010 Toshio Kuratomi - 1.0-1 - Add a patch to fix compilation problems on F15 * Nov 12 2010 Toshio Kuratomi - 1.0-1 - Fix spelling errors in package description -.... +---- Please remember that this is only acceptable if 1.0-1 has not yet been built. @@ -1207,10 +1234,11 @@ note that RPM will re-compress them into its preferred format. So the `+%files+` section MUST reference manpages with a pattern that takes this into account: -.... +[source, rpm-spec] +---- %files %{_mandir}/man1/foo.1* -.... +---- Note also that files installed in `+%{_mandir}+` are automatically marked by RPM as documentation. @@ -1244,9 +1272,10 @@ should document the reason for this decision in a comment in the spec file. If clang is being used to build a package, packagers must set the %toolchain macro to clang: -.... +[source, rpm-spec] +---- %global toolchain clang -.... +---- This ensures that Fedora's clang-specific compiler flags are used when compiling. @@ -1255,10 +1284,11 @@ If a packager wants to use conditional macros in a spec file to make it easier to switch between two different compilers, then the following macros names should be used: -.... +[source, rpm-spec] +---- %bcond_with toolchain_clang %bcond_with toolchain_gcc -.... +---- Packagers may also use the %build_cc, %build_cxx, or %build_cpp macros in the spec file in place of hard-coding the compiler name. @@ -1305,9 +1335,10 @@ of the executable code in the binary, such as return-to-libc attacks. In Fedora, PIE is enabled by default. To disable it in your spec, add: -.... +[source, rpm-spec] +---- %undefine _hardened_build -.... +---- If your package meets any of the following criteria you MUST NOT disable the PIE compiler flags: @@ -1438,9 +1469,10 @@ When a subpackage requires the base package, it must do so using a fully versioned arch-specific (for non-noarch packages) dependency: -.... +[source, rpm-spec] +---- Requires: %{name}%{?_isa} = %{version}-%{release} -.... +---- == Shared Libraries @@ -1576,11 +1608,12 @@ When a package only provides static libraries you MAY place all the static library files in the _*-devel_ subpackage. When doing this you also MUST have a virtual Provide for the _*-static_ package: - -.... ++ +[source, rpm-spec] +---- %package devel Provides: foo-static = %{version}-%{release} -.... +---- Packages which explicitly need to link against the static version MUST `+BuildRequire: foo-static+`, @@ -1602,10 +1635,11 @@ they act just like static libraries and need to be treated as such. Place all of the header files in the _*-devel_ subpackage and then you must have a virtual Provide for the _*-static_ package: -.... +[source, rpm-spec] +---- %package devel Provides: foo-static = %{version}-%{release} -.... +---- Packages which use the header library must `+BuildRequire: foo-static+`, so that the usage can be tracked. @@ -1718,11 +1752,12 @@ in the _rpmdevtools_ package. It is a good idea to add it to the `+%__arch_install_post+` macro in your `+~/.rpmmacros+` config file: -.... -%__arch_install_post \ +[source, rpm-spec] +---- +%__arch_install_post \ /usr/lib/rpm/check-rpaths \ /usr/lib/rpm/check-buildroot -.... +---- When _check-rpaths_ is run, you might see output like this: @@ -1792,11 +1827,12 @@ try passing the _--disable-rpath_ flag to configure. * If the application uses a local copy of libtool, add the following lines to the spec after %configure: -.... +[source, rpm-spec] +---- %configure sed -i 's|^hardcode_libdir_flag_spec=.*|hardcode_libdir_flag_spec=""|g' libtool sed -i 's|^runpath_var=LD_RUN_PATH|runpath_var=DIE_RPATH_DIE|g' libtool -.... +---- * Sometimes, the code/Makefiles can be patched to remove the _-rpath_ or _-R_ flag from being called. @@ -1928,23 +1964,26 @@ or there are changes desired to the .desktop file if the .desktop file's content/location does not need modification. Here are some examples of usage: -.... +[source, rpm-spec] +---- desktop-file-install \ --dir=%{buildroot}%{_datadir}/applications \ %{SOURCE3} -.... +---- -.... +[source, rpm-spec] +---- desktop-file-install \ --add-category="AudioVideo" \ --delete-original \ --dir=%{buildroot}%{_datadir}/applications \ %{buildroot}/%{_datadir}/applications/foo.desktop -.... +---- -.... +[source, rpm-spec] +---- desktop-file-validate %{buildroot}/%{_datadir}/applications/foo.desktop -.... +---- Do *not* apply a vendor tag to .desktop files (using --vendor). @@ -2158,16 +2197,18 @@ or else your package could fail to generate translation files in the buildroot. If the package uses gettext for translations, add -.... +[source, rpm-spec] +---- BuildRequires: gettext -.... +---- For Qt-based packages that use the Linguist tool chain, for the localization utilities add -.... +[source, rpm-spec] +---- BuildRequires: qt-devel -.... +---- If you have few enough locale files that they can all go into one package, you can use the `+%find_lang+` macro. @@ -2180,9 +2221,10 @@ You can then use that file to include all of the locales. after all of the files have been installed into the buildroot. The correct syntax for `+%find_lang+` is usually: -.... +[source, rpm-spec] +---- %find_lang %{name} -.... +---- In some cases, the application may use a different "name" for its locales. You may have to look at the locale files and see what they are named. @@ -2198,39 +2240,44 @@ You should then use this file in the `+%files+` list to include the locales detected by `+%find_lang+`. To do this, you should include it with the -f parameter to `+%files+`. -.... +[source, rpm-spec] +---- %files -f %{name}.lang %{_bindir}/foobar ... -.... +---- Note that `+%find_lang+` by default searches for gettext locales, but it can also handle Qt translations, localised manpages and help files. To process GNOME help files put into `+/usr/share/gnome/help/+` use -.... +[source, rpm-spec] +---- %find_lang %{name} --with-gnome -.... +---- To process KDE help files put into `+/usr/share/doc/HTML/+` use -.... +[source, rpm-spec] +---- %find_lang %{name} --with-kde -.... +---- To process Qt's `+.qm+` binary translation files use -.... +[source, rpm-spec] +---- %find_lang %{name} --with-qt -.... +---- To process localised manpages (doesn't include the default, non-localised one), use -.... +[source, rpm-spec] +---- %find_lang %{name} --with-man -.... +---- To see all the options, run `+/usr/lib/rpm/find-lang.sh+` in the terminal. @@ -2241,7 +2288,8 @@ Here is an example of proper usage of `+%find_lang+`, in `+foo.spec+` with the "foo" application localised using gettext and man pages named "bar" instead of "foo": -.... +[source, rpm-spec] +---- Name: foo ... %prep @@ -2268,7 +2316,7 @@ make DESTDIR=%{buildroot} install * Thu May 4 2006 Tom "spot" Callaway 0.1-1 - sample spec that uses %%find_lang -.... +---- === Why do we need to use %find_lang? @@ -2280,14 +2328,15 @@ also grab ownership of the locale directories, which is not permitted. * Most packages that have locales have lots of locales. Using `+%find_lang+` is much easier in the spec file than having to do: -.... +[source, rpm-spec] +---- %{_datadir}/locale/ar/LC_MESSAGES/%{name}.mo %{_datadir}/locale/be/LC_MESSAGES/%{name}.mo %{_datadir}/locale/cs/LC_MESSAGES/%{name}.mo %{_datadir}/locale/de/LC_MESSAGES/%{name}.mo %{_datadir}/locale/es/LC_MESSAGES/%{name}.mo ... -.... +---- * As new locale files appear in later package revisions, `+%find_lang+` will automatically include them when it is run, @@ -2346,9 +2395,10 @@ and for curl, add to your `+~/.curlrc+`: `+-R+`. Whenever possible, invocations of `+make+` should be done as -.... +[source, rpm-spec] +---- %make_build -.... +---- This generally speeds up builds and especially on SMP machines. @@ -2356,9 +2406,10 @@ Do make sure, however, that the package builds cleanly this way as some make files do not support parallel building. Therefore you should consider adding -.... +[source, rpm-spec] +---- %_smp_mflags -j3 -.... +---- to your `+~/.rpmmacros+` file -- even on UP machines -- as this will expose most of these errors. @@ -2660,20 +2711,22 @@ 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: -.... +[source, rpm-spec] +---- # 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: -.... +[source, rpm-spec] +---- # Don't crash with frobnicator applet # https://bugzilla.gnome.org/show_bug.cgi?id=12345 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 @@ -2685,24 +2738,27 @@ by knowing what patches are likely to appear in a new upstream release. You can indicate that you have sent the patch upstream and any known status: -.... +[source, rpm-spec] +---- # Sent upstream via email 20080407 Patch: foobar-fix-the-bar.patch -.... +---- -.... +[source, rpm-spec] +---- # Upstream has applied this in SVN trunk 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: -.... +[source, rpm-spec] +---- # This patch is temporary until we land the long term System.loadLibrary fix in OpenJDK Patch: jna-jni-path.patch -.... +---- === Applying Patches @@ -2750,11 +2806,12 @@ RPM treats it the same as if it was set to 0. Example: -.... +[source, rpm-spec] +---- Version: 1.2 Release: 3%{?dist} Epoch: 1 -.... +---- A package with those definitions would be considered greater than a package with a higher version or a higher release. @@ -2770,9 +2827,10 @@ it must be referred to in any place where `+%{version}-%{release}+` is used. For example, if a package being depended upon has an Epoch, this must be listed when adding a versioned dependency: -.... +[source, rpm-spec] +---- Requires: foo = %{epoch}:%{version}-%{release} -.... +---- === Epochs from Third Party Repositories @@ -2851,17 +2909,19 @@ If you install a sysctl configuration snippet foobar.conf into %\{_sysctldir} (/usr/lib/sysctl.d/) you must invoke %sysctl_apply in your %post section: -.... +[source, rpm-spec] +---- %sysctl_apply foobar.conf -.... +---- If you install a binfmt configuration snippet waldo.conf into %\{_binfmtdir} (/usr/lib/binfmt.d/) you must invoke %binfmt_apply in your %post section: -.... +[source, rpm-spec] +---- %binfmt_apply waldo.conf -.... +---- These have the effect of making the appropriate changes immediately upon package installation @@ -2887,10 +2947,11 @@ or is a compatible enough replacement to an existing package that are commonly found in version upgrade changes), provide clean upgrade paths and compatibility with: -.... +[source, rpm-spec] +---- Provides: oldpackagename = $provEVR Obsoletes: oldpackagename < $obsEVR -.... +---- $provEVR refers to an (Epoch-)Version-Release tuple the original unchanged package would have had @@ -2934,10 +2995,11 @@ and the last foo package release being foo-1.0-3%\{?dist} with Epoch: 2. The following should be added to bar (and similarly for all subpackages as applicable): -.... +[source, rpm-spec] +---- Provides: foo = 2:%{version}-%{release} Obsoletes: foo <= 2:1.0-4 # Important: We set the Obsoletes release to 4 to be higher than the previous Release: 3%{?dist} -.... +---- Explicit `+Provides:+` need to be aware of whether the package is supplying things that can be used in an arch-independent @@ -3035,7 +3097,8 @@ only from the lookaside cache and/or the Fedora git repository. If your package introduces build time circular dependencies, you should use this macro to bootstrap your package: -.... +[source, rpm-spec] +---- # When we are bootstrapping, we drop some dependencies, and/or build time tests. %bcond_with bootstrap @@ -3052,7 +3115,7 @@ BuildRequires: foo %check make check %endif -.... +---- TIP: Since Fedora 30, as a nice side-effect, @@ -3073,11 +3136,12 @@ If your package explicitly `+Provides:+` some functionality that is missing when bootstrapped, then that `+Provides:+` should look like: -.... +[source, rpm-spec] +---- %if %{without bootstrap} Provides: bar(some_functionality) %endif -.... +---- Please note that usage of pre-built binaries in bootstrap still needs an exception from the Packaging Committee @@ -3144,11 +3208,12 @@ It is possible to disable any BRP script simply by defining the corresponding variable to `+%{nil}+`. For example, to disable the brp-python-bytecompile script: -.... +[source, rpm-spec] +---- # Turn off Python bytecode compilation because this is a Jython # package and we will generate JVM bytecode instead %global __brp_python_bytecompile %{nil} -.... +---- Any package that disables a BRP script this way MUST also note the reason in an accompanying comment.