// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= DevFaqSuitesVsClusters
:jbake-type: wiki
:jbake-tags: wiki, devfaq, needsreview
:jbake-status: published

=== What is the difference between a suite and a cluster?

A suite is a project which bundles together a number of link:DevFaqWhatIsAModule.html[module] projects, lets you build them all together, and puts the resulting JARs in a directory structure the NetBeans Platform understands.

That directory structure is a link:DevFaqWhatIsACluster.html[cluster].  A cluster is a directory structure which the application launcher and module system understand.  A cluster is a _runtime artifact_ where the module system can find the modules that make up an application.

While it is common to think of a suite as _being_ a cluster (the build product of a suite _is_ a cluster, after all), they are not the same thing.

==== Suites

A suite is a container project used to group _module projects_ into a unit whose members can depend on one another, and also depend on a copy of the NetBeans platform.

The structure generated on disk when you compile a suite project is a link:DevFaqWhatIsACluster.html[cluster].

If you are creating a single module (perhaps an IDE extension or a _very simple_ link:http://platform.netbeans.org[NetBeans Platform-based application]) you can ignore suites, and just build/run/distribute a single stand-alone module.  You will still get a cluster structure on disk when you compile the module.  However, suite projects offer some additional features, such as building zip and JNLP application distributions.

You can always start with a stand-alone module project and later create a suite project and add your module to the suite.  If you are going to bundle multiple third-party libraries, and want the ability to provide updates of those libraries, you probably want a suite.

==== Inter-suite Dependencies

A suite may depend on

* Another suite
* A stand-alone module
* An external binary cluster (a cluster directory somewhere on disk which you might not have the source code to: link:DevFaqWhatIsACluster.html[DevFaqWhatIsACluster]).  Use the *Add Cluster* button on the Libraries tab of your suite's *Project Properties* dialog to set up such dependencies.

See link:DevFaqHowToReuseModules.html[DevFaqHowToReuseModules] for more details.

==== Clusters

A cluster is typically a subdirectory of a NB-based application's binary installation. Every module in the installation lives in one (and only one) cluster. For details on the structure of clusters, see link:DevFaqWhatIsACluster.html[DevFaqWhatIsACluster].

The installation is divided into clusters for purposes of:

1. Conceptual clarity.
2. Mapping to native packaging systems such as RPM, Debian/Ubuntu packages, Solaris packages, etc.

The NetBeans team has a policy of treating inter-cluster module dependencies as more significant than intra-cluster module dependencies with respect to backward compatibility.  The goal is to make it possible for product teams building on top of the NetBeans IDE to select a subset of the IDE to use&mdash;with cluster granularity rather than with module granularity. 

Cluster-granularity is simpler to grasp and integrate with native packaging (if the NetBeans IDE consisted of 500 Debian packages, nobody would be particularly happy about that). But there is nothing preventing you from reusing a subset with module granularity.

The NetBeans launcher (`nbexec`) accepts a list of cluster directories to load modules from&mdash;basically a search path. There are no further semantics to clusters.

The suite project type has a standard build target to assemble a complete application.  For simplicity, it simply places all modules built from suite sources into their own cluster named in accordance with the suite's name.  

NBMs may specify a cluster. The `netbeans/` subdirectory of the NBM (which is a ZIP file) has a file layout which matches the layout of files within a single cluster. Each cluster managed by Auto Update has an `update_tracking/` subdirectory with one XML file per module, enumerating the files which that module contributes to the cluster.

Currently the "NB Platform" is just the `platform` cluster from the IDE. The entire contents of the `platform` cluster may not be exactly what you want for every "platform" application, so a suite project allows you to exclude modules you do not wish to include.

Clusters are supposed to be medium-grained or coarse-grained, unlike modules which are generally fine-grained units.

See also:

* `harness/README` in your IDE distribution
* the *Help > Contents* pages on modules and applications
* link:http://platform.netbeans.org/articles/installation.html[http://platform.netbeans.org/articles/installation.html]

===== No Suites In NetBeans IDE Sources

The NetBeans IDE build (from sources on `hg.netbeans.org`) _does not use suites._

It uses a historical build infrastructure which partially overlaps the external module/suite build harness introduced in NetBeans 5.0, but which has different requirements, and is considerably more complex. 

Module projects physically inside the netbeans.org source tree cannot be "standalone" modules nor "suite component" modules.  They are simply netbeans.org modules, and as such use a (slightly) different format for metadata, and have access to somewhat different facilities specific to netbeans.org practices.  

The resulting build artifacts are, nonetheless, clusters. These clusters are simply built using a different build-infrastructure, where the cluster names and contents are defined in `.properties` files in `$NB_SRC/nbbuild/`.

=== Apache Migration Information

The content in this page was kindly donated by Oracle Corp. to the
Apache Software Foundation.

This page was exported from link:http://wiki.netbeans.org/DevFaqSuitesVsClusters[http://wiki.netbeans.org/DevFaqSuitesVsClusters] , 
that was last modified by NetBeans user Jglick 
on 2010-06-14T20:02:33Z.


*NOTE:* This document was automatically converted to the AsciiDoc format on 2018-01-10, and needs to be reviewed.