Source folders and src.includes

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.

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.