Below is a listing of software applications that you will need to install in order to develop in the OpenMRS codebase. The installation process may vary somewhat for Windows, Linux (Step By Step Instructions), or Mac OS X platforms. Still, OpenMRS depends mostly on Java which runs the same across those systems. This list will try to describe the software which you should install to start work on any development computer.
See also http://notes.openmrs.org/OpenMRS-University-2012-12-19 where you can find videos showing the same steps.
Dependencies to install
Java is the language in which OpenMRS is written. The latest version of OpenMRS requires at least Java version 1.6. If you plan to edit the source, you will need the JDK; if you plan just to run OpenMRS, you will only need the JRE.
If using a JDK, then navigate to Window -> Preferences -> Java -> Installed JRE's to check if the JDK has been set. If not, do so.
There are tests failing when run on JDK 1.7 so please use JDK 1.6 until TRUNK-3142 is resolved.
MySQL is the database software most people use for the OpenMRS database. You should know your MySQL root password, or have a database ready with username and password to install OpenMRS into.
Eclipse 4.2.x (Juno) Instructions
Eclipse IDE for Java EE Developers is the recommended Java development environment. Get the latest stable release (though OpenMRS should still function on older versions that can use Maven integration). Eclipse 4.2.2 includes support for Git, but not for Maven so it must be added via plugins. Some OpenMRS modules are still in SVN instead of Git, so if you need to access them, you will want to install SVN plugins as well. We recommend Eclipse 4.2 (Juno). However, the following installation instructions would also work on Eclipse 3.7 (Indigo) - just pay attention to which plugins you need with which version (and note there's a "shortcut" described below if you have a clean 3.7 install and want to just get all the additonal plugins in one go). If you are already running Eclipse 3.6 (Helios) and want to do OpenMRS development from there, see our old instructions.
Congratulations, if the above steps were successful, then Eclipse has been configured and is ready for use.
Jetty, a development-oriented J2EE server, is automatically provided with OpenMRS 1.8+, via Maven, and it integrates nicely with Eclipse's Run and Debug workflows. It is perfectly sufficient for most developer purposes.
Tomcat is a J2EE server on which OpenMRS can be deployed. Most production installations of OpenMRS run on tomcat, so if you want to test against the most common environment, you should install tomcat. You will want the core that matches your system specs the closest: probably 32-bit zip or 64-bit zip or bz2 on Linux.
Check out the core from Git Hub
Most importantly, you need to get the OpenMRS core code from GitHub: https://github.com/openmrs/openmrs-core
See Using Git for the overall docs.
For specific instructions for using Egit and Maven tools you have installed above, see Git IDE Integration.
If you are contributing to the main OpenMRS codebase, you want to check out "openmrs-core". If you want to contribute to a module, you should check out the release branch for the module's lowest required OpenMRS version (e.g.1.8.x or 1.9.x). OpenMRS began using Maven in 1.8.x, so for modules that run on earlier OpenMRS versions, you may find it easier to just check out1.8.x and test against that.
Use Maven to compile and generate source files.
Go to the most outer project directory and run:
It will compile, run tests, build all artifacts and install them to your local repo.
Before trying to run OpenMRS ensure you have MySQL running. Also, it is highly recommended to increase the memory available by following the steps in the Maven setup, or see Troubleshooting Memory Errors.
You can now run OpenMRS by deploying the built WAR file into a J2EE container such as Tomcat or Jetty, or you can run it directly from the source code using the Maven Jetty plugin. The latter method is easier for developers as you can launch it from your IDE. However, if running this way for the first time, you will need to first manually install the core logic module. To do this, download the logic omod and copy it to your modules directory. Then you you start OpenMRS as follows:
Wait for the [ INFO ] Started Jetty Server message and open the web browser at http://localhost:8080/openmrs. Follow the instructions.
(Optional) Module development
To contributing to an existing module, you need to check out its code.
If the module's source code is in Git, follow the Using Git instructions. If the module's source code is in subversion and the module is mavenized (i.e. it has a pom.xml file) then you should follow the same process described for the core code.
Older modules may be in subversion, and not yet mavenized (i.e. they have no pom.xml file). To check these out do New -> Checkout project from SVN.
After you cloned a module you need to build it with mvn clean install.
To install a module, start OpenMRS and go to Administration -> Manage modules -> Add or upgrade module. You need to upload here an omod file, which you can find under cloned_module/omod/target.
Once checked out, the pom file of each OpenMRS module will display the following error in Eclipse -
"Plugin execution not covered by lifecycle configuration: org.codehaus.mojo:build-helper-maven-plugin:1.5:parse-version (execution: parse-version, phase: initialize)"
This has no affect on the operation of the application, and can be safely ignored. (You may also choose "quick fix" and install the scm connector for this plugin.)