RPM How To: Intro. What is RPM? Why Building RPMS? Who is this howto designed for? Who can build RPMS? What do I need to build RPMS?

Transcription

1 RPM How To: Intro What is RPM? The RedHat Package Manager (RPM) is a powerful command line driven package management system capable of installing, uninstalling, verifying, querying, and updating computer software packages. Each software package consists of an archive of files along with information about the package like its version, a description, and the like. There is also a library API, permitting advanced developers to manage such transactions from programming languages such as C or Python. RPM is free software, released under the GNU GPL. Why Building RPMS? This project is to help people wanting to learn how to create RPMs, whether it's just for yourself or if it's for the bigger community. I am doing this how to to show how to build RPMS with enough quality so that others can use the RPMS you made. If you have decided to build RPMS my way, then you are doing it to make these available to others. Who is this howto designed for? This howto will explain how to build RPMS for PCLinuxOS. I will reduce the details to cover only i586 platform as it's the only platform used by PCLinuxOS. This howto is designed for people familiar with the command line and with using rpm as an installation tool (rpm ivh, rpm Uvh force and so on). If you are not familiar with these, I'd suggest that you read up a bit about it before reading these wiki pages. Who can build RPMS? Building RPMS can vary from easy small applications to intricate libraries with inter dependencies. A typical packager will be able to read and understand the programming language in which the application is written. While the packaging process itself does not require programming skills, there might be a requirement to patch the source code to enable its installation on your system (that's where programming skills comes in handy). Please don't worry, you don't need to be a programmer to be able to build RPMS. The RPM system will help you along the way. What do I need to build RPMS? The first thing we ask is that you download TinyMe and install it to a spare partition. Next, open the menu and go to System Tools > Run Program as different user > type in scite /etc/apt/sources.list > give the root password > scroll down to the part where it says #PCLinuxOS official repos > whichever line does not have a # in front of it is the repository you are using. At the end of that line, add testing so it looks something like this: rpm pclinuxos/2007 main extra nonfree kde testing

2 Save the file and close SciTE. NOTE: If you have any problems with the testing repository, please report them to the PCLinuxOS user mailing list. Please do make sure that the problem is with a PCLinuxOS RPM and not a TinyMe RPM. Next, open Synaptic and do a Reload > Mark all Upgrades. Don't click Apply just yet. Find and install the following packages: autoconf2.1_2.13 autoconf2.5_2.59 automake automake1.8_1.9 elfutils_0.120 gcc c++_4.1.1 gettext_0.120 libgettextmisc_0.14 libstdc++6 devel_4.1.1 libtool base_ rpm build_4.4.6 rpm pclinuxos setup build_1.29 spec helper_0.24 Now click Apply > Apply. Finished? Okay, let's move along

3 Setting up your system to build rpms In order to safely build RPMS, we are going to setup a build environment. By default, the build environment is in /usr/src/rpm and requires you to be logged as root to build RPMS. This is dangerous because while you are logged as a superuser, you have too much potential to harm your system and a failed attempt to build a RPM could damage your system. To create a build environment, you will first need to create a set of directories in your home folder (right them as I do as it is case sensitive). Below is an example of my build directories. /home/gettinther/src/rpm/rpms/noarch (this is where multi architecture rpms will be created) /home/gettinther/src/rpm/rpms/i586 (this is where i586 rpms will be created) /home/gettinther/src/rpm/rpms/i686 (this is where i686 rpms will be created) /home/gettinther/src/rpm/rpms/i486 (this is where i486 rpms will be created) /home/gettinther/src/rpm/rpms/i386 (this is where i386 rpms will be created) /home/gettinther/src/rpm/rpms/athlon (this is where athlon rpms will be created) /home/gettinther/src/rpm/build (this is where the source files are installed during the build process) /home/gettinther/src/rpm/srpms (this is where the source rpms will be created) /home/gettinther/src/rpm/sources (this is where you will place the source codes of the RPM to be built) /home/gettinther/src/rpm/specs (this is where you will place the spec file of the RPM to be built) /home/gettinther/src/tmp (this is where the build process takes place and error logs are created) Note: if you open a terminal (do not su to root!), you can just copy these commands from here and paste them in by using Shift+Insert. This will create the directory structure: cd ~ mkdir mkdir mkdir mkdir mkdir mkdir mkdir mkdir mkdir mkdir p p p p p p p p p p src/rpm/rpms/i386 src/rpm/rpms/i486 src/rpm/rpms/i586 src/rpm/rpms/i686 src/rpm/rpms/noarch src/rpm/rpms/athlon src/rpm/srpms src/rpm/sources src/rpm/build src/tmp Once we have all the directories setup, we need to create two files to let the system know that we will be using our own build environment. The two files must be placed in your home directory (my files are in /home/gettinther). The files are simple text files. The first file is called.rpmrc (do not forget the dot at the start of the name as it is a hidden file) Place the following content in this file. (The reason for this is that pclos only uses i586 architecture and developpers might have set their packages for different architectures.) buildarchtranslate: i386: i586 buildarchtranslate: i486: i586

4 buildarchtranslate: i586: i586 buildarchtranslate: i686: i586 The second file is called.rpmmacros (do not forget the dot at the start of the name as it is a hidden file). Place the following content in this file (do not forget to remove my name and put yours in it). You may also want to change pclos_tinyme to something else. (Your PCLinuxOS forum username would probably be a good idea.) %_topdir %_tmppath %distribution %vendor %distsuffix /home/gettinther/src/rpm /home/gettinther/src/tmp PCLinuxOS PCLinuxOS pclos_tinyme Our system is now almost ready to build rpms. So let's move on to the specfile.

5 The spec file In order to build a RPM, you will need a spec file (where all the building specifications are located) and the source code for the application. While getting the source code is only a question of downloading it from the developer's site, the spec file must be created. There are several ways to do it. The spec file and how to get it The spec file is the single most important part of the build process and the place where we will focus our attention. It can be extracted from an old package or written from scratch. If an old version of the package you wish to build exists, download the source rpm, also known as an SRPM (it will have the extension src.rpm) of the said packages. In order of preference, you should try to get first: Mandriva Fedora Suse Others The reason for this order is that they will have different level of compatibility (with Mandriva being the most compatible as we are a fork from them and Mandriva is a fork from red hat (fedora) and suse is a fork from red hat). Once you have downloaded the rpm, open a terminal where you have downloaded the rpm and type the following line as a user (DO NOT USE ROOT PRIVILEGE). rpm ivh nameofyoursourcerpm.rpm This will automatically install the spec file, source code and patches (if any) in the directories you created at the start of this process (spec file in ~/src/specs/, source and patches in ~/src/rpm/sources/). All we will need to do them is point the spec file to the updated source code and fix the spec file to suit our system (spec files differ between each distribution so a bit of code cleanup is required). We'll also need to see if the patches are relevant and useful for our particular distribution. The spec file: how to make one If we cannot find a suitable spec file, then we need to make one. Also, if we got one but need to fix it, then we'll need to go through the same process and the existing spec file will only fill in some of the blanks. I'm now going to show you how to make a spec file the PCLOS way. There are other ways to do it but I'm a tyrant and I only wrote this for the pclos community. Doing it another way or skipping tasks will only mean someone else will have to do it for you and what you've done would then be worthless. Now that we are clear, let's have a look inside the spec file. The spec file name must be the nameofyoursourcetarball.spec (do not add in the version number). If you are wondering about the colors I use, it's only that kwrite will automatically recognize a.spec file and format it accordingly (so you'll know if you make a typing mistake).

6 Inside the spec file We'll start with a snapshot of a spec file as a whole to get an idea of what we're up against. Below is the spec file for cwallpaper package I built for tinyme2007. This is a simple example of a spec file. Everything in it is as basic as could be. If you would like to get this spec file to follow along, you can download the SRPM here: TinyMe main SRPMs directory

7 The spec file is comprised of 3 sections: the summary section the build section the file section (there's also the changelog but I don't count that as a section) The Summary section The summary section contains all the information about the package we are about to build. Don't worry yet about the macros (commands starting with %). We'll see to these later. Summary: Short sentence to describe the application (a larger description will be added in the %description section Name: Name of the application. This name will be the rpm name and must be the name of the source code. (just good practice but as far as I'm concerned, it's the rule) Version: released version number. This is the release number issued with the source code. Once again it must stay the same as the source version. Release: That's the number you change after each correction of the rpm. The number will match the %changelog License: This is a license agreement under which the source is released. The licence agreement is always in the source code. Group: Group defines what kind of application you are building. The group list is the list you find in Synaptic on the left panel when you select Section. Always make sure that your group name matches one of the entry in synaptic. Source: Source is the name of the source package you are about to build into an rpm. The preferred source compression is tar.bz2 (the example one isn't but this was only a test rpm). As far as suitable rpm for inclusion in the pclos repo, it has to be tar.bz2 compression (you've been warned). Buildroot: The buildroot is the name of the directory where the temporary build of the package will take place. You don't need to worry about this yet. URL: Path to the location of the source code (If you don't know, find it!)

8 BuildRequires & Requires: This is the place where you place the build requirements which will enable you to successfully build the rpm. The easiest place to look for initial build requirements is the configure.ac in the source code. The other option is to attempt the build and read from the error message which libraries are missing. Also, at the end of the rpm process, one of the last message is the generation of requirements (for synaptic) but it's not always reliable and cannot be solely used. Here is a snapshot of the configure.ac file for cwallpaper: You can see that cwallpaper needs GTK+ 2.0 to work. For the build system to use this requirement during the build process, it must be able to recognize it. To find out the proper spelling to be used in the spec file, lookup Synaptic and search for the package and lookup provided packages (in this case libgtk +2.0). Be careful here, all name are case sensitive. Most applications will require that you have the development files for the required packages. As a general rule, you will add the packages you find in the configure.ac in the Requires: list (each requirement is separated by a space) and the devel file in the BuildRequires: So in this case we have: BuildRequires: libgtk+2.0 devel Requires: libgtk+2.0 All the above entries are compulsory. If they are not there, you'll only give more work to the official packagers who will need to clean up your work! If you want, you can also add the packager line: Packager: Gettinther Put your name there if you want it to show in Synaptic and other installation tools (there's nothing like a bit of vanity). There are other entries available but they do not concern us at present. Macros At this stage we will only see the macros used in the summary section.

9 %define This macro allows you link a macro to a particular word, number or function. This function is used at the beginning to set the name, version and release (also libraries name and more but we'll look at that at a more advanced stage. The spec file should always start with these 3 lines. It is not obligatory as you can fill in the data later on but it is good practice and the pclos standard (so it's the law as far as building for pclos is concerned). It also allows you to only have to write the name of the application only one and then use the %name macro elsewhere (same goes for version and release) so updates are quick and easy. %mkrel This function will automatically read from your.rpmmacros file you created to add the suffix when generating the name of the RPM. %name This function will be replaced by the name you defined at the start of the spec file. %name is the same as %{name} (only a question of preference. Some think that using {} make the macro more solid. %version This function will be replaced by the version you defined at the start of the spec file. %version is the same as %{version} %release This function will be replaced by the release you defined at the start of the spec file. %release is the same as %{release} As you can see, you can write macros in 2 different manners. Both are acceptable and will work. %_tmppath This function is used to call up the location of the directory defined in your.rpmmacros file. In this case it is used to point the build process to use the directory you created for the purpose of building RPMS. We are finished with the summary section so let's have a look at the build section.

10 The build section Here is where the whole building process takes place. I wrote using various formats to show that it will work no matter which way you decide to use. The whole build process uses macros to ensure that the build process takes place properly as it needs to be built in a pseudo environment (nothing is installed and the directories don't even exist yet). So, let's start! %description This macro allows you to put a detailed description of the package you are building. It has to be there even if you don't have anything more to say than in the summary section. %prep The prep macro, as it's name indicate will prepare the way for a successful build by cleaning old files from the src/rpm/build directory (this is called the build directory per opposition to the buildroot where the pseudo install will take place). %setup This function will extract the files from your source code and place them in the build directory. If your source directory inside your source tarball matches the name of the source tarball, just use %setup q

11 (the q is for quiet!). If the source directory name is different (often the source directory does not carry the version number), change the line as follows: %setup q n nameofthesourcedirectory %build This function signals the start of the building process (configure and make) %configure This is the normal./configure function used to build packages from source. Variant of this function are %{configure}, %configure2_5x. Use the one that suits your build. All of these allow you to add arguments ( prefix is one argument used to specify a path of installation (see the %{_prefix} macro) Always lookup the source code's configure files to see what arguments are available. %make This is the make command and accepts the same arguments as the normal make command. Variant of this function is %{make}. The variant allows you to place additional flags for the building process. %install This function signals the start of the installation process. %makeinstall This is the make install function carrying out the installation process. Variant of this function are %make install and %{_make} install. All of these allow you to add requirements (DESTDIR= $RPM_BUILD_ROOT specifies the location of the install process. It is not required for this example but can be useful sometimes). %clean This function will clean up the buildroot directory once the rpm build process is complete. Remember that if the build process fails, the buildroot will not be cleaned up so you'll need to clean it up yourself (the other option is to copy the function I used and place it in the prep section). %post This is the place where you add install scriptlets (events you want to happen after the installation of the rpm on someone's computer). Leave at least the line I placed unless you know enough to put something more advanced instead.

12 %postun This is the place where you add uninstall scriptlets (events you want to happen after the installation of the rpm on someone's computer). Leave at least the line I placed unless you know enough to put something more advanced instead. %{_prefix} Prefix is the default location where executables, libraries and other files should be placed on your system. This function is mostly used with configure when the source code you are using offer the option to have different install locations (pclos uses /usr/ as the default while other distributions use /usr/local/ for example). $ RPM_BUILD_ROOT This function designates the path to where the installation process is taking place. Use this function if you whish to access one of the installed files (to move it) or add extra files from other sources (we'll see that in the advanced packaging how to ; ). $ RPM_BUILD_DIR This function designate the path to where the source files are extracted from the original tarball. Use this function when looking to fetch a particular file from the build directory. So let's go for the final section, the file section.

13 The File section Here is where we place all the bits of information we have about the files created. %files Here you place the list of files that will be installed by your RPM. One easy way to get the list of files that will be installed to to run the rpm build process and leave the files list empty (you'll still need %files and %defattr). The build process will fail and tell you that certain files were found but not packaged. Simply copy the list back on your spec file and you're ready to go. You saw that I used more macros, here is a list of the most common ones: %{_bindir} /usr/bin %{_datadir} /usr/share %{_libdir} /usr/lib %{_sysconfdir} /etc %{_mandir} /usr/share/man %{_docdir} /usr/share/doc %{_iconsdir} /usr/share/icons %defattr(, root, root) This function defines the attributes the files should have by default unless otherwise stated in the file list (leave it as I wrote it). %doc While not present in this example, you will come often in contact with it. This function allows you to name the list of documents from the source code which should be copied in the rpm (required for most license agreements). A typical line would look like this: %doc AUTHORS COPYING ChangeLog INSTALL NEWS README TODO %changelog There you'll put the information on who did it, when and reasons for doing it. Just keep the same formatting as I used. Now, that was easy, wasn't it? : ) Now all we have to do is compile the RPM.

14 Compiling Your First RPM Compiling is probably the easiest part of the job since you now have your source code and such a wonderful spec file. Make sure that your source code is located in the ~/src/rpm/sources directory you built at the start of this document and that the spec file is in ~/src/rpm/specs directory. Open a terminal in the spec file directory and type the following command (ONCE AGAIN DO NOT GET SUPERUSER PRIVILEDGES) rpm ba nameofyourspecfile.spec The rpm will now build in front of your own eyes. You did it! The installation rpms will show up in the ~/src/rpm/i586 or ~/src/rpm/noarch depending on the source. The new source rpm will show up in ~/src/rpm/srpms. So, that's it? Well, not really. If you are lucky, the RPM built and works fine. Otherwise you will have to patch it (that's how you call fixing the source tarball to make it work with your base system) or tweak the spec file. I will show more advanced packaging functions and patching methods later on. Even if it worked, you still have to run the application and test every single element of it to make sure it's stable and works as it should. You built the RPM and you are going to give it to others to use, so it is now your responsibility. You have just become the maintainer of this package for PCLinuxOS. Congratulations. Now lets have a look at what other things we could do.

15 Splitting the RPM When dealing with RPMS, you sometime need to split the libraries from the other files. The reason for this is to minimize the footprint and allow the use of the libraries alone (when the application in itself is not required). You can also use this method to remove unwanted parts of an application with the option to add them when required (creating a separate plugin rpm for example). Also if development files are present, these should be separated. In order to create separate RPMS for the libraries, devel files or other reasons, you will need to create for each one: A new summary section A new file section The build section remains the same regardless of the number of subsections. Creating library names First we need to create the library names. So we'll start by defining the library macros. %define major 1 %define libname %mklibname %{name} %major %define libnamedev %mklibname %{name} %major d These 3 lines is the standard pclos method for defining library names and allows for the automatic generation of the proper names (use them, they are your friends). %major needs to be placed to allow for future incompatibility by allowing you to have 2 libraries with the same name but different major (in case of change of API) which in turn will allow old programs to use the old library while newer programs can use the new library. %mklibname creates the library name base on the arguments behind it (%{name} %{major} d ( d is for devel) So if we look at the example below, the rpms created will be: e_dbus pclos_tinyme2007.i586.rpm libe_dbus pclos_tinyme2007.i586.rpm libe_dbus1 devel pclos_tinyme2007.i586.rpm You can download the SRPM which contains this spec file at the TinyMe E17 repo section.

16

17 Now that we have defined the names of each sub packages we whish to build, we can build the summary sections and file sections. Each sub package must have it's own summary and file sections. They are not as complicated as the main package sections. Summary Section %package This specifies the name of the package being defined in this summary subsection. Typically, use n %libname. n tells %package to use the name %libname (which was defined earlier). Summary Required for each subsection. It uses the same principle as the main section. Group Required for each subsection. It uses the same principle as the main section. You can put additional requirements and requirements. Just add the lines BuildRequires: and Requires: like the main section. %description The sub package requires a description of what it does or what it's for. File Section The file section is similar to the main file section except that you will need to add the subsection name after the %file. Typical use is %file n nameofthesubsection. Okay! In the example above, you can see how libraries, development libraries are split. All library files and development files should be split for eventual use by some other application. We are now able to make an RPM and split it to have dedicated packages. Now we'll have a look at multiple sources.

18 Building RPMs from multiple sources Sometimes, when you get the original source code, you don't find it complete enough. You'd like to add a second source with a desktop file and extra icons for the said desktop file (for example). Adding additional sources is very easy (as long as you don't try to have a build process for these files as well. The proper procedure in this case is to build a separate rpm for each build process). Below is an example of who to use additional sources.

19

20 As you can see, in the summary section, there are additional sources. Source: This is the original source tarball. Source1: First additional source Source2: Second additional source Source3: Third additional source Once the sources have been created, place the corresponding source files in the /src/rpm/source directory. To install these files, simply use the command install m (specify the permissions for the file and the destination of the files) Don't forget to add these additional files in the file section of the spec file. Now, let's see how we can Patch this file.

21 Patching RPMs If you are lucky and the rpm works, that's fine. However, you will often need to add patches to fix the problems. What are patches? A patch is a modification that will be applied to the source code during the build process. Why using a patch and not just modify the source code? Modifying the source code is an absolute NO. While it would be fine for a single build, what's going to happen on the next release? Somebody else might then maintain that package and have to go through the same problems all over again. Also patches allows you to give feedback to the developpers and share informations with other distributions. How do I create a patch? Creating a patch is simple. First extract the source code in one location. If we take the example of cwallpaper, the source directory is cwallpaper 0.3. Make a copy of the whole directory & files and rename the source directory cwallpaper 0.3 old. You now have 2 exact copies of the source code. Go to cwallpaper 0.3 and carry out all necessary modifications to the source code to make it functional. I can't show you how to do that bit. This is where your programming skills comes in handy. Once all the modifications are carried out, open a terminal in the directory where the 2 source codes are located. Use the following function to create the patch file. Diff unr cwallpaper 0.3 old cwallpaper 0.3 >cwallpaper nameofthefix.patch This function will create a patch file for the entire directory structure named cwallpaper nameofthefix.patch and place it in the directory where the command was issued. OK, I have the patch. Now what do I do with it? Once the patch is created, place it with the source code in src/rpm/sources Now we are going to add the details to the spec file.

22 Now, as you can see in the spec file, I added patch0. To add a patch, you need to create an entry in the summary section starting with Patch0: (then patch1 patch2 and so on) and the name of the patch afterward.

23 The location of this line is typically after the source line (or lines if you have more than one source) To have the patch included in the build process, you then need to call the macro for that patch after setup but before the configure process. The process is called by the macro %patch followed by the number of the patch (0,1,2) and p (0, 1, 2). This p defines the number of step back from the patch path. What does this mean? For example, if I create the patch where the source directory is located, the path for the patch will be cwallpaper 0.3/Makefile. When the source is extracted during the build process the patch will be applied from within cwallpaper 0.3. If I do not apply a step back, the build process will look for cwallpaper 0.3 directory and not find it. If I add p1 to the patch line, the cwallpaper 0.3 step will be removed and the build process will then only look for Makefile. The b (with the extension you wish to add) argument allows you to create a backup of the file modified by the patch during the build process. Let's have a look at Creating a menu entry.

24 Creating A Menu Entry The spec file offers the option to create menu entries and files (desktop files or configuration files or bash script or any other text file you can think of). For the purpose of this howto, we are now going to add a menu entry for our application and the desktop file required.

25 To create the desktop file, we must first create the directory where the file will be created. To do this, we use the command mkdir p followed by the path of the directory. As we are building a rpm, we should use $RPM_BUILD_ROOT which will in turn become / when the RPM is installed. To create the desktop file, we use the cat command (see above example for typing format) finishing with «EOF (this signals the beginning of the text within the file being created).

26 Underneath we are writing up the file as it will be created. When the file is complete, write EOF to signal the end of the file. Don't forget to add the new file created in the %file section of the spec file. Now that we have a desktop file available, lets create a menu entry. PclinuxOS now uses XDG type menu so we need desktop file install command to create the entry (don't forget the \ at the end of every lines except the last one) The new system requires the vendor entry to be added to the desktop file (I showed it on the spec file as an example in case you are using an external desktop file and need to add it) You can also remove elements from the desktop file. In this case, we want to remove the pre xdg format categories so we use remove category= Packaging \ Now we add the new category format. add category= X PCLinuxOS System Configuration Packaging \ Finally we point the menu to the application desktop file directory and the desktop file itself. dir %{buildroot}%{_datadir}/applnk/utilities \ %{buildroot}%{_datadir}/applnk/utilities/%{name}.desktop So what is left to do now? Testing of course!

27 Testing Rpms Now comes the most boring but most important part of building the RPM. Building a RPM can be easy but it must work for everyone so the RPM must be installed on a few systems and tested and tested and tested again until you are sure that it is working as it should and that it does not adversely affect other applications. Yes that means you also need to run other applications when the application being tested is running. Final word? Well, if you've come this far, congratulations. You are a now able to build basic RPMS for the community. There are still lots of things you'll need to learn as you go along. I couldn't write them all down as I'd need to write a book to fit it all in (I know it's starting to look like one). I wish you the best of luck in your endeavor and hope that you may join us at to help support the growth of PCLinuxOS and maybe build a few RPMS with us. We have a project set up at the TinyMe site to help people who wish to learn how to build RPMs for PCLinuxOS and PCLinuxOS based distros.