4.1 指令碼檔案格式

一個 NSIS 指令碼檔案 (.nsi) 就是一個包含了指令碼程式碼的文字檔案。

命令

命令列的格式為: '命令 [引數]'

File "myfile"

註釋

以 ; 或 # 作為開始的行為註釋。你可以在命令後面添加註釋。你也可以使用 C 規範的註釋來註釋一行或多行。

; 註釋
# 註釋

# 註釋 \
    另一個註釋行 (檢視本節下面的 `長命令`)

/*
註釋
註釋
*/

Name /* 註釋 */ mysetup

File "我的檔案" ; 註釋

如果引數需要由 ; 或 # 開頭，你可以用雙引號把它括起來。

外掛

要呼叫一個外掛，使用 '外掛::命令 [引數]'。更多的資訊請檢視 外掛 DLLs。

nsExec::Exec "我的檔案"

數字

對於數字引數，使用十進位制 (數字) 或十六進位制 (以 0x 開頭的，比如: 0x12345AB), 或八進位制 (以 0 開頭且無 x)。

顏色被設定為十六進位制 RGB 形式，像 HTML 那樣但是沒有 # 開頭。

IntCmp 1 0x1 lbl_equal

SetCtlColors $HWND CCCCCC

字串

要使用一個包含空格的字串，需要用引號括起來:

MessageBox MB_OK "Hi 您好!"

引號僅有的作用就是當他們開始時包含一個引數。他們可以是單引號、雙引號或向後的單引號。

You can escape quotes using $\:

MessageBox MB_OK "I'll be happy" ; 把一個 ' 放在字串裡
MessageBox MB_OK 'And he said to me "Hi there!"' ; 把一個 " 放在字串裡
MessageBox MB_OK `And he said to me "I'll be happy!"` ; 這裡把 ' 和 " 都放到了字串裡
MessageBox MB_OK "$\"A quote from a wise man$\" said the wise man" ; 這裡演示了跳過引號的解析

要在字串裡使用回車、換行、Tab 等，請使用 $\r, $\n, $\t 等。 更多資訊...

變數

變數以 $ 開頭。使用者變數應該 (不是必須) 事先被宣告並且區分大小寫。

Var MYVAR

StrCpy $MYVAR "變數值"

更多的資訊...

長命令

要把命令擴充為多行，需要在行尾使用反斜槓 (\) ，下一行會被自動連線到上一行的尾部。例如:

CreateShortCut "$SMPROGRAMS\NSIS\ZIP2EXE project workspace.lnk" \
    "$INSTDIR\source\zip2exe\zip2exe.dsw"

MessageBox MB_YESNO|MB_ICONQUESTION \
    "是否要刪除資料夾中的所有檔案? \
    (如果你想保留任何你自己建立的檔案 \
     請點選[否])" \
    IDNO NoRemoveLabel

長命令多行擴充同樣適用於註釋，它可能會讓人混淆，因此應該儘量避免。

# 一個註釋\
    在這裡仍然是註釋...

4.2 變數

所有的變數都是全域性的並且可以用於區段和函式。需要注意的是，在預設情況下變數被限制在 1024 位元組。要擴大這個限制你需要使用一個更大 NSIS_MAX_STRLEN 值並重新 構建 NSIS 或者使用 特別版本。

4.2.1 使用者變數

$VARNAME

使用者變數可以用 Var 命令來宣告。你可以使用這些變數來儲存值，用於字串操作等等。

4.2.1.1 Var

[/GLOBAL] 變數名

宣告一個使用者變數。變數名允許的字元: [a-z][A-Z][0-9] 和 '_'。 所有定義的變數都是全域性的，即使在區段或函式內定義。 要使它表達更清楚一些，區段或函式內定義的變數必須使用 /GLOBAL 標記。在區段和函式之外不需要 /GLOBAL 標記。

Var example

Function testVar
  Var /GLOBAL example2

  StrCpy $example "example value"
  StrCpy $example2 "another example value"
FunctionEnd

4.2.2 其他可寫的變數

$0, $1, $2, $3, $4, $5, $6, $7, $8, $9, $R0, $R1, $R2, $R3, $R4, $R5, $R6, $R7, $R8, $R9

