5.1 Compiler Utility Commands

These commands are similar to the C preprocessor in terms of purpose and functionality. They allow file inclusion, conditional compilation, executable header packing and process execution during the build process. Note: None of these commands allow the use of variables.

这些命令都不允许使用变量。

Number literals support the 0b, 0o, 0n and 0x radix prefixes (base 2, 8, 10 and 16 respectively). Note: The deprecated plain 0 octal prefix is also supported in some places but its usage is discouraged.

5.1.1 !include

!include [/NONFATAL] [/CHARSET=ACP|OEM|CP#|UTF8|UTF16LE|UTF16BE] file

This command will include 'file' as if it was part of the original script. Note that if a file is included in another directory, the current directory is still where the script was compiled from (not where the included file resides). If the compiler can't find the file it will look for it in every include directory. See !addincludedir for more information. If the /nonfatal switch is used and no files are found, a warning will be issued instead of an error. /charset can be used to specify a codepage for plain text files without a BOM.

这个命令将包含“file”，就好像它是原始脚本的一部分一样。

!include WinMessages.nsh
!include Library.nsh
!include /CHARSET=CP1252 C:\MyConfig.nsi
!include ..\MyConfig.nsh
!include /NONFATAL file_that_may_exist_or_not.nsh

5.1.2 !addincludedir

!addincludedir directory

Adds another include directory to the include directories list. This list is searched when !include is used. This list's initial value is ${NSISDIR}\Include.

将另一个包含目录添加到包含目录列表。

!addincludedir ..\include
!include something.nsh

5.1.3 !addplugindir

!addplugindir [/x86-ansi | /x86-unicode] directory

Causes the NSIS compiler to scan the given directory for plug-in DLLs. If you don't specify the plug-in architecture it is assumed to match the current target architecture. If the architecture does not match the installer will probably crash!

使NSIS编译器扫描给定目录以查找插件dll。

!addplugindir ..\myplugin
MyPlugin::SomeFunction

5.1.4 !appendfile

!appendfile [/CHARSET=ACP|OEM|CP#|UTF8[SIG]|UTF16<LE|BE>[BOM]] [/RawNL] file text

Appends text to file. The text is written as ANSI (ACP) unless the file already has a BOM. Using /CHARSET will force a specific character encoding. $\n will be translated to $\r$\n on Windows unless you specify /RawNL.

附加文本到文件。

!tempfile FILE
!appendfile "${FILE}" "XPStyle on$\n"
!appendfile "${FILE}" "Name 'test'$\n"
!include "${FILE}"
!delfile "${FILE}"
!undef FILE

5.1.5 !cd

!cd new_path

This command will change the compiler to the new directory, new_path. new_path can be relative or absolute.

这个命令将把编译器改为新目录“new_path”。

!cd ..\more-scripts\new

5.1.6 !delfile

!delfile [/nonfatal] file

This command deletes a file.

该命令删除一个文件。

!tempfile FILE
!delfile "${FILE}"
!undef FILE

5.1.7 !echo

!echo message

This command will echo a message to the user compiling the script.

这个命令将向编译脚本的用户返回一条消息。

!echo "hello world"

5.1.8 !error

!error [message]

This command will issue an error to the script compiler and will stop execution of the script. You can also add a message to this error.

这个命令将向脚本编译器发出一个错误，并将停止脚本的执行。

!ifdef VERSION & NOVERSION
  !error "both VERSION and NOVERSION are defined"
!endif

5.1.9 !execute

!execute command [compare comparevalue | symbol]

This command will execute 'command' using a call to CreateProcess(). Unlike !system, it does not use the command line processor, so input/output redirection and commands like 'cd', 'dir' and 'type' can not be used. Currently, the only known advantage of !execute over !system is that it does not give trouble when the current working directory is specified using UNC.

该命令将通过调用CreateProcess()来执行command。

On POSIX platforms, !execute will use system() just like !system.

!execute '"$%WINDIR%\notepad.exe" /P "${NSISDIR}\COPYING"'

5.1.10 !makensis

!makensis parameters [compare comparevalue | symbol]

This command will !execute a new instance of MakeNSIS with the parameters you specify.

这个命令会使用!execute执行指定的参数MakeNSIS的新实例。

!makensis '-DGENERATEUNINST "${__FILE__}"' = 0
!system '"signtool" sign ...' = 0

5.1.11 !packhdr

!packhdr tempfile command

This option makes the compiler use an external EXE packer (such as Petite or UPX) to compress the executable header. Specify a temporary file name (such as "temp.dat") and a command line (such as "C:\program files\upx\upx -9 temp.dat") to compress the header.

此选项使编译器使用外部EXE打包器来压缩可执行头文件。

!packhdr "$%TEMP%\exehead.tmp" '"C:\Program Files\UPX\upx.exe" "$%TEMP%\exehead.tmp"'

5.1.12 !finalize

!finalize command [compare comparevalue]

This option will execute 'command' using a call to system() after the installer EXE has been generated. You can typically use it to sign (Authenticode) your installer. If 'command' contains a '%1' it will be replaced by the executables filename.

此选项将在生成安装程序EXE后通过调用system()来执行command。

!finalize 'sign.bat "%1" "MyProduct Installer" http://example.com'

5.1.13 !uninstfinalize

!uninstfinalize command [compare comparevalue]

This option will execute 'command' using a call to system() after the uninstaller EXE has been generated. You can typically use it to sign (Authenticode) your uninstaller. If 'command' contains a '%1' it will be replaced by the executables filename.

此选项将在生成卸载程序EXE后通过调用system()来执行command。

!uninstfinalize 'sign.bat "%1" "MyProduct Installer" http://example.com'

5.1.14 !system

!system command [compare comparevalue | symbol]

This command will execute 'command' using a call to system(). You can store the return value in a define ('symbol') or halt execution if the return value compared (using 'compare') to 'comparevalue' is false. 'compare' can be '<' or '>' or '<>' or '='.

该命令将通过调用system()来执行command。

!system '"%WINDIR%\notepad.exe" "${NSISDIR}\COPYING"'
!system 'echo !define something > newinclude.nsh'
!include newinclude.nsh
!ifdef something
  !echo "something is defined"
!endif
!system 'attrib +H Secret.txt' = 0
!system 'ping localhost' ERRLVL
!echo "Ping returned ${ERRLVL}"

5.1.15 !tempfile

!tempfile symbol

This command creates a temporary file. It puts its path into a define, named symbol.

这个命令创建一个临时文件。它把它的路径放到一个定义的，命名为symbol的路径中。

!tempfile PACKHDRTEMP
!packhdr "${PACKHDRTEMP}" '"C:\Program Files\UPX\upx.exe" "${PACKHDRTEMP}"'
!tempfile FILE
!define /date DATE "%H:%M:%S %d %b, %Y"
!system 'echo built on ${DATE} > "${FILE}"'
!undef DATE
File /oname=build.txt "${FILE}"
!delfile "${FILE}"
!undef FILE

5.1.16 !getdllversion

!getdllversion [/noerrors] [/packed] [/productversion] localfilename define_basename

This is similar to GetDLLVersionLocal, only it stores the version number in defines and can therefore be used anywhere, not just inside functions and sections. /packed returns the information in two DWORDs.

这类似于GetDLLVersionLocal，只是它将版本号存储在定义中，因此可以在任何地方使用，而不仅仅是在函数和条款中。

!getdllversion "$%WINDIR%\Explorer.exe" Expv_
!echo "Explorer.exe version is ${Expv_1}.${Expv_2}.${Expv_3}.${Expv_4}"

5.1.17 !gettlbversion

!gettlbversion [/noerrors] [/packed] localfilename define_basename

Get the version information from a .TLB file.

从.TLB文件中获取版本信息。

!gettlbversion /packed "$%WINDIR%\System32\stdole32.tlb" TLBVER_
!echo "${TLBVER_HIGH}.${TLBVER_LOW}"

5.1.18 !warning

!warning [message]

This command will issue a warning to the script compiler. You can also add a message to this warning.

这个命令将向脚本编译器发出警告。

!ifdef USE_DANGEROUS_STUFF
  !warning "using dangerous stuff"
!endif

5.1.19 !pragma

!pragma warning <enable|disable|default|error|warning> <code|all>
!pragma warning <push|pop>

The pragma commands allows you to change compiler features and behavior.

pragma命令允许您更改编译器的特性和行为。

!pragma warning disable 9000 ; Disable warning about using "Setup.exe" as the name
OutFile "Setup.exe"

5.1.20 !verbose

!verbose level | push | pop

This command will set the level of verbosity: 4=all, 3=no script, 2=no info, 1=no warnings, 0=none.

这个命令将设置冗长的级别。

Passing push will cause !verbose to push the current verbosity level on a special stack. Passing pop will cause !verbose to pop the current verbosity level from the same stack and use it.

!verbose push
!verbose 1
!include WinMessages.nsh
!verbose pop

5.2 Predefines

You can use these standard predefines to automatically add the build time to the title of development versions, add the date to the version number, etc.

您可以使用这些标准的预定义来自动地将构建时间添加到开发版本的标题中，将日期添加到版本号中，等等。

5.2.1 ${__COUNTER__}

Expands to a number. (Starting at 0 and incrementing by 1 every time it is used)

展开成一个数字。（从0开始，每次使用时递增1）

5.2.2 ${__FILE__}

Current script name.

当前脚本的名字。

5.2.3 ${__FILEDIR__}

Current script directory.

当前脚本目录。

5.2.4 ${__LINE__}

Current line number.

当前行号。

5.2.5 ${__DATE__}

Date when the script started compiling according to the current locale.

脚本根据当前区域设置开始编译的日期。

5.2.6 ${__TIME__}

Time when the script started compiling according to the current locale.

脚本根据当前区域设置开始编译的时间。

5.2.7 ${__TIMESTAMP__}

Date & time of the last modification to the script file according to the current locale.

根据当前区域设置对脚本文件进行最后修改的日期和时间。

5.2.8 ${NSIS_VERSION}

NSIS version used to build the script.

用于构建脚本的NSIS版本。

5.2.9 ${NSIS_PACKEDVERSION}

NSIS version as a 32-bit number.

NSIS版本为32位数字。

!if 0x3014000 >= "${NSIS_PACKEDVERSION}"
  !error "NSIS 3.15 or higher is required to build this installer!"
!endif

5.2.10 ${NSIS_CHAR_SIZE}

The size of a character code unit (in bytes). 1 in ANSI installers and 2 in Unicode installers.

字符代码单元的大小（以字节为单位）。

A grapheme cluster consists of a base character plus optional combining characters and diacritics and is defined as one or more code points. One or more code units is required to encode a single code point.

5.2.11 ${NSIS_PTR_SIZE}

The size of a pointer (in bytes) in the generated installer.

在生成的安装程序中指针的大小（以字节为单位）。

5.2.12 ${U+1}...${U+10FFFF}

A Unicode (UCS-4) character.

一个Unicode（UCS-4）字符。

DetailPrint "${U+2115}SIS" # DOUBLE-STRUCK CAPITAL N + "SIS"

5.2.13 Scope Predefines

Standard predefines that contain information about the current code scope.

标准预定义包含有关当前代码范围的信息。

5.2.13.1 ${__GLOBAL__}

Defined in the global scope.

在全局作用域中定义。

Section test
  !ifdef __GLOBAL__
    !error "this shouldn't be here!"
  !endif
SectionEnd

PageEx instfiles
  !ifdef __GLOBAL__
    !error "this shouldn't be here!"
  !endif
PageExEnd

5.2.13.2 ${__SECTION__}

Defined as the section name, without any prefixes, in section scope.

在条款范围内定义为条款名称，不带任何前缀。

!ifdef __SECTION__
  !error "this shouldn't be here!"
!endif

Section test
  !ifndef __SECTION__
    !error "missing predefine!"
  !endif

  !if ${__SECTION__} != test
    !error "wrong predefine value!"
  !endif
SectionEnd

Section !test
  !if ${__SECTION__} != test
    !error "wrong predefine value!"
  !endif
SectionEnd

Section un.test
  !if ${__SECTION__} != test
    !error "wrong predefine value!"
  !endif
SectionEnd

5.2.13.3 ${__FUNCTION__}

Defined as the function name, without any prefixes, in function scope.

在函数作用域中定义为函数名，不带任何前缀。

!ifdef __FUNCTION__
  !error "this shouldn't be here!"
!endif

Function test
  !ifndef __FUNCTION__
    !error "missing predefine!"
  !endif

  !if ${__FUNCTION__} != test
    !error "wrong predefine value!"
  !endif
FunctionEnd

Function un.test
  !if ${__FUNCTION__} != test
    !error "wrong predefine value!"
  !endif
FunctionEnd

5.2.13.4 ${__PAGEEX__}

Defined as the page type in PageEx scope.

PageEx范围内定义页面类型。

!ifdef __PAGEEX__
  !error "this shouldn't be here!"
!endif

PageEx instfiles
  !ifndef __PAGEEX__
    !error "missing predefine!"
  !endif

  !if ${__PAGEEX__} != instfiles
    !error "wrong page type"
  !endif
PageExEnd

5.2.13.5 ${__UNINSTALL__}

Defined in section, function or PageEx scopes of the uninstaller.

在section, function或PageEx范围中定义卸载程序。

!ifdef __UNINSTALL__
  !error "this shouldn't be here!"
!endif

Function test
  !ifdef __UNINSTALL__
    !error "this shouldn't be here!"
  !endif
FunctionEnd

Function un.test
  !ifndef __UNINSTALL__
    !error "missing predefine!"
  !endif
FunctionEnd

5.2.13.6 ${__MACRO__}

Defined as the name of the current macro.

定义为当前宏的名称。

5.3 Read environment variables

5.3.1 $%envVarName%

$%envVarName% will be replaced at compile time by the environment variable envVarName.

$%envVarName%将在编译时被环境变量envVarName替换。

5.4 Conditional Compilation

The compiler maintains a list of defined symbols, which can be defined using !define or the /D command line switch. These defined symbols can be used for conditional compilation (using !ifdef) or for symbol replacement (a simple form of macros). To replace a symbol with its value, use ${SYMBOL} (if SYMBOL is not defined, no translation will occur). The translation is first-come-first-served, meaning if you do:

编译器维护一个已定义符号列表，可以使用!define或/D命令行开关。这些定义的符号可以用于条件编译或符号替换。要用符号的值替换符号，请使用${SYMBOL}。

!define symbol_one ${symbol_two}

If symbol_two is defined when that line occurs, it will be replaced. Otherwise, any replacing will occur when ${symbol_one} is referenced.

如果symbol_two在该行出现时定义，它将被替换。否则，当引用${symbol_one}时，将发生任何替换。

Define/conditional compilation related commands:

5.4.1 !define

!define [/ifndef | /redef] ([/date|/utcdate] gflag [value]) | (/file gflag filename.txt) | (/intfmt gflag fmtstr value) | (/math gflag val1 OP val2)

This command will add gflag to the global define list. This will have a similar effect as using the /D switch on the command line (the define only becomes effective after the !define command).

这个命令将把gflag添加到全局定义列表中。

If /date or /utcdate are used, value will be passed to strftime() and the result will be used as the value of gflag. strftime converts special symbols into certain parts of the current time or date. For example, %H will be converted into the current hour in 24-hour format. For a complete list of available symbols, search for strftime on MSDN. On POSIX, you can get the list by using man strftime.

If /file is used, the entire text file specified (including whitespace and newlines) will be read and placed into gflag.

If /intfmt is used, value is interpreted as a integer and formated using the same syntax as IntFmt.

If /math is used, the result of 'val1 OP val2', where OP may be +, -, *, /, %, <<, >>, >>>, &, |, ^, ~, !, && or ||, will be used as the value of gflag. Note that val1 AND val2 MUST be integer values!

!define USE_SOMETHING
!define VERSION 1.2
!define /date NOW "%H:%M:%S %d %b, %Y"
!define /math RESULT 3 + 10
!define /math REST 15 % ${RESULT}
!define /file BunchaStuff somesourcefile.cpp
!define /redef USE_SOMETHING ${RESULT} ;redefine USE_SOMETHING
!define /intfmt HEX "0x%X" 3133078222

5.4.2 !undef

!undef [/noerrors] gflag [...]

Removes an item from the global define list. Note that ${SYMBOL} where SYMBOL is undefined will be translated to "${SYMBOL}".

从全局定义列表中删除项。

!define SOMETHING
!undef SOMETHING

5.4.3 !ifdef

!ifdef gflag [bcheck gflag [...]]

This command, when paired with an !endif command, will tell the compiler whether or not to compile the lines in between the two lines. If gflag is globally defined (using !define or the /D switch), then the contained lines will be compiled. Otherwise, they will be skipped. 'bcheck' can be specified as & (boolean and) or | (boolean or) along with more gflags -- precedence is simple, left to right.

这个命令，当与!Endif命令组合时，将告诉编译器是否编译这两行之间的行。如果gflag是全局定义的，所包含的行将被编译。

!define SOMETHING
!ifdef SOMETHING
  !echo "SOMETHING is defined"
!endif
!undef SOMETHING
!ifdef SOMETHING
  !echo "SOMETHING is defined" # will never be printed
!endif

5.4.4 !ifndef

!ifndefgflag [bcheck gflag [...]]]

The opposite of !ifdef. The lines will be compiled when the gflag has not been defined.

!ifdef的反义词。当gflag还没有定义时，这些行将被编译。

5.4.5 !if

!if [!] value [op value2]
!if [!] /FileExists "c:\path\file.exe"

This command, when paired with an !endif command, will tell the compiler whether or not to compile the lines in between the two lines. If value is non-zero, or the comparison of value and value2 depending on the operator results in true, the contained lines will be compiled. Otherwise, they will be skipped. op can be either == or != (case-insensitive string comparison), S== or S!= (case-sensitive string comparison), =, <>, <=, <, > or >= (int/hex/float comparison), & (bitwise AND comparison), && or || (boolean comparison). If [!] is set, the result will be flipped from true to false and vice versa.

这个命令，当与!Endif命令组合时，将告诉编译器是否编译这两行之间的行。如果value为“非零”，或者value和value2的比较结果取决于操作符为true，所包含的行将被编译。否则，它们将被跳过。如果[!]，则结果将从true转换为false，反之亦然。

!if 1 < 0x2
  !echo "1 is smaller than 2!!"
!else if ! 3.1 > 1.99
  !error "this line should never appear"
!else
  !error "neither should this"
!endif
!if /FileExists ".\cert.pfx"
  !finalize '".\sign.bat" "%1"'
!endif

5.4.6 !ifmacrodef

!ifmacrodef gflag [bcheck gflag [...]]]

