The first step for any kind of project type is to decide what the project will look like! You should have a clear idea of what files will reside in the project directory (or perhaps externally), using what file names, what the contents should be, what files will be updated by the IDE’s GUI, what by text editing, how future updates will affect file formats, etc.

If you use the standard Ant-based infrastructure (below), some of these decisions are made for you.

Most project types will define an AntBasedProjectType and keep basic project metadata in ''$projdir''/nbproject/project.xml (below). If you do not do this, e.g. if you need to support a third-party project layout (such as Apache Maven uses), then you will need to implement ProjectFactory yourself to recognize and load projects using your format. A project factory should be designed to be able to quickly reject candidate directories which are not in your layout. (Positive identification of your projects can be a little slower.)

Every project is represented by a Project object, which is created by your factory. Its only mandatory behavior is to be able to report the project directory it is associated with. Other than that, all of its behavior is controlled by its Lookup, basically a bag of optional capabilities. Usually org.openide.util.lookup.Lookups can be used to make a Lookup with a fixed list of entries.

All outside code should interact with your project via interfaces found in its lookup. Outside code can check to see if a given project has a capability, and if so, use it. Never make your Project implementation class publicly accessible. Whatever capabilities you wish to expose, do so from the lookup—you can define additional interfaces to expose to clients (public or semi-public, in API-exposing modules) and add implementations to your lookup (in non-public classes in your project type module) if you need to. Beware that the project infrastructure reserves the right to hide the original Project your factory creates and expose only a wrapper to outside callers, so it would never be correct to try to cast a Project object to an implementation class, even if you could access that implementation class.

Since all the project’s behavior is controlled by its lookup, the question becomes: what interfaces should I implement? There is a suggested list in the Javadoc for Project.getLookup(). Here is an overview of major kinds of interfaces and why you might need them.

Almost all project types will want to define their general appearance and behavior in the IDE’s GUI.

Most project types will wish to define some aspects of how their source directories are laid out, what they contain, and what may be added to them.

Most project types will have some kind of actions which can be performed on the project: build it, run some program it represents, etc.

Several queries are used to permit integration of various Java editing and browsing features in the IDE with the project system. Any projects which deal with Java sources should try to implement these queries.

