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 :

Starting from Haxe 3.0 , you can get the list of supported compiler flags by running haxe --help-defines

General

  • check-xml-proxy : lists unused fields of haxe.xml.Proxy
  • dump : creates a /dump directory 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) (macrotimes in 2.10-)
  • use-rtti-doc : enables macros to access field documentation / comments
  • absolute-path : PosInfos used by trace and others will contain the absolute file path

Flash specific

  • no-swf-compress : disables SWF output compression
  • haxe-boot : forces the SWF boot class to be named haxe instead of boot_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 swf
  • native-trace : writes trace output to flashlog.txt instead of to a textfield in the swf (was nativeTrace in 2.10-)
  • network-sandbox : uses the network sandbox flag for SWF output
  • swf-protected : by default the compiler turns all private fields public in SWF output. This flag will keep them protected instead.
    (Haxe private == AS3 protected)
  • as3-native : Instead of compiling all members in the external swf as public, this preserves their original protected and private namespace. (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 r5429
  • swf-script-timeout : Maximum script processing time before script stuck dialog box displays. (in seconds) Since SVN r5624
  • swf-preloader-frame : Insert empty first frame in swf. To be used together with -D flash-use-stage and -swf-lib. (example) Since SVN r5624
  • swf-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 r5685
  • swf-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 r5664
  • swf-gpu : Uses GPU compositing features when drawing graphics, where such acceleration is available. Since SVN r5662
  • swf-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 .neko source 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.

Starting from Haxe 3.0 , you can get the list of supported compiler flags by running haxe --help-metas

General metadata


  • @:require(xxx) : will only allow access to the given field if the xxx compiler 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 the xxx var 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 as final to 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 given Type. The compiler will not use enum switch for these, but instead uses the classic switch. The Type can be used by the code generator backend to know the actual field type (in general either String or Int)
  • @:macro and @: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 :

  • @:expose or @:expose("name") : this class will be available from the window object (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 without extern is already present in a SWF library, an error will be displayed. You can use @:bind before 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 the x property. Please note that the method returnGetX no 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) (was nodebug in 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"
  • @:classCode("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
version #19833, modified 2013-11-26 06:40:11 by AndyLi