The Spec File to build the Adempiere RPM was developed and tested on Fedora 13.

The Fedora Packaging Guidelines have been followed, with some exceptions:

Version and Release Numbering 

Version information should be in the form:

majorVersion.minorVersion-buildNumber.patchNumber[.releaseTag]

So if upstream releases its product as adempiere351a, it should be packaged as:

adempiere-3.5-1.X.a

(where 1 is the build number and X is the packager's "patch level", which is incremented on each build).

However, upstream maintains the build number as part of the version number, and it does not follow the convention of 0=pre-release, 1=release, >1=post-release. For RPM's version control method, it therefore makes more sense to use the revision in the Mercurial repository as build number.

We also want to have automatic patch-level numbering, and the build date seems most suitable for that purpose.

Therefore, our version numbering will have following syntax:

majorVersion.minorVersion.buildNumber-hgRevision.buildDate[.releaseTag]

which would result in following package names:

	adempiere331 -> adempiere-3.3.1-1943.buildDate
	adempiere354a -> adempiere-3.5.4-5276.buildDate.a
	adempiere360lts -> adempiere-3.6.0-6510.buildDate.lts

Pre-built Binaries and Libraries 

All binaries and libraries in Fedora packages must be built from source code. The source package is not allowed to contain pre-built binaries and libraries.

However, Adempiere comes with various *.jar archives containing pre-built *.class files.

Some of them are simply used as tools in the build-chain and would easily be replaceable with open-source Fedora libraries.

Others are used in the final product such as the jdbc-drivers for database connections. They would be more difficult to replace, although it would certainly be possible.

Since we are going to build Adempiere packages for our own use and not for distribution with Fedora, we will gracefully ignore this requirement for the time being.

Spec File Legibility 

All efforts have been made to keep the Spec File legible, whereby priority has been given to legibility in terms of humanly readable over being able to read and understand the algorithms.

Normally the user would only have to set or modify parameters at the beginning of the file (marked “SETTINGS”), add his sources and patches to the preamble (marked “your custom sources come here” and “your custom patches come here”), and install or apply them in the %prep section (marked “install your sources here” and “apply your patches here”). Everything else should just work.

Many different parameters can be used in the Spec File, and commenting them all in place would result in a very long settings section where important or conflicting parameters could easily be overlooked. Instead, the parameters are explained with their default values in the appendix of this manual. All parameters have sensible default values, so even if no parameters are set the Spec File will still produce an installable and runnable package.

Macros used by the build and installation scripts are defined and evaluated in a section titled “INITIALIZATION”, which comes between the settings and the preamble. Inside the scripts, the function and contents of those macros can be understood intuitively by their names, and as most people will not want to get into the detailed algorithms of how they were defined, the definitions are written in a way that keeps the Spec File nice and tidy and easily readable by humans. For debugging purposes, it is recommendable to expand those macros to multiple lines where necessary for easier understanding of conditions, loops, etc.

A lot of regular expressions are used in combination with grep, sed, and awk in the macro definitions. They are not further explained, as commenting one line of code with twenty lines of explanation would make the Spec File difficult to read as a whole.

Since all sub packages use exactly the same installation scripts (behavior is tweaked for each sub package by just setting some variables at the beginning of the scripts), rather than writing the scripts again and again, they have been included as source files which will be dynamically expanded when the packages are built.

The SOURCES directory easily becomes very messy when numerous source files and patches are scattered about. For this reason, the files distributed with the Source-RPM are prefixed with sXXX_ (for sources) and pXXX_ (for patches), where XXX corresponds to the patch or source number in the Spec File. Users are encouraged to name their sources and patches following the same scheme, starting with number 100.

Tags 

The Packager and Vendor tags are used in spite of the guideline's recommendation not to do so. They are used for identification and documentation purposes to differentiate between the original distribution and patched versions.

The BuildRoot tag is present for compatibility with other RedHat-like systems.

Requirements 

Adempiere requires Java to run. As of Adempiere 3.6.0, JDK 1.6 is required.

Actually any Java distribution can be used, and the original Sun Java software is most tested and reliable for Adempiere. But since it is not distributed as an RPM, and theoretically can be installed at any location, it is virtually impossible to check for it as a build or target requirement.

Therefore the openJDK distribution is listed as requirement for both compiling the source and installing the RPM on a target machine. The user is still free to use any Java distribution he wants, but openJDK must at least be installed.

Documentation 

Adempiere mainly uses online documentation. Text files such as README in the source code are often meaningless. However, all pdf files found in the source after compiling are copied into the documentation folder for all sub packages, regardless in which sub package they were found and without distinguishing whether they are for users, administrators or developers.

Users and Groups 

If the adempiere user or group already exists on the target system, an attempt is made to change the uid and gid to those defined in the Spec File, and to move the home directory to the location defined in the Spec File.

Introduction

Adempiere is written in Java and as such strives to run on any operating system which is supported by Java. In effect it means that Adempiere can run on any modern operating system such as Windows, Mac OS X, Solaris, and Linux.

To install Adempiere, you download the binary package as zip-file from sourceforge, drop it somewhere into the directory tree, unzip the file, run RUN_setup.sh, and you have Adempiere installed and configured. The procedure is the same on any operating system.

While this platform independence is remarkable, it comes at a cost: The software can not be optimized for any particular system. Particularly on Linux machines, there are several issues which shall be examined in more detail.

Preparing the Package Building Environment

Install the tools required for building the Adempiere RPM. (This needs to be done as root).

Create the RPM build tree in your home directory.

This command creates the following directory tree required by rpmbuild and configures your build settings in ~/.rpmmacros

rpmbuild
+-- BUILD
+-- RPMS
+-- SOURCES
+-- SPECS
+-- SRPMS
			

You can move the generated rpmbuild directory to any place you like, but then you must adjust the %_topdir setting in ~/.rpmmacros to point to that location.

For security reasons, the packages you build should be digitally signed. The digital signature allows users to verify that the package has been built by you, a trusted source, and has not been tampered with since then.

First, generate a public/private key pair with the gpg --gen-key command:

<code class="prompt">$ </code><span class="command"><strong>gpg --gen-key</strong></span>
gpg (GnuPG) 1.4.10; Copyright (C) 2008 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
	(1) RSA and RSA (default)
	(2) DSA and Elgamal
	(3) DSA (sign only)
	(4) RSA (sign only)
Your selection? <strong><code>1</code></strong>
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) <strong><code>2048</code></strong>
Requested keysize is 2048 bits
Please specify how long the key should be valid.
				0 = key does not expire
			<n>  = key expires in n days
			<n>w = key expires in n weeks
			<n>m = key expires in n months
			<n>y = key expires in n years
