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, die das Skriptverhalten steuern

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 nicht-kompilierten Skript
;@Ahk2Exe-IgnoreBegin
MsgBox Diese Meldung erscheint NICHT im kompilierten Skript
;@Ahk2Exe-IgnoreEnd
MsgBox Diese Meldung erscheint sowohl im kompilierten als auch nicht-kompilierten 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 nicht-kompilierten 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 nicht-kompilierten Skript innerhalb eines Kommentarblocks befindet.

Direktiven, die die Metadaten der EXE-Datei beeinflussen

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.

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 zurückgegebenen Wert 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 , Ressourcenname
Dateiname
Dateiname der Ressource, die hinzugefügt werden soll. 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.
Ressourcenname
(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: 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'

Bin

Spezifiziert die binäre Version von AutoHotkey, die in der generierten EXE-Datei enthalten sein soll. (Dies überschreibt alles, was in der GUI oder CLI angegeben ist.) 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-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
[Pfad\]Name
Die zu verwendende BIN-Datei. Wenn keine Dateiendung angegeben ist, wird .bin vermutet. Für Name kann auch ein Platzhaltermuster verwendet werden; zum Beispiel ANSI*, Unicode 32*, Unicode 64*, oder *bit für alle drei. Wenn kein Pfad angegeben ist, werden die Standard-BIN-Dateien im Compiler-Ordner durchgegangen. Der Compiler wird für jede übereinstimmende BIN-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 Meldungsfenster 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 Bin-Direktive.)

;@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_-Präfix).
Wert
Der zu verwendende Wert.

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_-Präfix), 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 = davor gesetzt 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.

;@Ahk2Exe-PostExec Programm [Parameter] , Bedingung
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:

Beispiel 1: (Um diese 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.

SetMainIcon

Überschreibt das EXE-Symbol, welches für die Kompilierung verwendet wird. (Um die anderen Symbole zu ändern, werfen Sie einen Blick auf das AddResource-Beispiel.)

;@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.
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).