From c47ef0933630c7c0c6f1fafa2ea4e59cd4e5725b Mon Sep 17 00:00:00 2001 From: Otto Liljalaakso Date: Apr 17 2023 18:56:18 +0000 Subject: [PATCH 1/3] Improve initial specfile in GNU Hello tutorial The packaging tutorial used to create the initial specfile with rpmdev-newspec, only to proceed to present a different initial specfile to be used. Still, some paragraphs later on referred to contents of rpmdev-newspec-generated specfile. Also, the tutorial starts with downloading upstream sources with wget even before creating the initial specfile. This leaves the relationship between downloaded sources and the specfile's Source tag unclear. These issues have confused people attempting to follow the tutorial, see [1,2]. Improve the tutorial by: * Just mentioning rpmdev-newspec, but instructing to simply paste the initial specfile from the tutorial. * Downloading upstream source only after the initial specfile has been created, with 'spectool -g' like local downloads are normally done. [1]: https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/thread/S3IQAJ6UASA2AZ43PVA3O3RMQX7EUMGO/ [2]: https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/message/HKEBC6YQS4CE4QAZTWTNARA4YWRLFZLN/ Signed-off-by: Otto Liljalaakso --- diff --git a/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc b/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc index 5bddc43..b52e103 100644 --- a/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc +++ b/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc @@ -39,33 +39,27 @@ you can peek there. Follow xref:Installing_Packager_Tools.adoc[Installing Packager Tools]. [#building] -== Building the RPM +== Creating the package directory -We need the source code of the project we are packaging, -often referred to as the _upstream_ source. -We will download it from the project's website -into a directory we create for packaging GNU Hello. -We are getting the compressed tarball archive, -which happens to be the preferred distribution form for most FOSS projects. +In Fedora, package build instructions are organized in so called dist-git repositories. +There is a separate repository for each package. +We mimick this system by creating a new directory for this tutorial. +In dist-git, the repository name matches the package name. +Fedora's rules for naming packages are written in https://docs.fedoraproject.org/en-US/packaging-guidelines/Naming/[Naming Guidelines]. +For GNU Hello, package can simply be named `hello`. +This is also the name of Fedora's https://packages.fedoraproject.org/pkgs/hello/hello/[official GNU Hello package]. ---- $ mkdir hello && cd hello -$ wget http://ftp.gnu.org/gnu/hello/hello-2.10.tar.gz ----- - -The RPM package is configured by `.spec` files. -We will create a template file `hello.spec`: - ----- -$ rpmdev-newspec hello ---- [#inside_spec] == Inside a Spec File -The fields in our `.spec` file need slight editing. -Please follow RPM Reference Manual's section https://rpm-software-management.github.io/rpm/manual/spec.html[Spec file format] for these fields. -In our case, the file might start as follows: +RPM packages are configured by `.spec` files. +Tools such was `rpmdev-newspec` can be used to generate empty specfiles for different purposes. +For this tutorial, just create a file called `hello.spec` and paste the following minimal specfile. +It does not work yet, but we will try to build it and fix errors as we encounter them. [source, rpm-spec] ---- @@ -75,7 +69,7 @@ Release: %autorelease Summary: Produces a familiar, friendly greeting License: GPL-3.0-or-later URL: https://www.gnu.org/software/hello/ -Source: https://ftp.gnu.org/gnu/hello/hello-%{version}.tar.gz +Source: http://ftp.gnu.org/gnu/hello/hello-%{version}.tar.gz %description The GNU Hello program produces a familiar, friendly greeting. Yes, this is @@ -98,44 +92,58 @@ you run it. %autochangelog ---- -The `+Version+` should mirror the upstream, -while `+Release+` numbers our work within Fedora. -`+%autorelease+` is part of https://docs.pagure.org/fedora-infra.rpmautospec/index.html[rpmautospec], +`+Version+` contains the version number of the packaged software. + +`+Release+` numbers specfile updates, package rebuilds and other work within Fedora. +The value used here, `+%autorelease+`, is part of https://docs.pagure.org/fedora-infra.rpmautospec/index.html[rpmautospec], which is https://fedoraproject.org/wiki/Changes/Rpmautospec_by_Default[recommended for Fedora packages]. It ties `+Release+` to package's Git history. -As we do not have a Git repository, the default value 1 will be used. +As we do not have a Git repository, `%autorelease` will evaluate to the default value of 1. -The first letter of the `+Summary+` should be uppercase -to avoid `+rpmlint+` complaints. Often, `+Summary+` and `+%description+` can be copied from the upstream README. +The first letter of the `+Summary+` should be uppercase to avoid `+rpmlint+` complaints. + +`+License+` describes the license of the resulting binary package using a SPDX license identifier. +It must follow Fedora's https://docs.fedoraproject.org/en-US/legal/license-field/[licensing guidelines]. +In practice, determining the correct value often means inspecting the license notifications in individual source files. +Upstream developers may also need to be asked for clarifications or corrections. +In this tutorial, we just take the upstream's word that the license is the GNU Public License, version 3 or later. -It is your responsibility to check the `+License+` status of the software. -Inspect the source files and their `+LICENSE+` files, -and talk to the authors as needed. +`+Source+` defines the upstream sources used when building the package. +Usually, as in this case, it is a url pointing to a tarball released by the upstream, +but it can also be a local file. +There can be multiple `+Source+` tags if needed. -The `+%changelog+` should document the work on preparing the RPM, -especially if there are security and bug patches -included on top of the base upstream source. +The `+%changelog+` documents the changes in each new package version and release. Changelog data can be displayed by `+rpm --query --changelog PACKAGE_NAME+`, -which is very useful, for instance, -to find out if specific bug and security patches were included in the installed software, -thanks to the diligent Fedora packagers who include this info -with the relevant https://cve.mitre.org/[CVE] numbers. -`+%autochangelog+` also comes from rpmautospec -and populates the changelog from Git commit messages. +which can be useful, for instance, to find out if specific bug and security patches are included. +Its value,`+%autochangelog+`, also comes from `rpmautospec`. +It populates the changelog from Git commit messages. As we do not have a Git repository, the changelog will be empty. -Multi-line sections like `+%changelog+` or `+%description+` -start on a line under the directive, +Multi-line sections like `+%changelog+` or `+%description+` start on a line under the directive, and end when the next section starts or the file ends. -Lines which are not needed (e.g. `+BuildRequires+` and `+Requires+`) -can be commented out with the hash `+#+` for now. +Lines which are not needed can be commented out with the hash `+#+`. + +You can find more information about these fields the RPM Reference Manual's section https://rpm-software-management.github.io/rpm/manual/spec.html[Spec file format]. + +== Downloading source -In many cases, -many lines in the template do not need to be changed at all, -at least for the initial attempt. +We need the source code defined by the `+Source+` tag, often referred to as the _upstream_ source. +This is most easily achieved by using the `spectool` command: + +---- +$ spectool -g hello.spec +---- + +You should now have the file listed in `+Source+` in your working directory: + +---- +$ ls *.tar.gz +hello-2.10.tar.gz +---- == Building the Package From dbb65ad014e56278abab9a206c82a6d0d9373a2b Mon Sep 17 00:00:00 2001 From: Otto Liljalaakso Date: Apr 17 2023 18:56:18 +0000 Subject: [PATCH 2/3] Explain URL tag's meaning in Packaging Tutorial Signed-off-by: Otto Liljalaakso --- diff --git a/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc b/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc index b52e103..7722cc1 100644 --- a/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc +++ b/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc @@ -110,6 +110,8 @@ In practice, determining the correct value often means inspecting the license no Upstream developers may also need to be asked for clarifications or corrections. In this tutorial, we just take the upstream's word that the license is the GNU Public License, version 3 or later. +`+URL+` points to upstream project's website. + `+Source+` defines the upstream sources used when building the package. Usually, as in this case, it is a url pointing to a tarball released by the upstream, but it can also be a local file. From 928e2bf5701b4bdee25697c1233f5933578869ac Mon Sep 17 00:00:00 2001 From: Otto Liljalaakso Date: Apr 17 2023 18:56:18 +0000 Subject: [PATCH 3/3] Describe specfile tags and sections in the tutorial Rpm specfile syntax is quite confusing in that both section names and macros are marked with the percent sign '%'. To avoid misunderstanding of contents of the initial specfile, add discussion of specfile tags, specfile sections and rpm macros. Signed-off-by: Otto Liljalaakso --- diff --git a/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc b/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc index 7722cc1..c3363b0 100644 --- a/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc +++ b/modules/ROOT/pages/Packaging_Tutorial_GNU_Hello.adoc @@ -92,6 +92,16 @@ you run it. %autochangelog ---- +The specfile starts with a set of _tags_, such as `Name:` and `Version:`, +followed by _sections_ such as `%description` and `%prep`. +Each tag fits into a single line, whereas each section continues until the next one starts. + +Note that, confusingly, in addition to marking the section names, +the percent sign `%` also marks RPM _macros_. +Thus e.g. `%autosetup`, `%configure` and `%make_build` are not sections. + +=== Tags + `+Version+` contains the version number of the packaged software. `+Release+` numbers specfile updates, package rebuilds and other work within Fedora. @@ -101,8 +111,8 @@ It ties `+Release+` to package's Git history. As we do not have a Git repository, `%autorelease` will evaluate to the default value of 1. -Often, `+Summary+` and `+%description+` can be copied from the upstream README. -The first letter of the `+Summary+` should be uppercase to avoid `+rpmlint+` complaints. +Often, `+Summary+` can be copied from the upstream README. +The first letter should be uppercase to avoid `+rpmlint+` complaints. `+License+` describes the license of the resulting binary package using a SPDX license identifier. It must follow Fedora's https://docs.fedoraproject.org/en-US/legal/license-field/[licensing guidelines]. @@ -117,6 +127,28 @@ Usually, as in this case, it is a url pointing to a tarball released by the upst but it can also be a local file. There can be multiple `+Source+` tags if needed. +=== Sections + +`+%description+` can often be copied from upstream README. + +`%prep` contains a shell script for preparing the sources for building. +It is often just the single macro `%autosetup`, +which, in this case, simply extracts the source. + +`%build` contains a shell script for the required build steps, +such as compiling sources to binaries. +GNU Hello uses https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html[Autotools] as its buildsystem, +so building involves running `configure` and `make`. +Macros `%configure` and `%make_build` invoke these commands using Fedora's compilation flags and other configuration. + +`%install` contains a shell script to copy the results from `%build` into an initially empty _build root_ directory. +As GNU Hello is using Autotools, macro `%make_install` is used. + +`%files` lists the content of the resulting package. +Mostly, the files come from the build root created in the `%install`, +but documentation and license files can also be added directly from the sources. +This section is left empty for now, to be filled later. + The `+%changelog+` documents the changes in each new package version and release. Changelog data can be displayed by `+rpm --query --changelog PACKAGE_NAME+`, which can be useful, for instance, to find out if specific bug and security patches are included. @@ -124,12 +156,9 @@ Its value,`+%autochangelog+`, also comes from `rpmautospec`. It populates the changelog from Git commit messages. As we do not have a Git repository, the changelog will be empty. -Multi-line sections like `+%changelog+` or `+%description+` start on a line under the directive, -and end when the next section starts or the file ends. - Lines which are not needed can be commented out with the hash `+#+`. -You can find more information about these fields the RPM Reference Manual's section https://rpm-software-management.github.io/rpm/manual/spec.html[Spec file format]. +You can find more information in the RPM Reference Manual's section https://rpm-software-management.github.io/rpm/manual/spec.html[Spec file format]. == Downloading source