.AS File Format – Compiling

The compilers

mxmlc -source-path=src -library-path+=libs -output=bin/Main.swf src/com/example/Main.as
compc -source-path=src -include-sources=src/com/example/util -output=bin/util.swc

Only classes that are reached from the main class, or listed for inclusion, end up in the SWF. A class that is only named in a string, such as one created with getDefinitionByName, must be referenced somewhere or included with -includes.

The source path

The compiler finds a class by turning its full name into a path under each folder of the source path: com.example.Main is com/example/Main.as. mxmlc takes -source-path (+= adds to the list) and adds the folder of the main file. Flash authoring uses the folder of the .fla, the document’s own source path and the application-wide one in its preferences. Compiled libraries come from the library path: SWC files with -library-path, or -external-library-path for ones the runtime will supply.

A class must sit in the file and folder its name gives; the compiler reports an error when the package or class name and the path disagree.

File encoding

The Flex and AIR compilers use the byte order mark when a file has one. Without it, they read the file in the encoding named by -actionscript-file-encoding, or else in the computer’s default encoding. MXML files are not affected, since their XML declaration gives the encoding. Saving every .as file as UTF-8 avoids any difference between computers.

The include directive

include "path/file.as";

Pastes the text of another file in place of the directive when the code is compiled, usually by a path relative to the file that holds the directive. The pasted text must make sense where it lands: a list of methods inside a class body, statements inside a function. After the included file changes, every SWF that uses it must be compiled again. include does not import classes. ActionScript 1.0 and 2.0 spelt it #include.

package com.example {
    import flash.display.Sprite;

    public class Player extends Sprite {
        include "PlayerMovement.as";     // methods shared with another class
    }
}

Conditional compilation

Constants defined outside the code, in the form namespace::name, are known to the compiler and can switch code on and off. CONFIG is the usual namespace, but any name works.

mxmlc -define=CONFIG::debug,true -define+=CONFIG::version,"'1.2'" …

package {
    import flash.display.Sprite;
    import com.example.DebugPanel;

    public class Main extends Sprite {
        public function Main() {
            CONFIG::debug {
                trace("built as version", CONFIG::version);
                showPanel();
            }
        }

        CONFIG::debug
        private function showPanel():void {
            addChild(new DebugPanel());
        }
    }
}

• A Boolean constant before a block, or before a single definition (CONFIG::debug public function …), keeps it when true and drops it entirely when false, like #ifdef in C. It works on definitions of classes, functions and variables and on blocks of statements.
• Constants cannot switch metadata tags or import lines on and off, according to Adobe’s documentation.
• String, number and Boolean constants can be used as values anywhere an expression goes; the compiler puts the value in.
• A value can be an expression the compiler can work out: "CONFIG::debug && !CONFIG::release", "4 - 1".
• String values need two sets of quotes on the command line, "'text'", and one in a configuration file: <value>'text'</value>.
• A definition on the command line overrides the same one in a configuration file; -define+= adds to the list and -define= replaces it.

Flash authoring takes the same constants in the ActionScript settings of the publish settings.

The document class and linked classes

A Flash document names one class as its document class. It extends MovieClip, or Sprite when the main timeline needs no frames of its own, and becomes the main timeline: the player creates it first, as the first child of the Stage. Without a document class, Flash generates one, named MainTimeline in a package named after the document (such as Untitled_fla), to hold the frame scripts.

A library symbol exported for ActionScript gets a class name and a base class in its linkage properties. When a .as file of that name exists on the source path, the symbol uses that class; otherwise Flash generates an empty class extending the base class. Instances placed on the stage with instance names become properties of the timeline’s class: with “Automatically declare stage instances” on (the default), Flash declares them as public variables; with it off, the class must declare them itself as public var.

Where Flash keeps these names and the frame scripts inside the .fla is described on the FLA pages. In the compiled SWF a SymbolClass tag links each symbol, and the main timeline as character 0, to its class; see Compiled bytecode.

Common compiler options

These are the mxmlc and compc names; Flash authoring has most of them as publish settings. Options can also be written in a configuration file, such as the SDK’s flex-config.xml or one given with -load-config.

SWC libraries

A SWC is a zip archive holding library.swf, the compiled classes, and catalog.xml, which lists every definition, what it depends on and the SWF’s digest. It may also hold assets, ASDoc and a manifest. A SWC is linked like source but is not recompiled; Flash authoring and the SDK compilers both use them.