Tips and Tricks

You are viewing an old version of this entry, click here to see latest version.

This is a collection of small things that you can tweak in the language or compiler flags in order to get specific behavior.

Compiler Flags

You can define a flag with -D flagname commandline parameter. Some flags produce an additional effect :

  • check-xml-proxy : tells at the end of compilation which fields of the haxe.xml.Proxy are not used
  • dump : will create a /dump directory containing the dumped Haxe typed AST (for compiler debugging purposes or curious hackers)
  • macrotimes : print per-macro execution time results (to use together with --times)
  • use_rtti_doc : enable 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 : disable SWF output compression
  • haxe-boot : force the SWF boot class to be named haxe instead of boot_XXXX (automatic for SWC output)
  • fdb : include the Debugger tag in SWF output and extra debug infos (enable interactive debugging of Flash content)
  • network-sandbox : use 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.
    (AS3 protected == Haxe private)
  • nativeTrace : writes trace output to flashlog.txt instead of to a textfield in the swf

CPP specific

  • no-compilation : generates Haxe/CPP code but does not compile it.

JavaScript specific

  • noEmbedJS : disable automatic-embedding of JS files in standard library (so far used by both js.SWFObject and js.JQuery)

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 get generated at runtime. Instead, it might be use by the Haxe compiler internals to perform specific tasks. Here's a list of used metadata compiler identifiers :

  • @:require(xxx) : will only allow to access 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.
  • @:final : the given class cannot be subclassed anymore
  • @:hack : allow to subclass a class that was marked as final (use at your own risks)
  • @: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 make it more easy to bind "extern" classes that might have a different name.
  • @:core_api : identify 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 Haxe compiler that this enum is just a collection of properties of given Type. In that case the compiler will not use enum switch for these, but instead classic switch. The Type can be used by the code generator backend to know 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)
  • @:overload : see below
  • @:extern static inline function foo() { ... } : this function will always be inlined but will not be generated as part of the resulting code new in 2.09
  • @:feature("value") : attributed to fields that are required for specific features, such as typed casts or reflection. new in nightly builds

JavaScript Specific

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 new in nightly builds
  • @:defineFeature : will set a feature when typed (even if inlined) new in nightly builds

Flash Specific

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") 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
  • @: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; new in nightly builds )
  • @: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) new in 2.09
  • @:nodebug function foo() { .... } : disable debug information for this method (even when compiled with -debug) new in 2.09

CPP Specific

In order to improve support for interacting with CPP, the following compiler metadata are available from the latest HXCPP repository and Haxe repository all new in 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 : ...

Overload

The @:overload metadata can be used when interfacing an external class method which arguments being of different types. You can declare the method in the following way :

@:overload(function(i:String):Bool{})
function foo( i : Int ) : Void;

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.

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 #15122, modified 2012-07-20 00:35:31 by jan_flanders