Skript-Compiler-Direktiven [v1.1.33+]

Inhaltsverzeichnis

Einführung

Skript-Compiler-Direktiven ermöglichen es dem Benutzer, genaue Angaben darüber zu machen, wie ein Skript via Ahk2Exe kompiliert werden soll. Einige der Features sind:

Der Skript-Compiler sucht nach speziellen Kommentaren im Quelltext-Skript und erkennt diese als Compiler-Direktiven. Alle Compiler-Direktiven müssen mit der Zeichenkette @Ahk2Exe- beginnen und als Kommentar gekennzeichnet werden (üblicherweise via ;).

Direktiven für das Skriptverhalten

Es ist möglich, Codeabschnitte aus dem kompilierten Skript zu entfernen. Setzen Sie vor und nach dem betroffenen Codeabschnitt die folgenden Direktiven:

MsgBox Diese Meldung erscheint sowohl im kompilierten als auch unkompilierten Skript
;@Ahk2Exe-IgnoreBegin
MsgBox Diese Meldung erscheint NICHT im kompilierten Skript
;@Ahk2Exe-IgnoreEnd
MsgBox Diese Meldung erscheint sowohl im kompilierten als auch unkompilierten Skript

Der umgekehrte Weg ist auch möglich; man kann einen Codeabschnitt markieren, der nur im kompilierten Skript ausgeführt werden soll:

/*@Ahk2Exe-Keep
MsgBox Diese Meldung erscheint nur im kompilierten Skript
*/
MsgBox Diese Meldung erscheint sowohl im kompilierten als auch unkompilierten Skript

Dies hat gegenüber A_IsCompiled den Vorteil, dass der Code während der Präprozessierung vollständig aus dem kompilierten Skript entfernt und folglich dessen Größe verringert wird. Umgekehrt gilt das Gleiche: Es ist nicht notwendig, A_IsCompiled zu prüfen, da sich der Code im unkompilierten Skript innerhalb eines Kommentarblocks befindet.

Direktiven für die Metadaten der EXE-Datei

Einführung

In den Parametern dieser Direktiven werden die folgenden Escapesequenzen unterstützt: ``, `,, `n, `r und `t. Kommas müssen immer mit einem Escapezeichen versehen werden, unabhängig von der Position des Parameters. "Integer" bezieht sich auf vorzeichenlose 16-Bit-Integer (0..0xFFFF).

Falls erforderlich, können Direktivenparameter auf die folgenden internen Variablen verweisen, indem man den Variablennamen mit %-Zeichen umschließt:

Gruppe 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.

Gruppe 2: A_AhkVersion, A_IsCompiled, A_IsUnicode, A_PtrSize.

Zusätzlich zu diesen Variablennamen gibt es noch die Spezialvariable A_WorkFileName, die den temporären Namen der gerade verwendeten EXE-Datei enthält. Diese kann genutzt werden, um den Dateinamen als Parameter an eine PostExec-Direktive zu übergeben, die auf die generierte EXE-Datei zugreifen muss.

[v1.1.34.04b+] Außerdem enthält die Spezialvariable A_BasePath den vollständigen Pfad und Namen der ausgewählten Basisdatei.

Des Weiteren gibt es die Spezialvariable A_PriorLine, die die Quellcodezeile enthält, die unmittelbar vor der aktuellen Compiler-Direktive steht. Dazwischenliegende leere Zeilen und Kommentaren werden ignoriert, ebenso wie alle Compiler-Direktiven-Zeilen. Diese Variable kann genutzt werden, um konstante Informationen aus dem Quelltext des Skripts "herauszupicken" und sie in späteren Compiler-Direktiven zu verwenden. Zum Beispiel könnten Sie damit auf die Versionsnummer des Skripts zugreifen, welche oft geändert wird. Diese Art des Zugriffs hat den Vorteil, dass die Versionsnummer nur einmal im Quellcode geändert werden muss - die Änderung wird dann zur entsprechenden Direktive weitergeleitet. (Weitere Informationen finden Sie im RegEx-Beispiel unten.)

Darüber hinaus können spezielle Benutzervariablen im Format U_Name mit den unten genannten Let- und Obey-Direktiven erstellt werden.