Ant-based projects always have an nbproject subdirectory in the project directory with a file nbproject/project.xml which identifies the project and can contain some metadata. Typically there are several other files in standard locations. See the [design.html#project-layout design document] for an overview of the general Ant-based project layout if you are not yet familiar with it, and study some actual project in the IDE such as a plain Java library project.

Now think about layout details specific to your project type. Perhaps you want to add another properties file for some unforeseen reason; this is up to you (almost all of the Ant-based project infrastructure classes will work happily with such a setup, except perhaps for ReferenceHelper, described below). Certainly you will want to decide what kinds of source files reside where and in what structure. For example, for a plain Java project, the specifics of the structure are:

These decisions are codified in an XML schema for the project.xml file (example). Currently the schema is not used for runtime validation, but that is expected to change; in the meantime, you are strongly recommended to define a schema to make sure you have clearly defined what can and cannot be stored in project.xml.

Your project type does not directly control the whole project.xml file. Rather, the Ant-based infrastructure will manage loading, parsing, and saving it, using APIs to be described below; and you only control one section of it, called the primary configuration data. You need to select an XML element name and namespace that will identify this block. For example, general Java projects use an element <data xmlns="http://www.netbeans.org/ns/j2se-project/2">. The target namespace for your XML schema should be this namespace: your schema will validate this block only, not the complete file.

You also need to define a primary configuration data block name for private.xml in the nbproject/private/ folder, whether or not you plan to write anything to this file. For example, general Java projects use <data xmlns="http://www.netbeans.org/ns/j2se-project-private/1">. You can just define an empty schema for this block that allows no content (example), or you can store real information here—some information about the project that should not be shared with other users and is not easily kept in properties files.

Also related to project.xml, you need to pick a project type identifier. This is just a short string—it could be the code name base of your module—which uniquely identifies your project type. This will be stored in the <type> element at the top of project.xml.

A Java project can likewise use a number of different Ant properties, such as src.dir, main.class, javac.classpath, run.jvmargs, etc. (XXX link to spec when available) You will need to decide what properties your project type will recognize and what the values should mean, while working on the build script (below).

Make a prototype of a real project—it does not need to be loadable by the IDE as a project yet, just have realistic source files and be buildable by Ant (either from the command line or through the IDE using e.g. the Favorites node). Write an empty build.xml:

And write an nbproject/build-impl.xml that does the various build steps you would like the project to do. Generally it should load some properties files first, e.g.

Note that it is conventional to begin the names of “internal” targets that should not be run directly (only as dependencies) with a hyphen (-).

Think about which targets the user should override in build.xml for what purpose. It is nice to put in “placeholder” targets which by default do nothing but which can easily be overridden to insert some custom steps at a certain point in the build.

Some project types have several variants for build-impl.xml, parametrized somehow. For example, plain Java projects behave a little differently depending on whether you are building and running against the “default platform” (the IDE’s own JDK) or an explicit JDK. The former case might look like (excluding irrelevant details):

whereas the latter case might look like:

The rule of thumb here is simple. If some aspect of the build can be parametrized using Ant properties in a straightforward way using the Ant tasks you have available, do so. For example, there is no need to create a different build-impl.xml just to change the build directory; this can be done using a property:

But in other cases, this is not possible. For example, Ant’s <junit> task can take a jvm attribute to specify an explicit JDK to run against. If you include this attribute, you have to set the JDK. When using the default platform, this attribute must not be there; when using an explicit platform, it must be there. Therefore build-impl.xml needs to be a bit different in these two cases (unless you included both versions in different targets and switched between them at runtime, though this can cause bloat in the build script). Build prototype scripts using all the variants you expect to encounter and verify that they all work the way you want.

Now to go back to project.xml for a moment: whatever variations in build-impl.xml you wish to support must be codified as metadata in project.xml. For example, a plain Java project can include an <explicit-platform> element or not; the presence or absence of this element determines which build-impl.xml variant is produced.

When you are satisfied with the build-impl.xml you have drafted (perhaps in multiple variants), it is time to write an XSLT stylesheet which produces it. The input to the stylesheet is the project.xml file and the output is the build script. Typically you will just copy most of the prototype build script verbatim into the stylesheet as the default content. You will also want to examine the project.xml input at least for a project name, and optionally also for any other information you need to construct different build script variants. For example, with a project.xml looking like this:

You might have a stylesheet like this:

Remember that { and } in attribute values have a special meaning in XSLT: if you want to use braces literally, e.g. for Ant property references, double them, e.g.

You will also want a stylesheet to generate build.xml, though typically this is quite simple:

You can fine-tune the XSLT for your build scripts, as well as the project.xml format and the list of Ant properties you want to recognize, without writing one line of NetBeans module source code. (Just run project.xml through your stylesheets to see the output, using any XSLT tool, such as that built into the NetBeans IDE.) All you are doing at this stage is defining some metadata for the project and verifying that Ant scripts generated from it do indeed build and run an example project the way you want.

Now it is time to begin writing the project type provider module proper. First you will need an implementation of AntBasedProjectType which registers your project type in the system. (Place this implementation in default lookup, e.g. using the META-INF/services/ section of your module JAR.) The project type class does not do much except report the project type identifier, and the local name and namespace used for the shared and private primary configuration data blocks (in project.xml and private.xml). The createProject method must create a particular project object; it is passed an AntProjectHelper object which gives you access to a variety of different Ant-based project functionality in a convenient way. You can immediately throw an IOException in case there is something badly wrong with the project on disk; a future version of NetBeans should also let you perform XML validation on project.xml at this time (cf. #42686).

You will need a separate class for the Project implementation, which will usually hold onto the instance of AntProjectHelper and use it to service requests.

Another common thing to set up in your project’s constructor is a property evaluator, which can load the current values of various properties from project.properties, private.properties, and build.properties, using Ant’s property evaluation semantics, and notify you of changes even in specific properties. A PropertyEvaluator instance is also a required parameter for many convenience factory methods and constructors in the Ant-based project support. Many projects can just call AntProjectHelper.getStandardPropertyEvaluator() to load properties from these three files in the usual way. If you have other property files your build script loads, or default values set in the build script, you can make a custom evaluator using factory methods in PropertyUtils—but beware that ReferenceHelper expects the standard semantics (so that it can store relative paths in project.properties and absolute paths in private.properties) and so may not work appropriately if you have a very different property loading model.

The project should create a Lookup containing its particular abilities and return this from the getLookup() method. Normally Lookups.fixed is adequate for this purpose. In principle a project’s lookup could change dynamically, but this is not normally required. More information on what to put in the lookup can be found below.

The normal way that build.xml and build-impl.xml are created is that these files are automatically generated whenever they are missing; and regenerated when they are out of date relative to the current XSLT stylesheet and project.xml, but not modified by the user. (private.xml is not considered: since it is per-user, the shared build script cannot be changed according to its contents.) Note that build-impl.xml is not supposed to be modified by the user, but at least if it is, those modifications will never be clobbered. build.xml can be modified, so if it is, it will not be regenerated; however it is not likely to need regeneration often or at all.

To configure the normal (re-)generation semantics, make sure your project’s lookup contains:

The Javadoc for GeneratedFilesHelper.refreshBuildScript describes the recommended parameters that should be passed to it from these two hooks. Remember that your XSLT stylesheets should be packaged in the module JAR so they can be passed to this method.

Other kinds of behavior are possible; check the GeneratedFilesHelper Javadoc for more information. You could also produce Ant build scripts using some method other than XSLT transformations (e.g. manual DOM manipulation), but GeneratedFilesHelper will not currently (#42735) help you determine whether the scripts are modified or out of date if you do this, so you would need to write this logic yourself.

PENDING