Create your ADempiere development environment

From ADempiere
Revision as of 10:27, 25 February 2014 by MJMcKay (Talk) (→‎Compile and Debug ADempiere)

Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.

⇐ 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 }} ⇒

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.

Note.gif Note:

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 linus 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.

Note.gif 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"
Note.gif Note:

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 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.gif 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.gif 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

Retrieved from "http://www.adempiere.com/index.php5?title=Create_your_ADempiere_development_environment&oldid=9667"