Development Environments

Creating a development environment is an exciting first step to becoming a developer with ADempiere. The development environment will allow you to test and debug the application and make changes back to the community. Before you begin, you should be familiar with the Software Development Procedure and ADempiere Version Control. To test the Web User Interface (webui) you will need to follow the steps in Creating WebUI Workspace using Eclipse Webtool after you create your development environment. It is also recommended that you create a separate project for customization work that will not be shared with all ADempiere users. See Create your ADempiere customization environment for more information.

If you have any issues, please join our chat. We'd be happy to help.

Preparing Your Environment

Download and install the Java JDK from the Oracle website or the OpenJDK website. You will need the version of the Standard Edition (SE) or Enterprise Edition (EE) Java Development Kit (JDK) that works with the version of software you are compiling. For some of the recent versions, these are:

• ADempiere 3.6 -- requires Java 6

• ADempiere 3.7 or 3.8 -- requires Java 7

• ADempiere branch 380#002 or higher -- requires Java 8+

Follow the installation instructions and set the environment variable JAVA_HOME to point to the installed JDK and add %JAVA_HOME%\bin to your PATH environment variable.

You can have multiple JDK versions installed and change which one you use by changing where JAVA_HOME points. Also, use the commands "which" on linux and "where" on dos to see where the called version is installed and "java -version" to check the version.

Download and install a database. You can use PostgreSQL, Oracle or MySQL. PostgreSQL is recommended. Read more at Database Server Installation & Setup.

If you have access to a database server, you can use that rather than install a local copy of the database.

Download and install a Java Integrated Development Environment such as Itellij IDEA or the Eclipse Integrated Development Environment (IDE) for Java EE Developers from the Eclipse web site. The rest of this section is based on Eclipse.

Download the ADempiere Source

Download, install and configure your version control tools. See ADempiere Version Control for instructions. You may find tools that integrate with Eclipse directly but it is recommended to use those that include the latest versions of Mercurial and Git. Once you have your pristine and working clones created, you should update the working clone to the desired branch head.

Import the your working clone as a project in your IDE. The project includes nested subprojects but it is not necessary to import these as separate projects.

Compile and Debug ADempiere

Use Eclipse to compile, build and debug/run ADempiere as the client or as a web application.

Before you can run or debug the application, you have to:

• configure Eclipse;

• ensure the application compiles properly;

• perform a "build" of the application; and

• import the seed data into the database

An alternative way to get started is to install the latest version of ADempiere client on your development computer. See Installing ADempiere Manually. This will ensure the setup parameters work and that the database seed is loaded properly. Most importantly, it will create a number of files that will be useful when you want to launch an instance of ADempiere from Eclipse. From the ADempiere home directory where the software was installed, these files are:

• adempiereEnv.properties - copied from adempiereEnvTemplate.properties, this file defines the environment used to setup ADempiere.

• adempiere.properties - this file is generated by the setup process and shouldn't be edited. Once created, you can copy and rename it to other locations and use it in the launch configurations described below so you change configurations easily. This will allow you to change target databases or ports as required to test your application.

• utils->myEnvironment.bat/sh copied from myEnvironmentTemplate.bat by the setup process. Generally, you shouldn't edit this file directly but use the run_setup/run_silentsetup scripts.

You can customize these files and keep a copy of them in a separate location in case they are overwritten by the version control processes.

Configure Eclipse

Before you can compile the ADempiere software, there are a few things you can do to make the process easier:

• Create debug and run "configurations" so you can reliably launch the application in a known state

• Create external tool "configurations" to launch the build processes and other tools

Many of these configurations are already shared within the project. If you can't see them in the Eclipse "Debug Configurations" or "Run Configurations", its likely that your project is setup slightly differently than the way the configuration was generated. Check the "Filter launch configurations..." dialog and deselect "Filter Deleted/Unavailable Projects". All the shared configurations should then appear in the list. To use one of these, copy it and modify it to fit with your setup. Be sure to make this a local copy in the "Common" tab. This will prevent your work from being over-written. A common difference would be in the project name or if the repository is setup as a single project or multiple projects. Some of the configurations use variables such as ${adempierePropertiesFile} which will need to be set before the configuration can be run.

Create Debug and Run Configurations

Debug and Run configurations make it easy to launch ADempiere. The configurations can be created under the Eclipse "Run" menu or on the Debug/Run icon pull downs.

