README for libmeegotouch.spec ============================= Author: Stefan.Hundhammer@basyskom.de Updated: 2010-04-29 RPM and spec file concepts ========================== (skip this section if you are familiar with RPM and spec files) libmeegotouch.spec is a spec file for creating RPM packages from the libmeegotouch sources. RPM ("Red Hat Package Manager") is a file format for (mostly binary) packages for Linux distributions such as Red Hat / Fedora, openSUSE, and MeeGo. The RPM file format is little more than a cpio (see "man 1 cpio") archive, very similar to a tar archive. In addition to the files it contains, there are also meta data that, among other things, specify dependencies between packages ("package A requires package B to run"). The spec file is the RPM counterpart to the debian/ subdirectory, but in one single file: It specifies build instructions, file lists, dependencies and administrative information like package name, version numbers etc. RPM has the concept of "pristine sources" and patches. In general (for a Linux distributor), the sources are taken from "upstream" (somewhere in the Internet) as a "tarball" (a .tar or .tar.gz or .tgz or .tar.bz2 file. To get those sources to compile and to run in that distribution's specific environment, a distributor might have to do some (hopefully minor) changes. Those changes are stored in "patches" (xy.patch or xy.diff) generated with the "diff" (see "man 1 diff") command. The patches are also listed in the .spec file; while building the package, RPM first unpacks the tarball(s) (there might be more than one) and then applies the patches one by one. The general idea is that these patches can be applied again if there is a newer version of the upstream sources, so the distributor only has to fetch another tarball and reuse the existing patches rather than having to go through the complete source tree and make all the changes again manually. Since this does not always work perfectly if there were major changes in the source tree, it helps to keep separate changes in separate patches to minimize rejected patches (patches that no longer can be cleanly applied with the "patch" (see "man 1 pach") command. Whenever a patch is not just specific to the specific system environment, but a general fix, it makes a lot of sense to "send the patch upstream", i.e. to mail it to the authors of the original sources. Creating RPM packages with this spec file ========================================= (1) Edit the version in the spec file. In this example: Version: 0.20.2 (2) Create a tarball. It is RPM file name convention to include the version number in both the tar file name and in the first level directory in that tar file: libmeegotouch-0.20.2.tar.bz2 containing libmeegotouch-0.20.2/benchmarks libmeegotouch-0.20.2/configure libmeegotouch-0.20.2/configure-win32.pl libmeegotouch-0.20.2/debian libmeegotouch-0.20.2/demos libmeegotouch-0.20.2/doc libmeegotouch-0.20.2/examples ... Also, exclude the .git subdirectory as well as any built files (.o files, binaries, moc files, ...) since they only blow up the tarball without any benefit. Simple approach: ~/projects/libmeegotouch % git clean -dfx ~/projects/libmeegotouch % cd .. ~/projects % mv libmeegotouch libmeegotouch-0.20.2 ~/projects % tar cjvf /tmp/libmeegotouch-0.20.2.tar.bz2 libmeegotouch-0.20.2 --exclude .git ~/projects % mv libmeegotouch-0.20.2 libmeegotouch (3.1) If building with OBS: (3.1.1) Check out the old version of this package from OBS: ~/projects/obs % osc co libmeegotouch (3.1.2) Go into that directory, remove the old tarball, copy the new one and the changed spec file there and check in those changes: ~/projects/obs % cd libmeegotouch ~/projects/obs/libmeegotouch % rm libmeegotouch-*.tar.bz2 ~/projects/obs/libmeegotouch % cp /tmp/libmeegotouch-0.20.2.tar.bz2 . ~/projects/obs/libmeegotouch % cp ../../libmeegotouch/libmeegotouch.spec . ~/projects/obs/libmeegotouch % osc addremove ~/projects/obs/libmeegotouch % osc ci -m "Updated to version 0.20.2" (3.1.3) Upon "osc ci", the package will automatically be rebuilt in OBS. Go to the web interface and monitor the results or use the "osc results" and "osc buildlog" commands: ~/projects/obs/libmeegotouch % osc results standard armv5el disabled (repository is published) standard armv7el disabled (repository is published) standard i586 succeeded (repository is published) ~/projects/obs/libmeegotouch % osc buildlog standard i586 >/tmp/build.log (3.2) If building without "rpmbuild" rather than with OBS: (3.2.1) Make sure the tarball and the spec file are in the same directory: ~ % mkdir /tmp/libmeegotouch ~ % mv /tmp/libmeegotouch-0.20.2.tar.bz2 /tmp/libmeegotouch ~ % cp projects/libmeegotouch/libmeegotouch.spec /tmp/libmeegotouch ~ % ls /tmp/libmeegotouch libmeegotouch-0.20.2.tar.bz2 libmeegotouch.spec (3.2.2) Find a directory on your hard drive where you have enough disk space to use as a "build root" and create a build root subdirectory there: % df -h /work Filesystem Size Used Avail Use% Mounted on /dev/sda7 69G 30G 37G 45% /home mkdir /work/tmp/build-root/ (3.2.3) Start a local "rpmbuild" with that build root: ~ % cd /tmp/libmeegotouch /tmp/libmeegotouch % rpmbuild -ba --buildroot /work/tmp/build-root libmeegotouch Subpackage strategy ================================= The one source tarball (libmeegotouch-x.y.tar.bz2) creates a number of RPM packages: - libmeegotouch: This is the main package, but it only contains one single file (LICENSE.LGPL) to satisfy packaging conventions (as enforced in MeeGo by the "rpmlint" tool). The main idea behind this main package is to serve as a collection for the real library packages: - libmeegotouchcore0 - libmeegotouchextensions0 - libmeegotouchsettings0 - libmeegotouchviews0 They each contain one of the libmeegotouch libraries. The main package "libmeegotouch" has "requires" dependencies set up on all of them so it is sufficient to install libmeegotouch.rpm to get all the modularized libs. - libmeegotouch-bin: Some binaries required by applications using libmeegotouch such as the theme daemon and the service mapper. - libmeegotouch-devel: Files needed for developing libmeegotouch-based applications: Header files, qmake specs etc.; please notice that the RPM package naming convention for development subpackages is -devel, not -dev like in Debian-based distributions. - meegotouch-devel-tools: Tools needed for developing libmeegotouch-based applications like the libmeegotouch-specific "moc" preprocessor etc. - libmeegotouch-doc: API documentation - meegotouch-demos: Container for the demo subpackages: - meegotouch-demos-widgetsgallery: Widget gallery demo - meegotouch-demos-widgetsgallery-tests - meegotouch-demos-appletinstallationsource - meegotouch-demos-applicationextension - libmeegotouch-tests: Unit tests - libmeegotouch-benchmarks: Benchmarks - libmeegotouch-l10n- packages: Messages / translations for user-visible strings in the lib packages. - libmeegotouch-l10n-eng-en : "Engineering English" - libmeegotouch-l10n-en: English - libmeegotouch-l10n-ar Arabic - libmeegotouch-l10n-de German - libmeegotouch-l10n-fi Finnish - libmeegotouch-l10n-hu Hungarian - libmeegotouch-l10n-ur Urdu - libmeegotouch-l10n-zh-cn Simplified Chinese - meegotouch-demos-widgetsgallery-l10n- packages: Messages / translatiosn for user-visible strings in the "widgets gallery" demo. Please note that the "rpmlint" checking tool enforces a 64 character limit per file name component because of the Joliet file system that is commonly used on CDs / DVDs. Thus, -engineering-english had to be abbreviated to -eng-en. - meegotouch-demos-widgetsgallery-l10n-eng-en - meegotouch-demos-widgetsgallery-l10n-ar - meegotouch-demos-widgetsgallery-l10n-de - meegotouch-demos-widgetsgallery-l10n-en - meegotouch-demos-widgetsgallery-l10n-fi - meegotouch-demos-widgetsgallery-l10n-hu - meegotouch-demos-widgetsgallery-l10n-ur - meegotouch-demos-widgetsgallery-l10n-zh-cn RPM spec file cheat sheet ========================= RPM Variables / Macros ---------------------- Variable definition: %define variable_name value Variable reference: %variable_name %{variable_name} Dependencies ------------- Requires: other_pkg This package requires package other_pkg to run (not for building!). BuildRequires: other_pkg This package requires package other_pkg for building (not at runtime!). Provides: some_capability This package provides a capability named "some_capability" that other packages might require. Note: A package always provides itself, so it's pointless to write Provides: mypackage in mypackage.spec. A package also automatically provides all shared libs it has in its file list, and a package built with a shared lib automatically requires that shared lib. For example, package libqt4-x11 automatically provides libQtGui.so.4, libQtSvg.so.4 etc.; likewise, it automatically requires libX11.so.6, libXext.so.6 etc. Package name and subpackages ---------------------------- The name of the main package is specified in Name: foo it can have any number of subpackages. A subpackage is defined with %package subpkg-name1 or %package -n subpkg-name2 Without the -n, it will be prefixed with the main package name and a dash: foo-subpkg-name1 With the -n, there will be no prefix: subpkg-name2 File lists ---------- All files generated during the build process must be listed in the file list(s). Wildcards may be used. %files is the file list of the main package. %files -n subpkg-name is the file list of subpackage "subpkg-name" (same rules as with %package: Prefixed with the main package name if specified without -n). %defattr(-,root,root) specifies the default file permission and ownership (user and group) for each item in the file list. %dir /usr/share/somewhere assigns directory ownership to this package. %config /etc/foo indicates that /etc/foo should be packaged as a configuration file with special rules what to do if it already exists when the package is installed so changes by the system administrator don't simply get lost during package update. %doc /usr/share/doc/packages/foo/* marks files as documentation. Build section ------------- %prep %setup mysource-47.11.tar.bz2 This removes an existing build directory for that package, creates a new one and unpacks the tarball there. %build This executes the commands following %build inside the build directory. The convention is to only build (compile and link) the project in that section, not install any files there. %install This is similar to %build, but the intention is to do "make install" and whatever else is required to install files to the target system in this section. IMPORTANT: Make sure to prefix all target paths with %{buildroot}, e.g. use %{buildroot}/usr/lib/whatever and not just /usr/lib/whatever. Misc ---- Group: System Environment/Libraries This specifies the RPM "group tag", a tree of categories where this package belongs to. Different distributions may have different predefined such categories. -devel subpackages should go to a category below "Development/". Further reading =============== http://www.rpm.org/max-rpm-snapshot/ http://docs.fedoraproject.org/drafts/rpm-guide-en/