This command, when paired with an !endif command, will tell the compiler whether or not to compile the lines in between the two lines. If the macro gflag exists, then the contained lines will be compiled. Otherwise, they will be skipped. 'bcheck' can be specified as & (boolean and) or | (boolean or) along with more gflags -- precedence is simple, left to right.

这个命令，当与!Endif命令组合时，将告诉编译器是否编译这两行之间的行。如果宏gflag存在，则包含的行将被编译。否则，它们将被跳过。

!macro SomeMacro
!macroend
!ifmacrodef SomeMacro
  !echo "SomeMacro is defined"
!endif

5.4.7 !ifmacrondef

!ifmacrondef gflag [bcheck gflag [...]]]

The opposite of !ifmacrodef. The lines will be compiled when the macro gflag does not exist.

与!ifmacrodef相反。当宏gflag不存在时，这些行将被编译。

5.4.8 !else

!else [if|ifdef|ifndef|ifmacrodef|ifmacrondef [...]]

This command allows to easily insert different code when different defines or macros are set. You can create blocks like !ifdef/!else/!endif, !ifdef/!else ifdef/!else/!endif etc.

该命令允许在设置了不同的定义或宏时轻松插入不同的代码。

!ifdef VERSION
OutFile installer-${VERSION}.exe
!else
OutFile installer.exe
!endif