The configurations need the following settings:

• Create a new Java Application configuration.

• Name: Call it something specific in the case that you have multiple projects

  • Main Tab - Project: browse to your ADempiere project

  • Main Tab - Main class: org.compiere.Adempiere

  • Arguments Tab - VM Arguments: -Xms64m -Xmx64m -Dorg.adempiere.server.embedded=true -DPropertyFile="C:\Adempiere\Adempiere.properties"

  • Common Tab - Select Debug and Run in the "Display in favorites menu"

Replace the path to the Adempiere.properties files with the one you wish to use. You can also change the VM Arguments to increase or decrease the amount of memory. The VM arguments define the minimum and maximum RAM allocation for the Java VM. Check the Java documentation for more information.

Create additional configurations for other projects as required.

Create External Tool Configurations

To assist with building ADempiere and other utility functions, you can create external tool configurations that will run the Ant build targets to perform various functions. External tool configurations can be created from the Run->External Tools->External Tools Configurations... menu. Each configuration needs the following settings:

• Select "Ant Build" and create a new launch configuration. Give the new configuration a good name like "ADempiere - build".

• Main Tab - BuildFile: ${workspace_loc:/adempiereTrunk/utils_dev/build.xml} - or wherever the utils_dev/build.xml is located.

• Build Tab - Select "Build before launch."

• Targets Tab - Select one or more targets. For the basic build, select the default, "complete".

• Common Tab - Save as local file and select Display in favorites menu - External Tools.

Create additional configurations as required. A helpful one uses the build target "install" which will partially delete the install location and then install the ADempiere software. The "Clean" target will clean the class directories and "clean all" will perform a clean and delete the install location. Review the code utils_dev/build.xml for more details.

There are many build files in the project that perform specific tasks. You can also create external tool configurations for these. One helpful one is in the migration directory to install migrations. For example, in the directory adempiereTrunk/migration/380lts-release/postgresql, the build.xml file can apply the long list of migration scripts from within Eclipse. You will need to copy the adempiereTrunk/migration/postgresql.properties.template file to postgresql.properties and modify it for your installation. Then create an External Tool Configuration to run the target "run-scripts".

You can also create external tool configurations for some of the basic shell scripts in ADempiere. These are created under the external tool "Program" category. Assuming you have installed adempiere on the C: drive, the suggested targets are:

• c:\adempiere\Run_Setup.bat/sh

• c:\adempiere\Run_SilentSetup.bat/sh

• c:\adempiere\utils\Run_ImportAdempiere.bat/sh

Compiling ADempiere

ADempiere is configured to use two directories for each project: a src directory and a build directory. They have the same structure within each project, differing only on the file suffixes: .class for the build directory and .java for the src directory. Compiling is the process of generating the .class files from of the .java files.

There are two ways for compiling:

• Automatically: by default, Eclipse builds (i.e. compiles) automatically when changes occur. Project > Build is checked by default after Eclipse installation.

• Manually: in desirable cases you may want to decide when to compile (for example, when debugging the ZK software). Ensure Project > Build Automatically is not checked. You have to remember to manually compile with Eclipse before running ADempiere.

Building ADempiere

Building is the process of archiving the class files into jar files and creating the installation files. Do not get confused with usage of the term "build". For Eclipse it means compiling the java files, whereas for ADempiere it is building the jar files.

There are three ways for building:

• Via console: open a console, change directory to /adempiere_trunk/utils_dev and run RUN_build.sh. This script performs a clean before building. You see the messages on the console.

• Via Eclipse ANT: in the navigator view, expand utils_dev and select the file build.xml. Run it via context menu (Run as > ANT Build). It is faster because it performs a build without clean.

• Via the external tool configurations created above to run the ANT build.

Build.xml draws information from the files build.properties and properties.xml. You can also create a file mybuild.properties to override these as required.

If you haven't installed a copy of the ADempiere client, you can do so with the ANT build as follows:

• Copy the utils_dev/build.properties file to utils_dev/mybuild.properties or to ${user.home}/.adempiere.properties. Edit the file and change the lines according to where the installed copy of Adempiere should go. For example, to install a copy in c:\adempiere, use these lines:

env.ADEMPIERE_ROOT=c:/
env.ADEMPIERE_HOME=${env.ADEMPIERE_ROOT}/Adempiere

