Package org.apache.flex.compiler.projects

This package contains interfaces representing projects.

See: Description

Interface Summary

Interface	Description
IASCProject	IASCProject can create ISWFTargets that build SWF from AS3 files in a manner similar to asc.
IASProject	Base interface for all project types that use a source manager and library manager to create ICompilationUnits.
ICompilerProject	All IProject implementations aggregate a project scope containing global definitions, a set of CompilationUnits, and a graph of dependencies between the CompilationUnits.
IFlexProject	Base interface for all project types that support all flex source file types ( mxml, fxg, css, etc ).

Class Summary

Class	Description
ProjectFactory	class factory for things like CompilerProject, FlexProject, etc...

Package org.apache.flex.compiler.projects Description

This package contains interfaces representing projects.

A project is a compilation environment for compiling compilation units into targets. It is a "steady-state" environment in which the intermediate results of the compilation process -- abstract syntax trees, file scopes, ABC bytecode, and so on -- are kept in memory in order to support efficient incremental compilation when files are added, changed, or removed, or when compilation options are changed.

The data structures maintained by the project and its compilation units also support code intelligence features -- code completion, the display of API documentation, "goto definition", outlining, refactoring, and so on -- in compiler clients such as integrated developement environments. To support these use cases, it it not necessary for a project to actually produce bytecode or build a SWF or SWC. Instead, a compilation unit can simply be asked to produce an intermediate result such as an abstract syntax tree.

A project belongs to a workspace, which stores data shared by multiple projects (such as a SWC cache). A project holds a strong reference to its workspace, but the workspace holds only a weak reference to its project.

A compilation unit manages a five-stage compilation process for a single file or ABC script. Compilation units are created by a project by enumerating all of the files on its source path and library path. Which compilation units actually get compiled is determined by the target driving the compilation. See the org.apache.flex.compiler.units package for more information about compilation units.

A project can create multiple targets to build multiple SWF and/or SWC files. Each target drives one or more (but not necessarily all) of the project's compilation units through their compilation phases, and assembles the resulting ABC or SWF tags into a SWF or SWC. See the org.apache.flex.compiler.targets package for more information about targets.

Some configuration options become project settings, while others become target settings. For example, the source path and library path are project settings, but whether a particular SWC is to be linked internally or externally (that is, whether is "on the external library path") is a target setting.

In addition to managing compilation units and targets, a project owns other important data structures shared by all the compilation units in the project:

• a project scope
• a dependency graph
• thread-local scope caches

The project scope supports name resolution between compilation units. It is always memory-resident. See the org.apache.flex.compiler.scopes package for more information about scopes.

The dependency graph tracks bidrectional dependencies between compilation units, in order to support incremental compilation. For example, when class B in one file extends class A in another file, that introduces a dependency of type INHERITANCE between the compilation unit representing the first file and the compilation unit representing the second file. There are four types of dependency, as described in the DependencyType enum. The dependency graph is always memory-resident.

Each thread-local scope cache optimizes name resolution within a single scope. Once an identifier in a scope has been resolved, the definition to which it resolved is stored in a scope cache for that scope. Subsequent identifiers with the same base name in the same scope must resolve identically, so the definition can be retrieved from the scope cache rather than re-resolved according to the name resolution algorithm. Weak references are used so that the scope caches can be garbage-collected.

A project also keeps track of all embeddings in all compilation units, and creates an EmbedCompilationUnit to create the class representing the embedded asset. This means that if a single file embeds the same asset with the same embedding attributes in multiple places, or if multiple files in a project embed the same asset with the same embedding attributes, then only one embed class will be created in the final SWF or SWC to represent the asset. The transcoded asset data is cached in the workspace, so that assets are not re-transcoded by each project that uses them.

The base interface for all projects is ICompilerProject. There are four different kinds of projects, each with its own subinterface:

IFlexProjectProject	Can create a SWF target to build a Flex application or module, or a SWC target to build a Flex library or resource bundle. Supports .mxml, .fxg, .css, and .properties files as well as .as files.
IFlashProject	Can create a SWF target to compile a set of .as files.
IFlashLibraryProject	Can cratea a SWF or SWC target to compile a set of .as files.
IASProject	Can create a SWF target that builds a SWF from .as files in the manner of asc rather than in the manner of mxmlc. That is, it uses a source list rather than a source path.