You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@royale.apache.org by ca...@apache.org on 2020/04/10 11:21:51 UTC
[royale-docs] branch master updated: add compiler and
compiler-options pages. Still WIP
This is an automated email from the ASF dual-hosted git repository.
carlosrovira pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/royale-docs.git
The following commit(s) were added to refs/heads/master by this push:
new e53bc98 add compiler and compiler-options pages. Still WIP
e53bc98 is described below
commit e53bc982914f89cff7a4e8a2c6f1f169e7389720
Author: Carlos Rovira <ca...@apache.org>
AuthorDate: Fri Apr 10 13:21:39 2020 +0200
add compiler and compiler-options pages. Still WIP
---
_data/toc.json | 8 ++
compiler.md | 65 +++++++++++++
compiler/compiler-options.md | 216 +++++++++++++++++++++++++++++++++++++++++++
3 files changed, 289 insertions(+)
diff --git a/_data/toc.json b/_data/toc.json
index 9a3633e..0716e4a 100644
--- a/_data/toc.json
+++ b/_data/toc.json
@@ -205,6 +205,14 @@
]
},
{
+ "path": "compiler.md",
+ "children": [
+ {
+ "path": "compiler/compiler-options.md"
+ }
+ ]
+ },
+ {
"path": "create-an-application.md",
"children": [
{
diff --git a/compiler.md b/compiler.md
new file mode 100644
index 0000000..b6b5bd3
--- /dev/null
+++ b/compiler.md
@@ -0,0 +1,65 @@
+---
+# 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.
+
+layout: docpage
+title: Compiler
+description: Refactoring code to remove circular dependencies
+permalink: /compiler
+---
+
+# Apache Royale Compiler
+
+Turn your source code into one or more compiled outputs
+
+Royale provide a compiler and a command-line debugger to turn your source code into the required output. The compiler takes [AS3](features/as3) & [MXML](features/mxml) (and CSS) as inputs.
+
+The main output of the compiler is **JavaScript** (some call it a transpiler or cross-compiler). The compiler can also output **SWFs** for the **Adobe Flash** runtimes. There is some initial work on **Web Assembly** output.
+
+> The compiler has been designed to make it relatively straightforward to add additional output formats.
+
+The code is based on the ActionScript Compiler 2.0 donated to Apache by Adobe. The SWF output was pretty much working at the time of donation. The JavaScript output code is a new implementation by Apache committers
+
+## User Guide
+
+The Royale Compiler does many things besides compile **MXML** and **ActionScript** into **JavaScript** and/or **SWF**. But if that's all you want to do, you can use the compiler with **Apache Maven**, **Apache Ant**, several **IDEs**, **NPM** and the command-line. Below are some pointers to getting started:
+
+### Apache Maven
+
+There are some examples in the `apache/royale-asjs` repo in the `examples` folder. The `pom.xml` files should be useful as a starting point. There are also **Maven archetypes** available in Apache Royale releases.
+
+### Apache Ant
+
+In an Apache Royale distribution, there is a `compiler-royaleTasks.jar` in the `js/lib` folder that contains Ant tasks for the Royale Compiler. There is an mxmlc task for creating applications and a compc task for creating libraries.
+
+### IDEs
+
+Consult your IDE documentation for how to launch the Royale Compiler. You can generate a IDE distribution from Apache Maven and/or Apache ANT.
+
+### NPM
+
+You should be able to run `mxmlc` or `compc` from the command-line after installing Royale via NPM. Use `mxmlc --help` to see the latest list of options.
+
+### Command-line
+
+The `js/bin` folder should contain `mxmlc` and `compc` scripts that will launch the compiler. Use `mxmlc --help` to see the latest list of options.
+
+## Compiler Options
+
+Royale provide several compiler options to customize the use. You can check the list of compiler options here:
+
+- [Compiler Options](compiler/compiler-options)
+
+> To read about how to contribute to Apache Royale Compiler use the following [Apache Royale Compiler Developer Guide](https://github.com/apache/royale-compiler/wiki/Developer-Guide) available on the Apache Royale Compiler Wiki.
\ No newline at end of file
diff --git a/compiler/compiler-options.md b/compiler/compiler-options.md
new file mode 100644
index 0000000..f8a3a17
--- /dev/null
+++ b/compiler/compiler-options.md
@@ -0,0 +1,216 @@
+---
+# 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.
+
+layout: docpage
+title: Compiler Options
+description: List of Available Compiler Options
+permalink: /compiler/compiler-options
+---
+
+# Compiler Options
+
+List of Available Compiler Options
+
+Royale provide the following list of compiler options
+
+## JavaScript Compiler Options
+
+### html-output-filename
+
+Specifies the file name of the HTML file generated by the compiler to load the Apache Royale application in the browser.
+
+```sh
+-compiler.html-output-filename custom.html
+```
+
+### html-template
+
+Specifies the path to an optional template for the the HTML file generated by the compiler to load the Apache Royale application in the browser.
+
+```sh
+-compiler.html-template ./path/to/template.html
+```
+
+#### Maven configuration:
+
+```xml
+<htmlTemplate>${basedir}/target/javascript/bin/js-debug/jewel-example-index-template.html</htmlTemplate>
+```
+
+### js-compiler-option
+
+Specifies one or more custom compiler options to pass to the Google Closure Compiler, which is used to create the release build of an Apache Royale application.
+
+```sh
+-compiler.js-compiler-option.variable_map_output_file gccvars.txt -compiler.compilation_level SIMPLE_OPTIMIZATIONS
+```
+
+#### Maven configuration:
+
+```xml
+<additionalCompilerOptions>-js-compiler-option=--variable_map_output_file gccvars.txt;-js-compiler-option+=--property_map_output_file gccprops.txt</additionalCompilerOptions>
+```
+
+### js-default-initializers
+
+Defaults to true. Enables or disables initialization of primitive (Number, Boolean, etc.) variables with default values in the generated JavaScript. Corresponds to AVM runtime implicit type intialization values.
+
+Note that some reflection utility functions require this to be true in order for them to work correctly in javascript.
+
+```sh
+-compiler.js-default-initializers
+```
+
+#### Maven configuration:
+
+```xml
+<additionalCompilerOptions>-js-default-initializers=true;</additionalCompilerOptions>
+```
+
+### js-define
+
+Defines a global constant at compile time for the JavaScript output. May be a boolean, number, string, or expression.
+
+```sh
+-compiler.js-define CONFIG::debugging true -compiler.js-define CONFIG::release false
+```
+
+For boolean and numeric values, you may pass in literals like true, false, or 123. String values must be formatted with nested quotes, like "'hello'", because the compiler will attempt to evaluate an expression when it encounters quotes.
+
+#### Maven configuration:
+
+```xml
+<defines>
+ <property>
+ <name>BUILD::buildNumber</name>
+ <value>'"${buildTimestamp}"'</value>
+ </property>
+ <property>
+ <name>BUILD::buildVersion</name>
+ <value>'"${project.version}"'</value>
+ </property>
+</defines>
+```
+
+Then in AS3 you can do:
+
+```as3
+// Build Number
+private static var _buildNumber :String = BUILD::buildNumber;
+
+// Project Version
+private static var _projectVersion :String = BUILD::buildVersion;
+```
+
+### js-load-config
+
+Specifies the locations of XML configuration files that define extra compiler options for JavaScript output.
+
+```sh
+-compiler.js-load-config path/to/project-config.xml
+```
+
+#### Maven configuration:
+
+### js-output
+
+The path where the generated JavaScript output should be saved, if output is also being used for the .swf output path.
+
+```sh
+-compiler.js-output path/to/output
+```
+
+#### Maven configuration:
+
+Use instead `outputDirectory`in `configuration` xml node
+
+### remove-circulars
+
+Tells the Apache Royale compiler to remove circular dependencies in the generated JavaScript, where possible.
+
+```sh
+-compiler.remove-circulars
+```
+
+#### Maven configuration:
+
+```xml
+<removeCirculars>true</removeCirculars>
+```
+
+### source-map
+
+Emits source maps in the debug build for each ActionScript file. The default value is false.
+
+```sh
+-compiler.source-map
+```
+
+#### Maven configuration:
+
+```xml
+<additionalCompilerOptions>-source-map=true;</additionalCompilerOptions>
+```
+
+### targets
+
+Specifies the target format of the code generated by the Apache Royale compiler. Multiple targets may be specified.
+
+```sh
+-compiler.targets JSRoyale,SWF
+```
+
+The following values for "targets" are supported:
+
+- "JSRoyale"
+- "JS"
+- "JSNode"
+- "JSNodeModule"
+- "SWF"
+
+#### Maven configuration:
+
+```xml
+<targets>JSRoyale</targets>
+```
+
+### warn-public-vars
+
+Enables or disables warnings about using public variables.
+
+```sh
+-compiler.warn-public-vars
+```
+
+#### Maven configuration:
+
+```xml
+<additionalCompilerOptions>-warn-public-vars=true;</additionalCompilerOptions>
+```
+
+### show-binding-warnings
+
+Set to false to remove all binding warnings
+
+```sh
+-compiler.show-binding-warnings=false
+```
+
+#### Maven configuration:
+
+```xml
+<additionalCompilerOptions>-show-binding-warnings=false;</additionalCompilerOptions>
+```
\ No newline at end of file