Help/cpack_gen/nsis.rst

   1 CPack NSIS Generator
   2 --------------------
   3
   4 CPack Nullsoft Scriptable Install System (NSIS) generator specific options.
   5
   6 .. versionchanged:: 3.22
   7  The NSIS generator requires NSIS 3.03 or newer.
   8
   9 Variables specific to CPack NSIS generator
  10 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  11
  12 The following variables are specific to the graphical installers built
  13 on Windows Nullsoft Scriptable Install System.
  14
  15 .. variable:: CPACK_NSIS_INSTALL_ROOT
  16
  17  The default installation directory presented to the end user by the NSIS
  18  installer is under this root dir. The full directory presented to the end
  19  user is: ``${CPACK_NSIS_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY}``
  20
  21 .. variable:: CPACK_NSIS_MUI_ICON
  22
  23  An icon filename.  The name of a ``*.ico`` file used as the main icon for the
  24  generated install program.
  25
  26 .. variable:: CPACK_NSIS_MUI_UNIICON
  27
  28  An icon filename.  The name of a ``*.ico`` file used as the main icon for the
  29  generated uninstall program.
  30
  31 .. variable:: CPACK_NSIS_INSTALLER_MUI_ICON_CODE
  32
  33  undocumented.
  34
  35 .. variable:: CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP
  36
  37  .. versionadded:: 3.5
  38
  39  The filename of a bitmap to use as the NSIS ``MUI_WELCOMEFINISHPAGE_BITMAP``.
  40
  41 .. variable:: CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP
  42
  43  .. versionadded:: 3.5
  44
  45  The filename of a bitmap to use as the NSIS ``MUI_UNWELCOMEFINISHPAGE_BITMAP``.
  46
  47 .. variable:: CPACK_NSIS_EXTRA_PREINSTALL_COMMANDS
  48
  49  Extra NSIS commands that will be added to the beginning of the install
  50  Section, before your install tree is available on the target system.
  51
  52 .. variable:: CPACK_NSIS_EXTRA_INSTALL_COMMANDS
  53
  54  Extra NSIS commands that will be added to the end of the install Section,
  55  after your install tree is available on the target system.
  56
  57 .. variable:: CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS
  58
  59  Extra NSIS commands that will be added to the uninstall Section, before
  60  your install tree is removed from the target system.
  61
  62 .. variable:: CPACK_NSIS_COMPRESSOR
  63
  64  The arguments that will be passed to the NSIS `SetCompressor` command.
  65
  66 .. variable:: CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL
  67
  68  Ask about uninstalling previous versions first.  If this is set to ``ON``,
  69  then an installer will look for previous installed versions and if one is
  70  found, ask the user whether to uninstall it before proceeding with the
  71  install.
  72
  73 .. variable:: CPACK_NSIS_MODIFY_PATH
  74
  75  Modify ``PATH`` toggle.  If this is set to ``ON``, then an extra page will appear
  76  in the installer that will allow the user to choose whether the program
  77  directory should be added to the system ``PATH`` variable.
  78
  79 .. variable:: CPACK_NSIS_DISPLAY_NAME
  80
  81  The display name string that appears in the Windows `Apps & features`
  82  in `Control Panel`
  83
  84 .. variable:: CPACK_NSIS_PACKAGE_NAME
  85
  86  The title displayed at the top of the installer.
  87
  88 .. variable:: CPACK_NSIS_INSTALLED_ICON_NAME
  89
  90  A path to the executable that contains the installer icon.
  91
  92 .. variable:: CPACK_NSIS_HELP_LINK
  93
  94  URL to a web site providing assistance in installing your application.
  95
  96 .. variable:: CPACK_NSIS_URL_INFO_ABOUT
  97
  98  URL to a web site providing more information about your application.
  99
 100 .. variable:: CPACK_NSIS_CONTACT
 101
 102  Contact information for questions and comments about the installation
 103  process.
 104
 105 .. variable:: CPACK_NSIS_<compName>_INSTALL_DIRECTORY
 106
 107  .. versionadded:: 3.7
 108
 109  Custom install directory for the specified component ``<compName>`` instead
 110  of ``$INSTDIR``.
 111
 112 .. variable:: CPACK_NSIS_CREATE_ICONS_EXTRA
 113
 114  Additional NSIS commands for creating `Start Menu` shortcuts.
 115
 116 .. variable:: CPACK_NSIS_DELETE_ICONS_EXTRA
 117
 118  Additional NSIS commands to uninstall `Start Menu` shortcuts.
 119
 120 .. variable:: CPACK_NSIS_EXECUTABLES_DIRECTORY
 121
 122  Creating NSIS `Start Menu` links assumes that they are in ``bin`` unless this
 123  variable is set.  For example, you would set this to ``exec`` if your
 124  executables are in an exec directory.
 125
 126 .. variable:: CPACK_NSIS_MUI_FINISHPAGE_RUN
 127
 128  Specify an executable to add an option to run on the finish page of the
 129  NSIS installer.
 130
 131 .. variable:: CPACK_NSIS_MENU_LINKS
 132
 133  Specify links in ``[application]`` menu.  This should contain a list of pair
 134  ``link`` ``link name``. The link may be a URL or a path relative to
 135  installation prefix.  Like::
 136
 137   set(CPACK_NSIS_MENU_LINKS
 138       "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html"
 139       "CMake Help" "https://cmake.org" "CMake Web Site")
 140
 141 .. variable:: CPACK_NSIS_UNINSTALL_NAME
 142
 143  .. versionadded:: 3.17
 144
 145  Specify the name of the program to uninstall the version.
 146  Default is ``Uninstall``.
 147
 148 .. variable:: CPACK_NSIS_WELCOME_TITLE
 149
 150   .. versionadded:: 3.17
 151
 152   The title to display on the top of the page for the welcome page.
 153
 154 .. variable:: CPACK_NSIS_WELCOME_TITLE_3LINES
 155
 156  .. versionadded:: 3.17
 157
 158  Display the title in the welcome page on 3 lines instead of 2.
 159
 160 .. variable:: CPACK_NSIS_FINISH_TITLE
 161
 162  .. versionadded:: 3.17
 163
 164  The title to display on the top of the page for the finish page.
 165
 166 .. variable:: CPACK_NSIS_FINISH_TITLE_3LINES
 167
 168  .. versionadded:: 3.17
 169
 170  Display the title in the finish page on 3 lines instead of 2.
 171
 172 .. variable:: CPACK_NSIS_MUI_HEADERIMAGE
 173
 174  .. versionadded:: 3.17
 175
 176  The image to display on the header of installers pages.
 177
 178 .. variable:: CPACK_NSIS_MANIFEST_DPI_AWARE
 179
 180  .. versionadded:: 3.18
 181
 182  If set, declares that the installer is DPI-aware.
 183
 184 .. variable:: CPACK_NSIS_BRANDING_TEXT
 185
 186  .. versionadded:: 3.20
 187
 188  If set, updates the text at the bottom of the install window.
 189  To set the string to blank, use a space (" ").
 190
 191 .. variable:: CPACK_NSIS_BRANDING_TEXT_TRIM_POSITION
 192
 193  .. versionadded:: 3.20
 194
 195  If set, trim down the size of the control to the size of the branding text string.
 196  Allowed values for this variable are ``LEFT``, ``CENTER`` or ``RIGHT``.
 197  If not specified, the default behavior is ``LEFT``.
 198
 199 .. variable:: CPACK_NSIS_EXECUTABLE
 200
 201  .. versionadded:: 3.21
 202
 203  If set, specify the name of the NSIS executable. Default is ``makensis``.
 204
 205 .. variable:: CPACK_NSIS_IGNORE_LICENSE_PAGE
 206
 207  .. versionadded:: 3.22
 208
 209  If set, do not display the page containing the license during installation.
 210
 211 .. variable:: CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS
 212
 213  .. versionadded:: 3.25
 214
 215  This variable is a :ref:`semicolon-separated list <CMake Language Lists>` of
 216  arguments to prepend to the nsis script to run.
 217  If the arguments do not start with a ``/`` or a ``-``, it will add one
 218  automatically to the corresponding arguments.
 219  The command that will be run is::
 220
 221     makensis.exe <preArgs>... "nsisFileName.nsi" <postArgs>...
 222
 223  where ``<preArgs>...`` is constructed from ``CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS``
 224  and ``<postArgs>...``  is constructed from ``CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS``.
 225
 226
 227 .. variable:: CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS
 228
 229  .. versionadded:: 3.25
 230
 231  This variable is a :ref:`semicolon-separated list <CMake Language Lists>` of
 232  arguments to append to the nsis script to run.
 233  If the arguments do not start with a ``/`` or a ``-``, it will add one
 234  automatically to the corresponding arguments.
 235  The command that will be run is::
 236
 237     makensis.exe <preArgs>... "nsisFileName.nsi" <postArgs>...
 238
 239  where ``<preArgs>...`` is constructed from ``CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS``
 240  and ``<postArgs>...``  is constructed from ``CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS``.