Create your ADempiere development environment
⇐ Table_of_Contents#Developer's_Guide{{#if: | | [[{{{2}}}]] }}{{#if: | | [[{{{3}}}]] }}{{#if: | | [[{{{4}}}]] }}{{#if: | | [[{{{5}}}]] }} | Create your ADempiere development environment{{#if: Software Testing and QA| | Software Testing and QA }} ⇒
Contents
Preparing your Environment
Download and install the latest version of Java JDK from the Oracle website. You will need the latest version of the Standard Edition (SE) or Enterprise Edition (EE) Java Development Kit (JDK). 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.
Download and install a database. You can use PostgreSQL, Oracle or MySQL. PostgreSQL is recommended. Read more at Database Server Installation & Setup.
Note: if you have access to a database server, you can use that rather than install a local copy of the database.
Download and install the latest version of the Eclipse Integrated Development Environment (IDE) for Java EE Developers from the Eclipse web site.
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.
You can import the ADempiere project and other projects/modules into your IDE as follows:
- Open Eclipse, java perspective, package explorer view
- Eclipse menu->File->New->Project
- In the following dialog, select "Java Project" and "Next"
- Type in "ADempiere" as the Project name
- Check the radio button "Create project from existing source"
- Click the "Browse" button and go to the directory which contains the working repository of the project or module you want to include (the directory has a file named ".project" )
- Click "Finish"
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
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"
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 a External Tool Configuration to run the target "run-scripts".
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.
Note: 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.
Database Setup
If you did not previously install Adempiere for end-users, you need a database. 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 (.bat or .sh) script in the adempiere/utils directory.
Note: You can setup an external tool configuration as described above to run any of the scripts in the ADempiere installation from within Eclipse.
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