You can customize the installer either by providing your own scripts that the existing templates includes, or you can provide your own templates.
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.
No matter which way you decide to customize the installation process, you will need to be familiar with NSIS and have easy access to the NSIS Docs.
We've also found the HM NIS EDIT tool, which is a free NSIS Editor/IDE, very useful.
The plugin provides three templates by default:
project.jelly to get access to information in
project.xml from within NSIS scripts.
setup.jelly which generates the final script for NSIS
compilation.
mui-setup.jelly which generates the final script for NSIS
compilation using the NSIS Modern User Interface.
This template produces a file (${maven.build.dir}/project.nsi)
which is included in the generated setup file.
The template makes available select values from the project.xml
for use in the installation process as constants, i.e. using the NSIS
!define statement.
| Constant | Value |
|---|---|
| PROJECT_BUILD_DIR | ${maven.build.dir} |
| PROJECT_DIST_BIN_DIR | ${maven.nsis.build.dir} |
| PROJECT_DIST_DIR | ${maven.build.dir} |
| PROJECT_FINAL_NAME | ${maven.nsis.final.name} |
| PROJECT_LICENSE_FILE | ${maven.license.licenseFile} |
| PROJECT_LICENSE_TEXT | ${maven.nsis.license.text} |
| PROJECT_LOGO | ${maven.nsis.logo} |
| PROJECT_NAME | ${pom.name} |
| PROJECT_ORGANIZATION | ${pom.organization.name} |
| PROJECT_REG_KEY | SOFTWARE\${pom.organization.name}\${pom.name}\${pom.currentVersion} |
| PROJECT_REG_UNINSTALL_KEY | Software\Microsoft\Windows\CurrentVersion\Uninstall\${pom.name} ${pom.currentVersion} |
| PROJECT_STARTMENU_FOLDER | $$SMPROGRAMS\${pom.organization}\${pom.name} ${pom.currentVersion} |
| PROJECT_URL | ${pom.url} |
| PROJECT_VERSION | ${pom.currentVersion} |
This template produces a file (${maven.build.dir}/setup.nsi)
which is used by the NSIS 'compiler', makensis.exe to
produce the installer.
The file, when processed, includes other files which you can optionally
provide, to add functionality to the installer. The property,
${maven.nsis.src}, which defaults to
${basedir}/src/nsis, is where you can place any NSIS source
files which you want included.
The setup.nsi file that is generated uses following list
of directories to search for files to include:
${maven.nsis.src} if it exists,${maven.build.dir}${plugin.resources}So anything in your NSIS source will override the defaults.
The generated setup.nsh file includes the following files:
| File | Purpose |
|---|---|
| before-install.nsh | Allow customization of code to be run before the install, e.g. check JAVA_HOME etc |
| BrandingImage.nsh | Adds a macro to display the project logo on the installer |
| desktop-shortcuts.nsh | Allow customization of desktop shortcuts to be added |
| Environment.nsh | Adds functionality to set environment variables |
| JDK.nsh | Adds a function to check for JAVA_HOME being set |
| project.nsh | The generated file with project details as constants |
| registry.nsh | Allow customization of environment variables and registry entries to be written |
| registry-uninstall.nsh | Allow customization of environment variables and registry entries to be removed on uninstall |
| remove-shortcuts.nsh | Allow customization of shortcuts deletion. The default script removes everything in ${PROJECT_STARTMENU_FOLDER}. |
| startmenu-shortcuts.nsh | Allow start menu shortcuts to be added |
Typically you wont provide overrides for BrandingImage.nsh, Environment.nsh and JDK.nsh, as these are utilities used in the setup.nsh script.
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 maven.nsis.logo* but maven.nsis.mui*.
To use this template you just have to define this property in your project :
maven.nsis.setup.template=${plugin.resources}/templates/mui-setup.jelly
There are several .nsh files that you can place in ${maven.nsis.src}
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.
This file is used to do any pre-installation checks. It can hold any valid NSIS code.
One example is to check the environment has been correctly set up, e.g.
Call AssertJavaHome
This will check, using the function provided in JDK.nsh,
that an environment variable for JAVA_HOME is available,
and abort the installation if it's not.
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.
As always, see the NSIS docs
for details on the code to use. The example below creates a shortcut
on the desktop to maven.bat from the installation directory
the user has chosen.
CreateShortCut "$DESKTOP\Maven.lnk" "$INSTDIR\bin\maven.bat" "" "$INSTDIR\bin\maven.bat" 0
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 MYAPP_HOME
with the value of the installation directory.
Push "MYAPP_HOME" Push "$INSTDIR" Call WriteEnvStr
Note: this relies on the included functions from Environment.nsh.
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 MYAPP_HOME.
Push "MYAPP_HOME"
Call un.DeleteEnvStr
If you provide this file, the installer will allow the user to choose
whether or not to create shortcuts in the Start Menu.
The shortcuts specified in this file will be created.
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"
You can of course provide your own versions of the project.jelly
and setup.jelly templates. This requires you to understand NSIS
and a little bit of jelly
as well.
To use your own templates, override the maven.nsis.project.template
and maven.nsis.setup.template variables.
The templates are expected to be well formed Jelly scripts, i.e. valid XML documents.
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 :-).