Tools, frameworks and modules

Code and other artifacts are typically structured in units, lets call them modules, although Eclipse and many other IDEs call them projects. Physically a module is represented by a folder with files containing meta-data (name, dependencies on other modules, etc.), instructions for building it and the code and artifacts themselves.

Different tools and frameworks organise modules in different ways, and for a developer it's essential to understand the expectations and requirements of these tools and frameworks. Complicating the matter is the fact that we often need to mix several tools and frameworks and make sure they have compatible meta-data for the module. E.g. it is pretty common to configure Eclipse projects to build with maven, hence, a module folder must be both configured as an Eclipse project and as a maven module. And if this module represents an Eclipse plugin or OSGi bundle project, we need to make OSGi happy, too.

Below we detail the structure and meta-data expected by these three tools and frameworks.

Eclipse modules (projects)

A folder is identified as an Eclipse module (Eclipse calls them projects) by the presence of a .project file (also see http://stackoverflow.com/questions/7186676/whats-in-an-eclipse-classpath-project-file). This file contains the project's name (which may differ from the folder's) and a list of so-called build participants. A build participant is an Eclipse component that takes part in the process of building the project, e.g. generating artifacts, compiling Java files, indexing files etc. Eclipse manages the build process by notifying the build participants of changed files and instructing them to perform their build tasks.

Which build participants a project needs is rather technical, but it is based on what kind/category of module we have. If it is an ordinary Java module, it needs a Java builder, if it's an Eclipse plugin module it needs two additional builders and if it's a maven project it needs a maven builder. Eclipse uses the concept of nature (similar to an aspect), which are listed in the .project file, each of which contributes build participants to the project.

Each build participant typically requires additional configuration stored in specific files. The Java builder is configured by the .classpath file, which can be edited as text file (not recommended) or by using the Project > Properties > Build path dialog. Similarly, the plugin builders use the META-INF/MANIFEST.MF and plugin.xml files, and the maven builder uses the pom.xml file (the same one used by the mvn command line tool). Quite often, information in these files needs to be consistent with each other, e.g. .classpath, MANIFEST.MF and pom.xml all may include information about the Java version and how to create the classpath used by the compiler, and if these are not consistent you may get strange results.

The Project > Properties > Build path dialog that is used for setting up the Java classpath

Eclipse supports hierarchical modules, in the sense that you may import modules from nested folders and view them as a hierarchy in the Project Explorer view.

OSGi modules (bundles)

An OSGi module (OSGi calls them bundles) is identified by the META-INF/MANIFEST.MF file. This file includes the module name (global identifier) and version, dependencies on other modules, exported packages and other requirements. It may also refer to other files, e.g. OSGi component description files. MANIFEST.MF may be edited as a text file, or by using the manifest editor which is the default editor for this file type. Note that MANIFEST.MF files are also used for holding meta-data of other kinds of modules when packaged in jar files, and OSGi extends this with bundle meta-data.

Overview tab, for editing name, version and Java version	Dependencies tab, with the required bundles	Runtime tab, with the exported packages

See also http://www.programcreek.com/2011/07/osgi-framework-architecture-three-conceptual-layers/, http://www.javaworld.com/article/2077837/java-se/java-se-hello-osgi-part-1-bundles-for-beginners.html, http://www.slideshare.net/alexproca1/osgi-overview

Eclipse plugin modules

An Eclipse plugin is actually an OSGi bundle, so META-INF/MANIFEST.MF is the most important configuration file. In addition, the plugin.xml file provides information about how the module extends Eclipse is various way, using the extension point mechanism (see Eclipse Architecture). The plugin.xml file is either created by hand or by tooling, when you explicitly or implicitly extend Eclipse. This will add a tab to the Manifest editor with an XML editor for the plugin.xml contents.

Maven module

A maven module is a module built using Apache maven and its mvn command line tool. The build process is controlled by the pom.xml file, which contains information about the module itself, like name and version, and the tools taking part in the build (similar to Eclipse's build participants). Mavens module concept is similar to, but not the same as an OSGi bundle. A maven module has a name (consisting of two parts, the artifact id and group id) and version, and can depend on other modules. In addition, maven modules form a hierarchy and configuration information (in pom.xml) is inherited down the hierarchy.

So why use maven instead of building with Eclipse? Well, maven lets you manage more complex builds than Eclipse can, and the build is easy to reproduce on other machines including build servers in the cloud, and hence, better for team work and larger and more complex projects. Does this mean we need to use the command line, instead of Eclipse for building? Luckily no, since with Eclipse's m2e plugin, an Eclipse project can be configured to use an embedded maven for managing the build process. Hence, it will be the pom.xml file for controlling the build.

Based on this, you could imagine that you had to duplicate information in MANIFEST.MF in pom.xml to use maven to build OSGi bundles and Eclipse plugins, but this is not the case. Instead you configure maven to use the Tycho extension, which reads the necessary dependency information from MANIFEST.MF, so you avoid this duplication. Think of Tycho as Eclipse's Java and plugin builders packages as a maven extension, so maven essentially can perform the same build as Eclipse does natively. Hence, when using m2e and Tycho, you actually make Eclipse use maven for building and maven in turn uses (part of) Eclipse. This also means that the build is controlled partly by the pom.xml file and partly by the MANIFEST.MF file, and hence, that these must include consistent names and versions.