Adding an Application to Appbat (Using application foo as an example)
- Determine the target version of the application source being used, the associated upstream source file. (ie. `foo-1.2.0.tar.gz`), and a preferred download location.
- Compile the application using lsbcc or the buildenv to determine if any patches are necessary to the app in order to make it lsb compliant. If changes are necessary, create a patch file with these changes. (e.g. `foo-1.2.0.patch`). In general, it is recommended to include a hint at the purpose of the patch in the patch name (e.g. `foo-1.2.0-lib64.patch` to add lib64 capability).
- For appbat, you really want to test with lsbcc since appbat will be built that way. They *should* give the same result, but debugging the right target makes sense anyway
- #3 Edit the `appbat/entities/system` file to add an entry for the new application. For example, if the app foo is just a regular utility type of application, it could be added right below the entry for gnupg like this:
<!-- Useful utility programs -->
<!ENTITY apps-tcltkexpect SYSTEM "apps/tcltkexpect.xml">
<!ENTITY apps-python SYSTEM "apps/python.xml">
<!ENTITY apps-gnupg SYSTEM "apps/gnupg.xml">
<!ENTITY apps-foo SYSTEM "apps/foo.xml">
- #4 Edit the `appbat/entities/package` file to add entities for the new application related files and versions. An example set of entities for the foo app would look like this:
<!ENTITY foo-version "1.2.0">
<!ENTITY foo-package "foo-1.2.0.tar.gz">
<!ENTITY foo-directory "foo-1.2.0">
<!ENTITY foo-patch "foo-1.2.0.patch">
- The `foo-version` entity is just the version of the upstream source package. The `foo-package` entity is the name of the source tar package (both gzip and bzip2 packages are acceptable). The `foo-directory` is the top directory of the source files in the source package. The `foo-patch` entity is the name of the patch file for the application (only present if a patch is necessary).
- It might be noted that the newer nALFS version has a more elegant syntax for this which might avoid us adding all these entries. Not that it's a huge deal...
- #5 Edit the `appbat/extras/package_locations` file to add an entry showing where the upsteam source package can be downloaded from. For example, if app foo can be downloaded from www.foo.org/sources, then the entry would look like this:
foo http://www.foo.org/sources none
- The "none" after the source locations indicates no backup locations are available. In order to avoid problems when the upstream source maintainer moves the source file it is best to place a copy of the source tar ball in the  directory. The script used to retrieve source files, `extras/entitycheck.py`, will get the package from the lsb ftp site if it cannot find it elsewhere.
- The "backup location" is for packages where the maintainer routinely moves an old version elsewhere when the new version is released. This is just accomodating different practices; some people leave every release in the same directory, if so you can use "none". Some create a version-specific subdirectory for each version, then you also don't have to do anything - but you have to update `package_locations` as well as the `package` entities when you bump versions. The third case is where, for example, 1.0.2 goes into subdirectory "old" once 1.0.3 is released - this means what worked when you created the appbat entry at some time later stops working, and you probably don't notice until someone else screams in anguish that the appbat build is broken. This is where that last field is used, if you can find a convention for where they put the old versions.
- #6 Edit the `appbat/extras/md5sums` file to add an entry for the app source package and, if necessary, the app patch file. The entries for app foo might look like this:
- The entity checker will generate a fresh `md5sums` file if asked, so once you've updated entities, all you need is `entitycheck.py -g`
- #7 Copy the application patch file to the `appbat/patches` directory and add this new file to cvs. Example steps for app foo might look like this:
cp /tmp/foo-1.2.0.patch appbat/patches
cvs add foo-1.2.0.patch
cvs ci -m "patch for foo" foo-1.2.0.patch
- #8 Edit the `appbat/apps/apps.xml` file to add an entry for the new application. The entry for app foo would look like this:
- #9 Create the xml file used to describe the build procedure for the new application in `appbat/apps` and add this file to cvs. It is usually best to use an existing application xml file as a template for the new file. There are several subsections of the xml file contained within the overall `<package>` section. At the top of the file are three entries present for most applications. The `<name>` entry is the name of the application. The `<version>` entry is the version of the application that is obtained from the entry added to the `appbat/entities/package` file. The `<options>` entry will almost always be "nofail" to allow appbat to build all applications even in the event one particular application is failing to build. The other three subsections are the `<prebuild>`, `<build>`, and `<postbuild>` sections. The `<prebuild>` section usually cleans up any previous builds and installs of the application, extracts the source from the source packge, applies any app patches, sets appropriate environment variables, and then configures the application. The `<build>` section usually just contains the step to compile the application. The `<postbuild>` section installs the application to the `appbat/pkgroot` directory and then removes the build directory. An example xml file for app foo might look like this:
- <param>-i &patch_dir;/&foo-patch;</param>
- Note that the `<prebuild>`, `<build>`, `<postbuild>` sections are conceptually very similar to what an RPM build, or in fact most open source types builds do: prepare, including applying patches and configuring; build; install.
- Also note the above is slightly simplified, most packages require to be configured slightly differently if there's a need to install into a library directory; the 32-bit platforms and IA64 install to `/usr/lib` and the other 64-bit platforms install to `/usr/lib64`. Existing examples will show how this is done.
- #10 Create the rpm spec file for the application in the `appbat/rpm` directory to describe how to package the application, and add to cvs. As with the xml file, it is best to start with the spec file for an existing app in the `appbat/rpm` directory. The first three lines in the file are fairly straightforward. The provide the brief summary description of the app, the name of the app package, and the version of the app. The "Release" entry is of the format X.lsbY where Y is the associated LSB certification program where the app will be used and X is the particular release number of the package. For example, if the app is to be used for LSB 3 certification and it is the second time the app has been built, then the field will be 2.lsb3. The Vendor, Packager, and License fields are the same for all apps in appbat. The Group field is just used to categorize apps in appbat. The Buildroot and AutoReqProv fields are the same for all apps in appbat. There will be multiple PreReq entries to show what is required by the application. Any core applications will only need to require lsb-core-arch. Additional requirements for lsb-graphics-arch and lsb-desktop-arch should be listed as well. Entries must be present for all supported LSB architectures. The description field in the spec file contains a more detailed explanation of the application. The pre, install, post, preun, postun, and clean fields may be empty or they could contain code to be executed when the app is installed or removed. The final entry in the spec file is the files section which lists the directories in the pkgroot install location containing the files that comprise the application package. The rpm spec file for the foo app might look like this:
Summary: An Example Application for Appbat
Vendor: Free Standards Group
Packager: Appbat Team <firstname.lastname@example.org>
%ifarch i386 i486 i585 i686 athlon
[[PreReq]]: lsb-core-ia32 >= 3.0
[[PreReq]]: lsb-core-ia64 >= 3.0
[[PreReq]]: lsb-core-ppc32 >= 3.0
[[PreReq]]: lsb-core-ppc64 >= 3.0
[[PreReq]]: lsb-core-s390 >= 3.0
[[PreReq]]: lsb-core-s390x >= 3.0
[[PreReq]]: lsb-core-amd64 >= 3.0
LSB conforming version of the foo application. This application is used as an example of the steps necessary to add an application to the LSB application battery.
%attr ( - bin bin ) /opt/lsb/appbat
- #11 To check for missing or corrupt files, run:
Once all the steps above are followed the new application should be built as part of building the overall appbat.
For questions concerning the application battery send email to email@example.com.