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.royale.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.royale.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.royale.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:

`IRoyaleProject` | Can create a SWF target to build a Royale application or module, or a SWC target to build a Royale 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.