Sämtliche Variablen stehen nicht nur für Direktivenparameter zur Verfügung, sondern können auch von jeder RT_MENU-, RT_DIALOG-, RT_STRING-, RT_ACCELERATORS-, RT_HTML- und RT_MANIFEST-Datei aus abgerufen werden, die der unten genannten AddResource-Direktive übergeben wurde.

Falls erforderlich, kann der Rückgabewert von den oben genannten Variablen manipuliert werden, indem man am Ende des Namens der internen Variable, vor dem Endzeichen %, bis zu 2 Parameter (genannt p2 und p3) einfügt, die alle mit einem Tildezeichen (~) voneinander getrennt sind. Die Parameter p2 und p3 werden als direkt geschriebener Text im zweiten und dritten Parameter einer RegExReplace-Funktion verwendet, um den Rückgabewert zu manipulieren. (Siehe RegEx-Kurzübersicht.) Beachten Sie, dass p3 optional ist.

Um ein Tildezeichen als Teil des Textes in p2 oder p3 einzufügen, setzen Sie ein umgekehrtes Häkchen davor, also `~. Um ein umgekehrtes Häkchen als Teil des Textes in p2 oder p3 einzufügen, verdoppeln Sie es, also ``.

RegEx-Beispiele:

Weitere Beispiele: Weitere funktionierende Beispiele, die heruntergeladen und untersucht werden können, finden Sie hier.

AddResource

Fügt der kompilierten EXE-Datei eine Ressource hinzu. (Siehe auch UseResourceLang)

;@Ahk2Exe-AddResource DateiName , RessourceName
DateiName
Dateiname der Ressource, die hinzugefügt werden soll. Wenn kein absoluter Pfad angegeben ist, wird die Datei im Arbeitsverzeichnis des Skripts vermutet (bzw. ist relativ zu diesem Verzeichnis). Der Typ der Ressource (als Integer oder Zeichenkette) kann durch Voranstellen eines Sternchens explizit angegeben werden: *Typ Dateiname. Lässt man dies weg, wird Ahk2Exe den Typ automatisch anhand der Dateiendung erkennen.
RessourceName
(Optional) Der Name, den die Ressource haben wird (kann eine Zeichenkette oder ein Integer sein). Lässt man diesen Parameter weg, wird standardmäßig der Name der Datei (ohne Pfad) verwendet - alles in Großbuchstaben.

Hier eine Liste mit gängigen Ressourcentypen und den Dateiendungen, die diese standardmäßig auslösen.

Beispiel 1: Die Standardsymbole ersetzen (außer das Hauptsymbol):

;@Ahk2Exe-AddResource Icon1.ico, 160  ; Ersetzt 'H auf Blau'
;@Ahk2Exe-AddResource Icon2.ico, 206  ; Ersetzt 'S auf Grün'
;@Ahk2Exe-AddResource Icon3.ico, 207  ; Ersetzt 'H auf Rot'
;@Ahk2Exe-AddResource Icon4.ico, 208  ; Ersetzt 'S auf Rot'

Beispiel 2: [v1.1.34+] Ein anderes Skript als separate RCDATA-Ressource einbinden (siehe Eingebettete Skripte):

;@Ahk2Exe-AddResource MeinSkript1.ahk, #2
;@Ahk2Exe-AddResource MeinSkript2.ahk, MEINERESSOURCE

Beachten Sie, dass jedes Skript, das mit dieser Direktive hinzugefügt wird, vollständig und separat vom Compiler verarbeitet wird und weitere Direktiven enthalten kann. Wenn es konkurrierende Direktiven gibt, wird die zuletzt vom Compiler gefundene verwendet.

Bin / Base [v1.1.33.10+]

Spezifiziert die Basisversion von AutoHotkey, die zum Generieren der EXE-Datei genutzt werden soll. Diese Direktive kann mit einem in der GUI oder CLI angegebenen Basisdateiparameter überschrieben werden. Diese Direktive kann bei Bedarf mehrfach angegeben werden, allerdings nur in einer Skriptdatei, die nicht via #Include eingebunden wird. Der Compiler wird mindestens einmal für jede gefundene Bin/Base-Direktive ausgeführt. (Wenn dieser Direktive aktuell ein Kommentar angehängt ist, muss dieser die  ;-Markierung verwenden. Um diese Direktive tatsächlich auszukommentieren, fügen Sie nach der ersten Kommentar-Markierung ein Leerzeichen ein.)

;@Ahk2Exe-Bin  [Pfad\]Name , [EXE_Pfad\][Name], Zeichensatz ; Veraltet
;@Ahk2Exe-Base [Pfad\]Name , [EXE_Pfad\][Name], Zeichensatz ; [v1.1.33.10+]
[Pfad\]Name
Die BIN- oder in [v1.1.33.10+] die EXE-Datei, die verwendet werden soll. Wenn keine Dateiendung angegeben ist, wird .bin vermutet. Wenn kein absoluter Pfad angegeben ist, wird die Datei im Arbeitsverzeichnis des Compilers vermutet (bzw. ist relativ zu diesem Verzeichnis). Für Name kann auch ein Platzhaltermuster verwendet werden; zum Beispiel ANSI*, Unicode 32*, Unicode 64*, oder *bit für alle drei. Der Compiler wird für jede übereinstimmende BIN- oder EXE-Datei ausgeführt. Es dürfen nur die internen Variablen der oben genannten Gruppe 1 verwendet werden.
[EXE_Pfad\][Name]
(Optional) Der Dateiname für die EXE-Datei. Jede angegebene Dateiendung wird mit .exe ersetzt. Wenn kein Pfad angegeben ist, wird die EXE-Datei im Ordner des Skripts erstellt. Wenn kein Name angegeben ist, bekommt die EXE-Datei den Standardnamen zugewiesen. (Dieser Parameter kann mit der ExeName-Direktive überschrieben werden.)
Zeichensatz
(Optional) Überschreibt den Standard-Zeichensatz, mit dem die Skript-Dateien verarbeitet werden. (Skripte sollten mit einer Byte-Order-Markierung (BOM) beginnen, was die Verwendung dieses Parameters überflüssig macht.)

ConsoleApp

Wechselt das Subsystem der EXE-Datei in den Konsolenmodus.

;@Ahk2Exe-ConsoleApp

Cont

Spezifiziert eine Fortsetzungszeile für die vorherige Direktive. Dies ermöglicht es, eine langzeilige Direktive so zu gestalten, dass sie im Quellcode gut lesbar ist.

;@Ahk2Exe-Cont Text
Text
Der Text, der an die vorherige Direktivenzeile angehängt werden soll, bevor diese Zeile verarbeitet wird. Der Text beginnt nach dem einzelnen Leerzeichen hinter dem Cont-Schlüsselwort.

Debug

Zeigt ein Mitteilungsfenster mit dem angegebenen Text an (für Debugging-Zwecke gedacht).

;@Ahk2Exe-Debug Text
Text
Ein Text, der angezeigt werden soll. Umschließen Sie jede Spezialvariable mit %-Zeichen, um ihren (manipulierten) Inhalt zu sehen.

ExeName

Spezifiziert den Standort und Namen für die generierte EXE-Datei. (Siehe auch Base-Direktive.) Diese Direktive kann mit einer in der GUI oder CLI angegebenen Ausgabedatei überschrieben werden.

;@Ahk2Exe-ExeName [Pfad\][Name]
[Pfad\][Name]
Der Name der EXE-Datei. Jede angegebene Dateiendung wird mit .exe ersetzt. Wenn kein Pfad angegeben ist, wird die EXE-Datei im Ordner des Skripts erstellt. Wenn kein Name angegeben ist, bekommt die EXE-Datei den Standardnamen zugewiesen.
Beispiel:
;@Ahk2Exe-Obey U_bits, = %A_PtrSize% * 8
;@Ahk2Exe-Obey U_type, = "%A_IsUnicode%" ? "Unicode" : "ANSI"
;@Ahk2Exe-ExeName %A_ScriptName~\.[^\.]+$%_%U_type%_%U_bits%

Let

Erstellt (oder modifiziert) eine oder mehrere Benutzervariablen, auf die via %U_Name% zugegriffen werden kann, ähnlich wie bei den internen Variablen (siehe oben).

;@Ahk2Exe-Let Name = Wert , Name = Wert, ...
Name
Der Name der Variable (mit oder ohne U_ am Anfang).
Wert
Der zu verwendende Wert.

Nop [v1.1.34.03c+]

Bewirkt nichts.

;@Ahk2Exe-Nop Text
Text
(Optional) Beliebiger Text, der ignoriert wird.
Beispiel:
Ver := A_AhkVersion "" ; Wenn angegebenes Literal nicht leer ist, tue 'SetVersion'
;@Ahk2Exe-Obey U_V, = "%A_PriorLine~U)^(.+")(.*)".*$~$2%" ? "SetVersion" : "Nop"
;@Ahk2Exe-%U_V%        %A_AhkVersion%%A_PriorLine~U)^(.+")(.*)".*$~$2%

Obey

Führt isolierte AutoHotkey-Befehle oder Ausdrücke aus, deren Ergebnisse in U_Name gespeichert werden müssen.

;@Ahk2Exe-Obey Name, BefehlOderAusdruck , Extra
Name
Der Name der Variable (mit oder ohne U_ am Anfang), in der das Ergebnis gespeichert werden soll.
BefehlOderAusdruck

Ein Befehl oder Ausdruck, der ausgeführt werden soll.

Bei Befehlen muss Name als Ausgabevariable angegeben werden (häufig der erste Parameter), z. B.

;@Ahk2Exe-Obey U_date, FormatTime U_date`, R D2 T2