• Create an external tool configuration to run the ANT target utils_dev/build.xml->install.

• Build ADempiere, if you haven't already (use your external tool or select utils_dev/build.xml and run as ANT build).

• Install ADempiere - using the external tool config created above.

• Create external tool configurations to execute programs c:\adempiere\run_setup and c:\adempiere\run_silentsetup as described above. Execute run_setup the first time and then run_silentsetup if you need to in the future. Set the parameters according to the instructions in Application Server Installation & Setup. This will create several of the needed files: adempiere.properties and utils/myEnvironment.bat.

Database Setup

ADempiere needs a database to function. If you haven't already installed one, follow the instructions in Database Server Installation & Setup.

Before you can run ADempiere, you will need to Initialize the ADempiere Database. You do this by executing the RUN_ImportAdempiere script in the ADEMPIERE_HOME/utils directory.

You can setup an external tool configuration as described above to run any of the scripts in the ADempiere installation from within Eclipse.

Debugging and Running the Client

Once all the installation items are complete, debugging or running the client is as simple as selecting the proper configuration. The application should launch immediately and you can use the power of Eclipse and Java to debug and change the application. The JVM capability of hot-swapping allows changes you make in the code to affect the running instance as you save the changes. For more information on using Eclipse, see the Eclipse documentation (Kepler).

Running and Debugging the Web Version

See Creating WebUI Workspace using Eclipse Webtool.

Debugging the Server

To debug the server you need to be able to compile and run the client.

Enable the debugging as follows:

• Append the following to the line that starts with ADEMPIERE_JAVA_OPTIONS to the file utils/myEnvironment.bat|sh

-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8888

The result will be something like:

@SET ADEMPIERE_JAVA_OPTIONS=-Xms64M -Xmx512M -DADEMPIERE_HOME=D:\Develop\Adempiere\stable\adempiere\Adempiere 
-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8888

• Start the server (using utils/RUN_Server2.sh). If you have compiled using the RUN_build.sh script mentioned in the prerequisites you'll find this script in adempiere/Adempiere/utils with the checkout directory as root).

• Use the "Attach debugger" option in your IDE. If you're using NetBeans you'll find that menu option under the main menu "Run". Attach to the server you're running ADempiere on using the specified port (in this example, port 8888).

• Add breakpoints as you please.

Procedures to Consider

If you are using a production database for testing, there is no need to import the seed data. You may have to migrate your database to a version that matches the software. You can do this by applying migration scripts (see Migration) or by using a Migration Tool which will compare your database against a reference and ensure that all the necessary information is added to your database. For more information, see the Migrate page.

First Time Use

Before you can debug the software, you will need to generate a few of the key configuration files required by the application. Assuming you have installed all the necessary software and have Eclipse configured properly, here are the steps:

1. Update your repository to the desired revision using your version control software. (Pick a working version for the first time - not a work in progress.)

2. Refresh Eclipse to ensure it is synced with the files in the repository following the update.

3. Copy uitls_dev/build.properties to mybuild.properties and modify to point the root to your local install directory - typically c: on windows machines.

4. Clean your development environment to remove old classes.

5. Build the code using the ANT build utils_dev/build.xml.

6. Install the code using the ANT install target in utils_dev/build.xml.

7. Run the RUN_Setup script in the install location (e.g. ${ADEMPIERE_HOME}/Run_Setup). For more information see Application Server Installation & Setup.
8. Copy the resulting adempiere.properties file to a safe location where it won't get overwritten inadvertently.

9. Create or modify your debug/run configurations to point the VM arguments to the copied adempiere.properties file.

10. Import the database seed (utils\Run_ImportAdempiere)

