This section covers the basics of setting up your IDE to start developing your own projects. The process of managing project contents and properties is centered around the Projects window. The most common tasks in setting up a project are creating a project, setting the project's target JDK, and configuring the project's properties such that resource libraries are available to it.
Before you start setting up your project, let's take a minute to get acquainted with some of the basic concepts involved with using the IDE.
In the IDE, you always work inside of a project. An IDE project is a group of Java source files and associated information about what belongs on the classpath, how to build and run the project, and so forth. You can create standard projects that use an IDE-generated Ant script to build the project, or create free-form projects that are based on your existing Ant scripts. The IDE stores project information in a project folder which includes an Ant build script and properties file that control the build and run settings, and a project.xml file that maps Ant targets to IDE commands.
Note: Though the IDE puts source directories within the project folder by default, your source directories do not necessarily need to be located in the project folder.
The following table summarizes the major differences between standard projects and free-form projects.
The IDE contains the following standard project templates:
The IDE contains the following free-form project templates:
Apache Ant is a Java-based build tool used to standardize and automate build and run environments for development. The IDE's project system is built directly on top of Ant. All of the project commands, like Build Main Project or Debug Main Project, call targets in the project's Ant script. You can therefore build and run your project outside the IDE exactly as it is built and run inside the IDE.
It is not necessary to know Ant to work with the IDE. You can set all the basic compilation and runtime options in the project's Project Properties dialog box and the IDE automatically updates your project's Ant script. If you are familiar with Ant, you can customize a standard project's Ant script or write your own Ant script for a project.
Even if you are an expert at using Ant, you probably still need to look in the Ant manual every once in a while. You can install the Ant manual directly in the IDE help system by going to the NetBeans Update Center and installing the Ant Documentation module. See Installing New Modules from the Update Center for more information on using the Update Center.
If you are looking for resources on learning Ant, see http://ant.apache.org/resources.html .
To create a new project, choose File > New Project (Ctrl-Shift-N). When the New Project wizard appears, simply select the right template for your project and complete the remaining wizard steps.
For instructions on using the New Project wizard, see the following documents:
When you finish creating a project, it opens in the IDE with its logical structure displayed in the Projects window and its file structure displayed in the Files window:
In addition, you can use the Favorites window to access any location on your computer. This is convenient when you want to access files and directories that are outside of your project directories. The Favorites window does not know anything about project classpath and membership, so no project-related commands like Compile File are available. You can open a class file in the Favorites window by double-clicking the file, however because there is no classpath information associated with that file you may see compilation errors when viewing the file in the Source Editor. You can open the Favorites window by choosing Window > Favorites (Ctrl-3).
When you develop a large application consisting of numerous source folders, it is common to split up your code into separate projects. Typically, one of these projects serves as the entry point for your application and, if it is a J2SE application, contains the application's main class. To tell the IDE which of your projects is the main entry point for your application, you set one project to be the main project. The IDE provides commands that act on the main project. For example, running the Build Main Project command builds both the main project and all of its required projects, thereby ensuring that all of your compiled classes are up-to-date. To set a project as the main project, right-click the project node in the Projects window, and choose Set as Main Project. Only one project can be the main project at any time.
You can import your project into NetBeans by using the project templates in the New Project wizard to create a NetBeans project based on your project type. After choosing the project type in the New Project wizard, choose the project template that uses existing sources, or if the project you want to import already has an Ant script, choose the template that uses your existing Ant script. Step through the wizard to locate the sources you want to import to create your project. Depending on which template you choose, the IDE creates a either a standard project with your existing sources or a free-form project using your existing sources and Ant script.
For more information on importing source code into the IDE, see the following step-by-step guides:
By default, the IDE uses the version of the J2SE platform (JDK) with which the IDE runs as the default Java platform for compilation, execution, and debugging. You can view your IDE's JDK version by choosing Help > About and clicking the Detail tab. The JDK version is listed in the Java field.
You can run the IDE with a different JDK version by starting the IDE with the
--jdkhome jdk-home-dir
switch from the command line or in your IDE-
HOME/etc/netbeans.conf
file. For more information, see Configuring IDE Startup Switches.
In the IDE, you can register multiple Java platforms and attach Javadoc and source code to each platform. Switching the target JDK for a standard project does the following:
You can switch the target JDK of your project by doing the following:
To register a new Java platform, choose Tools > Java Platform Manager from the main menu. Specify the directory that contains the Java platform as well as the sources and Javadoc needed for debugging.
Adding a group of class files to a project's classpath tells the IDE which classes the project should have access to during compilation and execution. The IDE also uses classpath settings to enable code completion, automatic highlighting of compilation errors, and refactoring. You can edit the classpath declarations for an existing project in the Project Properties dialog box.
If you have attached Javadoc and source files to a JAR file in the Library Manager, the IDE automatically adds the Javadoc and source files to the project when you register the JAR file on a project's classpath. You can step into classes and look up Javadoc pages for the classes without configuring anything else.
If each of your source roots is a separate standard project, you have to set up the classpath dependencies between the projects. Typically you set up one main project containing the project main class (in J2SE projects), and several required projects. A required project is a project that has been added to another project's classpath. When you clean and build a project, the IDE also cleans and builds its required projects. The required project's Javadoc and sources are also made available to the receiving project.
You can add any required projects to your
project by right-clicking the Libraries node in the Projects window, or
you can add them by specifying them in the Compile tab in the Project
Properties dialog box. When you want to add a required project, select
the project folder whose JAR files you want to add to the classpath
(the file chooser displays the icon for IDE project folders
). When adding projects in the Project Properties dialog box, make sure
that the Build Projects on Classpath checkbox is selected.
If you want to add a free-form project to the classpath of a standard project, you have to add the free-form project's JAR file to the standard project's classpath. To do this, you must first declare all of the free-form project's output files in the Output panel of the free-form project's Project Properties dialog box.
In free-form projects, the IDE uses targets in an existing Ant script to build, run, clean, test, and debug your application. If the Ant script does not contain targets for some of these functions, the functions are unavailable. To implement these functions you write targets either in your Ant script or in a secondary Ant script.
For more on setting up free-form projects, see the following article:
The IDE automatically recognizes Ant scripts and displays them as Ant script nodes (
) rather than as normal XML files. You can right-click Ant scripts in
the Projects window, Files window, or Favorites window to access a
pop-up menu of commands. You can also expand the Ant script node to see
an alphabetical list of subnodes representing the Ant script's targets.
Each of these subnodes also has a contextual menu of commands.
In the Projects, Files, and Favorites windows, an Ant script's subnodes are flagged in the following ways:
The only way to edit an Ant script is in the Source Editor. Double-click any of the Ant script's subnodes to jump to that target's location in the Source Editor. All of the normal XML search tools, selection tools, and keyboard shortcuts are available for editing Ant scripts, and the IDE provides code completion for all standard Ant tasks.
When you create a target that you want to run from the command line, give the target a description attribute. Then, if you forget the names of the targets or what they do, you can run the ant -projecthelp <script> command from the command line. With this command, Ant lists only those targets that have a description attribute, together with their descriptions. Especially when there are many targets in your Ant build script, emphasizing some and de-emphasizing others can be a useful way to distinguish between those that you use a lot and those that you use less often.
The font style of a subnode's label in the Projects, Files, and Favorites windows indicates the following:
Targets that are imported from another script but are overridden in the importing script are not listed. Only the overriding target is listed.
You can run targets in an Ant script from the Ant script's node in the Projects window, Files window, or Favorites window. To do so, right-click the Ant script node and choose a target from the Run Target submenu. Targets are sorted alphabetically. Only emphasized targets are listed. Choose Other Targets to run a target that has not been emphasized with a description attribute. Internal targets are excluded from these lists because they cannot be run independently.
Instead of running a target by using the Ant script node's contextual menu, you can simply right-click the target's node and choose Run Target.
In free-form projects, your Ant script handles the classpath for all of your source folders. To make project sources available to Ant, you need to specify the classpath for the project sources. If you have any custom tasks, you also need to add these tasks to Ant's classpath.
For more on using your own Ant scripts to compile, run, and debug free-form projects, see the following articles:
In free-form projects you tell the IDE what classes to make available for code completion and refactoring and specify the classpath for these project sources. You specify the classpath in the Java Sources Classpath settings in the Project Properties dialog box. You do this because by default the IDE ignores your environment's CLASSPATH variable whenever it runs Ant.
The classpath variable you set in the Project Properties dialog box does not affect the actual classpath of the project, which is specified in the Ant script. Declaring the classpath in the Project Properties dialog box does not change the actual compilation or runtime classpath of the source folders. However, the project classpath variable must match the classpath used by your Ant script in order to provide the correct information for code completion, error highlighting, and refactoring commands. You have to set an explicit classpath in your build scripts because the IDE ignores your environment's CLASSPATH variable whenever it runs Ant. If you change the classpath of one, you must change the class path of the other
In free-form projects, you can call up and run custom Ant tasks in your build script. For your Ant script to use customs tasks, you must include the tasks in the Ant script's classpath. For example, you may add a task to your build script to format your code with Jalopy. In order to do this, however, you have to add the Jalopy JAR file to Ant's classpath.
You can add custom tasks to Ant's classpath within the IDE by doing either of the following:
<project name="test" default="all" basedir="."> <target name="init"> <javac srcdir="tasksource" destdir="build/taskclasses"/> <jar jarfile="mytasks.jar"> <fileset dir="build/taskclasses"/> </jar> <taskdef name="customtask" classname="com.mycom.MyCustomTask"> <classpath> <pathelement location="mytasks.jar"/> </classpath> </taskdef> </target> </project>
The advantage of this method is that no special preparation is needed to begin using the script. The script is entirely self-contained and portable. This method also makes it easier to develop your tasks within the IDE, as the script compiles them for you automatically.
To make your build scripts even more robust, use a property instead of a hard-coded location to specify the classpath to your tasks. You can store the property in the build script itself or in a separate ant.properties file. You can then change the classpath setting throughout your script by simply changing the value of the specified property.
Note: When you modify the Ant classpath in the Options window, when you run Ant in the IDE the task is on Ant's classpath for all projects.