org.apache.royale.compiler.projects.package.html Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of compiler Show documentation

The Apache Royale Compiler

The newest version!






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.

`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.