暫存器。這些變數可以像使用者變數一樣使用，但常用於公用函式或巨集。你不需要宣告這些變數，所以當你在公用程式碼裡使用他們的時候不能有任何名字衝突。當在公用程式碼裡使用這些變數的時候，推薦你使用堆疊儲存和恢復他們原來的資料。這些變數也可以在外掛裡傳遞，因為他們可以被 DLL 外掛讀取和寫入。

$INSTDIR

安裝目錄 ($INSTDIR 可以使用 StrCpy、 ReadRegStr、 ReadINIStr 等等來更改。例如在 .onInit 函式裡可以用來做高階的檢測安裝定位)。

注意在解除安裝程式程式碼裡，$INSTDIR 為解除安裝程式所在的目錄而不是在安裝程式裡所指定的目錄。例如， 如果你把解除安裝程式放在 $WINDIR 裡並且使用者沒有移動它，那麼在解除安裝程式裡 $INSTDIR 就等於 $WINDIR。如果你要把解除安裝程式放到另外的位置，那麼你應該先把安裝程式的 $INSTDIR 值寫入登錄檔或者其它容易儲存的地方，然後在解除安裝程式裡讀取該值並賦值給解除安裝程式裡的 $INSTDIR。

$OUTDIR

當前輸出目錄 (通過 SetOutPath 或者通過 StrCpy、 ReadRegStr、 ReadINIStr 等等)

$CMDLINE

安裝程式命令列。命令列的格式可以是下列之一:

• "完整路徑\安裝程式.exe" 引數1 引數2 引數3
• 安裝程式.exe 引數1 引數2 引數3
• 對於解析“引數”部分，參閱 GetParameters。如果在命令列裡指定了 /D= (用來跳過安裝路徑的選擇)，那麼 /D= 後面的引數將不會被儲存在 $CMDLINE (前面的可以儲存)。

$LANGUAGE

當前使用的語言識別符號。例如，英語是 1033。你可以在 .onInit 裡更改此變數。

4.2.3 常量

常量通常用在 InstallDir 屬性裡。

需要注意的是一些新的常量並不是在所有的 OS 上都是正常的。例如, $CDBURN_AREA 僅在 Windows XP 及以上系統中才正常。 如果在 Windows 98 中使用,將會得到空值。除非特別提示，否則該常量都是在所有 OS 上有效的。

$PROGRAMFILES, $PROGRAMFILES32, $PROGRAMFILES64

程式檔案目錄 (通常為 C:\Program Files 但在執行時會檢測)。在 Windows x64 作業系統中, $PROGRAMFILES 和 $PROGRAMFILES32 指向C:\Program Files (x86) 同時 $PROGRAMFILES64 指向 C:\Program Files。當安裝 64 位應用程式時，使用 $PROGRAMFILES64。

$COMMONFILES, $COMMONFILES32, $COMMONFILES64

公用檔案目錄。這是應用程式共享元件的目錄 (通常為 C:\Program Files\Common Files 但在執行時會檢測)。在 Windows x64 作業系統中, $COMMONFILES 和 $COMMONFILES32 指向 C:\Program Files (x86)\Common Files 同時 $COMMONFILES64 指向 C:\Program Files\Common Files。當安裝 64 位應用程式時，使用 $COMMONFILES64。

$DESKTOP

Windows 桌面目錄 (通常為 C:\Windows\Desktop 但在執行時會檢測)。該常量的內容 (所有使用者或者當前使用者) 取決於 SetShellVarContext 設定。 預設為當前使用者。

$EXEDIR

可執行安裝程式執行時所在目錄 (從技術上來說你可以修改改變數，但並不是一個好方法)。

$EXEFILE

可執行安裝程式的基本名字。

$EXEPATH

可執行安裝程式的完整路徑。

${NSISDIR}

包含 NSIS 安裝目錄的符號定義標記。常用於在你想呼叫在 NSIS 目錄下的資源時。圖示、介面等等。

在 Windows 平臺等於 makensis 所在的目錄,而在其它平臺則在編譯時決定 (資訊請看 INSTALL 檔案)。你可以在編譯前通過修改 NSISDIR 環境變數來改變預設的設定。更多資訊請看 section 3.1.3。

$WINDIR

