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 2019/12/31 15:03:18 UTC
[royale-docs] branch master updated: improve optimization page
layout and add -js-dynamic-access-unknown-members to docs
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 d3d3366 improve optimization page layout and add -js-dynamic-access-unknown-members to docs
d3d3366 is described below
commit d3d33667c4381b09cee53db4410f5af3c208a933
Author: Carlos Rovira <ca...@apache.org>
AuthorDate: Tue Dec 31 16:03:07 2019 +0100
improve optimization page layout and add -js-dynamic-access-unknown-members to docs
---
.../compiler-configuration-settings.md | 117 +++++++++++----------
1 file changed, 60 insertions(+), 57 deletions(-)
diff --git a/create-an-application/optimizations/compiler-configuration-settings.md b/create-an-application/optimizations/compiler-configuration-settings.md
index 34823d4..7a912dd 100644
--- a/create-an-application/optimizations/compiler-configuration-settings.md
+++ b/create-an-application/optimizations/compiler-configuration-settings.md
@@ -19,44 +19,46 @@ title: Compiler configuration settings
description: Compiler configuration settings
permalink: create-an-application/optimizations/compiler-configuration-settings
---
-## (Optimization options)
+
# Compiler configuration settings
-Warning: This document is a work-in-progress/undergoing review.
+Optimization options
-Definitions:
-AVM
-: Actionscript Virtual Machine. You can also broadly interpret this to mean 'SWF at runtime', the 'flash player' or 'Adobe AIR runtime'.
+The following content explains optimizations for javascript output that you can use when configuring the Royale compiler directly. Often these settings involve removing some javascript emulations of runtime type-safety that are present in AVM.
-The following content explains optimizations for javascript output that you can use when configuring the Royale compiler directly.
-Often these settings involve removing some javascript emulations of runtime type-safety that are present in AVM.
-It can be useful to develop your application with these settings 'on' and then consider 'switching them off' for your release build when you have assured yourself it is safe to do so.
-This can help to improve performance and/or reduce the size of your final application build.
-These settings can be provided on the commandline or via royale-config.xml, or via the additionalOptions tag for compiler in maven's pom.xml.
+It can be useful to develop your application with these settings 'on' and then consider 'switching them off' for your release build when you have assured yourself it is safe to do so.
-|[Initialization of default values](create-an-application/optimizations/compiler-configuration-settings.html#default-initializers) |
-|[Implict Coercions of non-primitive types](create-an-application/optimizations/compiler-configuration-settings.html#implicit-complex-coercions) |
-|[Parity for strict equality comparisons](create-an-application/optimizations/compiler-configuration-settings.html#strict-equality-comparisons) |
-|[Vector Index Checking](create-an-application/optimizations/compiler-configuration-settings.html#vector-index-checking) |
+This can help to improve performance and/or reduce the size of your final application build. These settings can be provided on the commandline or via royale-config.xml, or via the additionalOptions tag for compiler in maven's pom.xml.
-* * *
-### Default initializers {#default-initializers}
-#### -js-default-initializers (this setting is true by default)
+## Available Options:
-This corresponds to AVM runtime implicit type intialization values, in particular for primitive types.
-Note that some reflection utility functions require this to be true in order for them to work correctly in javascript.
+- [Initialization of default values](create-an-application/optimizations/compiler-configuration-settings.html#default-initializers)
+- [Implict Coercions of non-primitive types](create-an-application/optimizations/compiler-configuration-settings.html#implicit-complex-coercions)
+- [Parity for strict equality comparisons](create-an-application/optimizations/compiler-configuration-settings.html#strict-equality-comparisons)
+- [Vector Index Checking](create-an-application/optimizations/compiler-configuration-settings.html#vector-index-checking)
+- [Dynamic access unknown members](create-an-application/optimizations/compiler-configuration-settings.html#dynamic-access-unknown-members)
+
+## Definitions:
+
+**AVM:** Actionscript Virtual Machine. You can also broadly interpret this to mean 'SWF at runtime', the 'flash player' or 'Adobe AIR runtime'.
->Todo: This content is yet to be created
+## Default initializers {#default-initializers}
+
+**-js-default-initializers**
+
+Defaults to true. Corresponds to AVM runtime implicit type intialization values, in particular for primitive types.
+Note that some reflection utility functions require this to be true in order for them to work correctly in javascript.
+_Todo: This content is yet to be created_
+## Implict Coercions of non-primitive types {#implicit-complex-coercions}
-* * *
-### Implict Coercions of non-primitive types {#implicit-complex-coercions}
-#### -js-complex-implicit-coercions (this setting is true by default)
+**-js-complex-implicit-coercions**
-This corresponds to AVM runtime implicit type coercions for non-primitive types (anything that is not a Number, int, uint, String, Boolean) and is not being cast to something that is untyped (__*__ type) or loosely typed, e.g. of **Object** type.
+Defaults to true. This corresponds to AVM runtime implicit type coercions for non-primitive types (anything that is not a Number, int, uint, String, Boolean) and is not being cast to something that is untyped (__*__ type) or loosely typed, e.g. of **Object** type.
An (overly simplistic) example would be:
+
```as3
var cat:Cat = new Cat();
var myCats:Array = [cat];
@@ -67,30 +69,24 @@ var myCats:Array = [cat];
var dog:Dog = myCats[0];
```
-With *-js-complex-implicit-coercions=true* (the default setting), the above example will behave the same in javascript at runtime as it would in AVM.
-However supporting this runtime behavior does generate extra type-checking code to achieve that result.
-In most cases this extra code can be eliminated in the output after the application has been validated to be error-free at runtime.
-There may however be cases with legacy actionscript that depend on error-handling for these situations and where refactoring that aspect is not a priority.
-In these cases it can be left on in the release build, or there is also the option to switch it off in general but force it to remain on for specific code scope, for example, using [@royalesuppresscompleximplicitcoercion](create-an-application/optimizations/doc-comment-directives.html#royalesuppresscompleximplicitcoercion).
+With true (the default setting), the above example will behave the same in javascript at runtime as it would in AVM. However supporting this runtime behavior does generate extra type-checking code to achieve that result.
+
+In most cases this extra code can be eliminated in the output after the application has been validated to be error-free at runtime. There may however be cases with legacy actionscript that depend on error-handling for these situations and where refactoring that aspect is not a priority. In these cases it can be left on in the release build, or there is also the option to switch it off in general but force it to remain on for specific code scope, for example, using [@royalesuppresscomplex [...]
+
+Does this feature always catch implicit complex coercions? No, currently there can still be cases which are missing this level of runtime type safety. Notably this can occur in the processing of mxml instances or binding support.
-Does this feature always catch implicit complex coercions?
-No, currently there can still be cases which are missing this level of runtime type safety.
-Notably this can occur in the processing of mxml instances or binding support.
+**Pro tip:** How do I know how much of my code is being affected by this setting? In the javascript **js‑debug** output, you can do a ***search in files*** for the string **/* implicit cast */** which precedes the compiler-generated code the to support this parity with AVM. That will show you all the sites where it is being output. As with all other code, this can be minimized in the js-release output, but as mentioned earlier, if the application does not have runtime errors, then [...]
-#### Pro tip:
-How do I know how much of my code is being affected by this setting?
-In the javascript **js‑debug** output, you can do a ***search in files*** for the string **/* implicit cast */** which precedes the compiler-generated code the to support this parity with AVM.
-That will show you all the sites where it is being output. As with all other code, this can be minimized in the js-release output, but as mentioned earlier, if the application does not have runtime errors, then the performance of the application could be optimized by eliminating these checks.
+## Parity for strict equality comparisons {#strict-equality-comparisons}
-* * *
-### Parity for strict equality comparisons {#strict-equality-comparisons}
-#### -js-resolve-uncertain (this setting is true by default)
+**-js-resolve-uncertain**
This is a relatively rare as3 language parity feature that is applied by the compiler when instantiating an unknown class.
It ensures greater compatibility between AVM and javascript, in particular for strict equality comparisons.
This is not just important for the binary operators like `===` or `!==`, but also for things like `Array.indexOf`, which uses strict equality for checking.
-An (overly simplistic) example would be:
+An (overly simplistic) example would be:
+
```as3
var clazz:Class = String;
var test:Array = ['test', new clazz(30.5)];
@@ -100,21 +96,24 @@ var idx:int = test.indexOf('30.5');
//in javscript, with js-resolve-uncertain=false, it would be -1 (incorrect)
```
-In most cases this setting is probably not going to cause performance issues. But it does add a small amount of extra overhead in both size and performance.
-The main variations to cover are the primitive types: **Number**, **String**, **Boolean** etc., as well as synthetic types for **int** and **uint**.
+In most cases this setting is probably not going to cause performance issues. But it does add a small amount of extra overhead in both size and performance.
+
+The main variations to cover are the primitive types: **Number**, **String**, **Boolean** etc., as well as synthetic types for **int** and **uint**.
+
So it can be switched off if after testing it is deemed safe to do so.
Or it can be specifically avoided or explicitly switched on in specific areas of code with [@royalesuppressresolveuncertain](create-an-application/optimizations/doc-comment-directives.html#royalesuppressresolveuncertain).
-***Pro tip:***
-How do I know how much of my code is being affected by this setting?
+**Pro tip:** How do I know how much of my code is being affected by this setting?
In javascript the **js‑debug** output, you can do a ***search in files*** for the string **Language.resolveUncertain**
-* * *
-### Vector index checking {#vector-index-checking}
-#### -js-vector-index-checks (this setting is true by default)
-This corresponds to AVM runtime checking during Vector index assignments (*note:* currently only for assignment, not access)
+## Vector index checking {#vector-index-checking}
+
+**-js-vector-index-checks**
+
+Defaults to true. This corresponds to AVM runtime checking during Vector index assignments (*note:* currently only for assignment, not access)
+
+An (overly simplistic) example would be:
-An (overly simplistic) example would be:
```as3
var myVec:Vector.<Number> = new Vector.<Number>();
myVec[1] = 2;
@@ -125,6 +124,7 @@ myVec[1] = 2;
```
or:
+
```as3
myVec = new Vector.<Number>(20,true); //create a fixed length Vector, with indices 0 to 19.
myVec[20] = 2;
@@ -134,10 +134,8 @@ myVec[20] = 2;
//In this case the length is 20, and the only assignment can be to indices 0 to 19
```
-With *-js-vector-index-checks=true* (the default setting), the above 2 examples will behave the same in javascript at runtime as they would in AVM and in both cases generate a runtime error.
-However supporting this runtime behavior does generate extra code to achieve that result.
-In most cases it could be avoided to assist with performance. This is particularly relevant when index level assignments are made inside a loop.
-Often the loop variable is used as the index for the value assignment, and in this case, it is usually already certain to be within the valid range for the targetted Vector instance.
+With true (the default setting), the above 2 examples will behave the same in javascript at runtime as they would in AVM and in both cases generate a runtime error. However supporting this runtime behavior does generate extra code to achieve that result. In most cases it could be avoided to assist with performance. This is particularly relevant when index level assignments are made inside a loop. Often the loop variable is used as the index for the value assignment, and in this case, it [...]
+
For example:
```as3
@@ -154,12 +152,17 @@ In the above example, the compiler will by default be generating something in ja
Where `myVec.checkIndex(i)` in the pseudocode checks that `i` is in the valid range for myVec, and returns it unchanged if it is, otherwise throws an error that corresponds to what would happen at runtime in AVM.
This is obviously not needed in the above case, and will definitely slow the loop down, so for performance reasons it is important to remove this generated code for large loops.
+
So once everything has been verified to work correctly in your app, it is often a good idea to switch off the generation of this type of code.
As with other settings it is possible to switch it off or on with more specificity by using [doc comment directives](create-an-application/optimizations/doc-comment-directives.html).
If you are porting legacy as3 code, it can be useful to check that the code does not rely on error trapping for any of these cases before switching this setting off.
-***Pro tip:***
-How do I know how much of my code is being affected by this setting?
-In javascript the **js‑debug** output, you can do a ***search in files*** for the string **Language.CHECK_INDEX**
-* * *
+**Pro tip:** How do I know how much of my code is being affected by this setting? In javascript the **js‑debug** output, you can do a ***search in files*** for the string **Language.CHECK_INDEX**
+
+## Dynamic access unknown members {#dynamic-access-unknown-members}
+
+**-js-dynamic-access-unknown-members**
+
+When using plain objects the release version will try to "minify" renaming field names. Adding that option will make your code larger.
+Using data class definition instead of plain objects in all cases will defeat the need to use this option. Adding data classes will also make your code bigger, but it can also make it smaller depending on how many accesses there are to the object's properties. But data classes will also get compiler checking that you didn't mis-type a property name and various data-binding warnings will go away, which should improve your productivity.