Wednesday, October 21, 2009

Execution Environment and javac entries

Execution Environment
Execution Environments have been explained in detail in this article. And from PDE API tooling perspective it has been explained here. In one line, EE represents the JRE. It is a set of properties, each marking a level of compliance. I am reproducing this table from 'Setting the Compilation Environment' help page.


Environment
Source
Target
CDC-1.0/Foundation-1.0
1.3
1.1
CDC-1.1/Foundation-1.1
1.3
1.2
OSGi/Minimum-1.0
1.3
1.1
OSGi/Minimum-1.1
1.3
1.2
JRE-1.1
1.1
1.1
J2SE-1.2
1.2
1.1
J2SE-1.3
1.3
1.1
J2SE-1.4
1.3
1.2
J2SE-1.5
1.5
1.5
JavaSE-1.6
1.6
1.6
PersonalJava-1.1
1.1
1.1
PersonalJava-1.2
1.1
1.1
CDC-1.0/PersonalBasis-1.0
1.3
1.1
CDC-1.0/PersonalJava-1.0
1.3
1.1
CDC-1.1/PersonalBasis-1.1
1.3
1.2
CDC-1.1/PersonalJava-1.1
1.3
1.2

There are more properties and are provided by org.eclipse.jdt.core

org.eclipse.jdt.launching plug-in provides an extension point (id = org.eclipse.jdt.launching.executionEnvironments) for contributing EEs. JDT Launching plug-in also extends it and provides the EEs that are listed in the above table. If you really want to see the code then check out JavaCore.java and CompilerOptions.java in org.eclipse.jdt.core plug-in.

Manifest.MF

The execution environment for a bundle can be defined in the Manifest.MF file. A typical entry for Java 1.4 environment will look like this.

Bundle-RequiredExecutionEnvironment: J2SE-1.4

The manifest editor provides an easier way on the Overview tab.


Execution Environment section on Overview page of Manifest Editor

The Add button opens a selection dialog with the list of available execution environments (contributed to the extension point org.eclipse.jdt.launching.executionEnvironments). By default the list is same as those listed in the table above.

jre.compilation.profile
The execution environment in build.properties is mentioned using the jre.compilation.profile entry. It takes same value as BREE entry in manifest.MF. Thus, the entry for Java 1.4 will look like this.

jre.compilation.profile = J2SE-1.4

javacSource, javacTarget and javacWarnings
These entries can be used to override the jre.compilation.profile entry in build.properties. A certain EE mandates a particular version for Java source and generated class file compliance. These versions can be overridden using these entries. These entries can be used without jre profile entry as well. If you just want to specify the java source version then only javacSource entry will suffice.

Looking at the table above we can see that J2SE-1.4 is Java source at version 1.3 and class files version 1.2 compliant. This can be mentioned in build.properties as

javacSource = 1.3
javacTarget = 1.2

Please note that the above two entries are not equivalent to jre profile entry for J2SE-1.4. This is because an EE is other properties too like system packages, boot delegation, assert and enum identifiers. See the schema description for the EE extension point discussed above.

Eclipse uses batch compiler to build the plug-ins. It is located inside org.eclipse.jdt.core. Since version 3.2, it is also available as separate download - ecj.jar - Eclipse Compiler for Java. The batch compiler accepts many options and a list and details can be found here. The javacSource and javacTarget entries map to -source and -target options.

javacWarnings.<library> entry is used to pass the warning options (-warn) to the compiler. The entry to suppress warnings for assert and enum identifiers in library.jar will look like this

javacWarnings.library.jar = -assertIdentifer, -enumIdentifier


Thursday, October 15, 2009

Eclipse Demo Camp. Bangalore '09

This year's Eclipse Demo Camp at Bangalore will be held on November 5, 2009. Various demos have already been lined up on topics like GEF 3D, SWTBot, Jazz, XText, E4 and JSDT. If you are working on some cool stuff and want to share it with Eclipse community then this is your best chance. Do get in touch as there is still room for couple of more demos.

30 participants from 15 different companies like IBM, HP, Oracle, Nokia, Bosch, Infosys  and ThoughtWorks (to name a few) have already registered. There are limited seats available so hurry up if you want to catch all the cool stuff Eclipse community is doing. Registration is free and available on First-come-First-serve basis. Details at Eclipse Wiki.

See you there.

Sunday, October 11, 2009

Source folders and src.includes

Source Folders

A source folder is, of course, a folder which contains source code. But where it is identified is in .classpath file. This is how a typical .classpath file looks like.

<?xml version="1.0" encoding="UTF-8"?>
<classpath>
<classpathentry kind="src" path="src"/>
<classpathentry kind="src" path="src_samples"/>
<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/J2SE-1.4"/>
<classpathentry kind="con" path="org.eclipse.pde.core.requiredPlugins"/>
<classpathentry kind="output" path="bin"/>
</classpath>

org.eclipse.pde.ui/.classpath

The kind="src" marks a folder as source folder. Similarly, the kind="output" marks a folder for output - where all the binaries will go after the build. In Eclipse you don't have to modify/manage the .classpath file manually. Various wizards are available to do all the work for us such that we never even have to look at .classpath file.

New Source Folder Wizard
Use New -> Source Folder from File or context menu to invoke the new source folder wizard. It's a very simple wizard. It asks for the project and the folder name. When you click Finish, it will create that folder and mark it as source folder.




New Source Folder Wizard
The way we can check that the folder has been marked as source folder is by opening .classpath file. But there is a simpler way. Check the Source tab on the project's Java Build Path properties page. This can be invoked as Project -> Properties or simple Alt + Enter on the project in Package Explorer view.


Java Build Path properties page
Source Folders and Output Folders

If you notice the check box towards the end "Allow output folders for source folders" is unchecked. This means the binaries for all the source folders will go to the default output folder (mentioned right below this checkbox, typically named as bin. The bin is for binaries and not like one in recycle bin).

However, we can select this check box and associate a specific output folder for every source folder. This will make the binaries for that particular source folder to get created in the associated folder. Note that this does not makes the associated folder an Output Folder. That is, no kind="output" entry in .classpath file. Only the source folder entry gets a output="foldername" attribute.


Java Build Path properties page with associated output folders

build.properties

The build path only brands the folders are source or otherwise. The actual build and output binaries are controlled by build.properties file.

src.includes
This entry in build.properties file specifies the folders whose contents also needs to be added to the source build. Source build is the source bundle or the source inside the exported plug-in. The emphasis on ALSO is to highlight the fact that the source folder are part of source build by default and they should not be added explicitly using src.includes. In fact, it only cause unwanted side effects as mentioned in bug #286808.

src.excludes

This entry explicitly removes a folder from source build. It is used when a parent folder is part of source build and only specific child folder has to be  excluded from the source build.

Both these entries take relative folder paths. The Build tab on the Manifest editor provides a very easy UI to deal with them so that we don't have to add them manually to build.properties.



Binary and Source build section on Build tab of Manifest editor
The corresponding build.properties will look like this.



build.properties

Similarly the bin.includes and bin.excludes are used to control the folders involved in the binary build. Again, notice that source folders and files like .classpath, MANIFEST.MF and plugin.xml have not been added to src.includes because they are not required in source build.