Windows 目錄 (通常為 C:\Windows 或者 C:\WinNT 但在執行時會檢測)。

$SYSDIR

Windows 系統目錄 (通常為 C:\Windows\System or C:\WinNT\System32 但在執行時會檢測)。

$TEMP

系統臨時目錄 (通常為 C:\Windows\Temp 但在執行時會檢測)。

$STARTMENU

開始選單目錄 (常用於新增一個開始選單項，使用 CreateShortCut)。該常量的內容 (所有使用者或者當前使用者) 取決於 SetShellVarContext 設定。預設為當前使用者。

$SMPROGRAMS

開始選單程式目錄 (當你想定位 $STARTMENU\程式 時可以使用它)。該常量的內容 (所有使用者或者當前使用者) 取決於 SetShellVarContext 設定。預設為當前使用者。

$SMSTARTUP

開始選單程式/啟動 目錄。該常量的內容 (所有使用者或者當前使用者) 取決於 SetShellVarContext 設定。預設為當前使用者。

$QUICKLAUNCH

在 IE4 活動桌面及以上的快速啟動目錄。如果快速啟動不可用，僅僅返回和 $TEMP 一樣。

$DOCUMENTS

文件目錄。一個當前使用者典型的路徑形如 C:\Documents and Settings\Foo\My Documents。該常量的內容 (所有使用者或者當前使用者) 取決於 SetShellVarContext 設定。預設為當前使用者。

該常量在 Windows 95 且 Internet Explorer 4 沒有安裝時無效。

$SENDTO

該目錄包含了“傳送到”選單快捷項。

$RECENT

該目錄包含了指向使用者最近文件的快捷方式。

$FAVORITES

該目錄包含了指向使用者網路收藏夾、文件等的快捷方式。該常量的內容 (所有使用者或者當前使用者) 取決於 SetShellVarContext 設定。預設為當前使用者。

該常量在 Windows 95 且 Internet Explorer 4 沒有安裝時無效。

$MUSIC

使用者的音樂檔案目錄。該常量的內容 (所有使用者或者當前使用者) 取決於 SetShellVarContext 設定。預設為當前使用者。

該常量僅在 Windows XP, ME 及以上有效。

$PICTURES

使用者的圖片檔案目錄。該常量的內容 (所有使用者或者當前使用者) 取決於 SetShellVarContext 設定。 預設為當前使用者。

該常量僅在 Windows 2000, XP, ME 及以上有效。

$VIDEOS

使用者的視訊檔案目錄。該常量的內容 (所有使用者或者當前使用者) 取決於 SetShellVarContext 設定。 預設為當前使用者。

該常量僅在 Windows XP, ME 及以上有效。

$NETHOOD

該目錄包含了可能存在於我的網路位置、網路上的芳鄰資料夾的連結物件。

該常量在 Windows 95 且 Internet Explorer 4 和活動桌面沒有安裝時無效。

$FONTS

系統字型目錄。

$TEMPLATES

文件模板目錄。該常量的內容 (所有使用者或者當前使用者) 取決於 SetShellVarContext 設定。 預設為當前使用者。

$APPDATA

應用程式資料目錄。當前使用者路徑的檢測需要 Internet Explorer 4 及以上。所有使用者路徑的檢測需要 Internet Explorer 5 及以上。該常量的內容 (所有使用者或者當前使用者) 取決於 SetShellVarContext 設定。 預設為當前使用者。

該常量在 Windows 95 且 Internet Explorer 4 和活動桌面沒有安裝時無效。

$LOCALAPPDATA

本機應用程式資料目錄。

該常量僅在 Windows 2000 及以上有效。

$PRINTHOOD

該目錄包含了可能存在於印表機資料夾的連結物件。

該常量在 Windows 95 和 Windows 98 上無效。

$INTERNET_CACHE

Internet Explorer 的臨時檔案目錄。

該常量在 Windows 95 和 Windows NT 且 Internet Explorer 4 和活動桌面沒有安裝時無效。

$COOKIES

Internet Explorer 的 Cookies 目錄。

該常量在 Windows 95 和 Windows NT 且 Internet Explorer 4 和活動桌面沒有安裝時無效。

$HISTORY

