Difference between revisions of "Create your ADempiere development environment"

Revision as of 06:26, 24 February 2014

⇐ 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: 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: 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

Configure Eclipse

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

• Install the latest version and setup the software to run as you wish. See Installing ADempiere Manually.
• Customize a few files for your specific installation
• 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

Customization for your installation

To ensure the application works correctly for your installation, you can customize the following files and keep a copy of them in a separate location in case they are overwritten by the version control processes. 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.

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.

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.

Eclipse Configurations

There are a number of helpful utilities which you can configure to assist the development process.

Running ADempiere Client

If developer is using multiple project Eclipse setup then in dbPort project there are two launch configurations crated for him. So he only need to start them!!

Running Adempiere through eclipse is simply a matter of creating a run configuration (Run -> Run... -> Java Application -> New) that points to the main method in dbPort/src/org.compiere/Adempiere.java.
(in eclipse3.3, Run -> Open Run Dialog...; under Java Application; if 'Adempiere' is not found, select 'New_configuration')

Fill the tabs with the following values as the minimum required values to have a new run configuration:
Tab 1:

  Name: adempiere_trunk (or whatever you wish)
  Project: adempiere_trunk (this has to be the name of the ADempiere project in Eclipse)
  Main class: org.compiere.Adempiere

Tab 2:

  VM Arguments: -Xms64m -Xmx64m (you may use less or more memory for ADempiere)

The VM Arguments define the minimum and maximum RAM allocation for Java VM. Ensure that you allocation enough RAM for ADempiere to run well in Eclipse. Similarly you can create a debug configuration to run Adempiere with hot code swapping to see your alterations as you work.

DB Setup

If you did not previously install Adempiere for end-users, you need a database. For its installation, follow the instructions in Getting Started.

Important: The database dump is found at data/seed/Adempiere[_pg].jar - simply unpack the file and import it into the db.

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