compiler/src/main/java/org/apache/royale/compiler/projects/package.html - royale-compiler - Git at Google

 <!--

   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

 -->

 <html>
 <body>

 This package contains interfaces representing <i>projects</i>.

 <p>
 A <i>project</i> is a compilation environment for compiling
 <i>compilation units</i> into <i>targets</i>.
 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.
 </p>

 <p>
 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.
 </p>

 <p>
 A project belongs to a <i>workspace</i>, 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.
 </p>

 <p>
 A <i>compilation unit</i> 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 <code>org.apache.royale.compiler.units</code> package
 for more information about compilation units.
 </p>

 <p>
 A project can create multiple <i>targets</i> 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 <code>org.apache.royale.compiler.targets</code> package
 for more information about targets.
 </p>

 <p>
 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.
 </p>

 <p>
 In addition to managing compilation units and targets,
 a project owns other important data structures shared
 by all the compilation units in the project:
 <ul>
 <li>a <i>project scope</i></li>
 <li>a <i>dependency graph</i></li>
 <li>thread-local <i>scope caches</i></li>
 </ul>
 </p>

 <p>
 The <i>project scope</i> supports <i>name resolution</i>
 between compilation units.
 It is always memory-resident.
 See the <code>org.apache.royale.compiler.scopes</code> package
 for more information about scopes.
 </p>

 <p>
 The <i>dependency graph</i> tracks bidrectional dependencies between
 compilation units, in order to support incremental compilation.
 For example, when <code>class B</code> in one file extends <code>class A</code>
 in another file, that introduces a dependency of type <code>INHERITANCE</code>
 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
 <code>DependencyType</code> enum.
 The dependency graph is always memory-resident.
 </p>

 <p>
 Each thread-local <i>scope cache</i> optimizes <i>name resolution</i>
 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.
 </p>

 <p>
 A project also keeps track of all <i>embeddings</i> in all compilation units,
 and creates an <code>EmbedCompilationUnit</code> 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.
 </p>

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

 <table border="1" cellspacing="0" cellpadding="3">
 	<tr>
 		<td><code>IRoyaleProject</code></td>
 		<td>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 <code>.mxml</code>, <code>.fxg</code>, <code>.css</code>,
 		and <code>.properties</code> files as well as <code>.as</code>
 		files.</td>
 	</tr>
 	<tr>
 		<td><code>IFlashProject</code></td>
 		<td>Can create a SWF target to compile a set of <code>.as</code>
 		files.</td>
 	</tr>
 	<tr>
 		<td><code>IFlashLibraryProject</code></td>
 		<td>Can cratea a SWF or SWC target to compile a set of <code>.as</code>
 		files.</td>
 	</tr>
 	<tr>
 		<td><code>IASProject</code></td>
 		<td>Can create a SWF target that builds a SWF from <code>.as</code> files
 		in the manner of <code>asc</code> rather than in the manner of <code>mxmlc</code>.
 		That is, it uses a source list rather than a source path.</td>
 	</tr>
 </table>

 </body>
 </html>
	<!--

	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.

	-->

	<html>
	<body>

	This package contains interfaces representing <i>projects</i>.

	<p>
	A <i>project</i> is a compilation environment for compiling
	<i>compilation units</i> into <i>targets</i>.
	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.
	</p>

	<p>
	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.
	</p>

	<p>
	A project belongs to a <i>workspace</i>, 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.
	</p>

	<p>
	A <i>compilation unit</i> 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 <code>org.apache.royale.compiler.units</code> package
	for more information about compilation units.
	</p>

	<p>
	A project can create multiple <i>targets</i> 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 <code>org.apache.royale.compiler.targets</code> package
	for more information about targets.
	</p>

	<p>
	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.
	</p>

	<p>
	In addition to managing compilation units and targets,
	a project owns other important data structures shared
	by all the compilation units in the project:
	<ul>
	<li>a <i>project scope</i></li>
	<li>a <i>dependency graph</i></li>
	<li>thread-local <i>scope caches</i></li>
	</ul>
	</p>

	<p>
	The <i>project scope</i> supports <i>name resolution</i>
	between compilation units.
	It is always memory-resident.
	See the <code>org.apache.royale.compiler.scopes</code> package
	for more information about scopes.
	</p>

	<p>
	The <i>dependency graph</i> tracks bidrectional dependencies between
	compilation units, in order to support incremental compilation.
	For example, when <code>class B</code> in one file extends <code>class A</code>
	in another file, that introduces a dependency of type <code>INHERITANCE</code>
	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
	<code>DependencyType</code> enum.
	The dependency graph is always memory-resident.
	</p>

	<p>
	Each thread-local <i>scope cache</i> optimizes <i>name resolution</i>
	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.
	</p>

	<p>
	A project also keeps track of all <i>embeddings</i> in all compilation units,
	and creates an <code>EmbedCompilationUnit</code> 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.
	</p>

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

	<table border="1" cellspacing="0" cellpadding="3">
	<tr>
	<td><code>IRoyaleProject</code></td>
	<td>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 <code>.mxml</code>, <code>.fxg</code>, <code>.css</code>,
	and <code>.properties</code> files as well as <code>.as</code>
	files.</td>
	</tr>
	<tr>
	<td><code>IFlashProject</code></td>
	<td>Can create a SWF target to compile a set of <code>.as</code>
	files.</td>
	</tr>
	<tr>
	<td><code>IFlashLibraryProject</code></td>
	<td>Can cratea a SWF or SWC target to compile a set of <code>.as</code>
	files.</td>
	</tr>
	<tr>
	<td><code>IASProject</code></td>
	<td>Can create a SWF target that builds a SWF from <code>.as</code> files
	in the manner of <code>asc</code> rather than in the manner of <code>mxmlc</code>.
	That is, it uses a source list rather than a source path.</td>
	</tr>
	</table>

	</body>
	</html>