Internet Explorer 的歷史記錄目錄。

該常量在 Windows 95 和 Windows NT 且 Internet Explorer 4 和活動桌面沒有安裝時無效。

$PROFILE

使用者的個人配置目錄。一個典型的路徑如 C:\Documents and Settings\Foo。

該常量僅在 Windows 2000 及以上有效。

$ADMINTOOLS

一個儲存管理工具的目錄。該常量的內容 (所有使用者或者當前使用者) 取決於 SetShellVarContext 設定。 預設為當前使用者。

該常量僅在 Windows 2000, ME 及以上有效。

$RESOURCES

本地的資源目錄儲存了主題和其他 Windows 資源 (通常為 C:\Windows\Resources 但在執行時會檢測)。

該常量僅在 Windows XP 及以上有效。

$RESOURCES_LOCALIZED

本地的資源目錄儲存了主題和其他 Windows 資源 (通常為 C:\Windows\Resources\1033 但在執行時會檢測)。

該常量僅在 Windows XP 及以上有效。

$CDBURN_AREA

一個在燒錄 CD 時儲存檔案的目錄。

該常量僅在 Windows XP 及以上有效。

$HWNDPARENT

父視窗的十進位制視窗控制代碼。

$PLUGINSDIR

該路徑是一個臨時目錄，當第一次使用一個外掛或一個呼叫 InitPluginsDir 時被建立。該資料夾當安裝程式退出時會被自動刪除。 這個資料夾的用意是用來儲存給 InstallOptions 使用的 INI 檔案、啟動畫面點陣圖或其他外掛執行需要的檔案。

4.2.4 在字串裡使用常量

$$

轉義，用來表示 $。

$\r

用來表示一個回車 (\r)。

$\n

用來表示新的一行 (\n)。

$\t

用來表示一個 Tab (\t)。

4.3 標記

標記是 Goto 指令的目標，或各種分支指令 (例如 IfErrors、 MessageBox、 IfFileExists, 和 StrCmp) 的目標。標記必須存在於一個區段或函式裡。標記是侷限於該範圍裡的，這意味著這些指令只能訪問和它們同處於一個區段或函式的標記。 要宣告一個標記很簡單:

MyLabel:

標記不能以 -, +, !, $, 或 0-9開頭。 當給多個需要指定標記的指令指定了標記，不要忘了使用空字串 ("") 或 0 來表示下一個指令(表示無 Goto 跳轉)。一個標記以句點 (.) 開頭時表示這是一個全域性的標記，你可以從任何區段或函式直接跳轉到它上面(但是你不能從一個安裝程式跳轉到一個解除安裝程式的全域性標記，反之亦然)。

4.4 相對跳轉

和標記不一樣，相對跳轉就如其名一樣，相對於被呼叫的地方。在任何你可用到標記的地方你也都可以相對跳轉。相對跳轉由數字標定。+1 跳轉到下一條指令(預設的步進)，+2 會跳過一條指令也並且從當前指令轉到第二條指令，-2 將往後跳兩條指令，+10 將會跳過 9 條指令，從當前指令跳到第十條指令。

一條指令就是在安裝程式執行時可以被執行的所有命令。 MessageBox、 Goto、 GetDLLVersion、 FileRead、 SetShellVarContext 都是指令。 AddSize、 Section、 SectionGroup、 SectionEnd、 SetOverwrite (和所有處於編譯器標記)、 Name、 SetFont、 LangString 都不是指令，因為它們在編譯時就被執行。

例子:

 Goto +2
   MessageBox MB_OK "你將看不到這個訊息框"
 MessageBox MB_OK "上一條資訊被略過，這條資訊才會被顯示"

 Goto +4
 MessageBox MB_OK "隨後的這條資訊將會被略過"
 Goto +3
 MessageBox MB_OK "你將不會看到這個訊息框"
 Goto -3
 MessageBox MB_OK "完成"

需要注意的是 巨集指令 並不是真正意義上的一條指令，在編譯時會被展開為若干條指令，所以你不能用相對跳轉來跳過一條巨集指令。下面的示例演示了相對跳轉並沒有真正跳過插入的巨集 (僅僅是跳過了巨集裡的第一條指令)，還是會顯示一個訊息框。

