Skriptcompilerdirektiven

Inhaltsverzeichnis

Einführung

Skriptcompilerdirektiven ermöglichen es dem Benutzer, genau festzulegen, wie ein Skript mit Ahk2Exe kompiliert werden soll. Einige der Features sind:

Der Skriptcompiler sucht nach speziellen Kommentaren im Quellskript und erkennt diese als Compilerdirektiven. Alle Compilerdirektiven werden durch die Zeichenkette @Ahk2Exe- mit vorangestellter Kommentarmarkierung (standardmäßig ;) eingeleitet.

Direktiven für das Skriptverhalten

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

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

Der umgekehrte Weg ist auch möglich, d.h. es kann ein Codeabschnitt markiert werden, 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 im 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 dasselbe: A_IsCompiled muss nicht geprüft werden, 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, wobei der Variablenname mit %-Zeichen umschlossen werden muss:

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_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 Variable kann verwendet werden, um den Dateinamen als Parameter an eine PostExec-Direktive zu übergeben, die auf die erzeugte EXE-Datei zugreifen muss.

Außerdem enthält die Spezialvariable A_BasePath den vollständigen Pfad und Namen der ausgewählten Basisdatei.

Weiterhin gibt es die Spezialvariable A_PriorLine, die die Quellcodezeile enthält, die unmittelbar vor der aktuellen Compilerdirektive steht. Dazwischenliegende Leerzeilen, Kommentare und Compilerdirektiven werden ignoriert. Mit dieser Variable können konstante Informationen aus dem Quelltext des Skripts extrahiert werden, um sie später in den Compilerdirektiven zu verwenden. Zum Beispiel kann damit auf die Versionsnummer des Skripts zugegriffen werden, die häufig 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 an die entsprechende Direktive weitergeleitet. (Weitere Informationen finden Sie im RegEx-Beispiel unten.)

Darüber hinaus können spezielle Benutzervariablen im Format U_Name mit den unten beschriebenen 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 AddResource-Direktive (siehe unten) übergeben wurde.

Falls erforderlich, kann der Rückgabewert der obigen Variablen manipuliert werden, indem am Ende des Namens der internen Variable, vor dem abschließenden %, bis zu 2 Parameter (genannt p2 und p3) eingefügt werden, jeweils getrennt durch ein Tildezeichen (~). Die Parameter p2 und p3 werden als Literale 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 eine Ressource zur kompilierten EXE-Datei 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 (oder relativ zum) Arbeitsverzeichnis des Skripts vermutet. Der Typ der Ressource (als Integer oder Zeichenkette) kann explizit durch ein vorangestelltes Sternchen angegeben werden: *Typ Dateiname. Wenn weggelassen, erkennt Ahk2Exe den Typ automatisch anhand der Dateiendung.
RessourceName
(Optional) Der Name, den die Ressource haben wird (kann eine Zeichenkette oder ein Integer sein). Wenn weggelassen, wird standardmäßig der Dateiname (ohne Pfad) in Großbuchstaben verwendet.

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