5.4.9 !endif

This command closes a block started with !if, !ifdef, !ifndef, !ifmacrodef or !ifmacrondef.

5.4.10 !insertmacro

!insertmacro macro_name [parameter] [...]

Inserts the contents of a macro that was created with !macro. If the macro was created with parameters, then you must pass as many parameters to the macro as it requires.

插入用!macro创建的宏的内容。如果宏是用“参数”创建的，那么你必须传递尽可能多的参数给宏。

!macro Print text
  DetailPrint "${text}"
!macroend
!insertmacro Print "some text"
!insertmacro Print "some more text"

5.4.11 !macro

!macro macro_name [parameter][...]

Creates a macro named 'macro_name'. All lines between the !macro and the !macroend will be saved. To insert the macro later on, use !insertmacro. !macro definitions can have one or more parameters defined. The parameters may be accessed the same way a !define would (e.g. ${PARMNAME}) from inside the macro.

创建一个名为macro_name的宏。

!macro SomeMacro parm1 parm2 parm3
  DetailPrint "${parm1}"
  MessageBox MB_OK "${parm2}"
  File "${parm3}"
!macroend

5.4.12 !macroend

Ends a macro that was started with !macro.

结束一个以!macro开始的宏。

5.4.13 !macroundef

!macroundef macro_name