!macro relative_jump_test
  MessageBox MB_OK "第一個巨集行first macro line"
  MessageBox MB_OK "第二個巨集行second macro line"
!macroend

Goto +2
!insertmacro relative_jump_test

4.5 頁面

每個(非靜默安裝) NSIS 安裝程式都有一個頁面設定。每個頁面可以是一個 NSIS 內建頁面或者一個由使用者函式(檢視 nsDialogs 或 InstallOptions 例項)建立的自定義頁面。

使用指令碼你可以控制這些頁面的次序, 外觀, 作用。你可以跳過頁面, 顏色繪為白色, 強制使用者停留在某個頁面直到特定條件成立, 顯示一個自述檔案頁面, 給輸入顯示一個自定義頁面或者更多的功能。在本節中，你將學會如何控制上述提到的功能。

關於頁面有兩個基本的命令， Page 和 UninstPage。前一個為新增一個頁面到安裝程式，後一個為新增一個頁面到解除安裝程式。在他們兩個命令的前面你可以用 PageEx 命令給他們新增一個頁面且包括一些選項。 PageEx 可以使你給新增的指定頁面設定選項而不是使用 PageEx 之外設定的預設設定。

4.5.1 次序關係

頁面的次序由 Page, UninstPage 和 PageEx 出現在腳本里的次序決定。例如:

 Page license
 Page components
 Page directory
 Page instfiles
 UninstPage uninstConfirm
 UninstPage instfiles

該程式碼告訴 NSIS 第一個顯示的是許可頁面，然後是元件選擇頁面，然後是目錄選擇頁面，最後是區段被執行的安裝記錄頁面，就像老式的安裝程式那樣。解除安裝程式將首先顯示解除安裝確認頁面然後是解除安裝執行記錄。

你可以把同一個頁面型別多次指定。

由於需要向下相容舊 NSIS 指令碼，如果沒有使用到安裝程式頁面命令，那麼隨後的這些安裝程式頁面將會被新增: 許可 (如果指定了 LicenseText 和 LicenseData), 元件選擇 (如果指定了 ComponentText 並且有一個以上非隱藏的區段), directory (如果指定了 DirText) 和安裝記錄。當沒有使用到解除安裝程式頁面命令，那麼隨後的解除安裝程式頁面將會被新增:解除安裝確認頁面 (如果指定了 UninstallText) 和解除安裝記錄。不推薦這種方法，強烈推薦的是把指令碼轉換為使用頁面命令，因為你可以使用新的標準語言字串。

4.5.2 頁面選項

每個頁面都有它自己唯一的資料設定來定義外觀和作用。這一段敘述了每種頁面使用的資料和怎麼樣來設定。 回撥函式 將在下節中說明而本節中處理。

下面的這個列表列出了某個頁面型別受什麼樣的命令影響。除非特別提及，否則這些命令都可以在 PageEx 區塊內外使用。如果在一個 PageEx 區塊內部使用那麼他們僅僅對由 PageEx 設定的當前頁面產生影響，否則他們將被設為其他所有頁面的預設值。

許可頁面

• LicenseText
• LicenseData
• LicenseForceSelection

元件選擇頁面

• ComponentText

目錄選擇頁面

• DirText
• DirVar - 僅能在 PageEx 裡使用
• DirVerify

解除安裝、安裝記錄頁面

• DetailsButtonText
• CompletedText

解除安裝確認頁面

• DirVar - 僅能在 PageEx 裡使用
• UninstallText

要設定頁面標題請使用 Caption 。

4.5.3 回撥

每個內建的頁面都有三個回撥函式: 一個預置函式,一個顯示建立函式和一個離開函式。預置函式在頁面被建立之前被直接的呼叫，顯示函式在頁面被建立後且在顯示之前被直接呼叫，離開函式在使用者按下下一頁按鈕之後並且在頁面離開之前被直接呼叫。

• 預置函式允許你使用 Abort 來跳過該頁面。
• 顯示函式允許你使用 CreateFont, SetCtlColors, SendMessage 和其他來調整頁面的使用者介面。
• 離開函式允許你使用 Abort 來強制使用者停留在當前頁面。

一個自定義的頁面僅有兩個回撥函式，一個是必須的建立頁面，另一個離開函式的作用就和內建頁面的離開函式一樣。

