View source for Developing Plug-Ins - Setup the workspace

<span style="color:red">'''This page contains outdated information. iDempiere has moved to Maven and Git'''</span>
[[Category:Development|P]]
[[Category:Developer documentation‏‎]]
[[Category:Plug-In Development]]
[[Category:HowTo]]
[[Category:CandidateForObsoleteNotice]]
__TOC__

==== ⚠️ '''Deprecated Page''' ====

'''This page is retained for historical reference only.''' The documentation has been updated and migrated to Docusaurus: https://docs.idempiere.org/docs/basic-development/plugin-development/developing-plugins


This tutorial is brought to you by Jan Thielemann from evenos GmbH (www.evenos-consulting.de). If you have questions, criticism or improvement suggestions, feel free to visit me ([[User:Jan.thielemann|Jan.thielemann]]) or write me [mailto:jan.thielemann@evenos.de an email]

=Goal of this tutorial=
In this tutorial you will learn how to setup the Eclipse development environment so you can start developing for iDempiere. This tutorial is based on http://www.globalqss.com/wiki/index.php/IDempiere/Setting_up_Eclipse but gives you some additional information.

If you have trouble, try to take a look at http://www.globalqss.com/wiki/index.php/IDempiere

=tl;dr=
https://www.youtube.com/watch?v=s8qwKyc1P3c
https://www.youtube.com/watch?v=HvWA86-ev1c

=The workflow=
If you want to develop for iDempiere, you will need some software. You need an IDE (eclipse), a SCM (Mercurial), a database-server (PostgreSQL or Oracle) and of course the source code for iDempiere.

==Mercurial==
Lets start with Mercurial. Mercurial is a distributed source control management tool with a very powerful way of merging without the pain of other comparable tools. If you are using a UNIX system, you normaly can install mercurial from the commandline using 

<pre>
apt-get install mercurial
</pre>

If your distribution does not have mercurial in its default repositories or if you are using Windows or OS X as your operating system, you can download Mercurial from http://mercurial.selenic.com/

==eclipse==
Eclipse is the most commonly used IDE when it comes to Java development. Most of the developers from the iDempiere project use eclipse. 

===Installation===
If you have a UNIX system, you normaly can install via the commandline.
<pre>
apt-get install eclipse
</pre>
However, if you want the latest version, you can download eclipse directly at http://eclipse.org/downloads/ . We at the evenos Consulting GmbH use the Eclipse IDE for Java EE Developers because it already includes some useful tools we use in our company (e. g. Mylyn) but the basic installation should also work. Download and unzip eclipse to a directory of your choice and start it.

===Buckminster===
Due to wikipedia, Buckminster is an Eclipse technology sub-project focused on component assembly. It is used to resolve dependencies and build the installers. It is available as a headless version as well as a eclipse plug-in. Here we will install the eclipse plug-in. To do this, open your eclipse and chose a workspace location of your choice. Normaly eclipse uses %USER_HOME%/workspace, which is ok for now. We will later change the workspace. After eclipse has started, you need to find out your eclipse platform version. To do this, go to the "Help" menu and click on "About Eclipse". In the popup, click on the "Installation Details" button. In the next popup, locate the "Eclipse Platform". If you use the eclipse IDE for Java EE Developers, it's located in this bundle. Note the version number. If you use eclipse Keplar for example, it should be something like 4.3.2.Mxxxxxxxx. The 4.3 is important, remember it. You can now close all the popups.

Now go to the "Help" menu again and chose "Install New Software". Here you have to add a new update site for Buckminster. This site depends on your eclipse version. If you use 4.3, you add:
<pre>
http://download.eclipse.org/tools/buckminster/updates-4.3
</pre>

If you use eclipse 4.2, the update site is:
<pre>
http://download.eclipse.org/tools/buckminster/updates-4.2
</pre>

Make sure the version number behind "updates-" fits your eclipse version. Otherwise you will get errors later. After you added the site, chose it from the dropdown and install the following bundles from the Buckminster section:
<pre>
Buckminster - Core
Buckminster - Maven support
Buckminster - PDE support
</pre>

