Script Compiler (Ahk2Exe) Directives [v1.1.??+]

Note: This file is depreciated! The updated documentation is now in the standard AutoHotkey.chm help file.

The script compiler accepts certain directives that allow further customisation the compiled script (.exe).
All compiler directives are introduced by the string @Ahk2Exe-, preceded by the comment flag.

Directives that control the script behaviour

It is possible to remove code sections from the compiled script by wrapping them in directives:

MsgBox This message appears in both the compiled and uncompiled script
;@Ahk2Exe-IgnoreBegin
MsgBox This message does NOT appear in the compiled script
;@Ahk2Exe-IgnoreEnd
MsgBox This message appears in both the compiled and uncompiled script

The reverse is also possible, i.e. marking a code section to only be executed in the compiled script:

/*@Ahk2Exe-Keep
MsgBox This message appears only in the compiled script
*/
MsgBox This message appears in both the compiled and uncompiled script

This has advantage over A_IsCompiled because the code is completely removed from the compiled script during preprocessing, thus making the compiled script smaller. The reverse is also true: it will not be necessary to check for A_IsCompiled because the code is inside a comment block in the uncompiled script.

Directives that control executable metadata

In the parameters of these directives, the following escape sequences are supported: ``, `,, `n, `r and `t. Commas always need to be escaped, regardless of the parameter position. "Integer" refers to unsigned 16-bit integers (0..0xFFFF).

If required, directive parameters can reference the following list of standard built-in variables by enclosing the variable name with % signs:-

Group 1: A_AhkPath, A_AppData, A_AppDataCommon, A_ComputerName, A_ComSpec, A_Desktop, A_DesktopCommon, A_MyDocuments, A_ProgramFiles, A_Programs, A_ProgramsCommon, A_ScriptDir, A_ScriptFullPath, A_ScriptName, A_Space, A_StartMenu, A_StartMenuCommon, A_Startup, A_StartupCommon, A_Tab, A_Temp, A_UserName, A_WinDir.

Group 2: A_AhkVersion, A_IsCompiled, A_IsUnicode, A_PtrSize.

In addition to these variable names, the special variable A_WorkFileName holds the temporary name of the processed .exe file. This can be used to pass the file name as a parameter to any PostExec directives which need to access the generated .exe.

Also, the special variable A_PriorLine contains the source line immediately preceding the current compiler directive. Intervening lines of blanks and comments only are ignored, as are any intervening compiler directive lines. This variable can be used to 'pluck' constant information from the script source, and use it in later compiler directives. An example would be accessing the version number of the script, which may be changed often. Accessing the version number in this way means that it needs to be changed only once in the source code, and the change will get copied through to the necessary directive. (See the example below for more information.)

As well, special user variables can be created with the format U_Name using the Let directive, described below.

In addition to being available for directive parameters, all variables can be accessed from any RT_MENU, RT_DIALOG, RT_STRING, RT_ACCELERATORS, RT_HTML, and RT_MANIFEST file supplied to the AddResource directive, below.

If needed, the value returned from the above variables can be manipulated by including at the end of the built-in variable name before the ending %, up to 2 parameters (called p2 and p3) all separated by tilde ~. The p2 and p3 parameters will be used as literals in the 2nd and 3rd parameters of a RegExReplace function to manipulate the value returned. (See RegEx Quick Reference.) Note that p3 is optional.

To include a tilde as data in p2 or p3, preceded it with a back-tick, i.e. `~.
To include a back-tick character as data in p2 or p3, double it, i.e. ``.

• %A_ScriptName~\.[^\.]+$~.exe% replaces the extension plus preceding full-stop, with .exe in the actual script name.
  (\.[^\.]+$~.exe means scan for a . followed by 1 or more non-. characters followed by end-of-string, and replace them with .exe)


• Assume there is a source line followed by two compiler directives as follows:
  CodeVersion := "1.2.3.4", company := "My Company"
;@Ahk2Exe-Let version = %A_PriorLine~U)^(.+"){1}(.+)".*$~$2%
;@Ahk2Exe-Let company = %A_PriorLine~U)^(.+"){3}(.+)".*$~$2%
  These directives copy the version number 1.2.3.4 into the special variable U_version, and the company name My Company into the special variable U_company for use in other directives later.
  (The {1} in the first regex was changed to {3} in the second regex to select after the third " to extract the company name.)

;@Ahk2Exe-AddResource FileName [, ResourceName]

;@Ahk2Exe-Bin [Path\]Name [, [Exe_path\][Name] , Codepage]

;@Ahk2Exe-ConsoleApp

;@Ahk2Exe-Cont Text

;@Ahk2Exe-Debug Text

;@Ahk2Exe-ExeName [Path\][Name]

;@Ahk2Exe-Let Name = Value [, Name = Value [, ...]]

;@Ahk2Exe-Obey Name, CmdOrExp [, Extra]

;@Ahk2Exe-PostExec Program [parameters]

;@Ahk2Exe-SetMainIcon [IcoFile]

;@Ahk2Exe-SetProp Value

;@Ahk2Exe-Set Prop, Value

;@Ahk2Exe-UpdateManifest RequireAdmin [, Name, Version]

;@Ahk2Exe-UseResourceLang LangCode