cornercorner
FeaturesPluginsDocs & SupportCommunityPartners

NBIExamples

Examples of installers based on NBI

Contents

Quick start

Here is a simple example of installer based on NBI.
To try it:

  • extract this zip archive to any folder (<path-to-dir>)
  • update <path-to-dir>/build/build.properties:
  • change data.zip.path=file:/C:/Distr/new/example/data to data.zip.path=file:/<path-to-dir>/data (on Unix using something like file:/export/home/MyInstaller/data).
  • change jdk.home=c:/java/jdk1.5.0_14 to jdk.home=<path-to-jdk5>, where <path-to-jdk5> is the path to JDK5 on your system
  • make sure ...
  • you have JAVA_HOME environment variable set and pointed to JDK5
  • you have ant1.7.0
  • change directory to <path-to-dir>/build
  • run 
    ant -f <path-to-dir>/build/build.xml

As the result, in about couple of minutes, you`ll have 6 installers at <path-to-dir>/build/output/bundles.


Build overview

The following steps happens when you run ant -f build.xml. Ant is been started and the default target (which is build) is executed, which, in turn, calls -clean,-checkout,-init,-init-properties,-post-init-clean,-build and -generate-bundles at the end.

  • -clean deletes the output dir (where installer from the previous build can be stored) and also deletes some temporary data from the previous build
  • -checkout copies the sources from nbi and from ext directory to <path-to-dir>/build/nbi_all directory which is used as the main build directory then
  • -init compiles classes (nbi/engine, infra/lib/registries-management, infra/build/.ant-lib/src, infra/build/.ant-lib/src-registries-management) in order to work with custom Ant tasks (if, set, create-bundle) later during the build process.
  • -init-properties dumps the global build properties to 
    environment.properties
    file which is used later during the build
  • -post-init-clean deletes the additional files that were created during the previous build and which were not deleted at -clean stage
  • -build builds NBI engine and helloworld product and stores the build artifacts in registry-temp directory to use later in the generate-bundles task.
  • NBI engine is built using 
    infra/build/engine/build.xml
    which in turn falls to {infra/build/.common/engine.xml}
  • helloworld product is built using 
    ext/infra/build/products/helloworld/build.xml
    which in turn falls to {infra/build/.common/product.xml}.
    That build, in general, combines the information about the product (like uid, name, version, description, supported platforms, dependencies on other products), the configuration logic library (ext/components/products/helloworld) and the data (files and descriptor with extra info like permissions, sizes, md5, etc) into the single "package" which NBI works with.
  • -generate-bundles calls create-bundle custom Ant task for 6 platforms and thus generates installers for that platforms. Some additional conversion is done then (e.g. installer zip is transformed to tgz to make more comfort work on Mac)
  • The create-bundle task source is at 
    nbi/infra/build/.ant-lib/src-registries-management/org/netbeans/installer/infra/build/ant/registries/CreateBundle.java
  • In a nutshell, this tasks falls to 
    nbi/infra/lib/registries-management/src/org/netbeans/installer/infra/lib/registries/impl/RegistriesManagerImpl.createBundle()
    .
    This method generates several files which are used as the input for running the NBI engine (which was made during '-build' task) in the silent and create-bundle modes with providing state-file by using --state option.
    NBI engine reads the information those files and generate the {bundle.jar} file which includes the NBI engine itself the the helloworld package.
    After that bundle.jar is wrapped by the platform specific launcher.

Runtime overview

First, read general installer workflow to be familiar with the architechture.

Improving the basic example

Here is a enhanced version of the previous example.

This example adds the following benefits (new things) in comparison with the first one:

  • creates also light-weight online installers (with the data been accessed via http or file protocol), see note below
  • adds infrastructure for customizing the engine (
    ext/engine
    and {ext/infra/build/engine})
  • sets custom URI for storing wizard components (
    nbi.wizard.components.instance.uri
    in {ext/engine/src/data/engine.properties})
  • sets custom wizard title, icon, sizes (depending on L&F used) - everything in 
    ext/engine/src/data/engine.properties
  • uses custom windows native launcher (
    ext/engine/src/native/launcher/windows/nlw.exe
    ) with custom icon (built-in) and custom messages ({ext/engine/src/native/launcher/windows/i18n/launcher.properties})
  • adds new UI panel - welcome - in installer and registers it in already mentioned wizard-components.xml
  • sets custom left/right images that are used in the wizard header while proceeding actions

Do the same steps as before, pay attention to 
bundles.release.url
and {bundles.release.dir} properties in build/build.properties.

Those are the properties that correspond to the values of the accessible URL and storage dir where the data will be accessed by the online installer.

E.g. you have tomcat been installed at the local system at 
C:\Program Files\Apache Software Foundation\tomcat
and run on port 8080, then set: 
bundles.release.url=http://localhost:8080/installers
bundles.release.dir=C:/Program Files/Apache Software Foundation/tomcat/webapps/ROOT/installer
Retrieved from "http://wiki.netbeans.org/NBIExamples"