| <!-- |
| |
| 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> |