You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@royale.apache.org by ha...@apache.org on 2021/12/14 12:38:59 UTC
[royale-docs] branch master updated: SWC creation instructions
This is an automated email from the ASF dual-hosted git repository.
harbs 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 929977d SWC creation instructions
929977d is described below
commit 929977d5aa680602a99bd4fa1447379170ba9d13
Author: Harbs <ha...@in-tools.com>
AuthorDate: Tue Dec 14 14:38:48 2021 +0200
SWC creation instructions
---
libraries/compiled-code-libraries.md | 295 +++++++++++++++++++++++++++++++++++
libraries/library-basics.md | 2 +-
2 files changed, 296 insertions(+), 1 deletion(-)
diff --git a/libraries/compiled-code-libraries.md b/libraries/compiled-code-libraries.md
new file mode 100644
index 0000000..5fc5943
--- /dev/null
+++ b/libraries/compiled-code-libraries.md
@@ -0,0 +1,295 @@
+---
+# 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: Compiled Code Libraries
+description: What are libraries in Royale
+permalink: /libraries/compiled-code-libraries
+---
+
+# Compiled Code Libraries
+
+Instructions on creating your own SWC libraries
+
+## Prerequisites
+Creating SWCs requires the full Royale SDK to be installed. The js-only version is not enough because the SWC contains a SWF file which can only be generated by the full SDK.
+
+## Concepts
+
+On the most basic level, SWC libraries are just compiled ActionScript classes. You need to include the necessary classes and the code will be included in your compiled SWC.
+
+Libraries can also declare components that can be used in MXML files by referencing a namespace.
+
+In this example, we're going to assume that you have both code and components to include.
+
+We're also going to use [asconfigc](https://github.com/BowlerHatLLC/vscode-as3mxml/wiki/asconfig.json) to build the library.
+
+## Building blocks
+There are several files you will likely use for creating libraries.
+
+1. manifest.xml
+2. MyLibrary.as
+3. defaults.css
+4. compile-config.xml
+5. js-compile-config.xml
+6. asconfig.json
+
+## The Manifest
+The manifest file (in our example named `manifest.xml`) is the file where you declare the components you want to make available to MXML using your namespace.
+
+A manifest file is a very simple xml file with the following structure:
+
+```
+<?xml version="1.0"?>
+<componentPackage>
+ <component id="MyComponent1" class="com.somesite.MyComponent1"/>
+ <component id="MyComponent2" class="com.somesite.MyComponent2"/>
+</componentPackage>
+
+```
+Where the `id` of each component is the qualified name you declare in MXML and the `class` is the fully qualified class path of your class.
+
+The namespace for your manifest is declared in `compile-config.xml` and `js-compile-config.xml` below.
+
+## The main class file
+In order for classes to be included in your SWC, you need to actually use them somewhere. Any classes which are declared in your manifest are considered "used", and they along with all their dependencies will be included. However, there will likely be other classes and utility functions which are not in the manifest that you want to include. The simplest solution for this is to have a Class which references all the classes you want included. To do this, you include `MyLibrary.as` at the [...]
+
+```
+package {
+
+ internal class MyLibrary {
+ import com.somesite.ClassA;ClassA;
+ import com.somesite.ClassB;ClassB;
+ import com.somesite.ClassC;ClassC;
+ import com.somesite.ClassD;ClassD;
+ }
+}
+
+```
+Just referencing the classes like that is enough to have them included.
+
+## The CSS file
+`defaults.css` is where you declare any HTML or Royale CSS that's needed for your library. This is where you declare default beads and the like. Make sure you declare your namespace that's used for the MXML declarations of you components.
+
+```
+@namespace "library://ns.somesite.com/kapow";
+@namespace js "library://ns.apache.org/royale/basic";
+
+MyComponent1
+{
+ IBeadModel: ClassReference("com.somesite.ComponentModel");
+ IBeadView: ClassReference("com.somesite.ComponentView");
+ IBeadController: ClassReference("com.somesite.ComponentController");
+}
+
+```
+## Config XML file
+The config file is a convenience file for loading compiler options. It's very helpful for libraries where you need to declare quite a bit of information. You need one config for the SWF build and another one for the JS build. The two files are quite similar.
+
+The notable difference between the two files:
+1. `compile-config.xml` has `playerglobal.swc` referenced in the `external-library-path`.
+2. `compile-config.xml` has `COMPILE::SWF` as `true` while `js-compile-config.xml` has `COMPILE::JS` as `true`.
+3. If you have a `lib/Foo.swc` JS typedef dependency that you want to include, you should add the following to the `js-compile-config.xml`:
+```
+ <js-external-library-path append="true">
+ <path-element>lib/Foo.swc</path-element>
+ </js-external-library-path>
+
+```
+
+
+`compile-config.xml`:
+```
+<royale-config>
+ <compiler>
+ <accessible>false</accessible>
+
+ <external-library-path>
+ <path-element>playerglobal.swc</path-element>
+ </external-library-path>
+ <allow-subclass-overrides>true</allow-subclass-overrides>
+
+ <mxml>
+ <children-as-data>true</children-as-data>
+ </mxml>
+ <binding-value-change-event>org.apache.royale.events.ValueChangeEvent</binding-value-change-event>
+ <binding-value-change-event-kind>org.apache.royale.events.ValueChangeEvent</binding-value-change-event-kind>
+ <binding-value-change-event-type>valueChange</binding-value-change-event-type>
+
+ <define>
+ <name>COMPILE::SWF</name>
+ <value>true</value>
+ </define>
+ <define>
+ <name>COMPILE::JS</name>
+ <value>false</value>
+ </define>
+
+ <keep-as3-metadata>
+ <name>Bindable</name>
+ <name>Managed</name>
+ <name>ChangeEvent</name>
+ <name>NonCommittingChangeEvent</name>
+ <name>Transient</name>
+ </keep-as3-metadata>
+
+ <locale/>
+
+ <library-path/>
+
+ <namespaces>
+ <namespace>
+ <uri>library://ns.somesite.com/kapow</uri>
+ <manifest>manifest.xml</manifest>
+ </namespace>
+ </namespaces>
+
+ <source-path>
+ <path-element>src</path-element>
+ </source-path>
+
+ <warn-no-constructor>false</warn-no-constructor>
+ </compiler>
+ <include-file>
+ <name>defaults.css</name>
+ <path>defaults.css</path>
+ </include-file>
+
+ <include-classes>
+ <class>MyLibrary</class>
+ </include-classes>
+
+ <include-namespaces>
+ <uri>library://ns.somesite.com/kapow</uri>
+ </include-namespaces>
+
+</royale-config>
+
+```
+
+`js-compile-config.xml`:
+```
+<royale-config>
+
+ <compiler>
+ <accessible>false</accessible>
+
+ <js-external-library-path append="true">
+ <path-element>lib/Foo.swc</path-element>
+ </js-external-library-path>
+ <allow-subclass-overrides>true</allow-subclass-overrides>
+
+ <mxml>
+ <children-as-data>true</children-as-data>
+ </mxml>
+ <binding-value-change-event>org.apache.royale.events.ValueChangeEvent</binding-value-change-event>
+ <binding-value-change-event-kind>org.apache.royale.events.ValueChangeEvent</binding-value-change-event-kind>
+ <binding-value-change-event-type>valueChange</binding-value-change-event-type>
+
+ <define>
+ <name>COMPILE::SWF</name>
+ <value>false</value>
+ </define>
+ <define>
+ <name>COMPILE::JS</name>
+ <value>true</value>
+ </define>
+
+ <keep-as3-metadata>
+ <name>Bindable</name>
+ <name>Managed</name>
+ <name>ChangeEvent</name>
+ <name>NonCommittingChangeEvent</name>
+ <name>Transient</name>
+ </keep-as3-metadata>
+
+ <locale/>
+
+ <library-path/>
+
+ <namespaces>
+ <namespace>
+ <uri>library://ns.somesite.com/kapow</uri>
+ <manifest>manifest.xml</manifest>
+ </namespace>
+ </namespaces>
+
+ <source-path>
+ <path-element>src</path-element>
+ </source-path>
+
+ <warn-no-constructor>false</warn-no-constructor>
+ </compiler>
+ <include-file>
+ <name>defaults.css</name>
+ <path>defaults.css</path>
+ </include-file>
+
+ <include-classes>
+ <class>MyLibrary</class>
+ </include-classes>
+
+ <include-namespaces>
+ <uri>library://ns.somesite.com/kapow</uri>
+ </include-namespaces>
+
+</royale-config>
+
+```
+
+## Building the library
+You asconfig.json file should look like this:
+
+```
+{
+ "config": "royale",
+ "type": "lib",
+ "compilerOptions": {
+ "targets": [
+ "JSRoyale"
+ ],
+ "external-library-path": [
+ "${royalelib}/libs",
+ "${royalelib}/../js/libs",
+ "libs"
+ ],
+ "js-external-library-path": [
+ "${royalelib}/js/libs",
+ "${royalelib}/../js/libs",
+ "libs"
+ ],
+ "load-config": [
+ "compile-config.xml"
+ ],
+ "js-load-config": [
+ "js-compile-config.xml"
+ ],
+ "include-classes": [
+ "MyLibrary"
+ ],
+ "include-sources": [
+ "src"
+ ],
+ "source-path": [
+ "src"
+ ],
+ "output": "target/MyLibrary.swc"
+ },
+ "additionalOptions":[
+ //include any options you want here
+ ]
+}
+```
\ No newline at end of file
diff --git a/libraries/library-basics.md b/libraries/library-basics.md
index fc3c3ab..0b655e9 100644
--- a/libraries/library-basics.md
+++ b/libraries/library-basics.md
@@ -39,7 +39,7 @@ There is no obvious way to tell the difference. Both have a `.swc` extension, al
### Compiled Code Libraries
Compiled code libraries are libraries which contain code that will end up in your compiled application (assuming you use that code). These can be code that you might use internally across multiple projects, or it can be a library that was compiled by someone else. Much of the Royale framework is compiled into `swc` files that are used in applications.
-Compiled code libraries are created using the `compc` compiler. (TODO add sample configs for doing this)
+Compiled code libraries are created using the `compc` compiler. [See here for detailed instructions on how to create one.](compiled-code-libraries)
### Typedef libraries
Typedef libraries are libraries which define the types of different classes, but contain no code that would be added to an application. Typedef libraries are used for core Web APIs and third party javascript libraries which could be included in applications as separate javascript files (such as jQuery). Typedef libraries are similar to Typescript `d.ts` files.
Re: [royale-docs] branch master updated: SWC creation instructions
Posted by Harbs <ha...@gmail.com>.
OK. I’ll remove that comment. I’m pretty sure it used to work like that, but things have definitely improved over the years.
> On Dec 14, 2021, at 7:05 PM, Josh Tynjala <jo...@bowlerhat.dev> wrote:
>
>> Creating SWCs requires the full Royale SDK to be installed. The js-only
> version is not enough because the SWC contains a SWF file which can only be
> generated by the full SDK.
>
> This doesn't seem right to me. You should be able to create a JS-only .swc
> file without the full SDK. The JS-only SDK still includes the SWF compiler.
> It's just the .swc libraries for SWF that are excluded from the full SDK.
> The compiler binaries should be exactly the same between both SDKs.
>
> --
> Josh Tynjala
> Bowler Hat LLC <https://bowlerhat.dev>
>
>
> On Tue, Dec 14, 2021 at 4:39 AM <ha...@apache.org> wrote:
>
>> This is an automated email from the ASF dual-hosted git repository.
>>
>> harbs 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 929977d SWC creation instructions
>> 929977d is described below
>>
>> commit 929977d5aa680602a99bd4fa1447379170ba9d13
>> Author: Harbs <ha...@in-tools.com>
>> AuthorDate: Tue Dec 14 14:38:48 2021 +0200
>>
>> SWC creation instructions
>> ---
>> libraries/compiled-code-libraries.md | 295
>> +++++++++++++++++++++++++++++++++++
>> libraries/library-basics.md | 2 +-
>> 2 files changed, 296 insertions(+), 1 deletion(-)
>>
>> diff --git a/libraries/compiled-code-libraries.md
>> b/libraries/compiled-code-libraries.md
>> new file mode 100644
>> index 0000000..5fc5943
>> --- /dev/null
>> +++ b/libraries/compiled-code-libraries.md
>> @@ -0,0 +1,295 @@
>> +---
>> +# 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: Compiled Code Libraries
>> +description: What are libraries in Royale
>> +permalink: /libraries/compiled-code-libraries
>> +---
>> +
>> +# Compiled Code Libraries
>> +
>> +Instructions on creating your own SWC libraries
>> +
>> +## Prerequisites
>> +Creating SWCs requires the full Royale SDK to be installed. The js-only
>> version is not enough because the SWC contains a SWF file which can only be
>> generated by the full SDK.
>> +
>> +## Concepts
>> +
>> +On the most basic level, SWC libraries are just compiled ActionScript
>> classes. You need to include the necessary classes and the code will be
>> included in your compiled SWC.
>> +
>> +Libraries can also declare components that can be used in MXML files by
>> referencing a namespace.
>> +
>> +In this example, we're going to assume that you have both code and
>> components to include.
>> +
>> +We're also going to use [asconfigc](
>> https://github.com/BowlerHatLLC/vscode-as3mxml/wiki/asconfig.json) to
>> build the library.
>> +
>> +## Building blocks
>> +There are several files you will likely use for creating libraries.
>> +
>> +1. manifest.xml
>> +2. MyLibrary.as
>> +3. defaults.css
>> +4. compile-config.xml
>> +5. js-compile-config.xml
>> +6. asconfig.json
>> +
>> +## The Manifest
>> +The manifest file (in our example named `manifest.xml`) is the file where
>> you declare the components you want to make available to MXML using your
>> namespace.
>> +
>> +A manifest file is a very simple xml file with the following structure:
>> +
>> +```
>> +<?xml version="1.0"?>
>> +<componentPackage>
>> + <component id="MyComponent1" class="com.somesite.MyComponent1"/>
>> + <component id="MyComponent2" class="com.somesite.MyComponent2"/>
>> +</componentPackage>
>> +
>> +```
>> +Where the `id` of each component is the qualified name you declare in
>> MXML and the `class` is the fully qualified class path of your class.
>> +
>> +The namespace for your manifest is declared in `compile-config.xml` and
>> `js-compile-config.xml` below.
>> +
>> +## The main class file
>> +In order for classes to be included in your SWC, you need to actually use
>> them somewhere. Any classes which are declared in your manifest are
>> considered "used", and they along with all their dependencies will be
>> included. However, there will likely be other classes and utility functions
>> which are not in the manifest that you want to include. The simplest
>> solution for this is to have a Class which references all the classes you
>> want included. To do this, you include `MyLibrary.as` at the [...]
>> +
>> +```
>> +package {
>> +
>> + internal class MyLibrary {
>> + import com.somesite.ClassA;ClassA;
>> + import com.somesite.ClassB;ClassB;
>> + import com.somesite.ClassC;ClassC;
>> + import com.somesite.ClassD;ClassD;
>> + }
>> +}
>> +
>> +```
>> +Just referencing the classes like that is enough to have them included.
>> +
>> +## The CSS file
>> +`defaults.css` is where you declare any HTML or Royale CSS that's needed
>> for your library. This is where you declare default beads and the like.
>> Make sure you declare your namespace that's used for the MXML declarations
>> of you components.
>> +
>> +```
>> +@namespace "library://ns.somesite.com/kapow";
>> +@namespace js "library://ns.apache.org/royale/basic";
>> +
>> +MyComponent1
>> +{
>> + IBeadModel: ClassReference("com.somesite.ComponentModel");
>> + IBeadView: ClassReference("com.somesite.ComponentView");
>>
>> + IBeadController:
>> ClassReference("com.somesite.ComponentController");
>> +}
>> +
>> +```
>> +## Config XML file
>> +The config file is a convenience file for loading compiler options. It's
>> very helpful for libraries where you need to declare quite a bit of
>> information. You need one config for the SWF build and another one for the
>> JS build. The two files are quite similar.
>> +
>> +The notable difference between the two files:
>> +1. `compile-config.xml` has `playerglobal.swc` referenced in the
>> `external-library-path`.
>> +2. `compile-config.xml` has `COMPILE::SWF` as `true` while
>> `js-compile-config.xml` has `COMPILE::JS` as `true`.
>> +3. If you have a `lib/Foo.swc` JS typedef dependency that you want to
>> include, you should add the following to the `js-compile-config.xml`:
>> +```
>> + <js-external-library-path append="true">
>> + <path-element>lib/Foo.swc</path-element>
>> + </js-external-library-path>
>> +
>> +```
>> +
>> +
>> +`compile-config.xml`:
>> +```
>> +<royale-config>
>> + <compiler>
>> + <accessible>false</accessible>
>> +
>> + <external-library-path>
>> + <path-element>playerglobal.swc</path-element>
>> + </external-library-path>
>> + <allow-subclass-overrides>true</allow-subclass-overrides>
>> +
>> + <mxml>
>> + <children-as-data>true</children-as-data>
>> + </mxml>
>> +
>> <binding-value-change-event>org.apache.royale.events.ValueChangeEvent</binding-value-change-event>
>> +
>> <binding-value-change-event-kind>org.apache.royale.events.ValueChangeEvent</binding-value-change-event-kind>
>> +
>> <binding-value-change-event-type>valueChange</binding-value-change-event-type>
>> +
>> + <define>
>> + <name>COMPILE::SWF</name>
>> + <value>true</value>
>> + </define>
>> + <define>
>> + <name>COMPILE::JS</name>
>> + <value>false</value>
>> + </define>
>> +
>> + <keep-as3-metadata>
>> + <name>Bindable</name>
>> + <name>Managed</name>
>> + <name>ChangeEvent</name>
>> + <name>NonCommittingChangeEvent</name>
>> + <name>Transient</name>
>> + </keep-as3-metadata>
>> +
>> + <locale/>
>> +
>> + <library-path/>
>> +
>> + <namespaces>
>> + <namespace>
>> + <uri>library://ns.somesite.com/kapow</uri>
>> + <manifest>manifest.xml</manifest>
>> + </namespace>
>> + </namespaces>
>> +
>> + <source-path>
>> + <path-element>src</path-element>
>> + </source-path>
>> +
>> + <warn-no-constructor>false</warn-no-constructor>
>> + </compiler>
>> + <include-file>
>> + <name>defaults.css</name>
>> + <path>defaults.css</path>
>> + </include-file>
>> +
>> + <include-classes>
>> + <class>MyLibrary</class>
>> + </include-classes>
>> +
>> + <include-namespaces>
>> + <uri>library://ns.somesite.com/kapow</uri>
>> + </include-namespaces>
>> +
>> +</royale-config>
>> +
>> +```
>> +
>> +`js-compile-config.xml`:
>> +```
>> +<royale-config>
>> +
>> + <compiler>
>> + <accessible>false</accessible>
>> +
>> + <js-external-library-path append="true">
>> + <path-element>lib/Foo.swc</path-element>
>> + </js-external-library-path>
>> + <allow-subclass-overrides>true</allow-subclass-overrides>
>> +
>> + <mxml>
>> + <children-as-data>true</children-as-data>
>> + </mxml>
>> +
>> <binding-value-change-event>org.apache.royale.events.ValueChangeEvent</binding-value-change-event>
>> +
>> <binding-value-change-event-kind>org.apache.royale.events.ValueChangeEvent</binding-value-change-event-kind>
>> +
>> <binding-value-change-event-type>valueChange</binding-value-change-event-type>
>> +
>> + <define>
>> + <name>COMPILE::SWF</name>
>> + <value>false</value>
>> + </define>
>> + <define>
>> + <name>COMPILE::JS</name>
>> + <value>true</value>
>> + </define>
>> +
>> + <keep-as3-metadata>
>> + <name>Bindable</name>
>> + <name>Managed</name>
>> + <name>ChangeEvent</name>
>> + <name>NonCommittingChangeEvent</name>
>> + <name>Transient</name>
>> + </keep-as3-metadata>
>> +
>> + <locale/>
>> +
>> + <library-path/>
>> +
>> + <namespaces>
>> + <namespace>
>> + <uri>library://ns.somesite.com/kapow</uri>
>> + <manifest>manifest.xml</manifest>
>> + </namespace>
>> + </namespaces>
>> +
>> + <source-path>
>> + <path-element>src</path-element>
>> + </source-path>
>> +
>> + <warn-no-constructor>false</warn-no-constructor>
>> + </compiler>
>> + <include-file>
>> + <name>defaults.css</name>
>> + <path>defaults.css</path>
>> + </include-file>
>> +
>> + <include-classes>
>> + <class>MyLibrary</class>
>> + </include-classes>
>> +
>> + <include-namespaces>
>> + <uri>library://ns.somesite.com/kapow</uri>
>> + </include-namespaces>
>> +
>> +</royale-config>
>> +
>> +```
>> +
>> +## Building the library
>> +You asconfig.json file should look like this:
>> +
>> +```
>> +{
>> + "config": "royale",
>> + "type": "lib",
>> + "compilerOptions": {
>> + "targets": [
>> + "JSRoyale"
>> + ],
>> + "external-library-path": [
>> + "${royalelib}/libs",
>> + "${royalelib}/../js/libs",
>> + "libs"
>> + ],
>> + "js-external-library-path": [
>> + "${royalelib}/js/libs",
>> + "${royalelib}/../js/libs",
>> + "libs"
>> + ],
>> + "load-config": [
>> + "compile-config.xml"
>> + ],
>> + "js-load-config": [
>> + "js-compile-config.xml"
>> + ],
>> + "include-classes": [
>> + "MyLibrary"
>> + ],
>> + "include-sources": [
>> + "src"
>> + ],
>> + "source-path": [
>> + "src"
>> + ],
>> + "output": "target/MyLibrary.swc"
>> + },
>> + "additionalOptions":[
>> + //include any options you want here
>> + ]
>> +}
>> +```
>> \ No newline at end of file
>> diff --git a/libraries/library-basics.md b/libraries/library-basics.md
>> index fc3c3ab..0b655e9 100644
>> --- a/libraries/library-basics.md
>> +++ b/libraries/library-basics.md
>> @@ -39,7 +39,7 @@ There is no obvious way to tell the difference. Both
>> have a `.swc` extension, al
>> ### Compiled Code Libraries
>> Compiled code libraries are libraries which contain code that will end up
>> in your compiled application (assuming you use that code). These can be
>> code that you might use internally across multiple projects, or it can be a
>> library that was compiled by someone else. Much of the Royale framework is
>> compiled into `swc` files that are used in applications.
>>
>> -Compiled code libraries are created using the `compc` compiler. (TODO add
>> sample configs for doing this)
>> +Compiled code libraries are created using the `compc` compiler. [See here
>> for detailed instructions on how to create one.](compiled-code-libraries)
>>
>> ### Typedef libraries
>> Typedef libraries are libraries which define the types of different
>> classes, but contain no code that would be added to an application. Typedef
>> libraries are used for core Web APIs and third party javascript libraries
>> which could be included in applications as separate javascript files (such
>> as jQuery). Typedef libraries are similar to Typescript `d.ts` files.
>>
Re: [royale-docs] branch master updated: SWC creation instructions
Posted by Josh Tynjala <jo...@bowlerhat.dev>.
> Creating SWCs requires the full Royale SDK to be installed. The js-only
version is not enough because the SWC contains a SWF file which can only be
generated by the full SDK.
This doesn't seem right to me. You should be able to create a JS-only .swc
file without the full SDK. The JS-only SDK still includes the SWF compiler.
It's just the .swc libraries for SWF that are excluded from the full SDK.
The compiler binaries should be exactly the same between both SDKs.
--
Josh Tynjala
Bowler Hat LLC <https://bowlerhat.dev>
On Tue, Dec 14, 2021 at 4:39 AM <ha...@apache.org> wrote:
> This is an automated email from the ASF dual-hosted git repository.
>
> harbs 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 929977d SWC creation instructions
> 929977d is described below
>
> commit 929977d5aa680602a99bd4fa1447379170ba9d13
> Author: Harbs <ha...@in-tools.com>
> AuthorDate: Tue Dec 14 14:38:48 2021 +0200
>
> SWC creation instructions
> ---
> libraries/compiled-code-libraries.md | 295
> +++++++++++++++++++++++++++++++++++
> libraries/library-basics.md | 2 +-
> 2 files changed, 296 insertions(+), 1 deletion(-)
>
> diff --git a/libraries/compiled-code-libraries.md
> b/libraries/compiled-code-libraries.md
> new file mode 100644
> index 0000000..5fc5943
> --- /dev/null
> +++ b/libraries/compiled-code-libraries.md
> @@ -0,0 +1,295 @@
> +---
> +# 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: Compiled Code Libraries
> +description: What are libraries in Royale
> +permalink: /libraries/compiled-code-libraries
> +---
> +
> +# Compiled Code Libraries
> +
> +Instructions on creating your own SWC libraries
> +
> +## Prerequisites
> +Creating SWCs requires the full Royale SDK to be installed. The js-only
> version is not enough because the SWC contains a SWF file which can only be
> generated by the full SDK.
> +
> +## Concepts
> +
> +On the most basic level, SWC libraries are just compiled ActionScript
> classes. You need to include the necessary classes and the code will be
> included in your compiled SWC.
> +
> +Libraries can also declare components that can be used in MXML files by
> referencing a namespace.
> +
> +In this example, we're going to assume that you have both code and
> components to include.
> +
> +We're also going to use [asconfigc](
> https://github.com/BowlerHatLLC/vscode-as3mxml/wiki/asconfig.json) to
> build the library.
> +
> +## Building blocks
> +There are several files you will likely use for creating libraries.
> +
> +1. manifest.xml
> +2. MyLibrary.as
> +3. defaults.css
> +4. compile-config.xml
> +5. js-compile-config.xml
> +6. asconfig.json
> +
> +## The Manifest
> +The manifest file (in our example named `manifest.xml`) is the file where
> you declare the components you want to make available to MXML using your
> namespace.
> +
> +A manifest file is a very simple xml file with the following structure:
> +
> +```
> +<?xml version="1.0"?>
> +<componentPackage>
> + <component id="MyComponent1" class="com.somesite.MyComponent1"/>
> + <component id="MyComponent2" class="com.somesite.MyComponent2"/>
> +</componentPackage>
> +
> +```
> +Where the `id` of each component is the qualified name you declare in
> MXML and the `class` is the fully qualified class path of your class.
> +
> +The namespace for your manifest is declared in `compile-config.xml` and
> `js-compile-config.xml` below.
> +
> +## The main class file
> +In order for classes to be included in your SWC, you need to actually use
> them somewhere. Any classes which are declared in your manifest are
> considered "used", and they along with all their dependencies will be
> included. However, there will likely be other classes and utility functions
> which are not in the manifest that you want to include. The simplest
> solution for this is to have a Class which references all the classes you
> want included. To do this, you include `MyLibrary.as` at the [...]
> +
> +```
> +package {
> +
> + internal class MyLibrary {
> + import com.somesite.ClassA;ClassA;
> + import com.somesite.ClassB;ClassB;
> + import com.somesite.ClassC;ClassC;
> + import com.somesite.ClassD;ClassD;
> + }
> +}
> +
> +```
> +Just referencing the classes like that is enough to have them included.
> +
> +## The CSS file
> +`defaults.css` is where you declare any HTML or Royale CSS that's needed
> for your library. This is where you declare default beads and the like.
> Make sure you declare your namespace that's used for the MXML declarations
> of you components.
> +
> +```
> +@namespace "library://ns.somesite.com/kapow";
> +@namespace js "library://ns.apache.org/royale/basic";
> +
> +MyComponent1
> +{
> + IBeadModel: ClassReference("com.somesite.ComponentModel");
> + IBeadView: ClassReference("com.somesite.ComponentView");
>
> + IBeadController:
> ClassReference("com.somesite.ComponentController");
> +}
> +
> +```
> +## Config XML file
> +The config file is a convenience file for loading compiler options. It's
> very helpful for libraries where you need to declare quite a bit of
> information. You need one config for the SWF build and another one for the
> JS build. The two files are quite similar.
> +
> +The notable difference between the two files:
> +1. `compile-config.xml` has `playerglobal.swc` referenced in the
> `external-library-path`.
> +2. `compile-config.xml` has `COMPILE::SWF` as `true` while
> `js-compile-config.xml` has `COMPILE::JS` as `true`.
> +3. If you have a `lib/Foo.swc` JS typedef dependency that you want to
> include, you should add the following to the `js-compile-config.xml`:
> +```
> + <js-external-library-path append="true">
> + <path-element>lib/Foo.swc</path-element>
> + </js-external-library-path>
> +
> +```
> +
> +
> +`compile-config.xml`:
> +```
> +<royale-config>
> + <compiler>
> + <accessible>false</accessible>
> +
> + <external-library-path>
> + <path-element>playerglobal.swc</path-element>
> + </external-library-path>
> + <allow-subclass-overrides>true</allow-subclass-overrides>
> +
> + <mxml>
> + <children-as-data>true</children-as-data>
> + </mxml>
> +
> <binding-value-change-event>org.apache.royale.events.ValueChangeEvent</binding-value-change-event>
> +
> <binding-value-change-event-kind>org.apache.royale.events.ValueChangeEvent</binding-value-change-event-kind>
> +
> <binding-value-change-event-type>valueChange</binding-value-change-event-type>
> +
> + <define>
> + <name>COMPILE::SWF</name>
> + <value>true</value>
> + </define>
> + <define>
> + <name>COMPILE::JS</name>
> + <value>false</value>
> + </define>
> +
> + <keep-as3-metadata>
> + <name>Bindable</name>
> + <name>Managed</name>
> + <name>ChangeEvent</name>
> + <name>NonCommittingChangeEvent</name>
> + <name>Transient</name>
> + </keep-as3-metadata>
> +
> + <locale/>
> +
> + <library-path/>
> +
> + <namespaces>
> + <namespace>
> + <uri>library://ns.somesite.com/kapow</uri>
> + <manifest>manifest.xml</manifest>
> + </namespace>
> + </namespaces>
> +
> + <source-path>
> + <path-element>src</path-element>
> + </source-path>
> +
> + <warn-no-constructor>false</warn-no-constructor>
> + </compiler>
> + <include-file>
> + <name>defaults.css</name>
> + <path>defaults.css</path>
> + </include-file>
> +
> + <include-classes>
> + <class>MyLibrary</class>
> + </include-classes>
> +
> + <include-namespaces>
> + <uri>library://ns.somesite.com/kapow</uri>
> + </include-namespaces>
> +
> +</royale-config>
> +
> +```
> +
> +`js-compile-config.xml`:
> +```
> +<royale-config>
> +
> + <compiler>
> + <accessible>false</accessible>
> +
> + <js-external-library-path append="true">
> + <path-element>lib/Foo.swc</path-element>
> + </js-external-library-path>
> + <allow-subclass-overrides>true</allow-subclass-overrides>
> +
> + <mxml>
> + <children-as-data>true</children-as-data>
> + </mxml>
> +
> <binding-value-change-event>org.apache.royale.events.ValueChangeEvent</binding-value-change-event>
> +
> <binding-value-change-event-kind>org.apache.royale.events.ValueChangeEvent</binding-value-change-event-kind>
> +
> <binding-value-change-event-type>valueChange</binding-value-change-event-type>
> +
> + <define>
> + <name>COMPILE::SWF</name>
> + <value>false</value>
> + </define>
> + <define>
> + <name>COMPILE::JS</name>
> + <value>true</value>
> + </define>
> +
> + <keep-as3-metadata>
> + <name>Bindable</name>
> + <name>Managed</name>
> + <name>ChangeEvent</name>
> + <name>NonCommittingChangeEvent</name>
> + <name>Transient</name>
> + </keep-as3-metadata>
> +
> + <locale/>
> +
> + <library-path/>
> +
> + <namespaces>
> + <namespace>
> + <uri>library://ns.somesite.com/kapow</uri>
> + <manifest>manifest.xml</manifest>
> + </namespace>
> + </namespaces>
> +
> + <source-path>
> + <path-element>src</path-element>
> + </source-path>
> +
> + <warn-no-constructor>false</warn-no-constructor>
> + </compiler>
> + <include-file>
> + <name>defaults.css</name>
> + <path>defaults.css</path>
> + </include-file>
> +
> + <include-classes>
> + <class>MyLibrary</class>
> + </include-classes>
> +
> + <include-namespaces>
> + <uri>library://ns.somesite.com/kapow</uri>
> + </include-namespaces>
> +
> +</royale-config>
> +
> +```
> +
> +## Building the library
> +You asconfig.json file should look like this:
> +
> +```
> +{
> + "config": "royale",
> + "type": "lib",
> + "compilerOptions": {
> + "targets": [
> + "JSRoyale"
> + ],
> + "external-library-path": [
> + "${royalelib}/libs",
> + "${royalelib}/../js/libs",
> + "libs"
> + ],
> + "js-external-library-path": [
> + "${royalelib}/js/libs",
> + "${royalelib}/../js/libs",
> + "libs"
> + ],
> + "load-config": [
> + "compile-config.xml"
> + ],
> + "js-load-config": [
> + "js-compile-config.xml"
> + ],
> + "include-classes": [
> + "MyLibrary"
> + ],
> + "include-sources": [
> + "src"
> + ],
> + "source-path": [
> + "src"
> + ],
> + "output": "target/MyLibrary.swc"
> + },
> + "additionalOptions":[
> + //include any options you want here
> + ]
> +}
> +```
> \ No newline at end of file
> diff --git a/libraries/library-basics.md b/libraries/library-basics.md
> index fc3c3ab..0b655e9 100644
> --- a/libraries/library-basics.md
> +++ b/libraries/library-basics.md
> @@ -39,7 +39,7 @@ There is no obvious way to tell the difference. Both
> have a `.swc` extension, al
> ### Compiled Code Libraries
> Compiled code libraries are libraries which contain code that will end up
> in your compiled application (assuming you use that code). These can be
> code that you might use internally across multiple projects, or it can be a
> library that was compiled by someone else. Much of the Royale framework is
> compiled into `swc` files that are used in applications.
>
> -Compiled code libraries are created using the `compc` compiler. (TODO add
> sample configs for doing this)
> +Compiled code libraries are created using the `compc` compiler. [See here
> for detailed instructions on how to create one.](compiled-code-libraries)
>
> ### Typedef libraries
> Typedef libraries are libraries which define the types of different
> classes, but contain no code that would be added to an application. Typedef
> libraries are used for core Web APIs and third party javascript libraries
> which could be included in applications as separate javascript files (such
> as jQuery). Typedef libraries are similar to Typescript `d.ts` files.
>