compiler: document for release build optimization that's separate from compiler-options
diff --git a/_data/toc.json b/_data/toc.json
index 86c76c0..640110e 100644
--- a/_data/toc.json
+++ b/_data/toc.json
@@ -243,6 +243,9 @@
"children": [
{
"path": "compiler/compiler-options.md"
+ },
+ {
+ "path": "compiler/release-build-file-size-optimization.md"
}
]
},
diff --git a/compiler/compiler-options.md b/compiler/compiler-options.md
index 2aa4d0e..de3873c 100644
--- a/compiler/compiler-options.md
+++ b/compiler/compiler-options.md
@@ -24,7 +24,7 @@
List of all available compiler options
-The [**mxmlc** and **compc** compilers](compiler/) have a number of useful configuration options. The list below is also available by running `mxmlc -help advanced` in a terminal.
+The [**mxmlc** and **compc** compilers](compiler) have a number of useful configuration options. The list below is also available by running `mxmlc -help advanced` in a terminal.
- `-allow-dynamic-bindings` -- Controls whether data binding may use reflection for dynamic access.
- `-api-report` `<filename>` -- Used to generate a report of APIs used in a project.
@@ -506,17 +506,7 @@
<additionalCompilerOptions>-keep-asdoc=false;</additionalCompilerOptions>
```
-## Reduce size of release builds
-
-The following compiler options may be used to reduce the output size of JavaScript release builds. However, using these options may also prevent certain coding patterns in ActionScript and JavaScript from working correctly, so use with caution.
-
-There are two main ways to reduce the size of a release build:
-
-- **Disable exported symbols.** When a symbol is _exported_, it may be accessed by external JavaScript `<script>` elements in the same page. If a symbol is not exported, and it is not referenced elsewhere in the Royale project, the compiler may determine that it is "dead code" that should be removed from a release build.
-
-- **Allow renaming of symbols.** When a symbol is not allowed to be renamed in a release build, it may be accessed using dynamic string access, such as `object["myProperty"]`. If a symbol is not prevented from being renamed, the compiler may determine that it can change the name of the symbol to a shorter value to reduce the size of the release build. If a symbol is renamed, dynamic string access will not be possible without knowing the new name of the symbol.
-
-### Export public symbols {#export-public-symbols}
+### export-public-symbols {#export-public-symbols}
In a release build, determines if symbols in the `public` namespace will be exported or not. The default value is `true`.
@@ -532,7 +522,7 @@
<additionalCompilerOptions>-export-public-symbols=false;</additionalCompilerOptions>
```
-### Export protected symbols {#export-protected-symbols}
+### export-protected-symbols {#export-protected-symbols}
In a release build, determines if symbols in the `protected` namespace will be exported. The default value is `false`.
@@ -548,7 +538,7 @@
<additionalCompilerOptions>-export-protected-symbols=true;</additionalCompilerOptions>
```
-### Export internal symbols {#export-internal-symbols}
+### export-internal-symbols {#export-internal-symbols}
In a release build, determines if symbols in the `internal` namespace will be exported. The default value is `false`.
@@ -564,7 +554,7 @@
<additionalCompilerOptions>-export-internal-symbols=true;</additionalCompilerOptions>
```
-### Prevent renaming of public symbols {#prevent-rename-public-symbols}
+### prevent-rename-public-symbols {#prevent-rename-public-symbols}
In a release build, determines if symbols in the `public` namespace may be renamed or not. The default value is `true`.
@@ -591,7 +581,7 @@
- [`prevent-rename-public-static-accessors`](compiler/compiler-options.html#prevent-rename-public-static-accessors)
- [`prevent-rename-public-instance-accessors`](compiler/compiler-options.html#prevent-rename-public-instance-accessors)
-### Prevent renaming of protected symbols {#prevent-rename-protected-symbols}
+### prevent-rename-protected-symbols {#prevent-rename-protected-symbols}
In a release build, determines if symbols in the `protected` namespace may be renamed or not. The default value is `true`.
@@ -618,7 +608,7 @@
- [`prevent-rename-protected-static-accessors`](compiler/compiler-options.html#prevent-rename-protected-static-accessors)
- [`prevent-rename-protected-instance-accessors`](compiler/compiler-options.html#prevent-rename-protected-instance-accessors)
-### Prevent renaming of internal symbols {#prevent-rename-internal-symbols}
+### prevent-rename-internal-symbols {#prevent-rename-internal-symbols}
In a release build, determines if symbols in the `internal` namespace may be renamed or not. The default value is `true`.
@@ -645,7 +635,7 @@
- [`prevent-rename-internal-static-accessors`](compiler/compiler-options.html#prevent-rename-internal-static-accessors)
- [`prevent-rename-internal-instance-accessors`](compiler/compiler-options.html#prevent-rename-internal-instance-accessors)
-### Prevent renaming of public static methods {#prevent-rename-public-static-methods}
+### prevent-rename-public-static-methods {#prevent-rename-public-static-methods}
In a release build, determines if static methods in the `public` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-public-symbols` compiler option is `false`.
@@ -661,7 +651,7 @@
<additionalCompilerOptions>-prevent-rename-static-methods=false;</additionalCompilerOptions>
```
-### Prevent renaming of public instance methods {#prevent-rename-public-instance-methods}
+### prevent-rename-public-instance-methods {#prevent-rename-public-instance-methods}
In a release build, determines if instance (non-static) methods in the `public` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-public-symbols` compiler option is `false`.
@@ -677,7 +667,7 @@
<additionalCompilerOptions>-prevent-rename-public-instance-methods=false;</additionalCompilerOptions>
```
-### Prevent renaming of public static variables {#prevent-rename-public-static-variables}
+### prevent-rename-public-static-variables {#prevent-rename-public-static-variables}
In a release build, determines if static variables in the `public` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-public-symbols` compiler option is `false`.
@@ -693,7 +683,7 @@
<additionalCompilerOptions>-prevent-rename-static-variables=false;</additionalCompilerOptions>
```
-### Prevent renaming of public instance variables {#prevent-rename-public-instance-variables}
+### prevent-rename-public-instance-variables {#prevent-rename-public-instance-variables}
In a release build, determines if instance (non-static) variables in the `public` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-public-symbols` compiler option is `false`.
@@ -709,7 +699,7 @@
<additionalCompilerOptions>-prevent-rename-public-instance-variables=false;</additionalCompilerOptions>
```
-### Prevent renaming of public static accessors {#prevent-rename-public-static-accessors}
+### prevent-rename-public-static-accessors {#prevent-rename-public-static-accessors}
In a release build, determines if static accessors (getters and setters) in the `public` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-public-symbols` compiler option is `false`.
@@ -725,7 +715,7 @@
<additionalCompilerOptions>-prevent-rename-static-accessors=false;</additionalCompilerOptions>
```
-### Prevent renaming of public instance accessors {#prevent-rename-public-instance-accessors}
+### prevent-rename-public-instance-accessors {#prevent-rename-public-instance-accessors}
In a release build, determines if instance (non-static) accessors (getters and setters) in the `public` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-public-symbols` compiler option is `false`.
@@ -741,7 +731,7 @@
<additionalCompilerOptions>-prevent-rename-public-instance-accessors=false;</additionalCompilerOptions>
```
-### Prevent renaming of protected static methods {#prevent-rename-protected-static-methods}
+### prevent-rename-protected-static-methods {#prevent-rename-protected-static-methods}
In a release build, determines if static methods in the `protected` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-protected-symbols` compiler option is `false`.
@@ -757,7 +747,7 @@
<additionalCompilerOptions>-prevent-rename-static-methods=false;</additionalCompilerOptions>
```
-### Prevent renaming of protected instance methods {#prevent-rename-protected-instance-methods}
+### prevent-rename-protected-instance-methods {#prevent-rename-protected-instance-methods}
In a release build, determines if instance (non-static) methods in the `protected` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-protected-symbols` compiler option is `false`.
@@ -773,7 +763,7 @@
<additionalCompilerOptions>-prevent-rename-protected-instance-methods=false;</additionalCompilerOptions>
```
-### Prevent renaming of protected static variables {#prevent-rename-protected-static-variables}
+### prevent-rename-protected-static-variables {#prevent-rename-protected-static-variables}
In a release build, determines if static variables in the `protected` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-protected-symbols` compiler option is `false`.
@@ -789,7 +779,7 @@
<additionalCompilerOptions>-prevent-rename-static-variables=false;</additionalCompilerOptions>
```
-### Prevent renaming of protected instance variables {#prevent-rename-protected-instance-variables}
+### prevent-rename-protected-instance-variables {#prevent-rename-protected-instance-variables}
In a release build, determines if instance (non-static) variables in the `protected` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-protected-symbols` compiler option is `false`.
@@ -805,7 +795,7 @@
<additionalCompilerOptions>-prevent-rename-protected-instance-variables=false;</additionalCompilerOptions>
```
-### Prevent renaming of protected static accessors {#prevent-rename-protected-static-accessors}
+### prevent-rename-protected-static-accessors {#prevent-rename-protected-static-accessors}
In a release build, determines if static accessors (getters and setters) in the `protected` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-protected-symbols` compiler option is `false`.
@@ -821,7 +811,7 @@
<additionalCompilerOptions>-prevent-rename-static-accessors=false;</additionalCompilerOptions>
```
-### Prevent renaming of protected instance accessors {#prevent-rename-protected-instance-accessors}
+### prevent-rename-protected-instance-accessors {#prevent-rename-protected-instance-accessors}
In a release build, determines if instance (non-static) accessors (getters and setters) in the `protected` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-protected-symbols` compiler option is `false`.
@@ -837,7 +827,7 @@
<additionalCompilerOptions>-prevent-rename-protected-instance-accessors=false;</additionalCompilerOptions>
```
-### Prevent renaming of internal static methods {#prevent-rename-internal-static-methods}
+### prevent-rename-internal-static-methods {#prevent-rename-internal-static-methods}
In a release build, determines if static methods in the `internal` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-internal-symbols` compiler option is `false`.
@@ -853,7 +843,7 @@
<additionalCompilerOptions>-prevent-rename-static-methods=false;</additionalCompilerOptions>
```
-### Prevent renaming of internal instance methods {#prevent-rename-internal-instance-methods}
+### prevent-rename-internal-instance-methods {#prevent-rename-internal-instance-methods}
In a release build, determines if instance (non-static) methods in the `internal` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-internal-symbols` compiler option is `false`.
@@ -869,7 +859,7 @@
<additionalCompilerOptions>-prevent-rename-internal-instance-methods=false;</additionalCompilerOptions>
```
-### Prevent renaming of internal static variables {#prevent-rename-internal-static-variables}
+### prevent-rename-internal-static-variables {#prevent-rename-internal-static-variables}
In a release build, determines if static variables in the `internal` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-internal-symbols` compiler option is `false`.
@@ -885,7 +875,7 @@
<additionalCompilerOptions>-prevent-rename-static-variables=false;</additionalCompilerOptions>
```
-### Prevent renaming of internal instance variables {#prevent-rename-internal-instance-variables}
+### prevent-rename-internal-instance-variables {#prevent-rename-internal-instance-variables}
In a release build, determines if instance (non-static) variables in the `internal` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-internal-symbols` compiler option is `false`.
@@ -901,7 +891,7 @@
<additionalCompilerOptions>-prevent-rename-internal-instance-variables=false;</additionalCompilerOptions>
```
-### Prevent renaming of internal static accessors {#prevent-rename-internal-static-accessors}
+### prevent-rename-internal-static-accessors {#prevent-rename-internal-static-accessors}
In a release build, determines if static accessors (getters and setters) in the `internal` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-internal-symbols` compiler option is `false`.
@@ -917,7 +907,7 @@
<additionalCompilerOptions>-prevent-rename-static-accessors=false;</additionalCompilerOptions>
```
-### Prevent renaming of internal instance accessors {#prevent-rename-internal-instance-accessors}
+### prevent-rename-internal-instance-accessors {#prevent-rename-internal-instance-accessors}
In a release build, determines if instance (non-static) accessors (getters and setters) in the `internal` namespace may be renamed or not. The default value is `true`. This option will be ignored if the `prevent-rename-internal-symbols` compiler option is `false`.
diff --git a/compiler/release-build-file-size-optimization.md b/compiler/release-build-file-size-optimization.md
new file mode 100644
index 0000000..5937065
--- /dev/null
+++ b/compiler/release-build-file-size-optimization.md
@@ -0,0 +1,78 @@
+---
+# 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: Release build file size optimization
+description: How to reduce the size of release builds
+permalink: /compiler/release-build-file-size-optimization
+---
+# Release build file size optimization
+
+Reduce the size of release builds
+
+A number of [compiler options](compiler/compiler-options) are available for Royale that allow you to reduce the output size of JavaScript release builds. However, using these options may also prevent certain coding patterns in ActionScript and JavaScript (such as reflection capabilities) from working correctly, so read carefully to understand what the tradeoffs are for enabling these options and whether it will affect how you must write your code.
+
+There are two main ways to reduce the size of a release build:
+
+- Disabling exported symbols to external JavaScript
+- Allowing symbols to be renamed as part of minification
+
+A symbol, in this case, is a class, an interface, a field, or a method. It is possible to control these settings based on a symbol's namespace, such as `public`, `protected`, or `internal`. Symbols that are `private` are never exported and may be renamed.
+
+> These options are available when compiling a release build of an _application_ with the **mxmlc** compiler. They are not supported when compiling a _library_ with the **compc** compiler. Libraries are always compiled as debug builds when targeting JavaScript, and they will be optimized later, if they are included in an application's release build.
+
+## Disable exported symbols
+
+If a symbol is _exported_, it may be accessed by external JavaScript `<script>` elements in the same page. If a symbol is not exported, and it is not referenced elsewhere in the Royale project, the compiler may determine that it is "dead code" that should be removed from a release build.
+
+If external JavaScript never needs to access variables or call functions exposed by your Royale application, it should be safe to disable export of symbols.
+
+The following options are available to control whether symbols are exported or not. Symbols that are `private` are never exported.
+
+- [`-export-public-symbols`](compiler/compiler-options#export-public-symbols)
+- [`-export-protected-symbols`](compiler/compiler-options#export-protected-symbols)
+- [`-export-internal-symbols`](compiler/compiler-options#export-internal-symbols)
+
+## Allow renaming of symbols
+
+When you prevent the compiler from renaming a symbol in a minifinied release build, the symbol may be accessed using dynamic string access, such as `object["myProperty"]`. If a symbol is allowed to be renamed, the compiler may determine that it can change the name of the symbol to a shorter value to reduce the size of the release build. If a symbol is renamed, dynamic string access will not be possible without knowing the new name of the symbol.
+
+The following [compiler options](compiler/compiler-options) are available to control whether symbols may be renamed or not, based on the namespace.
+
+- [`-prevent-rename-public-symbols`](compiler/compiler-options#prevent-rename-public-symbols)
+- [`-prevent-rename-protected-symbols`](compiler/compiler-options#prevent-rename-protected-symbols)
+- [`-prevent-rename-internal-symbols`](compiler/compiler-options#prevent-rename-internal-symbols)
+
+Additionally, several more granular [compiler options](compiler/compiler-options) are available to prevent or allow certain _categories_ of symbols to be renamed.
+
+- [`prevent-rename-public-static-methods`](compiler/compiler-options.html#prevent-rename-public-static-methods)
+- [`prevent-rename-public-instance-methods`](compiler/compiler-options.html#prevent-rename-public-instance-methods)
+- [`prevent-rename-public-static-variables`](compiler/compiler-options.html#prevent-rename-public-static-variables)
+- [`prevent-rename-public-instance-variables`](compiler/compiler-options.html#prevent-rename-public-instance-variables)
+- [`prevent-rename-public-static-accessors`](compiler/compiler-options.html#prevent-rename-public-static-accessors)
+- [`prevent-rename-public-instance-accessors`](compiler/compiler-options.html#prevent-rename-public-instance-accessors)
+- [`prevent-rename-protected-static-methods`](compiler/compiler-options.html#prevent-rename-protected-static-methods)
+- [`prevent-rename-protected-instance-methods`](compiler/compiler-options.html#prevent-rename-protected-instance-methods)
+- [`prevent-rename-protected-static-variables`](compiler/compiler-options.html#prevent-rename-protected-static-variables)
+- [`prevent-rename-protected-instance-variables`](compiler/compiler-options.html#prevent-rename-protected-instance-variables)
+- [`prevent-rename-protected-static-accessors`](compiler/compiler-options.html#prevent-rename-protected-static-accessors)
+- [`prevent-rename-protected-instance-accessors`](compiler/compiler-options.html#prevent-rename-protected-instance-accessors)
+- [`prevent-rename-internal-static-methods`](compiler/compiler-options.html#prevent-rename-internal-static-methods)
+- [`prevent-rename-internal-instance-methods`](compiler/compiler-options.html#prevent-rename-internal-instance-methods)
+- [`prevent-rename-internal-static-variables`](compiler/compiler-options.html#prevent-rename-internal-static-variables)
+- [`prevent-rename-internal-instance-variables`](compiler/compiler-options.html#prevent-rename-internal-instance-variables)
+- [`prevent-rename-internal-static-accessors`](compiler/compiler-options.html#prevent-rename-internal-static-accessors)
+- [`prevent-rename-internal-instance-accessors`](compiler/compiler-options.html#prevent-rename-internal-instance-accessors)
\ No newline at end of file
