| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <title>Platform Installer Tutorial</title> |
| <link rel="stylesheet" type="text/css" href="https://netbeans.org/netbeans.css"/> |
| <meta name="AUDIENCE" content="NBUSER"/> |
| <meta name="TYPE" content="ARTICLE"/> |
| <meta name="EXPIRES" content="N"/> |
| <meta name="indexed" content="y"/> |
| <meta name="description" |
| content="A short guide to getting started with the NetBeans Platform Installer."/> |
| <!-- Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. --> |
| <!-- Use is subject to license terms.--> |
| </head> |
| <body> |
| |
| <h1>NetBeans Platform Installer Integration Tutorial</h1> |
| |
| <p>In this tutorial, you learn how to use the infrastructure of the |
| NetBeans IDE installer to generate and customize an |
| installer for your own NetBeans Platform application.</p> |
| |
| <p><img src="../images/articles/74/netbeans_stamp_74_73_72.png" class="stamp" width="114" height="114" alt="Content on this page applies to NetBeans IDE 7.3" title="Content on this page applies to NetBeans IDE 7.3"/></p> |
| <p><b>Contents</b></p> |
| <ul class="toc"> |
| <li><a href="#generating">Generating and Using the Default Installer</a></li> |
| <li><a href="#customizing">Customizing the Installation Wizard</a></li> |
| <li><a href="#bundling">Bundling Additional Resources</a> |
| <ul> |
| <li><a href="#bundling-glassfish">Bundling GlassFish</a></li> |
| <li><a href="#bundling-jre">Bundling the JRE</a></li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p><b>Background Reading</b></p> |
| <p>This tutorial is derived from the following sources:</p> |
| <ul> |
| <li><a href="http://wiki.netbeans.org/NBI">http://wiki.netbeans.org/NBI</a></li> |
| <li><a href="http://installer.netbeans.org/docs/nbi-devguide.html">http://installer.netbeans.org/docs/nbi-devguide.html</a></li> |
| </ul> |
| |
| <p><b>To follow this tutorial, you need the software and resources listed in the following table.</b></p> |
| |
| <table> |
| <tbody> |
| <tr> |
| <th class="tblheader" scope="col">Software or Resource</th> |
| <th class="tblheader" scope="col">Version Required</th> |
| </tr> |
| <tr> |
| <td class="tbltd1"><a href="https://netbeans.org/downloads/index.html">NetBeans IDE</a></td> |
| <td class="tbltd1">version 7.2.1 or above</td> |
| </tr> |
| <tr> |
| <td class="tbltd1"><a href="http://java.sun.com/javase/downloads/index.jsp">Java Developer Kit (JDK)</a></td> |
| <td class="tbltd1">version 7 or above</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <!-- ===================================================================================== --> |
| <p></p> |
| <h2><a name="generating"></a>Generating and Using the Default Installer</h2> |
| <p>In this section, you set up the Paint Application, which is one |
| of the sample applications distributed with NetBeans IDE, |
| and generate the default NetBeans installer for it.</p> |
| <div class="indent"> |
| <h3 class="tutorial">Generating the Default Installer</h3> |
| <div class="indent"> |
| <ol> |
| <li><p>Go to File | New Project and go to Samples | NetBeans Modules, |
| where you will find the Paint Application:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/paint-app-1.png" alt="1"/></p> |
| <p>Complete the wizard and you should see the Paint Application in the Projects window.</p> |
| </li> |
| <li><p>Right-click the application, choose Properties, and then go to the Installer tab. |
| Select the operating systems for which you'd like to create installers, as |
| shown below:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/paint-app-2.png" alt="1"/></p> |
| <p>Specify whether you want to compress the installer and then click OK.</p> |
| </li> |
| <li><p>Right-click the application and choose Package as | Installers, as |
| shown below:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/paint-app-3.png" alt="1"/></p> |
| <p class="notes"><b>Note:</b> The process that creates installers |
| can take a long time, especially if you specified that multiple |
| installers should be created. Use the Output window to follow |
| the creation process.</p> |
| </li> |
| <li><p>Switch to the Files window, expand the application's "dist" folder, |
| and you should see one or more installers that have been generated, |
| together with a ZIP distribution of the application:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/paint-app-4.png" alt="1"/></p> |
| </li> |
| </ol> |
| </div> |
| <h3 class="tutorial">Using the Default Installer</h3> |
| <div class="indent"> |
| <ol> |
| <li><p>Right-click the installer and choose "Open in System", as shown below:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/paint-app-5.png" alt="1"/></p> |
| <p class="tips">Alternatively, if the above instruction does |
| not work in your operating system, leave NetBeans IDE, go into your filesystem outside the IDE, |
| and launch the installer in the standard way applicable |
| to your operating system.</p> |
| </li> |
| <li><p>After a moment, you should see the first panel of the installer wizard, as shown below:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/paint-app-6.png" alt="1"/></p> |
| <p>Click Next.</p> |
| </li> |
| <li><p>In the second panel, specify a location where the application will be installed, |
| together with whether a desktop icon and a start menu entry should be created:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/paint-app-7.png" alt="1"/></p> |
| <p>Click Next.</p> |
| </li> |
| <li><p>In the third panel, you are shown a summary prior to the installation starting:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/paint-app-8.png" alt="1"/></p> |
| <br/> |
| <p>Click Install. You are shown the progression of the installation procedure:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/paint-app-9.png" alt="1"/></p> |
| <br/> |
| <p>When the installation is complete, the panel below is shown:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/paint-app-1a.png" alt="1"/></p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <p>Now that you have learned how to create and use the default installer, let's customize it!</p> |
| |
| <!-- ===================================================================================== --> |
| <p></p> |
| <h2><a name="customizing"></a>Customizing the Installation Wizard</h2> |
| <p>In this section, you configure the NetBeans Installation (nbi) infrastructure |
| in various ways. Then, when you generate the installer again, as shown in |
| the previous section, your configurations will automatically be applied. |
| The nbi infrastructure is a standard part of every |
| NetBeans IDE installation, as shown |
| in the screenshot below, and is always found within the NetBeans IDE installation |
| directory's "harness" subdirectory: |
| </p> |
| |
| <p><img style="border: 1px solid" src="../images/tutorials/nbi/721/favorites-view.png" alt="Favorites"/></p> |
| |
| <p>Below, you are shown how to change the installer's |
| images, texts, size, destination directory, and panels. After you make a change, regenerate |
| the installer to see the impact of your changes.</p> |
| |
| <div class="indent"> |
| <h3 class="tutorial">Customizing the Wizard Images</h3> |
| <div class="indent"> |
| <ol> |
| <li><p>In the "harness/nbi" folder, go to "stub/ext/engine", which is the folder shown |
| in the screenshot below. Then continue expanding the folders until |
| you find the images shown below:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/customize-icons-1.png" alt="1"/></p> |
| </li> |
| <li><p>Replace the images with your own images and then generate the installer again, |
| following the instructions in the previous section.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <div class="indent"> |
| <h3 class="tutorial">Customizing the Wizard Texts</h3> |
| <div class="indent"> |
| <ol> |
| <li><p>In the "harness/nbi" folder, go to "stub/ext/engine", which is the folder shown |
| in the screenshot below. Then continue expanding the folders until |
| you find the <tt>Bundle.properties</tt> file shown below:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/customize-texts-1.png" alt="1"/></p> |
| </li> |
| <li><p>Replace the texts with your own and then regenerate the installer, |
| which is explained in the previous section.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <div class="indent"> |
| <h3 class="tutorial">Customizing the Wizard Size</h3> |
| <div class="indent"> |
| <ol> |
| <li><p>In the "harness/nbi" folder, go to "stub/ext/engine", which is the folder shown |
| in the screenshot below. Then continue expanding the folders until |
| you find the <tt>engine.properties</tt> file shown below:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/customize-sizes-1.png" alt="1"/></p> |
| </li> |
| <li><p>Replace the sizes with your own and then regenerate the installer, |
| which is explained in the previous section.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <div class="indent"> |
| <h3 class="tutorial">Customizing the Wizard Destination Directory</h3> |
| <div class="indent"> |
| <ol> |
| <li><p>In the "harness/nbi" folder, go to "stub/ext/infra", which is the folder shown |
| in the screenshot below. Then continue expanding the folders until |
| you find the <tt>build.properties</tt> file shown below:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/customize-destinationdir-1.png" alt="1"/></p> |
| </li> |
| <li><p>Replace the values of the <tt>product.properties</tt> keys with |
| your own and then regenerate the installer, |
| which is explained in the previous section.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <div class="indent"> |
| <h3 class="tutorial">Customizing the Wizard Panels</h3> |
| <div class="indent"> |
| <ol> |
| <li><p>In the "harness/nbi" folder, go to "stub/ext/components", which is the folder shown |
| in the screenshot below. Then continue expanding the folders until |
| you find the <tt>HelloWorldPanel.java</tt> and the <tt>wizard.xml</tt> file shown below:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/customize-panels-1.png" alt="1"/></p> |
| </li> |
| <li><p>Create new panels and register them |
| in the <tt>wizard.xml</tt> file or |
| unregister panels by removing their |
| registration entries found in the <tt>wizard.xml</tt> file.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| |
| <p>Now that you have learned how to customize the default installer, let's add additional resources to it!</p> |
| |
| <!-- ===================================================================================== --> |
| <p></p> |
| <h2><a name="bundling"></a>Bundling Additional Resources</h2> |
| <p>In this section, you learn how to bundle additional resources |
| together with your installer.</p> |
| |
| <div class="indent"> |
| <h3 class="tutorial"><a name="bundling-glassfish"></a>Bundling GlassFish</h3> |
| <p>Some NetBeans Platform applications use GlassFish in one way or another. Using |
| the instructions below, you can bundle GlassFish with your installer and |
| add a new panel to the installer wizard so that users can specify where |
| and how GlassFish should be installed.</p> |
| <p class="tips">These instructions can be applied to |
| any other tool or application that should be bundled and installed together with |
| your NetBeans Platform application–simply replace each instance of "GlassFish" |
| below with the name of the tool or application you'd like to bundle with |
| the installer of your NetBeans Platform application.</p> |
| <div class="indent"> |
| <ol> |
| <li><p>Start by creating a ZIP file of |
| your installation of GlassFish. Somewhere on disk, |
| you should have GlassFish installed. Remove any domain folders |
| you have there, since the procedure that follows will result in |
| a "domain1" domain automatically being created at the time when the |
| installer finished.</p> |
| <p class="notes"><b>Note:</b> If you have some custom libraries |
| that GlassFish will need, simply include them in the appropriate |
| folders in GlassFish before you ZIP it up. That means you'll be |
| providing a custom GlassFish distribution |
| tailor made for the application you've created. Otherwise, |
| ZIP up the default standard GlassFish distribution and the user will have |
| that when they complete the installer.</p> |
| <p>Put the ZIP file anywhere on disk, such as in the home directory. Later, |
| your ZIP file |
| will be located by the nbi infrastructure, |
| unzipped, and packed into the installer, once you choose |
| "Package as | Installers" in the IDE.</p> |
| </li> |
| <li><p>In the <tt>components</tt> folder and the <tt>infra</tt> folder, |
| find the <tt>helloworld</tt> folders, shown below:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/bundle-glassfish-1.png" alt="1"/></p> |
| <p>Copy the <tt>helloworld</tt> folders, one by one, and paste them in |
| the same folders where the <tt>helloworld</tt> folders are found. Name |
| both new folders <tt>glassfish</tt>, as shown below:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/bundle-glassfish-2.png" alt="1"/></p> |
| <p class="tips"> Depending on the operating system you're using, |
| make sure you have write permission for the folders into which |
| you're copying, otherwise |
| you will not be able to complete the copy action. To fix this, |
| go outside the IDE to the folder in your filesystem and fix |
| the permissions set on the folder so that you have write permission.</p> |
| </li> |
| <li><p>In <tt>nbi/build.xml</tt>, include <tt>glassfish</tt> in the <tt>-clean</tt> |
| and <tt>-build</tt> targets. Do this by copying the <tt>helloworld</tt> |
| equivalents and replacing <tt>helloworld</tt> references with <tt>glassfish</tt> |
| references. In the same file, change <tt>create-bundle</tt> so that <tt>glassfish</tt> |
| is included, as highlighted below:</p> |
| |
| <pre class="examplecode"><create-bundle root="${output.dir}/registry-temp" |
| platform="${platform}" |
| target="${bundles.release.dir}/${bundle.files.prefix}-${platform}.${bundle.extention}"> |
| <component uid="${main.product.uid}" version="1.0.0.0.0"/> |
| <b><component uid="glassfish" version="1.0.0.0.0"/></b> |
| </create-bundle></pre> |
| |
| </li> |
| <li><p>In <tt>nbi/stub/ext/infra/products/glassfish</tt>, open |
| <tt>build.properties</tt> and change the value |
| of <tt>product.data.1.path</tt> so that it points to |
| the location on disk of your GlassFish ZIP file. In the |
| same file, change the value of <tt>product.uid</tt> to <tt>glassfish</tt>.</p> |
| </li> |
| </ol> |
| </div> |
| <p>When you regenerate the installer, |
| as explained in the previous section, your GlassFish |
| ZIP file will be included in the installer. When you |
| run the installer, a new panel will be shown for |
| installing GlassFish. When the wizard is complete, |
| GlassFish will be installed, together with the application.</p> |
| <h3 class="tutorial"><a name="bundling-jre"></a>Bundling the JRE</h3> |
| <P>In many cases, the users of your NetBeans Platform application |
| may not have a Java runtime environment (JRE) installed on their system. As a result, |
| they will not be able to start your NetBeans Platform application, in fact, they |
| will not even be able to start your installer, and will need to |
| download and configure the JRE manually. To help your users, you can bundle the JRE |
| with the installer and create the installer and the NetBeans Platform |
| application in such a way that they |
| will automatically use the bundled JRE when starting up.</P> |
| <p class="notes"><b>Note:</b> The instructions below apply to Windows. |
| For Unix systems, refer to <a href="http://netbeans.dzone.com/including-jre-in-nbi">Including the JRE in a NetBeans Platform Installer on Ubuntu Linux</a>.</p> |
| <div class="indent"> |
| <p><b>Preparing the JRE</b></p> |
| <div class="indent"> |
| <ol> |
| <li><p>Go to your JDK installation and copy the JRE somewhere else, |
| separately, so that you |
| don't accidentally destroy the JDK you're using to run Java programs, |
| such as NetBeans IDE. For purposes of this |
| tutorial, we will copy the folder "jre", from the JDK, |
| to a new folder named "C:\AJava":</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/bundle-jre-1.png" alt="1"/></p> |
| </li> |
| <li>The <tt>C:\\AJava\jre\lib\rt.jar</tt> is large. In this step, we're going |
| to replace <tt>rt.jar</tt> with a compressed version of |
| the same JAR. Go to C:\\AJava\jre\lib and run: |
| <pre>pack200 -J-Xmx1024m rt.jar.pack.gz rt.jar</pre> |
| <p>Now go into C:\\AJava\jre\lib and delete the "rt.jar". |
| </p> |
| </li> |
| <li>Go to C:\\AJava\jre and select the "bin" folder and the "lib" folder. Right-click and ZIP the selected folders. You'll end up with "jre.zip". |
| </li> |
| <li>Put "unzipsfx.exe", <a href="http://www.info-zip.org/pub/infozip/">which can |
| you get here</a> or <a href="http://wiki.netbeans.org/DevFaqAccessSourcesUsingMercurial">by |
| downloading the NetBeans sources</a> and then looking in the |
| "nbi/infra/build/jvm/tools/unzipsfx" folder, |
| into the same folder as where the "jre.zip" is found. Then, in the folder |
| where "unzipsfx.exe" and "jre.zip" are found, run this: |
| <pre>copy /B unzipsfx.exe + jre.zip jre.exe</pre> |
| <p>The result of the above is that you now have a "jre.exe" file, which is a self-extractable |
| ZIP archive. To try it out, |
| run it and then you'll find the "jre" installed |
| on your system. We now need to bundle this "jre.exe" into the installer, via the Ant |
| script that configures the installer, as outlined in the steps that follow. |
| </p> |
| </li> |
| </ol> |
| </div> |
| <p><b>Configuring the NetBeans Installer Infrastructure</b></p> |
| <div class="indent"> |
| <ol> |
| <li>Replace "create-bundle" in the "build.xml" |
| found in the IDE's "harness/nbi/stub" folder with the following: |
| <pre class="examplecode"><create-bundle root="${output.dir}/registry-temp" platform="${platform}" |
| target="${bundles.release.dir}/${bundle.files.prefix}-${platform}.${bundle.extention}"> |
| <component uid="${main.product.uid}" version="1.0.0.0.0"/> |
| <b><property name="nbi.bundled.jvm.file" value="C:\\AJava\jre\jre.exe"/></b> |
| </create-bundle></pre> |
| <p class="tips"> Depending on the operating system you're using, |
| make sure you have write permission for the above file, otherwise |
| you will not be able to make changes to it. To fix this, |
| go outside the IDE to the file in your filesystem and fix |
| the permissions set on the file so that you have write permission.</p> |
| </li> |
| <li>Put this right at the end of "install(Progress progress)" in ConfigurationLogic.java, which is within "harness/nbi/stub/ext/components/products/helloworld/src/org/mycompany": |
| <pre>File javaHome = new File(System.getProperty("java.home")); |
| File target = new File(installLocation, "jre"); |
| try { |
| FileUtils.copyFile(javaHome, target, true); //FileUtils is one of the NBI core classes, already imported |
| } catch (IOException e) { |
| throw new InstallationException("Cannot copy JRE",e); |
| } |
| |
| // to add uninstaller logic: |
| SystemUtils.getNativeUtils().addUninstallerJVM(new LauncherResource(false, target));</pre> |
| <p>And, in the "uninstall(Progress progress)" method, add this right before the last statement: |
| </p> |
| <pre>File jre = new File(installLocation, "jre"); |
| if (jre.exists()) { |
| try { |
| for (File file : FileUtils.listFiles(jre).toList()) { |
| FileUtils.deleteOnExit(file); |
| } |
| FileUtils.deleteOnExit(installLocation); |
| } catch (IOException e) { |
| //ignore |
| } |
| }</pre> |
| <p>Add this to the import statement section at the top of the file:</p> |
| |
| <pre>import org.netbeans.installer.utils.system.launchers.LauncherResource;</pre> |
| |
| <p class="notes"><b>Note:</b> You will see compilation errors, i.e., red error marks, |
| throughout the code. That is because you have not opened the code |
| as projects into the IDE. Don't worry, the code will compile once |
| you regenerate the installer later in this tutorial.</p> |
| <p class="tips"> Depending on the operating system you're using, |
| make sure you have write permission for the above file, otherwise |
| you will not be able to make changes to it. To fix this, |
| go outside the IDE to the file in your filesystem and fix |
| the permissions set on the file so that you have write permission.</p> |
| <p>You have now specified how and when the "jre" will be installed by the installer wizard. |
| </p> |
| </li> |
| </ol> |
| </div> |
| <p><b>Configuring the NetBeans Platform Application to Use the Bundled JRE</b></p> |
| <div class="indent"> |
| <ol> |
| <li><p>In your application, e.g., in "nbproject" of your application, |
| create a ".conf" file with. For example, for purposes of this |
| tutorial, switch to the Files window, right-click on the Paint Application's |
| "nbproject" folder, and choose New | Other and then select |
| Other | Empty File. Click Next, type "paintit.conf", and click Finish. |
| You should now see this:</p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/bundle-jre-2.png" alt="1"/></p> |
| </li> |
| <li><p>Paste the content below into the <tt>paintit.conf</tt> file. |
| As you can see below, |
| you need to make sure that the <tt>jdkhome</tt> key has its value set to |
| "jre", which is the folder relative to the installation directory where |
| your bundled JRE will be unpacked:</p> |
| <pre>default_userdir="C://paintit" |
| default_cachedir="C://paintit" |
| default_options="-J-client -J-Xss2m -J-Xms32m -J-XX:PermSize=32m -J-ea" |
| jdkhome="jre"</pre> |
| <p class="tips"> Read about <a href="http://wiki.netbeans.org/FaqWhatIsUserdir">userdir & cachedir</a> in the NetBeans Wiki.</p> |
| </li> |
| <li><p>Register the conf file in the application's "project.properties" file, i.e., |
| in the same file where <tt>app.name</tt> is defined, like this:</p> |
| <pre>app.conf=nbproject/paintit.conf</pre> |
| <p>The <tt>paintit.conf</tt> file |
| needs to be defined relative to the application root folder. In this case, |
| we have put the file within the "nbproject" folder, which has as its |
| parent the application root folder. Now you have specified |
| that the application will use the configuration file that you have provided, |
| within which the bundled JRE is defined as the JRE to be used for |
| starting up the application. |
| </p> |
| </li> |
| <li><p>Regenerate the installer, |
| as explained in the previous section, and the |
| installer will be created, as always. However, when you run |
| the installer, the JRE |
| will be unbundled into a temp folder and the installer |
| will use that JRE to run itself. A copy of the JRE will be made |
| to a folder named "jre" within the root |
| folder of your application, where the "jdkhome" |
| setting in the .conf file of the application points. |
| For the Paint Application, you |
| should now see the following: |
| </p> |
| <br/> |
| <p><img src="../images/tutorials/nbi/721/bundle-jre-3.png" alt="1"/></p> |
| <p>Run the application via the executable in the "bin" folder |
| and the JRE within the application root folder |
| will be used to start it.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| |
| <p>Now that you have learned how to create, customize, and bundle additional resources with the NetBeans installer, |
| read the resources below for many additional details and other |
| information that may be relevant to your business needs:</p> |
| <ul> |
| <li><a href="http://wiki.netbeans.org/NBI">http://wiki.netbeans.org/NBI</a></li> |
| <li><a href="http://installer.netbeans.org/docs/nbi-devguide.html">http://installer.netbeans.org/docs/nbi-devguide.html</a></li> |
| </ul> |
| |
| <div class="feedback-box"><a href="https://netbeans.org/about/contact_form.html?to=3&subject=Feedback:%20NetBeans%20Platform%20Installer%207.2.1%20Tutorial">Send Us Your Feedback</a></div> |
| |
| </body> |
| |
| </html> |
