Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
283 lines (233 sloc) 16.4 KB
\chapter{Compiler Usage}
\label{compiler-usage}
\paragraph{Basic Usage}
The Haxe Compiler is typically invoked from command line with several arguments which have to answer two questions:
\begin{itemize}
\item What should be compiled?
\item What should the output be?
\end{itemize}
To answer the first question, it is usually sufficient to provide a class path via the \ic{-cp path} argument, along with the main class to be compiled via the \ic{-main dot_path} argument. The Haxe Compiler then resolves the main class file and begins compilation.
The second question usually comes down to providing an argument specifying the desired target. Each Haxe target has a dedicated command line switch, such as \ic{-js file_name} for JavaScript and \ic{-php directory} for PHP. Depending on the nature of the target, the argument value is either a file name (for \ic{-js}, \ic{-swf} and \ic{neko}) or a directory path.
\paragraph{Common arguments}
\emph{Input:}
\begin{description}
\item[\ic{-cp path}] Adds a class path where \ic{.hx} source files or packages (sub-directories) can be found.
\item[\ic{-lib library_name}] Adds a \Fullref{haxelib} library. By default the most recent version in the local Haxelib repository is used. To require a specific library version use \ic{-lib library_name:version}. To require a version from git use \ic{-lib library_name:git:https://github.com/user/project.git\#commit} where the optional \#commit can be a branch, tag or commit hash.
\item[\ic{-main dot_path}] Sets the main class.
\item[\ic{-D <var[=value]>}] Define a \tref{conditional compilation flag}{lf-condition-compilation}.
\end{description}
\emph{Output:}
\begin{description}
\item[\ic{-js file_name.js}] Generates \tref{JavaScript}{target-javascript} source code in specified file.
\item[\ic{-as3 directory}] Generates ActionScript 3 source code in specified directory.
\item[\ic{-swf file_name.swf}] Generates the specified file as \tref{Flash}{target-flash} .swf.
\item[\ic{-neko file_name.n}] Generates \tref{Neko}{target-neko} binary as specified file.
\item[\ic{-php directory}] Generates \tref{PHP}{target-php} source code in specified directory. Use \ic{-D php7} for PHP7 source code.
\item[\ic{-cpp directory}] Generates \tref{C++}{target-cpp} source code in specified directory and compiles it using native C++ compiler.
\item[\ic{-cs directory}] Generates \tref{C\#}{target-cs} source code in specified directory.
\item[\ic{-java directory}] Generates \tref{Java}{target-java} source code in specified directory and compiles it using the Java Compiler.
\item[\ic{-python file_name.py}] Generates \tref{Python}{target-python} source code in the specified file.
\item[\ic{-lua file_name.lua}] Generates \tref{Lua}{target-python} source code in the specified file.
\item[\ic{-hl file_name.hl}] Generates \tref{HashLink}{target-hl} byte code in specified file.
\item[\ic{-cppia file_name.cppia}] Generates the specified script as \tref{cppia}{target-cppia} file.
\item[\ic{-x <file>}] Shortcut for compiling and executing a neko file.
\item[\ic{--no-output}] compiles but does not generate any file.
\item[\ic{--interp}] interpret the program using internal macro system.
\end{description}
\paragraph{Other global arguments}
\begin{description}
\item[\ic{-xml <file>}] Generate XML types description. Useful for API documentation generation tools like \href{https://github.com/HaxeFoundation/dox}{Dox}.
\item[\ic{-v}] Turn on verbose mode.
\item[\ic{-dce <std|full|no>}] Set the \Fullref{cr-dce} mode (default std).
\item[\ic{-debug}] Add debug information to the compiled code.
\item[\ic{-resource <file>[@name]}] Add a named resource file.
\item[\ic{-prompt}] Prompt on error.
\item[\ic{-cmd}] Run the specified command after a successful compilation.
\item[\ic{--no-traces}] Don't compile trace calls in the program.
\item[\ic{--gen-hx-classes}] Generate hx headers for all input classes.
\item[\ic{--display}] Display code tips to provide \tref{completion information for IDEs and editors}{cr-completion-overview}.
\item[\ic{--times}] Measure compilation times.
\item[\ic{--no-inline}] Disable \Fullref{class-field-inline}.
\item[\ic{--no-opt}] Disable code optimizations.
\item[\ic{--remap <package:target>}] Remap a package to another one.
\item[\ic{--macro}] Call the given \tref{initialization macro}{macro-initialization} before typing anything else.
\item[\ic{--wait <host:port>}] Wait on the given port for commands to run).
\item[\ic{--connect <host:port>}] Connect on the given port and run commands there).
\item[\ic{--cwd <dir>}] Set current working directory.
\end{description}
\paragraph{Target specific arguments}
\begin{description}
\item[\ic{--php-front <filename>}] Select the name for the php front file.
\item[\ic{--php-lib <filename>}] Select the name for the php lib folder.
\item[\ic{--php-prefix <name>}] Prefix all classes with given name.
\item[\ic{-swf-version <version>}] Change the SWF version.
\item[\ic{-swf-header <header>}] Define SWF header (width:height:fps:color).
\item[\ic{-swf-lib <file>}] Add the SWF library to the compiled SWF.
\item[\ic{-swf-lib-extern <file>}] Use the SWF library for type checking.
\item[\ic{--flash-strict}] More type strict flash API.
\item[\ic{-java-lib <file>}] Add an external JAR or class directory library.
\item[\ic{-net-lib <file>[@std]}] Add an external .NET DLL file.
\item[\ic{-net-std <file>}] Add a root std .NET DLL search path.
\item[\ic{-c-arg <arg>}] Pass option \ic{arg} to the native Java/C\# compiler.
\end{description}
\trivia{Run commands after compilation}{Use \ic{-cmd} to run the specified command after a successful compilation. It can be used to run (testing) tools or to directly run the build, e.g. \ic{-cmd java -jar bin/Main.jar} (for Java), \ic{-cmd node main.js} (for Node.js) or \ic{-cmd neko Main.n} (for Neko) etcetera.}
\paragraph{Global compiler configuration macros:}
In order to include single modules, their paths can be listed directly on command line or in hxml: \ic{haxe ... ModuleName pack.ModuleName}. For more specific includes or excludes, use these \tref{initialization macros}{macro-initialization}:
\begin{description}
\item[\ic{--macro include(pack:String, recursive=true, ?ignore:Array<String>, ?classPaths:Array<String>, strict=false)}]
Includes all modules in package pack in the compilation. If \ic{recursive} is true, the compiler recursively adds all sub-packages.
\item[\ic{--macro exclude(pack:String, recursive=true}]
Exclude a specific class, enum, or all classes and enums in a package from being generated. Excluded types become \expr{extern}. If \ic{recursive} is true, the compiler recursively excludes all sub-packages.
\item[\ic{--macro excludeFile(fileName:String)}]
Exclude classes and enums listed from given external file (one per line) from being generated.
\item[\ic{--macro keep(?path:String, ?paths:Array<String>, recursive=true)}]
Marks a package, module or sub-type dot path to be kept by DCE. This also extends to the sub-types of resolved modules. If \ic{recursive} is true, the compiler recursively keeps all sub-packages for package paths.
\item[\ic{--macro includeFile(file:String, position)}]
Embed a JavaScript file at compile time. \ic{position} can be either "top", "inline" or "closure".
\end{description}
The full documentation of these methods can be found in the \href{http://api.haxe.org/haxe/macro/Compiler.html}{\expr{haxe.macro.Compiler}} API documentation.
\paragraph{Help}
\begin{description}
\item[\ic{haxe -version}] Print the current Haxe compiler version.
\item[\ic{haxe -help}] Display this list of options.
\item[\ic{haxe --help-defines}] Print help for all \tref{compiler specific defines}{compiler-usage-flags}.
\item[\ic{haxe --help-metas}] Print help for all \tref{compiler metadata}{lf-condition-compilation}.
\end{description}
\paragraph{Related content}
\begin{itemize}
\item \href{http://code.haxe.org/category/compilation/}{Compilation tutorials} in the Haxe Code Cookbook.
\end{itemize}
\section{HXML}
\label{compiler-usage-hxml}
\tref{Compiler arguments}{compiler-usage} can be stored in a .hxml file and can be executed with \ic{haxe <file.hxml>}.
In hxml it is possible to use newlines and comments which makes it easier to maintain Haxe build configurations.
It is possible to supply more arguments after the hxml file, e.g. \ic{haxe build.hxml -debug}.
\emph{Example:}
This example has a configuration which compiles the class file \ic{website.HomePage.hx} to JavaScript into a file called \ic{bin/homepage.js}, which is located in the \ic{src} class path. And uses full dead code elimination.
\lang{hxml}\begin{lstlisting}
-cp src
-dce full
-js bin/homepage.js
-main website.HomePage
\end{lstlisting}
\paragraph{Multiple build compilations}
Hxml configurations allow multiple compilation using these arguments:
\begin{description}
\item[\ic{--next}] Separate several Haxe compilations.
\item[\ic{--each}] Append preceding parameters to all haxe compilations separated by \ic{--next}. This reduces the repeating params.
\end{description}
\emph{Example:}
This example has a configuration which compiles three different classes into their own JavaScript files. Each build uses \ic{src} as class path and uses full dead code elimination.
\lang{hxml}\begin{lstlisting}
-cp src
-dce full
--each
-js bin/homepage.js
-main website.HomePage
--next
-js bin/gallery.js
-main website.GalleryPage
--next
-js bin/contact.js
-main website.ContactPage
\end{lstlisting}
\paragraph{Comments inside hxml}
Inside .hxml files use a hash (i.e. \ic{\#}) to comment out the rest of the line.
\emph{Calling build configurations inside HXML:}
It is possible to create a configuration that looks like this:
\lang{hxml}\begin{lstlisting}
build-server.hxml
--next
build-website.hxml
--next
build-game.hxml
\end{lstlisting}
\section{Global Compiler Flags}
\label{compiler-usage-flags}
Starting from Haxe 3.0, you can get the list of supported \tref{compiler flags}{lf-condition-compilation} by running \expr{haxe --help-defines}
\begin{center}
\begin{tabular}{| l | l |}
\hline
\multicolumn{2}{|c|}{Global Compiler Flags} \\ \hline
Flag & Description \\ \hline
\expr{absolute-path} & Print absolute file path in trace output \\
\expr{advanced-telemetry} & Allow the SWF to be measured with Monocle tool \\
\expr{analyzer} & Use static analyzer for optimization (experimental) \\
\expr{as3} & Defined when outputing flash9 as3 source code \\
\expr{check-xml-proxy} & Check the used fields of the xml proxy \\
\expr{core-api} & Defined in the core api context \\
\expr{core-api-serialize} & Mark some generated core api classes with the Serializable attribute on C\# \\
\expr{cppia} & Generate experimental cpp instruction assembly \\
\expr{dce=<mode:std|full|no>} & Set the \tref{dead code elimination}{cr-dce} mode (default std) \\
\expr{dce-debug} & Show \tref{dead code elimination}{cr-dce} log \\
\expr{debug} & Activated when compiling with \expr{-debug} \\
\expr{display} & Activated during completion \\
\expr{dll-export} & GenCPP experimental linking \\
\expr{dll-import} & GenCPP experimental linking \\
\expr{doc-gen} & Do not perform any removal/change in order to correctly generate documentation \\
\expr{dump} & Dump the complete typed AST for internal debugging in a dump subdirectory - use \expr{dump=pretty} for Haxe-like formatting \\
\expr{dump-dependencies} & Dump the classes dependencies in a dump subdirectory \\
\expr{dump-ignore-var-ids} & Remove variable IDs from non-pretty dumps (helps with diff) \\
\expr{erase-generics} & Erase generic classes on C\# \\
\expr{fdb} & Enable full flash debug infos for FDB interactive debugging \\
\expr{file-extension} & Output filename extension for cpp source code \\
\expr{flash-strict} & More strict typing for flash target \\
\expr{flash-use-stage} & Keep the SWF library initial stage \\
\expr{force-lib-check} & Force the compiler to check -net-lib and -java-lib added classes (internal) \\
\expr{force-native-property} & Tag all properties with \expr{:nativeProperty} metadata for 3.1 compatibility \\
\expr{format-warning} & Print a warning for each formated string, for 2.x compatibility \\
\expr{gencommon-debug} & GenCommon internal \\
\expr{haxe-boot} & Given the name 'haxe' to the flash boot class instead of a generated name \\
\expr{haxe-ver} & The current Haxe version value. Version 3.1.3 is \ic{3.103}, version 3.2.0 is \ic{3.200}, 3.1.10 is \ic{3.110}. version 3.4.0 is \ic{3.400} etc. This allows doing \ic{\#if (haxe_ver >= 3.103)} \\
\expr{hxcpp-api-level} & Provided to allow compatibility between hxcpp versions \\
\expr{include-prefix} & prepend path to generated include files \\
\expr{interp} & The code is compiled to be run with \expr{--interp} \\
\expr{java-ver=[version:5-7]} & Sets the Java version to be targeted \\
\expr{js-classic} & Don't use a function wrapper and strict mode in JS output \\
\expr{js-es5} & Generate JS for ES5-compliant runtimes \\
\expr{js-unflatten} & Generate nested objects for packages and types \\
\expr{keep-old-output} & Keep old source files in the output directory (for C\#/Java) \\
\expr{loop-unroll-max-cost} & Maximum cost (number of expressions * iterations) before loop unrolling is canceled (default 250) \\
\expr{macro} & Defined when code is compiled in the \tref{macro context}{macro} \\
\expr{macro-times} & Display per-macro timing when used with \expr{--times} \\
\expr{net-ver=<version:20-45>} & Sets the .NET version to be targeted \\
\expr{net-target=<name>} & Sets the .NET target. Defaults to net. xbox, micro \_(Micro Framework\_, compact \_(Compact Framework)\_ are some valid values \\
\expr{neko-source} & Output neko source instead of bytecode \\
\expr{neko-v1} & Keep Neko 1.x compatibility \\
\expr{network-sandbox} & Use local network sandbox instead of local file access one \\
\expr{no-compilation} & Disable CPP final compilation \\
\expr{no-copt} & Disable completion optimization \_(for debug purposes)\_ \\
\expr{no-debug} & Remove all debug macros from cpp output \\
\expr{no-deprecation-warnings} & Do not warn if fields annotated with \expr{@:deprecated} are used \\
\expr{no-flash-override} & Change overrides on some basic classes into HX suffixed methods flash only \\
\expr{no-opt} & Disable optimizations \\
\expr{no-pattern-matching} & Disable \tref{pattern matching}{lf-pattern-matching} \\
\expr{no-inline} & Disable \tref{inlining}{class-field-inline} \\
\expr{no-root} & GenCS internal \\
\expr{no-macro-cache} & Disable macro context caching \\
\expr{no-simplify} & Disable simplification filter \\
\expr{no-swf-compress} & Disable SWF output compression \\
\expr{no-traces} & Disable all \expr{trace} calls \\
\expr{php-prefix} & Compiled with \expr{--php-prefix} \\
\expr{real-position} & Disables haxe source mapping when targetting C\# \\
\expr{replace-files} & GenCommon internal \\
\expr{scriptable} & GenCPP internal \\
\expr{shallow-expose} & Expose types to surrounding scope of Haxe generated closure without writing to window object \\
\expr{source-map-content} & Include the hx sources as part of the JS source map \\
\expr{swc} & Output a SWC instead of a SWF \\
\expr{swf-compress-level=<level:1-9>} & Set the amount of compression for the SWF output \\
\expr{swf-debug-password=<yourPassword>} & Set a password for debugging. 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. \\
\expr{swf-direct-blit} & Use hardware acceleration to blit graphics \\
\expr{swf-gpu} & Use GPU compositing features when drawing graphics \\
\expr{swf-metadata=<file.xml>} & Include contents of \expr{<file.xml>} as metadata in the swf. \\
\expr{swf-preloader-frame} & Insert empty first frame in swf. To be used together with \expr{-D flash-use-stage} and \expr{-swf-lib} \\
\expr{swf-protected} & Compile Haxe private as protected in the SWF instead of public \\
\expr{swf-script-timeout} & Maximum ActionScript processing time before script stuck dialog box displays (in seconds) \\
\expr{swf-use-doabc} & Use DoAbc swf-tag instead of DoAbcDefine \\
\expr{sys} & Defined for all system platforms \\
\expr{unsafe} & Allow unsafe code when targeting C\# \\
\expr{use-nekoc} & Use nekoc compiler instead of internal one \\
\expr{use-rtti-doc} & Allows access to documentation during compilation \\
\expr{vcproj} & GenCPP internal \\
\end{tabular}
\end{center}