After the installation finished, you may need to restart eclipse.

===MercurialEclipse===
MercurialEclipse is another useful plug-in for eclipse. It lets you do different mercurial actions from within eclipse with a graphical user interface. However, it's your own choice if you want to use the commandline, another graphical tool like tortoisehg or MercurialEclipse. To install MercurialEclipse, you have to add the following site just like you did with Buckminster:
<pre>
http://cbes.javaforge.com/update
</pre>
If the update site is down, you can still download it directly from the project site http://javaforge.com/project/HGE

==PostgreSQL==
PosgreSQL is a open source database object-relational database system. If you don't want to pay a lot of money for Oracle, we recommend you to use postgres instead. It is fast, stable and highly configurable.
 
===Installation===
If you have a UNIX system, the installation of postgres is really simple '''but be careful''', depending on your servers locale settings you could get problems later. We highly recommend you to use a utf8 locale.
<pre>
apt-get install postgresql-9.3
</pre>

I also suggest you to install some additional tools:
<pre>
apt-get install postgresql-common
apt-get install postgresql-contrib-9.3
</pre>

You also can download PostgreSQL for Windows, OS X or other systems at http://www.postgresql.org/download/

===Configuration===
After the installation, you need to do some basic configuration. On UNIX systems, the two files you mostly want to modify are
<pre>
/etc/postgresql/9.3/main/pg_hba.conf
/etc/postgresql/9.3/main/postgresql.conf
</pre>

In the pg_hba.conf, you configure who is allowed to access your databases from the local computer or the network. We normaly trust all the users in our local network so we add/replace the following lines:
<pre>
local   all             all                                trust
host    all             all             192.168.0.0/24     trust
</pre>
This will allow all computers from within our network to access all databases with all users. You can also implement a more secure security policy here but for development that should be fine. The host line is there because in our company, many developers use the same development database on a database server.

In the postgresql.conf you have to make a minor change so that the database server listens on the network. We normaly only change the following line which is outcommented by default:
<pre>
listen_addresses = '*'
</pre>

After these changes, you need to restart the database server.

===Prepare the database===
Before we can use a postgres database for our iDempiere, we first need a new user and a database. To create the user, you can either use a graphical tool like pgAdmin3 or you can use the commandline:
<pre>
sudo su - postgres
psql -U postgres -c "CREATE ROLE adempiere SUPERUSER LOGIN PASSWORD 'adempiere'"
</pre>

To create the database, you can use the following command:
<pre>
createdb  --template=template0 -E UNICODE -O adempiere -U adempiere idempiere
</pre>

If you are using PostgreSQL, you also have to enable the UUID extension
<pre>
9.0 and lesser:
psql -d idempiere -U adempiere -f db/ddlutils/postgresql/uuid-ossp.sql

9.1 and above:
psql -d idempiere -U adempiere -c 'CREATE EXTENSION "uuid-ossp"'
</pre>

==Sourcecode==
Now we come to the interesting part, the source code.

===Clone the repository===
First, you need the source code on your machine. To do this, you can either use MercurialEclipse, the command line or another graphical tool. You can clone the code via https which is a little bit slower or via ssh:
<pre>
cd workspace
hg clone https://bitbucket.org/idempiere/idempiere
</pre>
<pre>
cd workspace
hg clone ssh://hg@bitbucket.org/idempiere/idempiere
</pre>

===Create the targetPlatform===
Once you have the repository cloned, switch to the directory and create a new folder called targetPlatform
<pre>
cd workspace/idempiere
mkdir targetPlatform
</pre>
The targetPlatform directory will be used to store the different dependencies you need for iDempiere. After you created this directory, open eclipse but this time, chose the iDempiere repository as the workspace. After Eclipse opens, the project explorer will be empty. Don't worry about this, we will fix it in a second.

