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 with XML format. 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 participant a project needs is rather technical, but it is based on what kind 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) each of which decides which build participants are needed.

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.

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, dependencies on other modules and other requirements. It may also refer to other files, e.g. OSGi component description files.