Tips and Tricks
You can use compiler flags or compiler metadata to tweak the language or to get specific behavior.
Compiler Flags
You can define your own flag with the -D flagname commandline parameter for conditional compilation.
The following list describes some predefined flags :
haxe --help-defines
General
check-xml-proxy: lists unused fields ofhaxe.xml.Proxydump: creates a/dumpdirectory containing the dumped Haxe typed AST (for compiler debugging purposes or curious hackers)macro-times: prints per-macro execution time results (to use together with--times) (macrotimesin 2.10-)use-rtti-doc: enables macros to access field documentation / commentsabsolute-path: PosInfos used by trace and others will contain the absolute file path
Flash specific
no-swf-compress: disables SWF output compressionhaxe-boot: forces the SWF boot class to be namedhaxeinstead ofboot_XXXX(automatic for SWC output)fdb: enables interactive debugging of Flash content. It includes the Debugger tag in the output SWF and adds extra debug infos . This also redirects trace ouput to flashlog.txt instead of to a textfield in the swfnative-trace: writes trace output to flashlog.txt instead of to a textfield in the swf (wasnativeTracein 2.10-)network-sandbox: uses the network sandbox flag for SWF outputswf-protected: by default the compiler turns allprivatefieldspublicin SWF output. This flag will keep themprotectedinstead.
(Haxe private == AS3 protected)as3-native: Instead of compiling all members in the external swf aspublic, this preserves their originalprotectedandprivatenamespace. (used together with-swf-lib) removed in 3.0- flash-use-stage : To be used together with -swf-lib. Place objects found on the stage of the SWF lib. (Not to be used together with -swf-header)
advanced-telemetry: adds Scout (aka Monocle) support Since SVN r5429swf-script-timeout: Maximum script processing time before script stuck dialog box displays. (in seconds) Since SVN r5624swf-preloader-frame: Insert empty first frame in swf. To be used together with -D flash-use-stage and -swf-lib. (example) Since SVN r5624swf-debug-password=yourPassword: Used together with -D fb. The password field is encrypted by using the MD5 algorithm and prevents unauthorised debugging of your swf. Without this flag -D fdb will use no password. Since SVN r5685swf-metadata=data.xml: Embeds XML metadata in the SWF file so that, for example, a search engine can locate this data
, access a title for the SWF file, and display that title in search results. Flash Player itself always ignores the metadata.
The format of the metadata is RDF that is compliant with Adobe’s Extensible Metadata Platform (XMP™) specification. For more information about RDF and XMP, see RDF primer, RDF syntax and XMP Since SVN r5664swf-gpu: Uses GPU compositing features when drawing graphics, where such acceleration is available. Since SVN r5662swf-directblit: Uses hardware acceleration to blit graphics to the screen, where such acceleration is available.. Since SVN r5663
Note: swf-gpu and swf-directblit are relevant only when a SWF file is playing in the standalone Flash Player.
When a SWF file plays in a web browser plug-in, swf-directblit is equivalent to specifying a wmode of “direct” in the tags that embed the SWF inside the HTML page, while swf-gpu is equivalent to a wmode of “gpu”. Minimum swf-version for both is 10.
CPP specific
no-compilation: generates Haxe/CPP code but does not compile it.
Java specific
no-compilation: generates Haxe/Java code but does not compile it.
C# specific
no-compilation: generates Haxe/C# code but does not compile it.no_root: all top-level classes will be compiled into the haxe.root namespace, in order to avoid the issue of duplicate class definitions between the haxe built-in classes (Array, List, etc.) and .NET definitions.- "real_position" : disables source mapping since Haxe 3.0 RC2
JavaScript specific
embed-js: automatic-embedding of JS files in standard library (so far used by both js.SWFObject and js.JQuery) since 3.0- [deprecated]
noEmbedJS: disables automatic-embedding of JS files in standard library (so far used by both js.SWFObject and js.JQuery) Since 2.10-
Neko Specific
neko-source: generates.nekosource but does not compile it to.n
Compiler Metadata
If a metadata identifier starts with :, then the corresponding metadata will not be generated at runtime. Instead, it might be used by the Haxe compiler internals to perform specific tasks. Here's a list of used metadata compiler identifiers :
General metadata
@:require(xxx): will only allow access to the given field if thexxxcompiler condition variable is set (for instance with-D xxx). Can also be set on a whole class, in that case the class can still be referenced but all its statics and its constructor accesses are forbidden if thexxxvar is not set. You can also specify a custom error message with @:require(xxx,"Requires XXX")@:final: the given class cannot be subclassed anymore@:hack: allows a class marked asfinalto be subclassed (use at your own risk)@:native("my.real.Path"): the given class (and all its accesses) will be compiled as if its real class path was the one given in parameter. This makes it more easy to bind "extern" classes that might have a different name.@:coreApi: identifies this class as a "core api class". Its API will get checked against the abstract one declared in the Haxe standard library.@:fakeEnum(Type): tells the Haxe compiler that this enum is just a collection of properties of the givenType. The compiler will not use enum switch for these, but instead uses the classic switch. TheTypecan be used by the code generator backend to know the actual field type (in general either String or Int)@:macroand@:build, see Macros@:keep: the given class or field will be preserved in the generated output even if never directly referenced. Use it in conjunction with --dead-code-elimination.@:keepSub: extends @:keep to all child classes (which can be ideal for e.g. a common base class of a unit testing framework). Use it in conjunction with --dead-code-elimination.@:overload: can be used when interfacing an external class method with arguments of different types. You can have several overload declarations, the return type of the first one that is matched will be used. Overload metadata is only useful for extern classes, it is most likely not usable for user-written Haxe classes. A simple example:@:overload(function(i:String):Bool{}) function foo( i : Int ) : Void;
@:extern static inline function foo() { ... }: this function will always be inlined but will not be generated as part of the resulting code. (since 2.09)@:optional: declares optional fields in typedefs. (since 2.09)@:feature("value"): attributed to fields that are required for specific features, such as typed casts or reflection. (since 2.10)@:noCompletion: does not list the field as part of compiler completion results (since 3.0)@:noUsing: don't allow this static field to be used as part of the "using" mixin (since 3.0)@:allow(my.pack): This will give access to all private fields of a class to all the classes in the package my.pack (and its sub-packages). See Access Control for more info. (since 3.0)@:access(my.pack.MyClass): Used together with an external library or other code which for some reason you can't modify to add the necessary @:allow declarations. See Access Control for more info. (since 3.0)@:generic: To be used instead of 'implements haxe.rtti.Generic' to declare generic classes. (since 3.0)@:publicFields: To be used instead of 'implements haxe.Public', which changes the default fields' visibility from private to public. This also applies to sub classes. (since 3.0)
JavaScript Specific metadata
In order to improve support for interacting with JavaScript, the following compiler metadata are available for the JavaScript platform only :
@:exposeor@:expose("name"): this class will be available from thewindowobject (since 2.10)@:defineFeature: will set a feature when typed (even if inlined) (since 2.10)@:runtime: ... (since 2.10)@:initPackage: ...
Flash Specific metadata
In order to improve support for interacting with AS3 and Flash IDE, the following compiler metadata are available for Flash9+ platform only :
@:bind: when a class declared in Haxe withoutexternis already present in a SWF library, an error will be displayed. You can use@:bindbefore your class declaration to have it override the original SWF class declaration.@:bitmap("myfile.png|jpg|gif") class MyBitmapData extends flash.display.BitmapData {}: include a given bitmap file into the target SWF and associate it to MyBitmapData class. The file is looked-up using the classpath. use with `new MyBitmapData(0,0)`@:file("a.dat") class MyByteArray extends flash.utils.ByteArray: include a given binary file into the target SWF and associate it to MyByteArray class@:font("path.ttf", range="") class MyFont extends flash.text.Font: embed the specified TrueType font into the swf. The second argument can be used limit the range of embedded characters, e.g. to"a-z0-9{}HW"(since 3.0)@:sound("file.wav|mp3") class MySound extends flash.media.Sound: include a given sound file into the target SWF and associate it to MySound class@:ns("namespace"): the specified field or method will be given this namespace@:protected: the specified field or method is marked as protected (used when overriding protected methods for instance)@:getter(x) function returnGetX() return 5: will generate a native getter on thexproperty. Please note that the methodreturnGetXno longer exists, so do not call it directly. This feature is mainly used to override superclass getters.
(To expose the x property to the rest of your haxe code, add @:extern public var x(default,never) : Int; (since 2.10)@:setter(x) function setX( v : Float ) : Void { ... }: same as@:getter, but for setting the property.@:meta(Event(name="test",type="Foo")): generates the corresponding Flash metadata@:debug function foo() { .... }: force debug information to be generated for this method (even when compiled without-debug) (since 2.09)@:noDebug function foo() { .... }: disable debug information for this method or the whole class (even when compiled with-debug) (wasnodebugin 2.10-)
CPP Specific metadata
In order to improve support for interacting with CPP, the following compiler metadata are available from the latest HXCPP repository and Haxe repository (all since 2.09) :
@:headerCode("#include <stdio.h>"): Inject code into class header file - eg for types of injected members.@:headerClassCode("code"): Inject code into header class definition - eg member variables/functions.@:cppFileCode("code"): Inject code into top of cpp file - eg local includes, local functions, static variables.@:functionCode("code"): Inject code into top of function - eg, whole implementation.@:functionTailCode("code"): Inject code into end of function - eg, close functionCode, or continue processing.@:buildXml("xml fragment"): Inject code into the bottom of the build.xml code.@:cppNamespaceCode("code"): ...@:headerNamespaceCode("code"): ...@:noStack: ...@:depend("code"): Add a dependency in the build.xml file.@:include("ClassName"): Generate "#include ..." to .h/.cpp where the class is being imported.
Java Specific metadata
In order to improve interaction with native Java code, there were created some java-specific metadata:
@:protected: the specified field or method is marked as protected (used when overriding protected methods for instance)@:internal: the specified field or method is marked as internal (used when overriding protected methods for instance)@:final: the specified field or method is marked as final@:volatile: the specified field or method is marked as volatile@:transient: the specified field or method is marked as transient@:functionBody("Code"): will replace the contents of the target function with "code"@:classContents("Code"): Inject "code" to the contents of the class
Undocumented metadata
Metadata the compiler accepts, but do not have any documentation.
@:remove: Works in JavaScript target. Classes and Interfaces marked with this meta data will not generate any output.
TODO: Needs confirmation!
Character Code
You can use the .code property on a constant single-char string in order to compile its ASCII character code :
"#".code // will compile as 35