4253799288
git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@534287 13f79535-47bb-0310-9956-ffa450edef68
301 lines
13 KiB
XML
301 lines
13 KiB
XML
<?xml version="1.0"?>
|
|
<!--
|
|
/*
|
|
* 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.
|
|
*/
|
|
-->
|
|
|
|
<document>
|
|
|
|
<properties>
|
|
<title>Maven NSIS Plug-in</title>
|
|
<author email="dion@apache.org">dIon Gillard</author>
|
|
</properties>
|
|
|
|
<body>
|
|
<section name="Overview">
|
|
<ol>
|
|
<li><a href="#Customizing">Customizing</a></li>
|
|
<li><a href="#Default_Templates">Default Templates</a></li>
|
|
<li><a href="#Default_Template_Scripts">Default Template Scripts</a></li>
|
|
<li><a href="#Custom_Templates">Custom Templates</a></li>
|
|
</ol>
|
|
</section>
|
|
<section name="Customizing">
|
|
<p>
|
|
You can customize the installer either
|
|
by providing your own scripts that the existing templates
|
|
includes, or you can provide your own templates.
|
|
</p>
|
|
<p>
|
|
Of these, the easiest is to provide your own scripts to supplement the
|
|
default templates. The most complex is to provide your own custom
|
|
templates.
|
|
</p>
|
|
<p>
|
|
No matter which way you decide to customize the installation process,
|
|
you will need to be familiar with
|
|
<a href="http://nsis.sourceforge.net/">NSIS</a> and have easy
|
|
access to the <a href="http://nsis.sourceforge.net/Docs/">NSIS Docs</a>.
|
|
</p>
|
|
<p>
|
|
We've also found the <a href="http://hmne.sourceforge.net/">HM NIS EDIT</a>
|
|
tool, which is a free NSIS Editor/IDE, very useful.
|
|
</p>
|
|
</section>
|
|
|
|
<section name="Default Templates">
|
|
<p>
|
|
The plugin provides three templates by default:
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
<code>project.jelly</code> to get access to information in
|
|
<code>project.xml</code> from within NSIS scripts.
|
|
</li>
|
|
<li>
|
|
<code>setup.jelly</code> which generates the final script for NSIS
|
|
compilation.
|
|
</li>
|
|
<li>
|
|
<code>mui-setup.jelly</code> which generates the final script for NSIS
|
|
compilation using the <a href="http://nsis.sourceforge.net/Docs/Modern%20UI/Readme.html" target="_blank">NSIS Modern User Interface</a>.
|
|
</li>
|
|
</ol>
|
|
<subsection name="project.jelly">
|
|
<p>
|
|
This template produces a file (<code>${maven.build.dir}/project.nsi</code>)
|
|
which is included in the generated setup file.
|
|
</p>
|
|
<p>
|
|
The template makes available select values from the <code>project.xml</code>
|
|
for use in the installation process as constants, i.e. using the NSIS
|
|
<code>!define</code> statement.
|
|
</p>
|
|
<table>
|
|
<tr><th>Constant</th> <th>Value</th></tr>
|
|
<tr><td>PROJECT_BUILD_DIR</td> <td>${maven.build.dir}</td></tr>
|
|
<tr><td>PROJECT_DIST_BIN_DIR</td> <td>${maven.nsis.build.dir}</td></tr>
|
|
<tr><td>PROJECT_DIST_DIR</td> <td>${maven.build.dir}</td></tr>
|
|
<tr><td>PROJECT_FINAL_NAME</td> <td>${maven.nsis.final.name}</td></tr>
|
|
<tr><td>PROJECT_LICENSE_FILE</td> <td>${maven.license.licenseFile}</td></tr>
|
|
<tr><td>PROJECT_LICENSE_TEXT</td> <td>${maven.nsis.license.text}</td></tr>
|
|
<tr><td>PROJECT_LOGO</td> <td>${maven.nsis.logo}</td></tr>
|
|
<tr><td>PROJECT_NAME</td> <td>${pom.name}</td></tr>
|
|
<tr><td>PROJECT_ORGANIZATION</td> <td>${pom.organization.name}</td></tr>
|
|
<tr><td>PROJECT_REG_KEY</td> <td>SOFTWARE\${pom.organization.name}\${pom.name}\${pom.currentVersion}</td></tr>
|
|
<tr><td>PROJECT_REG_UNINSTALL_KEY</td> <td>Software\Microsoft\Windows\CurrentVersion\Uninstall\${pom.name} ${pom.currentVersion}</td></tr>
|
|
<tr><td>PROJECT_STARTMENU_FOLDER</td> <td>$$SMPROGRAMS\${pom.organization}\${pom.name} ${pom.currentVersion}</td></tr>
|
|
<tr><td>PROJECT_URL</td> <td>${pom.url}</td></tr>
|
|
<tr><td>PROJECT_VERSION</td> <td>${pom.currentVersion}</td></tr>
|
|
</table>
|
|
</subsection>
|
|
<subsection name="setup.jelly">
|
|
<p>
|
|
This template produces a file (<code>${maven.build.dir}/setup.nsi</code>)
|
|
which is used by the NSIS 'compiler', <code>makensis.exe</code> to
|
|
produce the installer.
|
|
</p>
|
|
<p>
|
|
The file, when processed, includes other files which you can optionally
|
|
provide, to add functionality to the installer. The property,
|
|
<code><a href="properties.html">${maven.nsis.src}</a></code>, which defaults to
|
|
<code>${basedir}/src/nsis</code>, is where you can place any NSIS source
|
|
files which you want included.
|
|
</p>
|
|
<p>
|
|
The <code>setup.nsi</code> file that is generated uses following list
|
|
of directories to search for files to include:
|
|
</p>
|
|
<ol>
|
|
<li><code>${maven.nsis.src}</code> if it exists,</li>
|
|
<li><code>${maven.build.dir}</code></li>
|
|
<li><code>${plugin.resources}</code></li>
|
|
</ol>
|
|
<p>
|
|
So anything in your NSIS source will override the defaults.
|
|
</p>
|
|
<p>
|
|
The generated setup.nsh file includes the following files:
|
|
</p>
|
|
<table>
|
|
<tr><th>File</th><th>Purpose</th></tr>
|
|
<tr>
|
|
<td>before-install.nsh</td>
|
|
<td>Allow customization of code to be run before the install, e.g. check JAVA_HOME etc</td>
|
|
</tr>
|
|
<tr>
|
|
<td>BrandingImage.nsh</td>
|
|
<td>Adds a macro to display the project logo on the installer</td>
|
|
</tr>
|
|
<tr>
|
|
<td>desktop-shortcuts.nsh</td>
|
|
<td>Allow customization of desktop shortcuts to be added</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Environment.nsh</td>
|
|
<td>Adds functionality to set environment variables</td>
|
|
</tr>
|
|
<tr>
|
|
<td>JDK.nsh</td>
|
|
<td>Adds a function to check for <code>JAVA_HOME</code> being set</td>
|
|
</tr>
|
|
<tr>
|
|
<td>project.nsh</td>
|
|
<td>The generated file with project details as constants</td>
|
|
</tr>
|
|
<tr>
|
|
<td>registry.nsh</td>
|
|
<td>Allow customization of environment variables and registry entries to be written</td>
|
|
</tr>
|
|
<tr>
|
|
<td>registry-uninstall.nsh</td>
|
|
<td>Allow customization of environment variables and registry entries to be removed on uninstall</td>
|
|
</tr>
|
|
<tr>
|
|
<td>remove-shortcuts.nsh</td>
|
|
<td>Allow customization of shortcuts deletion. The default script removes everything in ${PROJECT_STARTMENU_FOLDER}.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>startmenu-shortcuts.nsh</td>
|
|
<td>Allow start menu shortcuts to be added</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
Typically you wont provide overrides for BrandingImage.nsh,
|
|
Environment.nsh and JDK.nsh, as these are utilities used in the setup.nsh
|
|
script.
|
|
</p>
|
|
</subsection>
|
|
<subsection name="mui-setup.jelly">
|
|
<p>
|
|
This template is very similar to setup.jelly. It uses NSIS Modern UI and allows more customization for the installer Look And Feel.
|
|
It includes the same list of files, except for BrandingImage.nsh which isn't useful.
|
|
It doesn't use properties <a href="properties.html">maven.nsis.logo* but maven.nsis.mui*</a>.
|
|
</p>
|
|
<p>To use this template you just have to define this property in your project : </p>
|
|
<source>maven.nsis.setup.template=${plugin.resources}/templates/mui-setup.jelly</source>
|
|
</subsection>
|
|
</section>
|
|
|
|
<section name="Default Template Scripts">
|
|
<p>
|
|
There are several .nsh files that you can place in <code>${maven.nsis.src}</code>
|
|
directory to add functionality to the installer. In this section, we'll look
|
|
at an example for each of the scripts included by the default template that
|
|
will be overridden.
|
|
</p>
|
|
|
|
<subsection name="before-install.nsh">
|
|
<p>
|
|
This file is used to do any pre-installation checks. It can hold any
|
|
<a href="http://nsis.sourceforge.net/Docs/">valid NSIS code</a>.
|
|
</p>
|
|
<p>
|
|
One example is to check the environment has been correctly set up, e.g.
|
|
</p>
|
|
<source>Call AssertJavaHome</source>
|
|
<p>
|
|
This will check, using the function provided in <code>JDK.nsh</code>,
|
|
that an environment variable for <code>JAVA_HOME</code> is available,
|
|
and abort the installation if it's not.
|
|
</p>
|
|
</subsection>
|
|
|
|
<subsection name="desktop-shortcuts.nsh">
|
|
<p>
|
|
If you provide this file, the installer will allow the user to choose
|
|
whether or not to create shortcuts on the desktop. The shortcuts specified
|
|
in this file will be created.
|
|
</p>
|
|
<p>
|
|
As always, see the <a href="http://nsis.sourceforge.net/Docs/">NSIS docs</a>
|
|
for details on the code to use. The example below creates a shortcut
|
|
on the desktop to <code>maven.bat</code> from the installation directory
|
|
the user has chosen.
|
|
</p>
|
|
<source>CreateShortCut "$DESKTOP\Maven.lnk" "$INSTDIR\bin\maven.bat" "" "$INSTDIR\bin\maven.bat" 0</source>
|
|
</subsection>
|
|
|
|
<subsection name="registry.nsh">
|
|
<p>
|
|
During installation, you may want to add entries to the user's registry
|
|
or environment for use either in your application, the installation process, or uninstall.
|
|
Here's a small example that adds an environment variable called <code>MYAPP_HOME</code>
|
|
with the value of the installation directory.
|
|
</p>
|
|
<source>
|
|
Push "MYAPP_HOME"
|
|
Push "$INSTDIR"
|
|
Call WriteEnvStr
|
|
</source>
|
|
<p>
|
|
Note: this relies on the included functions from <code>Environment.nsh</code>.
|
|
</p>
|
|
</subsection>
|
|
|
|
<subsection name="registry-uninstall.nsh">
|
|
<p>
|
|
During uninstallation, you must remove any entries to the user's registry
|
|
or environment. Here's a small example that removes an environment variable
|
|
called <code>MYAPP_HOME</code>.
|
|
</p>
|
|
<source>
|
|
Push "MYAPP_HOME"
|
|
Call un.DeleteEnvStr
|
|
</source>
|
|
</subsection>
|
|
|
|
<subsection name="startmenu-shortcuts.nsh">
|
|
<p>
|
|
If you provide this file, the installer will allow the user to choose
|
|
whether or not to create shortcuts in the <code>Start Menu</code>.
|
|
The shortcuts specified in this file will be created.
|
|
</p>
|
|
<source>
|
|
CreateShortCut "${PROJECT_STARTMENU_FOLDER}\Myapp.lnk" "$INSTDIR\bin\myapp.bat" "" "$INSTDIR\bin\myapp.bat" 0
|
|
CreateShortCut "${PROJECT_STARTMENU_FOLDER}\Uninstall.lnk" "$INSTDIR\Uninst.exe" "" "$INSTDIR\Uninst.exe" 0
|
|
CreateShortCut "${PROJECT_STARTMENU_FOLDER}\Homepage.lnk" "http://www.myapp.nfi/"
|
|
CreateShortCut "${PROJECT_STARTMENU_FOLDER}\User Guide.lnk" "http://www.myapp.nfi/user-guide.html"
|
|
</source>
|
|
</subsection>
|
|
|
|
</section>
|
|
|
|
<section name="Custom Templates">
|
|
<p>
|
|
You can of course provide your own versions of the <code>project.jelly</code>
|
|
and <code>setup.jelly</code> templates. This requires you to understand NSIS
|
|
and a little bit of <a href="http://jakarta.apache.org/commons/jelly/">jelly</a>
|
|
as well.
|
|
</p>
|
|
<p>
|
|
To use your own templates, override the <code>maven.nsis.project.template</code>
|
|
and <code>maven.nsis.setup.template</code> variables.
|
|
</p>
|
|
<p>
|
|
The templates are expected to be well formed Jelly scripts, i.e. valid
|
|
XML documents.
|
|
</p>
|
|
<p>
|
|
If you do provide your own templates, you have complete control over
|
|
the way the installation process will work. You will also be able to
|
|
completely ruin it as well :-).
|
|
</p>
|
|
</section>
|
|
</body>
|
|
</document>
|