11. Apply Migrations to the seed (only if required. Migrations will be sql or xml files located in the migration\<version>-release folder. If this folder is empty, no action is required.

    1. Apply SQL migrations - usually for versions before the 380 release.

       1. In Eclipse, copy the adempiere/migration/postgres.properties.template to postgres.properties (or the equivalent file with oracle/mysql depending on your database). Modify the file according to your database setup.

       2. Navigate to the applicable directory in the adempiere/migration folder (e.g. adempiere/migration/370LTS-release/postgres) and run the ANT build.xml in that directory.

    2. Apply XML Migrations - after version 380LTS. Execute the debug/run configuration "Load XML Migrations". This will also apply all post migration scripts.

After these steps you should be able to debug the application from within eclipse using a debug/run configuration.

If you rename the adempiere.properties file, you can create copies with different setup options so you can change the main options simply by selecting different debug/run configurations.

Major Software Update

Following an update to your repository performed through the version control system, you will need to do the following steps, depending on the extent and nature of the change.

This procedure assumes you have all the necessary software installed and have successfully debugged ADempiere from Eclipse in the past.

1. Refresh your development environment.

2. Clean your development environment to remove old classes.

3. Build the code - that is the ANT build discussed above. This will create the necessary library files.

4. Import the database seed and apply migrations as described above.

After these steps you should be able to debug the application.

Working with a Clone from the Official ADempiere Repository

The ADempiere Project uses a Fork and Pull model. It is best practice to fork the ADempiere repository, develop within that fork, and then have the technical team "pull" your changes into the ADempiere repository.

This is best practice for ADempiere developers, for individuals who want to contribute or when you are working on a module/feature with a team and you commit, push, revert, merge etc. in many cycles before deciding to publish.

The steps to do so are described in ADempiere Version Control but, in summary, here the steps:

• Go to the Adempiere repository in Github, login with your Github account and fork from it following these instructions.
• Go to your Github account (for example https://github.com/MY_GITHUB_ACCOUNT) and see your fork. It will be under https://github.com/MY_GITHUB_ACCOUNT/adempiere.
• Clone the ADempiere repository locally with for example git clone [e-mail]:MY_GITHUB_ACCOUNT/adempiere.git or with Eclipse or your favorite IDE.

• Create a new branch for your development work. Follow the branch naming conventions in the Software Development Procedure - be specific. Keep your local branches limited to a single bug fix or feature development. Use as many branches as you need.
• Make some software changes and commit and push your local changes as usual and then push to your fork on github.

• When you want your changes to be submitted to the Technical Team to be accepted, follow these instructions or these instructions. Pay attention to the target branch on the ADempiere repository.
• Keeping your fork synced

  • When needed, sync your fork with the ADempiere repository as described here.
  • You then open your local project in Eclipse and pull changes from your fork.

Troubleshooting

Problems (and their solutions) that people often have when compiling ADempiere.

Use the proper Java version.

Make sure that the JDK and JREs used in Eclipse and installed on your computer are consistent. Check the Eclipse workspace settings, project settings and build settings if you run into problems.

Shell Scripts (Linux)

On Linux systems, you have to add "execute" permission to all the shell scripts before you start! Run the following command from the directory above the Adempiere directory to convert all shell script files.

find Adempiere -name *.sh -exec chmod +x "{}" \;

Thanks to "DeathMeat" on Freenode #adempiere for that. Notes: for OpenSuSE 10.1, it requires quote for the *.sh, which we shall type:

find Adempiere -name "*.sh" -exec chmod +x "{}" \;

• Errors running standard unix shell scripts

The standard unix shell scripts were created on a dos/windows platform and contain special characters that are incompatible with unix and which can cause strange errors when you run the scripts. The common dos2unix utility will correct this problem. Running the following command from the directory above the Adempiere install directory should fix this

find Adempiere -name *.sh -exec dos2unix -d "{}" \;

Thanks again to DeathMeat from freenode #adepiere for that.In addition to the shell scripts (i.e. *.sh files) you may also need to run this utility (dos2unix) against the file Adempiere/jboss/bin/run.conf.

OutOfMemoryError when running the ant build

Allow the ant Process to use more (heap) memory. One way of doing this is by setting the ANT_OPTS environment variable. Example for Windows:

set ANT_OPTS=-Xmx256M

For many Linux system, such as OpenSuSE, Fedora, Red Hat

export ANT_OPTS=-Xmx256M

You may get a MailLogger Exception

MailLogger failed to send e-mail!java.lang.Exception: Missing required parameter: MailLogger.from

Add these lines to Adempiere/utils_dev/mybuild.properties:

MailLogger.from=[e-mail] MailLogger.success.to=[e-mail] MailLogger.failure.to=[e-mail]

See also

• The interesting German version De_DE/eclipse-setup that goes right through debugging from the JBoss server.
• Hacker's guide
• Compile
• Creating WebUI Workspace using Eclipse Webtool