Key is valid for? (0) <strong><code>0</code></strong>
Key does not expire at all
Is this correct? (y/N) <strong><code>y</code></strong>

You need a user ID to identify your key; the software constructs the user
ID from the Real Name, Comment and Email Address in this form:
		"Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"

Real name: <strong><code>www.mycompany.com</code></strong>
Email address: <strong><code>devnull@mycompany.com</code></strong>
Comment: <strong><code>rpm signature</code></strong>

You selected this USER-ID:
		"www.mycompany.com (rpm signature) <devnull@mycompany.com>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? <strong><code>O</code></strong>
You need a Passphrase to protect your secret key.

Enter passphrase: <strong><code>secret passphrase</code></strong>
Repeat passphrase: <strong><code>secret passphrase</code></strong>

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
.+++++
........+++++
..+++++
gpg: key F9D8EE90 marked as ultimately trusted
public and secret key created and signed.

gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, classic trust model
gpg: depth: 0  valid:   2  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 2u
pub   2048R/F9D8EE90 2010-10-17
			Key fingerprint = 983D 704A 024A 861F 9FCB  5CA2 4875 7B66 F9D8 EE90
uid   www.mycompany.com (rpm signature) <devnull@mycompany.com>
sub   2048R/496CD9ED 2010-10-17
			

Next, the public key needs to be extracted:

This file needs to be publicly distributed so that users can verify the signature of the RPM packages which you built and signed.

Finally, you need to configure rpmbuild to use the signature you just created by adding the %_signature and %_gpg_name macros to the .rpmmacros file in your home directory. The file should now look something like this:

%_topdir        /home/<em>username</em>/rpmbuild
%_signature     gpg
%_gpg_name      www.mycompany.com (rpm signature) <devnull@mycompany.com>
…
…

			

Using the Adempiere SRPM

Once your package building environment has been set up, you can download and unpack the Adempiere source RPM:

The source files will have been installed in ~/rpmbuild/SOURCES, and the specification file ("Spec" file) in ~/rpmbuild/SPECS/adempiere.spec

Build behavior is controlled by various parameters which are set at the beginning of the Spec File. See Appendix A for a detailed description.

Additional sources and patches can be added to the SOURCES directory to apply extensions and customizations to the Adempiere source code.

As new files are added, the SOURCES directory quickly gets very messy. For this reason, the files distributed with the Source-RPM are prefixed with sXXX_ (for sources) and pXXX_ (for patches), where XXX corresponds to the patch or source number in the Spec File. Users are encouraged to name their sources and patches following the same naming scheme.

Sources and patches must be listed in the Spec File using the Source<number>: filename and Patch<number>: filename pragmas.

Source and patch numbers 0-99 are reserved for the maintainer of the Adempiere source RPM, so you may add source files and patches starting with number 100.

…
…
# Sources
# -------

# standard sources
…
…

# your custom sources come here
# (start with number 100)
Source100:	s100_MMyModel.java
Source101:	s101_myScript.sh


# Patches
# -------

# standard patches
…
…

# your custom patches come here
# (start with number 100)
Patch100:	p100_myPatch1.patch
Patch101:	p101_myPatch2.patch
…
…
			

The sources and patches thus defined in the Spec File's preamble must be installed or applied in the %prep section, which is usually done with the install shell command and %patch macro.

…
…
%prep
…
…
	cd $rpmBuildDir/source/custom

 standard patches
 ----------------
…
…

 install your sources here
 -------------------------
install -pD -m0644 %{SOURCE100} base/src/org/adempiere/model/MMyModel.java
install -pD -m0755 %{SOURCE101} utils/myScript.sh

 apply your patches here
 -----------------------
%patch -P100 -p1
%patch -P101 -p1
…
…

			

The install command works like cp, with the addition that it will create all leading components in the path to the target file if they are missing (-D option), preserve the source file's timestamp (-p option), and set the permission mode of the target file (-m option).

The %patch macro invokes the patch command to apply patches to the source. The patch file number is specified with the -P (upper case P) option, and the -p (lower case p) option tells the patch command how many leading slashes and directories are to be omitted from filenames in the patch file. This will be explained in the next chapter.

For building Adempiere packages, the %patch macro has been extended to accept following additional parameters:

Packages are generated using the rpmbuild --sign -b… /path/to/adempiere.spec command, where the --sign option will sign the package using the gpg-signature we created earlier, and the stage up to which the packages are built is defined with the -b… switch:

The resulting RPM packages can be found in ~/rpmbuild/RPMS/noarch, and the source RPM in ~/rpmbuild/SRPMS.

When using --sign, rpmbuild will prompt you for a passphrase. Enter the same phrase which was used when the gpg key was generated.

Creating Patches

Distributing RPM Packages

The binary packages generated by rpmbuild can now be installed on target machines using the rpm command. Before doing so, the public GPG key must be loaded into the rpm database. Both must be done as root.

But of course it would be much more efficient to have a central repository from which client machines can use tools like yum for automatic installation and upgrading.

Distributing the server package through a central yum repository might not be such a good idea, especially if it was built using pre-configured settings. That would enable anybody to download the server package and access critical information such us database passwords. And anyway, servers should always be upgraded manually.

A web server is needed to distribute packages from a yum repository. The httpd server can be installed using yum, and for our purposes it can be started out of the box without having to configure it. Below commands have to be run as root.

Create an adempiere directory under /var/www/html, and copy the GPG public key and the RPM packages to be distributed into it. Make sure that everybody has read permissions for those files.

Create the repository by executing createrepo . (the last dot is important!) inside /var/www/html/adempiere

Your yum repository is now up and running and can be accessed from client machines.

For distributing upgrades, simply drop the new RPM files into the repository and run createrepo . again.

Before being able to use your new Adempiere repository, client machines must be aware that it exists. As root, create a file adempiere.repo in /etc/yum.repos.d with following contents:

[adempiere]
name=Adempiere
baseurl=http://<em>address.of.your.web.server</em>/adempiere
enabled=1
			

And of course the public key for signature verification must be imported into the RPM database (needs to be done as root):

Now yum can be used to install, upgrade, or remove your Adempiere packages:

If the client machine has daily run of yum enabled, it will automatically upgrade to the newest package published in the adempiere repository.