Release Management/Customizing the Setup Tool
Contents |
Introduction
The Setup Tool is used in Openbravo ERP for doing the initial configuration in custom and development installations. It provides a comfortable user interface to configure the basic files required by Openbravo ERP to be built and to run properly. This includes information like database connection information or a directory for the ERP attachments.
Objective
The Setup Tool offers an easy way for end users to configure all the files required for Openbravo ERP to build and run properly. Currently the files are the following ones:
- config/Openbravo.properties
- config/log4j.lcf
- .classpath
- .settings/org.eclipse.wst.common.component
While all this files contain templates can be copied and configured by hand, it's hard to keep track of all the files that the development team requires users to configure. So the setup tool is always up to date with these changes and provides a simplified way of doing this.
Note that it supports both graphical and command line environments.
General process
The Setup Tool is a binary file that is generated from a XML file. This XML includes a definition of what fields we want to include in each window. And we use a program called BitRock InstallBuilder to build binaries from that XML file. Currently we generate binaries for AIX, FreeBSD (x86 and x86_64), HPUX, Linux (x86, x86_64, IA64 and PPC), OpenBSD, OSX, (open)Solaris (Intel, Sparc) and Windows.
Infrastructure setup
The first step to get the environment ready is to install BitRock InstallBuilder. We do not use the latest version of the package, and it is no longer available in the official download website. So ask the Release Management Team to provide you this, if you think you should have it.
Once you have the tar file, uncompress it give it permissions to your everyday user:
$ cd /opt && tar zxvf /tmp/installbuilder.tgz $ ln -sf installbuilder-5.4.10 installbuilder $ chown -R johndoe:johndoe /opt/installbuilder
Add it to the PATH of your everyday user (if you use bash, otherwise do the equivalent in your shell):
$ echo "export PATH=$PATH:/opt/installbuilder/bin" > /home/johndoe/.bashrc $ source $HOME/.bashrc
Then check out the setp tool sources, stored in a Subversion repository:
$ cd $HOME/src/openbravo/erp $ svn co https://dev.openbravo.com/svn/packaging/setup
XML structure
Now let's analyze the structure of the repository we've just checked out:
$HOME/src/openbravo/erp/setup | |-- images/ -> Directory containing some png images used in the binary. |-- licenses/ -> Directory containing the license used in a window. |-- output/ -> Directory where the binaries are stored. Once committed the ant setup task takes the binaries from this URL. |-- setup-properties.xml -> XML file that feeds BitRock InstallBuilder to create the final binaries.
The setup-properties.xml file has the following general structure:
<project> <!-- 1. General information about the installer, like the name, the license, dimensions and images --> <installationType>update</installationType> <shortName>OpenbravoERPsetup</shortName> <fullName>Openbravo ERP</fullName> <!-- (..) --> <!-- 2. PreInstallation actions, such as getting the current values from the Openbravo.properties --> <preInstallationActionList> <!-- (...) --> </preInstallationActionList> <!-- 3. All the screens of the program, marked in the code with the ''paramenterList'' XML tag --> <parameterList> <!-- (...) --> </parameterList> <!-- 4. PostInstallation actions, such as setting the selected values into Openbravo.properties, log4j.lcf, etc --> <postInstallationActionList> <!-- (...) --> </postInstallationActionList> </project>
We'll take some lines of config/Openbravo.properties to see what the tool does with them:
$ cat /some/erp/root/config/Openbravo.properties (..) bbdd.rdbms=POSTGRE bbdd.driver=org.postgresql.Driver bbdd.url=jdbc:postgresql://localhost:5432 bbdd.sid=openbravo (..)
First, the tool takes the already selected values of those properties in the preInstallationActionList tag. That is, it detects that bbdd.rdbms is set to POSTGRE so it selects PostgreSQL in combo box when that window appears to the user.
Next, when that window appears (window defined with a parameterList tag) the user can choose between PostgreSQL and Oracle in that combo box.
The final choice is saved in the config/Openbravo.properties when the user confirms it with the final "OK" button in the tool. And this is implemented in the postInstallationActionList tag.
Common controls
In this section we'll see how to implement the different kind of most used controls, such as a text box, a combo box, etc.
Text box
Use the stringParameter tag for this. Example:
<stringParameter> <name>contextname</name> <description>Context name</description> <allowEmptyValue>1</allowEmptyValue> <width>40</width> </stringParameter>
Directory selection box
Use the directoryParameter tag for this. Example:
<directoryParameter> <name>attachpath</name> <description>Attachments directory</description> <allowEmptyValue>1</allowEmptyValue> <width>40</width> </directoryParameter>
Combo box
Use the choiceParameter tag for this. Example:
<choiceParameter> <name>dateformat</name> <title>Date format</title> <description>Date format</description> <default>DD_MM_YYYY</default> <optionList> <option> <text>DD MM YYYY</text> <value>DDMMYYYY</value> </option> <option> <text>MM DD YYYY</text> <value>MMDDYYYY</value> </option> <option> <text>YYYY MM DD</text> <value>YYYYMMDD</value> </option> </optionList> </choiceParameter>
Radio buttons
Use the choiceParameter tag with the radiobuttons value in the displayType tag for this. Example:
<choiceParameter> <name>bbddrdbms</name> <description>Please select a database</description> <allowEmptyValue>1</allowEmptyValue> <ask>1</ask> <width>40</width> <optionList> <option text="Oracle" value="ORACLE"/> <option text="PostgreSQL" value="POSTGRE"/> </optionList> <displayType>radiobuttons</displayType> </choiceParameter>
Common actions
Get/Set values of variables from Java properties files
Openbravo ERP uses the Java property format for both config/Openbravo.properties and config/log4j.lcf. So we mostly want to read the values of the properties and change them to other values.
To get the value of a property and store it in a variable, in this case we'll take the attach.path property and save its value in the attachpath variable (BitRock internal variable):
<propertiesFileGet> <file>Openbravo.properties</file> <key>attach.path</key> <variable>attachpath</variable> <abortOnError>0</abortOnError> </propertiesFileGet>
We mostly do this property retrievals in the preInstallationActionList tag.
Now imagine that the attachpath variable has been selected by the user using a directory box. To set its value back to the property file:
<propertiesFileSet> <file>Openbravo.properties</file> <key>attach.path</key> <value>${attachpath}</value> </propertiesFileSet>
Validations
In some situations it is very valuable to validate if the input given by the users makes sense in the given control. For example, if we have a text box that asks for the port number of the database server, it does not make sense for the user to enter non-numerical or empty values. For this purpose we can use validations.
As an example:
<validationActionList> <throwError> <text>Please enter a valid port</text> <ruleEvaluationLogic>and</ruleEvaluationLogic> <ruleList> <regExMatch text="${ora_bbddport}" logic="does_not_match" pattern="^[0-9]*$"/> <compareText logic="does_not_equal" text="${ora_bbddport}" value=""/> </ruleList> </throwError> </validationActionList>
Build and publish binaries
To build a binary for a specific platform (example: linux):
$ cd $HOME/src/openbravo/erp/setup $ /opt/installbuilder/bin/builder build setup-properties.xml linux
We recommend adding the following script somewhere your PATH (e.g. $HOME/bin/bitrock-installer-rebuild.sh), which will make your life easier to create the binaries for all the platforms:
#!/bin/sh xmlfile=$1 if [ ! -f $xmlfile ]; then echo 'File does not exist.' exit 1 fi shift if [ $# -eq 0 ]; then archs='linux windows linux-x64 linux-ia64 osx solaris-sparc solaris-intel linux-ppc freebsd6 freebsd6-x64 openbsd3 hpux aix' else archs=$* fi for i in $archs; do /opt/installbuilder/bin/builder build $xmlfile $i done
For testing purposes it is useful just to build one binary for your own system:
$ bitrock-installer-rebuild.sh $HOME/src/openbravo/erp/setup/setup-properties.xml linux
So once you are happy with the results, to build all the installers:
$ bitrock-installer-rebuild.sh $HOME/src/openbravo/erp/setup/setup-properties.xml
The results are stored in /opt/installbuilder/output/
For OSX it creates a directory, so we need to compress it:
$ rm -f $HOME/src/openbravo/erp/setup/output/* $ cp -r /opt/installbuilder/output/setup* $HOME/src/openbravo/erp/setup/output/ $ cd $HOME/src/openbravo/erp/setup/output/ $ tar zcvf setup-properties-osx.app.tar.gz setup-properties-osx.app $ rm -rf setup-properties-osx.app
To publish the files, just commit the files to the Subversion repository:
$ cd $HOME/src/openbravo/erp/setup/ $ svn ci -m "Update the setup binaries with x and y"
References
- BitRock InstallBuilder official FAQ.
- BitRock InstallBuilder user guide, located at /opt/installbuilder/docs/userguide.pdf in your file system.