Deletes a macro.

删除一个宏。

5.4.14 !searchparse

!searchparse [/ignorecase] [/noerrors] [/file] source_string_or_file substring_start OUTPUTSYMBOL1 [substring [OUTPUTSYMBOL2 [substring ...]]]

Parses source_string_or_file (which is treated as a string, or as a filename if /file is set), looking for substring_start. If substring_start is found, then OUTPUTSYMBOL1 is defined to the rest of the string (minus any other substring that may be found). Any number of OUTPUTSYMBOLx may be specified, and the final substring is optional.

解析source_string_or_file（视为字符串，如果设置了/file则将其视为文件名），查找substring_start。如果找到了substring_start，则将OUTPUTSYMBOL1定义为字符串的其余部分（减去可能找到的任何其他子字符串）。可以指定任意数量的OUTPUTSYMBOLx，最后的子字符串是可选的。

If /noerrors is specified, matching less than the full number of strings is allowed (all OUTPUTSYMBOLx after the not-found substring will be ignored).

If /file is specified, the file is treated as a series of lines. The file is searched until all substrings are matched. If /noerrors is specified and not all strings are matched, the first line with the most symbols matched is used.

# search filename.cpp for a line '#define APP_VERSION "2.5"' and set ${VER_MAJOR} to 2, ${VER_MINOR} to 5.
!searchparse /file filename.cpp `#define APP_VERSION "` VER_MAJOR `.` VER_MINOR `"`

5.4.15 !searchreplace

!searchreplace [/ignorecase] symbol_out source_string searchfor replacewith

Searches source_string, looking for searchfor and replacing all instances of it with replacewith. Unlike !define, !searchreplace allows you to redefine symbol_out without warning or error.

搜索source_string，查找并使用replacewith替换它的所有实例。

# defines ${blah} to "i like ponies"
!searchreplace blah "i love ponies" "love" "like"