For many projects, Apache Ant is used as the build tool (Ant is used as the internal build tool for NetBeans projects). It is not uncommon for these projects to have custom Ant build scripts that are used to build, test, and deploy the projects.
Rather than having to amend the structure of existing projects, NetBeans provides the facility to create a Free-Form project. In a Free-Form project, NetBeans invokes Ant targets to perform build options.
The Ant script used in these types of projects must be managed independently of NetBeans, and any changes required to the build procedure must be directly defined within the projects' build script.
Free-Form projects are only recommended when an existing Ant project has a fixed structure, but the developer wants to use NetBeans for further development of the project. For smaller projects, creating a new NetBeans project or a Maven project may be a better option.
This recipe shows how to create a Free-Form project from within the NetBeans IDE by importing an existing Ant project.
Getting ready
This recipe assumes that you have an existing Java project that uses Ant as the build tool and shows you how to import the project into a NetBeans Free-Form project.
How to do it…
1. Click on File and then click on New Project....
2. On the resultant dialog, select the Java category and select the Java Free-Form Project project, as shown in the following screenshot:
3. Click on Next.
4. Browse for the Ant project's location. NetBeans should then parse the build.xml file for the project and populate the Build Script, Project Name, and Project Folder options.
5. Click on Next.
6. Five NetBeans actions are now shown (Build Project, Clean Project, Generate Javadoc, Run Project, and Test Project). Select the Ant targets for these project actions. If there is no Ant build target for a specific action (for example, the Ant build script has no ability to generate Javadoc), then leave the action blank.
7. Click on Next.
8. Enter Source Package Folders and Test Package Folders for the project.
As with the previous stage, NetBeans will attempt to work out these values from the build.xml file.
9. Click on Next.
10. If there are any additional classpath entries required, specify them as Java Sources Classpath.
11. Click on Next.
12. From the Output JARs of Folders Containing Compiled Classes field, select the folders that contain the compiled classes or .jar files.
13. If any Javadoc is generated during the build process, enter the location in the Javadoc Output field.
14. Click on Finish for NetBeans to create the Free-Form project.
How it works…
When a Free-Form project is created, NetBeans creates a special type of project that uses a custom Ant script to build the project. This project can have the source code stored wherever it is defined by the Ant script and does not have to follow the code layout guidelines of NetBeans.
As with other types of projects created within NetBeans, once the project is created, it is opened and shown in the Projects explorer, as shown in the following screenshot:
As long as the relevant mappings were defined correctly between NetBeans actions and the Ant targets, the developer can build, clean, run, test, and generate Javadoc from within the IDE using the standard menu items and keyboard shortcuts.
Selecting the build.xml file within the Projects explorer shows all of the Ant targets that have been defined within the file. Double-clicking on any of these will run the target.
It is important to note that any changes made to the project settings via NetBeans, for example, adding extra dependencies to the project or additional source roots, will not affect the way the project is build. The project is built exactly as defined within the build.xml file. This can sometimes lead to confusion; for example, NetBeans may show that there are no missing dependencies for a project, but the project itself will not build due to missing dependencies. It is important to remember that it is the Ant file itself (not NetBeans) that defines how the project is built.
There's more...
As stated in the previous section, it's important to remember that, with Free-Form projects, the project is built by Ant as defined within the build.xml file. Any changes to the project's metadata within NetBeans will not affect how the project is built.
To add extra source nodes to a project or to add additional dependencies, it is important that these are first defined within the build.xml file and then added at the NetBeans project level. This is achieved within NetBeans by right-clicking on a Free-Form project and selecting Properties. The resulting dialog box allows all of the configuration options defined at the project creation to be modified.
Using a different version of Ant
NetBeans is bundled with a version of Ant. This enables developers to use Ant from within NetBeans without having to install a separate copy.
If you wish to use a different version of Ant within Free-Form projects, this can be configured by selecting Tools and then clicking on Options from the main NetBeans menu. On the Options dialog box, select Java and then select the Ant tab.
Within this Options dialog box, a different version of Ant can be specified together with any classpath or properties required to build your projects.
To quickly change back to the default version of Ant supplied with NetBeans, click on the Ant Home Default button within the Java section of the Options dialog box.