Click on the Eclipse menu "Window" and chose "Preferences". Go to the section "Plug-in Development" and select the entry "Target Platform". Here you click on "Add...". In the popup, select "Nothing" and click on "Next". Provide a name like "iDempiere Target" and hit the "Add..." button. Chose "Directory" and click on "Next". In the location field, you can either browse your filesystem and chose the targetPlatform directory you created or you can type in:
<pre>
${workspace_loc}/targetPlatform
</pre>
Click on "Finish" and you will see the directory with 0 plug-ins available. Hit "Finish" once again and you are nearly done. Now select the newly created target definition to make it active and click on "OK".

===Materialize the Project===
The final step is to materialize the project. To do this, hit the "File" menu and chose "Import...". Search for "Materialize from Buckminster MSPEC, CQUERY or BOM" in the Buckminster section. Click on "Next" and hit the "Browse" button. Chose the org.adempiere.sdk-feature directory from the idempiere repository and open the adempiere.mspec. Eclipse will now start materializing the project. Once it has finished, you should see all the bundles in the project explorer. Some of them might have a red cross but don't worry about this. Just build all projects one or two times (by chosing the "Project" menu and selecting "Build All" or simply by hitting Ctrl+B). After you build all the code, the errors should be gone and you can run the code.


==Run the Code==
Before you can start the application you need some additional last steps.
===Import the Database===
The first step is to import the database. To do this, you can go to the iDempiere directory on your hard drive and switch to the org.adempiere.server-feature/data/seed directory. Here you have seeds for different versions of database servers. If you installed PostgreSQL 9.3 as suggested, then you can unzip the Adempiere_pg.jar and import it into the database we created earlier:

<pre>
cd ~/workspace/idempiere/org.adempiere.server-feature/data/seed
unzip Adempiere_pg.jar
psql -U adempiere -d idempiere -f Adempiere_pg.dmp
</pre>

For Oracle databases, use the Adempiere.jar or for older PostgreSQL versions (<9.0) use the Adempiere_pg84.jar.

===Run the setup===
Once the database is imported you can switch back to Eclipse and run the setup. You don't need the setup if you want to start the Swing client but if you want to run the server from within eclipse, you first need to run the setup. To do this, click on the "Run" menu and chose "Run Configurations". Select the install.console.app from the Eclipse Application section and run it. On the console window, you have to provide some information:
*Java Home (should be found automatically)
*iDempiere Home (should be found automatically)
*Key Store Password (provide your own or use the default password)
*Application Server Host Name (the name of your computer)
*Application Server Web Port (default is 8080)
*Application Server SSL Port (default is 8443)
*DB Already Exists (here you should chose "Y")
*Database Type (chose your database type)
*Database Server Host Name (name of the computer where the database server runs)
*Database Server Port (default is 5432 for PostgreSQL if you haven't changed it)
*Database Name (idempiere or whatever you called it when you created it)
*Database User (adempiere or whatever you called it when you created it)
*Database Password (adempiere or whatever you entered when you created the user)
*Database System User Password (leave it empty except if the setup fails for this reason)
*Mail Server Host Name (this one cannot be empty or the setup will fail. However, you can basically enter whatever you like)
*Mail User Login (you mail login credentials)
*Mail User Password (you mail login credentials)
*Administrator EMail (you mail login credentials)
*Save Changes (chose "Y")

After the setup, files called idempiere.properties and idempiereEnv.properties will be created in the workspace directory which the server needs to start. Also the setup will tell you if it was successful or not.

===Start the Application===
If you have done everything right, you are now able to start the server and develop for iDempiere. To start the server, once again go to the Run Configurations but this time chose the server.product. Run it and after you see the message "WebUIServlet.init: iDempiere Web Client started successfully", you can access the WebUI on via a webbrowser of your choice on http://<host>:<port>/webui 

If your computer for example is called bea and you use port 8080, then here are some interesting pages to visit:

* Admin Panel: http://bea:8080/
* WebUI: http://bea:8080/webui
* WebServices: http://bea:8080/ADInterface/services
* Apache Felix Web OSGi Console: http://bea:8080/osgi/system/console/bundles