例項:

 Page license skipLicense "" stayInLicense
 Page custom customPage "" ": 自定義頁面"
 Page instfiles

 Function skipLicense
   MessageBox MB_YESNO "你想跳過許可頁面嗎？" IDNO no
     Abort
   no:
 FunctionEnd

 Function stayInLicense
   MessageBox MB_YESNO "你想停留在許可頁面嗎？" IDNO no
     Abort
   no:
 FunctionEnd

 Function customPage
   GetTempFileName $R0
   File /oname=$R0 customPage.ini
   InstallOptions::dialog $R0
   Pop $R1
   StrCmp $R1 "cancel" done
   StrCmp $R1 "back" done
   StrCmp $R1 "success" done
   error: MessageBox MB_OK|MB_ICONSTOP "InstallOptions 錯誤:$\r$\n$R1"
   done:
 FunctionEnd

4.5.4 Page

custom [建立函式] [離開函式] [標題] [/ENABLECANCEL]
  或
internal_page_type [預置函式] [顯示函式] [離開函式] [/ENABLECANCEL]

要新增一個安裝程式頁面，見上述章節，瞭解更多關於相對於自定義頁面的內建頁面和回撥函式資訊。

內建的頁面型別:

• license - 許可協議頁面
• components - 元件選擇頁面
• directory - 安裝目錄選擇頁面
• instfiles - 安裝執行頁面
• uninstConfirm - 解除安裝確認頁面

最後一個頁面的取消按鈕會被禁用來防止混亂。要允許這種行為請使用 /ENABLECANCEL 。

4.5.5 UninstPage

custom [建立函式] [離開函式] [標題] [/ENABLECANCEL]
  或
internal_page_type [預置函式] [顯示函式] [離開函式] [/ENABLECANCEL]

要新增一個解除安裝程式頁面，見上述章節，瞭解更多關於相對於自定義頁面的內建頁面和回撥函式資訊。

內建的頁面型別 請參考 Page 。

4.5.6 PageEx

[un.](custom|uninstConfirm|license|components|directory|instfiles)

新增一個安裝程式頁面或一個解除安裝程式頁面(如果使用了 un. 字首)。每一個 PageEx 必須和 PageExEnd 配合使用。在一個 PageEx 區塊你可以對這個頁面進行特殊的設定，這些設定不會被其他頁面使用。沒有被設定的選項將使用 PageEx 外部區塊的的設定或者當什麼都沒有指定時使用預設設定。要對頁面設定子標題使用 Caption 或 SubCaption 。要對一個使用 PageEx 的頁面設定回撥函式請使用 PageCallbacks。 見上述章節，瞭解更多關於相對於自定義頁面的內建頁面的資訊。

使用例項:

 PageEx license
   LicenseText "自述檔案"
   LicenseData readme.rtf
 PageExEnd

 PageEx license
   LicenseData license.txt
   LicenseForceSelection checkbox
 PageExEnd

4.5.7 PageExEnd

結束一個 PageEx 區塊。

4.5.8 PageCallbacks

([建立函式] [離開函式]) | ([預置函式] [顯示函式] [離開函式])

對一個使用 PageEx 定義的頁面設定回撥函式。僅能在 PageEx 區塊裡使用。見上述章節，瞭解更多關於回撥函式資訊。

PageEx license
  PageCallbacks licensePre licenseShow licenseLeave
PageExEnd

4.6 區段

每一個 NSIS 安裝程式包含一個或多個區段。所有的這些區段都使用下面的這些命令來建立、修改和結束。

• 每一個區段包含零個或多個指令。
• 區段是安裝程式執行的實體，並且如果設定了 ComponentText ，那麼使用者就可以選擇禁止或允許每一個可見的區段。
• 如果一個區段名為 'Uninstall' 或以 'un.' 為字首，那麼它就是一個解除安裝程式區段。

4.6.1 區段命令

4.6.1.1 AddSize

大小(單位為:KB)

告訴安裝程式當前的區段需要一個額外的 "大小" KB 磁碟空間。僅在一個區段裡有效(在區段外或函式裡無效)。

Section
AddSize 500
SectionEnd

相關推薦