Saturday, November 21, 2009

source.<library> and output.<library>

The source and output properties in build.properties control the folders to be compiled and where to place the resulting output. The eclipse help briefly talks about it.
    * source.<library> - lists source folders that will be compiled (e.g. source.xyz.jar=src/, src-ant/). If the library is specified in your plug-in.xml or manifest.mf, the value should match it;
    * output.<library> - lists the output folder receiving the result of the compilation;

Source Folders and Output Folders


Source and Output folder have already been discussed in this post. Only the source folders gets compiled and the generated class files get stored in the corresponding output folder. A project can have one or more source folder. If a source folder does not have a output folder attached to it explicitly, its output will go to the default output folder. The .classpath file stores all this information.

source.. and output..

The real syntax is source.<library> and output.<library> where <library> is generally the name of the jar. Here the second dot signifies the default library. Any source folder assigned to it gets it output reside in the root when the plug-in is build. The output.. entry tells the PDE Build where to pick the classes for source.. from.
Typical entries look like this
source.. = src/
output.. = bin/

When a plug-in with above entries is build the structure of the plug-in jar will look like this
org.example.sample_1.0.0
│   plugin.xml
│
├───icons
│       sample.gif
│
├───META-INF
│       MANIFEST.MF
│
└───org
    └───example
        └───sample
            │   Activator.class
            │
            └───actions
                    SampleAction.class

More complex plug-ins have more than one source folder. org.eclipse.pde.core is one such plug-in. It is good practice to assign separate output folder for separate source folders. This is not mandatory.
Lets assume src and src_an are the two source folders and their corresponding output folders are bin and bin_ant. Then a build.properties like
source.. = src/
output.. = bin/
source.ant_tasks/anttasks.jar = src_ant/
output.ant_tasks/anttasks.jar = bin_ant/
will create a plug-in which will look something like this
org.example.sample_1.0.0
│   plugin.xml
│
├───ant_tasks
│       anttasks.jar
│
├───icons
│       sample.gif
│
├───META-INF
│       MANIFEST.MF
│
└───org
    └───example
        └───sample
            │   Activator.class
            │
            └───actions
                    SampleAction.class
The contents of the src_ant folder will get compiled and jared in to anttasks.jar inside ant_tasks folder because of the source.ant_tasks/anttasks.jar = src_ant/ entry.

Classpath vs source/output entries

The source folder and output folder information is already available in class path then why source/output entries are needed? The classpath entries are used to compile source code. But the PDE Build relies on the source/output entries while building (or exporting) the plug-ins. Suppose a plug-in A refers to a class C in plug-in B. Then while building the plug-in A PDE Build will look into build.properties of plug-in B to locate the C.class.

Rules of using source. and output. entries
  1. Every source folder should appear in a source. entry.
  2. A source folder can appear in one and only one source. entry.
  3. The source and output folders are specified as their path relative to the root of the project.
  4. All source folders whose output folder is same should belong to same source. entry.
  5. The corresponding output folders should be mentioned in the corresponding output.entry.
Note that should in above rules means that rule is a good practice and not an obligation but if not followed the result of PDE Build might be unexpected.