Using the build system in NetBeans

While it is possible to build the code of your project in NetBeans, eclipse will currently give you a much smoother integration experience. Contributions towards automatically generating NetBeans files from our build system are very welcome. Currently, NetBeans projects have to be set up manually.

NetBeans has, in the background, an ant based build system that is not unlike our own build system. You can combine these, but you need to take some pre- cautions when you create a NetBeans project. Potential problem: by default, NetBeans want to create its own build.xml ant file in the project directory. The solution is to first create a project, including the appropriate build file, and the appropriate directory structure including the lib, the src, test\lib, and test\src directories. Check that it compiles, etcetera, but after that: do an ant clean. (Otherwise, NetBeans will complain that there is already a build directory in your project.)

Then there are basically two options to proceed: the first is to create a NetBeans "free form" project. In that case, NetBeans will simply pick up your existing build.xml file, and use that for it own builds. Disadvantage: it's ok for basic editing, compiling, etcetera, but you cannot prot from all NetBeans features. The second option is to create a new NetBeans "Java project from existing sources". In that case, NetBeans has its own build file, now called nbbuild.xml. Advantage: you can profit from all NetBeans features, and it will not disturb the shared build files. Disadvantage: you must setup the NetBeans project carefully and manually update it for library changes, as we will describe now.

  1. We assume that you are using NetBeans 7.2 (or higher)
  2. create, outside NetBeans, a basic project in line with our build system. If you have an existing project, that's ok as well. Ensure that you have "resolved" the project dependencies, so that the contents of the lib and test\lib directories is what you need. (Use ant resolve)
  3. Ensure that the your project has no build directory: for instance use ant clean.
  4. Now create a new project within NetBeans. Choose "New Java Project with Existing Sources".
  5. Choose the correct project name (by default we pick the project directory name), and select the correct project folder. Enable the "Use dedicated Folder for Storing Libraries" option, but choose a different name than ".\lib". For instance, choose "nbproject\lib". NetBeans stores some of its "own" info in its "lib" folder. Unfortunately, our version manager Ivy will discard such info from .\lib when you do an "ant resolve" operation, so we must give the NetBeans lib a special place.
  6. "Next", add the src folder to the list of "Source Package Folders", and add the test\src folder to "Test Package Folders".
  7. "Now you can \Finish", and you have a NetBeans project. Except that it won't compile, because you must correct the library settings:
  8. The NetBeans "Projects" panel on the left show two sets of libraries: "Libraries" and "Test Libraries" Right click on "Libraries" and choose "Add JAR/Folder". Navigate to the project's lib folder and add all jars that you find there. Also add the project's resource directory here. (This will ensure that this directory is on Java's classpath, so the "getResourceAsStream" method for loading resource data will work) Leave the "Reference as Relative Path" option enabled: this prevents NetBeans from copying into its own nbproject\lib directory. Do the same with "Test Libraries", this time using the jars from test\lib, and the test\resource directory. As you can see we now have a junit-4.8.2.jar, that is present in our lib directory, but also two more NetBeans "libraries", one for JUnit3.8.2 and one for JUnit4.8.2. The latter two should be removed.
  9. By now, the project should be in shape: no unresolved libraries, it compiles and runs, and JUnits test work.
  10. Note that whenever you change the contents of the lib directories, you will have to go back to the project properties page (from the File menu), and reestablish the correct libraries settings. For example, say you had some file "guava-r06.jar" inside your lib directory, but after the resolve operation it has been replaced by "guava-r07.jar" NetBeans now automatically removes guava-r06.jar from its libraries, but does not auto-understand that it needs guava-r07.jar instead. Right-click on the NetBeans project name, and choose "Resolve Reference Problems...". Select guava-r06.jar and click "Resolve". Now you can navigate to the project's lib directory, and select the new guava-r07.jar. For the time being, NetBeans is now satisfied. In reality, it has not really removed the reference to guava-r06.jar, but it has added a redirection inside your own "private" NetBeans settings. So next time that you resolve, it cannot find guava-r06.jar again. You can correct this by first removing the guava jar from the NetBeans library, then adding the correct version. Problem: you cannot remove it while the reference problem is not solved. In the end, the easy solution is to first remove all jar files from lib (and also from test\lib if you expect changes over there) before the resolve, then add them back after the resolve.

building jar files

By default, compiled class files are included in the jar file produced by a build. But also all files inside the src directory, except for .java and .form files are included. That is convenient if you want to include "resource" files, like data files, images , icons etcetera: put them in the appropriate source directory, and use the Java getResourceAsStream() method for reading the data. Although this works, our strong preference is to include \resources" into its own resource directory within your project. (Our ant build system puts your project's own resource directory on the classpath, as well as other directories that you specify in the file) NetBeans auto-include of src documents is also not so nice if you have some secret-remarks.txt, or some huge remarks.doc word file in your source directories. In this case, you must set the files to exclude for packaging. For instance, via: Build | Set Main Project Configuration | Customize..., or via right-clicking the project tab, and selecting \Properties". Choose the \Packaging" tab, and to the "Exclude from jar file", for instance, add, /*.txt, /*.doc.