Create an account


Thread Rating:
  • 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Fedora - How RPM packages are made: the spec file

#1
How RPM packages are made: the spec file

<div><p>In the <a href="https://fedoramagazine.org/how-rpm-packages-are-made-the-source-rpm/">previous article on RPM package building</a>, you saw that source RPMS include the source code of the software, along with a “spec” file. This post digs into the spec file, which contains instructions on how to build the RPM. Again, this article uses <em>fpaste</em> as an example.</p>
<p> <span id="more-29207"></span> </p>
<h2>Understanding the source code</h2>
<p>Before you can start writing a spec file, you need to have some idea of the software that you’re looking to package. Here, you’re looking at fpaste, a very simple piece of software. It is written in Python, and is a one file script. When a new version is released, it’s provided here on Pagure: <a href="https://pagure.io/releases/fpaste/fpaste-0.3.9.2.tar.gz">https://pagure.io/releases/fpaste/fpaste-0.3.9.2.tar.gz</a></p>
<p>The current version, as the archive shows, is 0.3.9.2. Download it so you can see what’s in the archive:</p>
<pre class="wp-block-preformatted">$ <strong>wget https://pagure.io/releases/fpaste/fpaste...gz</strong>
$ <strong>tar -tvf fpaste-0.3.9.2.tar.gz</strong>
drwxrwxr-x root/root 0 2018-07-25 02:58 fpaste-0.3.9.2/
-rw-rw-r-- root/root 25 2018-07-25 02:58 fpaste-0.3.9.2/.gitignore
-rw-rw-r-- root/root 3672 2018-07-25 02:58 fpaste-0.3.9.2/CHANGELOG
-rw-rw-r-- root/root 35147 2018-07-25 02:58 fpaste-0.3.9.2/COPYING
-rw-rw-r-- root/root 444 2018-07-25 02:58 fpaste-0.3.9.2/Makefile
-rw-rw-r-- root/root 1656 2018-07-25 02:58 fpaste-0.3.9.2/README.rst
-rw-rw-r-- root/root 658 2018-07-25 02:58 fpaste-0.3.9.2/TODO
drwxrwxr-x root/root 0 2018-07-25 02:58 fpaste-0.3.9.2/docs/
drwxrwxr-x root/root 0 2018-07-25 02:58 fpaste-0.3.9.2/docs/man/
drwxrwxr-x root/root 0 2018-07-25 02:58 fpaste-0.3.9.2/docs/man/en/
-rw-rw-r-- root/root 3867 2018-07-25 02:58 fpaste-0.3.9.2/docs/man/en/fpaste.1
-rwxrwxr-x root/root 24884 2018-07-25 02:58 fpaste-0.3.9.2/fpaste
lrwxrwxrwx root/root 0 2018-07-25 02:58 fpaste-0.3.9.2/fpaste.py -&gt; fpaste
</pre>
<p>The files you want to install are:</p>
<ul>
<li><em>fpaste.py</em>: which should go be installed to /usr/bin/.</li>
<li><em>docs/man/en/fpaste.1</em>: the manual, which should go to /usr/share/man/man1/.</li>
<li><em>COPYING</em>: the license text, which should go to /usr/share/license/fpaste/.</li>
<li><em>README.rst, TODO</em>: miscellaneous documentation that goes to /usr/share/doc/fpaste.</li>
</ul>
<p>Where these files are installed depends on the Filesystem Hierarchy Standard. To learn more about it, you can either read here: <a href="http://www.pathname.com/fhs/">http://www.pathname.com/fhs/</a> or look at the man page on your Fedora system:</p>
<pre class="wp-block-preformatted">$ man hier</pre>
<h3>Part 1: What are we building?</h3>
<p>Now that we know what files we have in the source, and where they are to go, let’s look at the spec file. You can see the full file here: <a href="https://src.fedoraproject.org/rpms/fpaste/blob/master/f/fpaste.spec">https://src.fedoraproject.org/rpms/fpaste/blob/master/f/fpaste.spec</a></p>
<p>Here is the first part of the spec file:</p>
<pre class="wp-block-preformatted">Name: fpaste
Version: 0.3.9.2
Release: 3%{?dist}
Summary: A simple tool for pasting info onto sticky notes instances
BuildArch: noarch
License: GPLv3+
URL: https://pagure.io/fpaste
Source0: https://pagure.io/releases/fpaste/fpaste-0.3.9.2.tar.gz Requires: python3 %description
It is often useful to be able to easily paste text to the Fedora
Pastebin at http://paste.fedoraproject.org and this simple script
will do that and return the resulting URL so that people may
examine the output. This can hopefully help folks who are for
some reason stuck without X, working remotely, or any other
reason they may be unable to paste something into the pastebin</pre>
<p><em>Name</em>, <em>Version</em>, and so on are called <em>tags</em>, and are defined in RPM. This means you can’t just make up tags. RPM won’t understand them if you do! The tags to keep an eye out for are:</p>
<ul>
<li><em>Source0</em>: tells RPM where the source archive for this software is located.</li>
<li><em>Requires</em>: lists run-time dependencies for the software. RPM can automatically detect quite a few of these, but in some cases they must be mentioned manually. A run-time dependency is a capability (often a package) that must be on the system for this package to function. This is how <em><a href="https://fedoramagazine.org/managing-packages-fedora-dnf/">dnf</a></em> detects whether it needs to pull in other packages when you install this package.</li>
<li><em>BuildRequires</em>: lists the build-time dependencies for this software. These must generally be determined manually and added to the spec file.</li>
<li><em>BuildArch</em>: the computer architectures that this software is being built for. If this tag is left out, the software will be built for all supported architectures. The value <em>noarch</em> means the software is architecture independent (like fpaste, which is written purely in Python).</li>
</ul>
<p>This section provides general information about fpaste: what it is, which version is being made into an RPM, its license, and so on. If you have fpaste installed, and look at its metadata, you can see this information included in the RPM:</p>
<pre class="wp-block-preformatted">$ <strong>sudo dnf install fpaste</strong>
$ <strong>rpm -qi fpaste</strong>
Name : fpaste
Version : 0.3.9.2
Release : 2.fc30
...</pre>
<p>RPM adds a few extra tags automatically that represent things that it knows.</p>
<p>At this point, we have the general information about the software that we’re building an RPM for. Next, we start telling RPM what to do.</p>
<h3>Part 2: Preparing for the build</h3>
<p>The next part of the spec is the preparation section, denoted by <em>%prep</em>:</p>
<pre class="wp-block-preformatted">%prep
%autosetup</pre>
<p>For fpaste, the only command here is %autosetup. This simply extracts the tar archive into a new folder and keeps it ready for the next section where we build it. You can do more here, like apply patches, modify files for different purposes, and so on. If you did look at the contents of the source rpm for Python, you would have seen lots of patches there. These are all applied in this section. </p>
<p>Typically anything in a spec file with the <strong>%</strong> prefix is a macro or label that RPM interprets in a special way. Often these will appear with curly braces, such as <em>%{example}</em>.</p>
<h3>Part 3: Building the software</h3>
<p>The next section is where the software is built, denoted by “%build”. Now, since fpaste is a simple, pure Python script, it doesn’t need to be built. So, here we get:</p>
<pre class="wp-block-preformatted">%build
#nothing required</pre>
<p>Generally, though, you’d have build commands here, like:</p>
<pre class="wp-block-preformatted">configure; make</pre>
<p>The build section is often the hardest section of the spec, because this is where the software is being built from source. This requires you to know what build system the tool is using, which could be one of many: Autotools, CMake, Meson, Setuptools (for Python) and so on. Each has its own commands and style. You need to know these well enough to get the software to build correctly.</p>
<h3>Part 4: Installing the files</h3>
<p>Once the software is built, it needs to be installed in the <em>%install</em> section:</p>
<pre class="wp-block-preformatted">%install
mkdir -p %{buildroot}%{_bindir}
make install BINDIR=%{buildroot}%{_bindir} MANDIR=%{buildroot}%{_mandir}</pre>
</p>
<p>RPM doesn’t tinker with your system files when building RPMs. It’s far too risky to add, remove, or modify files to a working installation. What if something breaks? So, instead RPM creates an artificial file system and works there. This is referred to as the <em>buildroot</em>. So, here in the buildroot, we create <em>/usr/bin</em>, represented by the macro <em>%{_bindir}</em>, and then install the files to it using the provided Makefile.</p>
<p>At this point, we have a built version of fpaste installed in our artificial buildroot.</p>
<h3>Part 5: Listing all files to be included in the RPM</h3>
<p>The last section of the spec file is the files section, <em>%files</em>. This is where we tell RPM what files to include in the archive it creates from this spec file. The fpaste file section is quite simple:</p>
<pre class="wp-block-preformatted">%files
%{_bindir}/%{name}
%doc README.rst TODO
%{_mandir}/man1/%{name}.1.gz
%license COPYING</pre>
<p>Notice how, here, we do not specify the buildroot. All of these paths are relative to it. The <em>%doc</em> and <em>%license</em> commands simply do a little more—they create the required folders and remember that these files must go there. </p>
<p>RPM is quite smart. If you’ve installed files in the <em>%install</em> section, but not listed them, it’ll tell you this, for example.</p>
<h3>Part 6: Document all changes in the change log</h3>
<p>Fedora is a community based project. Lots of contributors maintain and co-maintain packages. So it is imperative that there’s no confusion about what changes have been made to a package. To ensure this, the spec file contains the last section, the Changelog, <em>%changelog</em>:</p>
<pre class="wp-block-preformatted">%changelog
* Thu Jul 25 2019 Fedora Release Engineering - 0.3.9.2-3
- Rebuilt for https://fedoraproject.org/wiki/Fedora_31_Mass_Rebuild * Thu Jan 31 2019 Fedora Release Engineering - 0.3.9.2-2
- Rebuilt for https://fedoraproject.org/wiki/Fedora_30_Mass_Rebuild * Tue Jul 24 2018 Ankur Sinha - 0.3.9.2-1
- Update to 0.3.9.2 * Fri Jul 13 2018 Fedora Release Engineering - 0.3.9.1-4
- Rebuilt for https://fedoraproject.org/wiki/Fedora_29_Mass_Rebuild * Wed Feb 07 2018 Fedora Release Engineering - 0.3.9.1-3
- Rebuilt for https://fedoraproject.org/wiki/Fedora_28_Mass_Rebuild * Sun Sep 10 2017 Vasiliy N. Glazov - 0.3.9.1-2
- Cleanup spec * Fri Sep 08 2017 Ankur Sinha - 0.3.9.1-1
- Update to latest release
- fixes rhbz 1489605
...
....
</pre>
<p>There must be a changelog entry for <em>every</em> change to the spec file. As you see here, while I’ve updated the spec as the maintainer, others have too. Having the changes documented clearly helps everyone know what the current status of the spec is. For all packages installed on your system, you can use rpm to see their changelogs:</p>
<pre class="wp-block-preformatted">$ rpm -q --changelog fpaste</pre>
<h2>Building the RPM</h2>
<p>Now we are ready to build the RPM. If you want to follow along and run the commands below, please ensure that you followed the steps <a href="https://fedoramagazine.org/how-rpm-packages-are-made-the-source-rpm/">in the previous post</a> to set your system up for building RPMs. </p>
<p>We place the fpaste spec file in <em>~/rpmbuild/SPECS</em>, the source code archive in <em>~/rpmbuild/SOURCES/</em> and can now create the source RPM:</p>
<pre class="wp-block-preformatted">$ <strong>cd ~/rpmbuild/SPECS</strong>
$ <strong>wget https://src.fedoraproject.org/rpms/fpast...ec</strong> $ <strong>cd ~/rpmbuild/SOURCES</strong>
$ <strong>wget https://pagure.io/fpaste/archive/0.3.9.2...gz</strong> $ <strong>cd ~/rpmbuild/SOURCES</strong>
$ <strong>rpmbuild -bs fpaste.spec</strong>
Wrote: /home/asinha/rpmbuild/SRPMS/fpaste-0.3.9.2-3.fc30.src.rpm</pre>
<p>Let’s have a look at the results:</p>
<pre class="wp-block-preformatted">$ <strong>ls ~/rpmbuild/SRPMS/fpaste*</strong>
/home/asinha/rpmbuild/SRPMS/fpaste-0.3.9.2-3.fc30.src.rpm $ <strong>rpm -qpl ~/rpmbuild/SRPMS/fpaste-0.3.9.2-3.fc30.src.rpm</strong>
fpaste-0.3.9.2.tar.gz
fpaste.spec</pre>
<p>There we are — the source rpm has been built. Let’s build both the source and binary rpm together:</p>
<pre class="wp-block-preformatted">$ cd ~/rpmbuild/SPECS
$ rpmbuild -ba fpaste.spec
..
..
..</pre>
<p>RPM will show you the complete build output, with details on what it is doing in each section that we saw before. This “build log” is extremely important. When builds do not go as expected, we packagers spend lots of time going through them, tracing the complete build path to see what went wrong. </p>
<p>That’s it really! Your ready-to-install RPMs are where they should be:</p>
<pre class="wp-block-preformatted">$ <strong>ls ~/rpmbuild/RPMS/noarch/</strong>
fpaste-0.3.9.2-3.fc30.noarch.rpm</pre>
<h2>Recap</h2>
<p>We’ve covered the basics of how RPMs are built from a spec file. This is by no means an exhaustive document. In fact, it isn’t documentation at all, really. It only tries to explain how things work under the hood. Here’s a short recap:</p>
<ul>
<li>RPMs are of two types: <em>source</em> and <em>binary</em>.</li>
<li>Binary RPMs contain the files to be installed to use the software.</li>
<li>Source RPMs contain the information needed to build the binary RPMs: the complete source code, and the instructions on how to build the RPM in the spec file.</li>
<li>The spec file has various sections, each with its own purpose.</li>
</ul>
<p>Here, we’ve built RPMs locally, on our Fedora installations. While this is the basic process, the RPMs we get from repositories are built on dedicated servers with strict configurations and methods to ensure correctness and security. This Fedora packaging pipeline will be discussed in a future post. </p>
<p>Would you like to get started with building packages, and help the Fedora community maintain the massive amount of software we provide? You can <a href="https://fedoraproject.org/wiki/Join_the_package_collection_maintainers">start here by joining the package collection maintainers</a>.</p>
<p>For any queries, post to the <a href="https://lists.fedoraproject.org/archives/list/[email protected]/">Fedora developers mailing list</a>—we’re always happy to help!</p>
<h2>References</h2>
<p>Here are some useful references to building RPMs:</p>
<ul>
<li><a href="https://fedoraproject.org/wiki/How_to_create_an_RPM_package">https://fedoraproject.org/wiki/How_to_create_an_RPM_package</a></li>
<li><a href="https://docs.fedoraproject.org/en-US/quick-docs/create-hello-world-rpm/">https://docs.fedoraproject.org/en-US/quick-docs/create-hello-world-rpm/</a></li>
<li><a href="https://docs.fedoraproject.org/en-US/packaging-guidelines/">https://docs.fedoraproject.org/en-US/packaging-guidelines/</a></li>
<li><a href="https://rpm.org/documentation.html">https://rpm.org/documentation.html</a></li>
</ul>
<hr class="wp-block-separator" />
</div>


https://www.sickgaming.net/blog/2019/09/...spec-file/
Reply



Forum Jump:


Users browsing this thread:
2 Guest(s)

Forum software by © MyBB Theme © iAndrew 2016