Beispiel 1: Standardsymbole ersetzen (außer 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: Ein weiteres Skript als separate RCDATA-Ressource inkludieren (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

Gibt die Basisversion von AutoHotkey an, die zur Erzeugung der EXE-Datei verwendet 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 Top-Level-Skriptdatei (also nicht in einer #Include-Datei). 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 Kommentarmarkierung ein Leerzeichen ein.)

;@Ahk2Exe-Bin  [Pfad\]Name , [EXE_Pfad\][Name], Codepage ; Veraltet
;@Ahk2Exe-Base [Pfad\]Name , [EXE_Pfad\][Name], Codepage
[Pfad\]Name
Die zu verwendende BIN- oder EXE-Datei. Wenn keine Dateiendung angegeben ist, wird .bin vermutet. Wenn kein absoluter Pfad angegeben ist, wird die Datei im (oder relativ zum) Arbeitsverzeichnis des Compilers vermutet. Für Name kann auch ein Platzhaltermuster verwendet werden, z.B. ANSI*, Unicode 32*, Unicode 64*, oder *bit für alle drei. Der Compiler wird für jede gefundene BIN- oder EXE-Datei ausgeführt. Es dürfen nur die internen Variablen aus der ersten Gruppe oben 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. Es dürfen nur die internen Variablen aus der ersten Gruppe oben verwendet werden. (Dieser Parameter kann mit der ExeName-Direktive überschrieben werden.)
Codepage
(Optional) Überschreibt die Standard-Codepage, mit der die Skriptdateien verarbeitet werden. (Skripte sollten mit einer Byte-Order-Markierung (BOM) beginnen, was die Verwendung dieses Parameters überflüssig macht.)

ConsoleApp

Schaltet das Subsystem der EXE-Datei in den Konsolenmodus.

;@Ahk2Exe-ConsoleApp

Cont

Gibt eine Fortsetzungszeile für die vorherige Direktive an. Dies ermöglicht es, eine langzeilige Direktive im Quellcode besser lesbar zu machen.

;@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. Fügen Sie Spezialvariablen zwischen %-Zeichen ein, um ihren (manipulierten) Inhalt zu sehen.

ExeName

Gibt den Speicherort und Namen der erzeugten EXE-Datei an. (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 mit %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 vorangestelltem U_).
Wert
Der zu verwendende Wert.

Nop

Bewirkt nichts.

;@Ahk2Exe-Nop Text
Text
(Optional) Beliebiger Text, der ignoriert wird.
Beispiel:
Ver := A_AhkVersion "" ; Wenn das in Anführungszeichen gesetzte 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 Ergebnis in U_Name gespeichert wird.

;@Ahk2Exe-Obey Name, BefehlOderAusdruck , Extra
Name
Der Name der Variable (mit oder ohne vorangestelltem U_), 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 = vorangestellt 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 z.B. 2 ist, werden die Ergebnisse in U_name, U_name1 und U_name2 gespeichert. Der Wert in jedem name muss zuerst durch den Ausdruck oder Befehl gesetzt werden.

PostExec

Gibt ein Programm an, das nach einer erfolgreichen Kompilierung ausgeführt werden soll, bevor (oder nachdem) eine Komprimierung der EXE-Datei erfolgt. Diese Direktive kann mehrfach angegeben werden und wird in der vom Compiler gesehenen Reihenfolge ausgeführt, gemäß der durch den Bedingung-Parameter definierten Warteschlange.

;@Ahk2Exe-PostExec Programm [Parameter] , Bedingung, ArbeitVerz, Versteckt, FehlerIgnorieren
Programm [Parameter]
Das Programm, das ausgeführt werden soll, inklusive Parameter. Um den Zugriff auf die verarbeitete EXE-Datei zu ermöglichen, geben Sie die Spezialvariable A_WorkFileName als Parameter in Anführungszeichen 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% angegebene Eingabedatei zurückschieben. (Beachten Sie, dass die EXE-Datei Binärdaten enthalten wird.)
Bedingung

(Optional) Lassen Sie diesen Parameter leer, wenn das Programm vor einer Komprimierung ausgeführt werden soll. Andernfalls geben Sie eine der folgenden Zahlen an, um das Programm nach einer bestimmten Komprimierung auszuführen:

ArbeitVerz
(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. Wenn weggelassen, wird standardmäßig das Verzeichnis des Compilers (Ahk2Exe) verwendet.
Versteckt
(Optional) Wenn auf 1 gesetzt, wird das Programm versteckt gestartet.
FehlerIgnorieren
(Optional) Wenn auf 1 gesetzt, werden Fehler während des Programmstarts oder der Programmausführung nicht an den Benutzer gemeldet.

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

Mit diesem Beispiel können alle Verweise auf "AutoHotkey" aus der erzeugten EXE-Datei entfernt werden, 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, sodass 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 BinMod.ahk-Skript.)

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

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

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 angegeben ist, das mit der 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. Wenn weggelassen, 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 abgearbeitet werden, unabhängig von der Reihenfolge, in der sie angegeben sind.

;@Ahk2Exe-SetEigenschaft Wert
Eigenschaft

Der Name der Eigenschaft, die geändert werden soll. Muss einer der unten aufgeführten sein.

Eigenschaft Beschreibung
CompanyName Ändert den Firmennamen.
Copyright Ändert die rechtlichen Copyright-Informationen.
Description Ändert die Dateibeschreibung. In Windows 8 und höher ändert dies auch den Namen des Skripts im Task-Manager unter "Prozesse".
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 Hexadezimalzahlen das Präfix 0x haben müssen.
LegalTrademarks Ändert die rechtlichen Informationen zum Markenzeichen.
Name Ändert den Produktnamen und den internen Namen.
OrigFilename Ändert die Informationen zum originalen Dateinamen.
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 durch Punkte getrennten Zahlen (bis zu vier), die am Anfang des Versionstextes stehen können. Ungefüllte Felder werden auf Null gesetzt. Zum Beispiel bewirkt 1.3-Alpha, dass die binäre Versionsnummer 1.3.0.0 erzeugt wird. 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 abgearbeitet werden, unabhängig von der Reihenfolge, in der sie angegeben sind. Diese Direktive ist nur für spezielle Anwendungsfälle gedacht.

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

UpdateManifest

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

;@Ahk2Exe-UpdateManifest BenötigtAdmin , Name, Version, UIAccess
BenötigtAdmin
Setzen Sie diesen Parameter auf 1, wenn die EXE-Datei nur mit administrativen Rechten ausgeführt werden soll. Setzen Sie ihn auf 2, wenn die EXE-Datei nur mit den höchsten verfügbaren Rechten ausgeführt werden soll. Setzen Sie ihn auf 0, um nichts zu verändern.
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 positionsabhängig und beeinflusst alle nachfolgenden AddResource-Direktiven.

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