Bei Ausdrücken muss = davorgesetzt werden, z. B.

;@Ahk2Exe-Obey U_type, = "%A_IsUnicode%" ? "Unicode" : "ANSI"

Ausdrücke können im Befehlsformat geschrieben werden, z. B.

;@Ahk2Exe-Obey U_bits, U_bits := %A_PtrSize% * 8

Falls erforderlich, trennen Sie mehrere Befehle und Ausdrücke mit `n.

Extra
(Optional) Eine Zahl (1-9), die die Anzahl der zusätzlichen Ergebnisse angibt, die zurückgegeben werden sollen. Wenn Extra beispielsweise 2 ist, werden die Ergebnisse in U_name, U_name1 und U_name2 gespeichert. Der Wert in jedem name muss zuerst vom Ausdruck oder Befehl gesetzt werden.

PostExec

Spezifiziert ein Programm, das nach einer erfolgreichen Kompilierung ausgeführt werden soll, bevor (oder nachdem) eine Komprimierung der EXE-Datei erfolgt. Diese Direktive kann mehrmals vorkommen und wird in der vom Compiler gesehenen Reihenfolge ausgeführt, entsprechend der durch den When-Parameter festgelegten Warteschlange.

;@Ahk2Exe-PostExec Programm [Parameter] , Bedingung, ArbeitVerz, Versteckt, FehlerIgnorieren
Programm [Parameter]
Ein Programm, das ausgeführt werden soll, inklusive einem oder mehr Parameter. Um den Zugriff auf die verarbeitete EXE-Datei zu ermöglichen, geben Sie die Spezialvariable A_WorkFileName als in Anführungszeichen gesetzten Parameter an, z. B. "%A_WorkFileName%". Wenn das Programm die EXE-Datei ändert, muss das Programm die geänderte EXE-Datei in die via %A_WorkFileName% spezifizierte Eingabedatei zurückschieben. (Beachten Sie, dass die EXE-Datei binäre Daten enthalten wird.)
Bedingung

(Optional) Lassen Sie diesen Parameter weg, um das Programm vor einer Komprimierung ausführen zu lassen. Ansonsten können Sie eine der folgenden Zahlen angeben, um das Programm nach einer bestimmten Komprimierung ausführen zu lassen:

ArbeitVerz [v1.1.33.03+]
(Optional) Das Arbeitsverzeichnis, in dem das Programm gestartet werden soll. Umschließen Sie den Namen nicht mit doppelten Anführungszeichen, selbst wenn er Leerzeichen enthält. Lässt man diesen Parameter weg, wird standardmäßig das Verzeichnis des Compilers (Ahk2Exe) verwendet.
Versteckt [v1.1.33.03+]
(Optional) Wenn dieser Parameter auf 1 gesetzt ist, wird das Programm versteckt gestartet.
FehlerIgnorieren [v1.1.33.03+]
(Optional) Wenn dieser Parameter auf 1 gesetzt ist, werden Fehler, die während des Starts oder der Ausführung des Programms auftreten, nicht dem Benutzer gemeldet.

Beispiel 1: (Um die ersten beiden Beispiele zu verwenden, laden Sie zunächst BinMod.ahk herunter und kompilieren Sie es gemäß den Anweisungen des heruntergeladenen Skripts.)

Dieses Beispiel kann verwendet werden, um jegliche Referenzen zu "AutoHotkey" aus der generierten EXE-Datei zu entfernen, um zu verschleiern, dass es sich um ein kompiliertes AutoHotkey-Skript handelt:

;@Ahk2Exe-Obey U_au, = "%A_IsUnicode%" ? 2 : 1    ; Skript ANSI oder Unicode?
;@Ahk2Exe-PostExec "BinMod.exe" "%A_WorkFileName%"
;@Ahk2Exe-Cont  "%U_au%2.>AUTOHOTKEY SCRIPT<. DATA              "

Beispiel 2: Dieses Beispiel ändert eine UPX-komprimierte EXE-Datei derart, dass sie nicht mehr mit UPX -d dekomprimiert werden kann:

;@Ahk2Exe-PostExec "BinMod.exe" "%A_WorkFileName%"
;@Ahk2Exe-Cont  "11.UPX." "1.UPX!.", 2

(Weitere Beispiele finden Sie im Skript BinMod.ahk selbst.)

Beispiel 3: Dieses Beispiel spezifiziert die Komprimierung, die für ein kompiliertes Skript verwendet werden soll, wenn in der CLI oder GUI keine angegeben ist. Es werden die Standardparameter angezeigt, die der Compiler normalerweise verwendet.

Für MPRESS:

;@Ahk2Exe-PostExec "MPRESS.exe" "%A_WorkFileName%" -q -x, 0,, 1

Für UPX:

;@Ahk2Exe-PostExec "UPX.exe" "%A_WorkFileName%"
;@Ahk2Exe-Cont  -q --all-methods --compress-icons=0, 0,, 1

ResourceID [v1.1.34+]

Weist eine untypische Ressourcen-ID zu, die für das Hauptskript bei Kompilierungen verwendet wird, die eine EXE-Basisdatei verwenden (siehe Eingebettete Skripte). Diese Direktive kann mit einer in der GUI oder CLI angegebenen Ressourcen-ID überschrieben werden. Diese Direktive wird ignoriert, wenn sie in einem Skript vorkommt, das über die AddResource-Direktive eingefügt wurde.

;@Ahk2Exe-ResourceID Name
Name
Die zu verwendende Ressourcen-ID. Numerische Ressourcen-IDs müssen aus einem Rautezeichen (#), gefolgt von einer Dezimalzahl, bestehen.

SetMainIcon

Überschreibt das EXE-Symbol, welches für die Kompilierung verwendet wird. (Um die anderen Symbole zu ändern, siehe AddResource-Beispiel.) Diese Direktive kann mit einer in der GUI oder CLI angegebenen Symboldatei überschrieben werden. Das neue Symbol ist möglicherweise nicht sofort im Windows Explorer sichtbar, wenn die kompilierte Datei zuvor mit einem anderen Symbol vorhanden war. Das neue Symbol kann jedoch durch Auswählen von Refresh Windows Icons im File-Menü von Ahk2Exe angezeigt werden.

;@Ahk2Exe-SetMainIcon Symboldatei
Symboldatei
(Optional) Die zu verwendende Symboldatei. Lässt man diesen Parameter weg, wird das Standardsymbol von AutoHotkey verwendet.

SetEigenschaft

Ändert eine Eigenschaft in den Versionsinformationen der kompilierten EXE-Datei. Beachten Sie, dass alle Eigenschaften in alphabetischer Reihenfolge verarbeitet werden, unabhängig von der Reihenfolge, in der sie angegeben sind.

;@Ahk2Exe-SetEigenschaft Wert
Eigenschaft

Der Name einer Eigenschaft, die geändert werden soll. Muss eine der unten genannten sein.

Eigenschaft Beschreibung
CompanyName Ändert den Firmennamen.
Copyright Ändert die rechtlichen Copyright-Informationen.
Description Ändert die Dateibeschreibung. In Windows 8 und höher wird dadurch auch der Name des Skripts im Task-Manager unter "Prozesse" geändert.
FileVersion Ändert die Dateiversion, sowohl im Text- als auch Binärformat. (Einzelheiten finden Sie unter Version weiter unten.)
InternalName Ändert den internen Namen.
Language Ändert den Sprachcode. Bitte beachten Sie, dass hexadezimale Zahlen das Präfix 0x haben müssen.
LegalTrademarks Ändert die rechtlichen Informationen bezüglich des Markenzeichens.
Name Ändert den Produktnamen und den internen Namen.
OrigFilename Ändert die Informationen bezüglich des originalen Dateinamens.
ProductName Ändert den Produktnamen.
ProductVersion Ändert die Produktversion, sowohl im Text- als auch Binärformat. (Einzelheiten finden Sie unter Version weiter unten.)
Version

Ändert die Dateiversion und die Produktversion, sowohl im Text- als auch Binärformat.

Ahk2Exe füllt die binären Versionsfelder mit den via Punkte getrennten Zahlen (bis zu vier), die am Anfang des Versionstextes stehen können. Ungefüllte Felder werden auf Null gesetzt. 1.3-Alpha beispielsweise würde die binäre Versionsnummer 1.3.0.0 erzeugen. Wenn diese Eigenschaft nicht geändert wird, wird standardmäßig die AutoHotkey-Version verwendet, die zum Kompilieren des Skripts verwendet wurde.

Wert
Der Wert, auf den die Eigenschaft gesetzt werden soll.

Set

Ändert Eigenschaften in den Versionsinformationen der kompilierten EXE-Datei, die nicht von der SetEigenschaft-Direktive abgedeckt werden. Beachten Sie, dass alle Eigenschaften in alphabetischer Reihenfolge verarbeitet werden, unabhängig von der Reihenfolge, in der sie angegeben sind. Diese Direktive ist nur für besondere Anwendungsfälle gedacht.

;@Ahk2Exe-Set Eigenschaft, Wert
Eigenschaft
Der Name einer Eigenschaft, die geändert werden soll.
Wert
Der Wert, auf den die Eigenschaft gesetzt werden soll.

UpdateManifest

Ändert Einzelheiten im Manifest der EXE-Datei. Diese Direktive ist nur für besondere Anwendungsfälle gedacht.

;@Ahk2Exe-UpdateManifest BenötigtAdmin , Name, Version, UIAccess
BenötigtAdmin
Setzen Sie diesen Parameter auf 1, um die EXE-Datei nur mit administrativen Rechten ausführen zu lassen. Setzen Sie ihn auf 2, um die EXE-Datei nur mit den höchsten verfügbaren Rechten ausführen zu lassen. Setzen Sie ihn auf 0, um ihn unverändert zu lassen.
Name
(Optional) Ein Name, der im Manifest gesetzt werden soll.
Version
(Optional) Eine Version, die im Manifest gesetzt werden soll.
UIAccess
(Optional) Setzen Sie diesen Parameter auf 1, um UIAccess im Manifest zu aktivieren.

UseResourceLang

Ändert die Ressourcensprache, welche von AddResource verwendet wird. Diese Direktive ist von der Position abhängig und beeinflusst alle nachfolgenden AddResource-Direktiven.

;@Ahk2Exe-UseResourceLang Sprachcode
Sprachcode
Der Sprachcode. Bitte beachten Sie, dass hexadezimale Zahlen das Präfix 0x haben müssen. Die Standard-Ressourcensprache ist US English (0x0409).