-
Notifications
You must be signed in to change notification settings - Fork 15
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
64 changed files
with
2,936 additions
and
1,142 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| <!DOCTYPE html><html><head> | ||
| <title>Type cycles – ammer manual</title> | ||
| <meta charset="utf-8"> | ||
| <link rel="stylesheet" href="css/style.css" media="all"> | ||
| <link rel="stylesheet" href="css/highlight.css" media="all"> | ||
| <script src="search.js"></script> | ||
| </head><body> | ||
| <header><a href="index.html"><h1>ammer</h1></a></header> | ||
| <nav id="menu"> | ||
| <input autocomplete="off" tabindex="0" title="Click here to search" id="search" type="text" placeholder="Enter search term here"> | ||
| <label for="search"></label> | ||
| <div class="menu-split"></div> | ||
| <div class="menu-split show"><ul><li><a href="index.html">Introduction</a></li><ul><li><a href="intro-overview.html">Overview</a></li></ul><ul><li><a href="intro-terminology.html">Terminology</a></li></ul><ul><li><a href="intro-use.html">Why <code>ammer</code>?</a></li></ul><ul><li><a href="intro-installation.html">Installation</a></li></ul><ul><li><a href="intro-start.html">Getting started</a></li></ul></ul><ul><li><a href="definition.html">Definition</a></li><ul><li><a href="definition-library.html">Library definition</a></li><ul><li><a href="definition-library-functions.html">Functions</a></li></ul><ul><li><a href="definition-library-variables.html">Variables</a></li></ul><ul><li><a href="definition-sub.html">Sublibraries</a></li></ul></ul><ul><li><a href="definition-type.html">Datatypes</a></li><ul><li><a href="definition-type-opaque.html">Opaque types</a></li></ul><ul><li><a href="definition-type-struct.html">Structs</a></li></ul><ul><li><a href="definition-type-instance.html">Instance methods</a></li></ul><ul><li><a href="definition-type-enum.html">Enums</a></li></ul><ul><li><a href="definition-type-haxe.html">Haxe types</a></li></ul><ul><li><a href="definition-type-callbacks.html">Callbacks</a></li></ul><ul><li><a href="definition-link.html">Linking subdefinitions</a></li></ul></ul></ul><ul><li><a href="configuration.html">Configuration</a></li><ul><li><a href="configuration-providing.html">Providing flags</a></li></ul><ul><li><a href="configuration-project.html">Project-wide configuration</a></li></ul><ul><li><a href="configuration-library.html">Library configuration</a></li></ul></ul><ul><li><a href="target.html">Target details</a></li><ul><li><a href="target-feature-parity.html">Feature parity</a></li></ul><ul><li><a href="target-hxcpp.html">C++</a></li></ul><ul><li><a href="target-cs.html">C#</a></li></ul><ul><li><a href="target-eval.html">Eval</a></li></ul><ul><li><a href="target-hashlink.html">HashLink</a></li></ul><ul><li><a href="target-java.html">Java</a></li></ul><ul><li><a href="target-lua.html">Lua</a></li></ul><ul><li><a href="target-neko.html">Neko</a></li></ul><ul><li><a href="target-nodejs.html">Node.js</a></li></ul><ul><li><a href="target-python.html">Python</a></li></ul></ul><ul><li><a href="ref.html">Reference</a></li><ul><li><a href="ref-ffi.html">FFI types</a></li></ul><ul><li><a href="ref-def.html"><code>ammer.def.*</code> types</a></li></ul><ul><li><a href="ref-lib.html"><code>ammer.Lib</code></a></li></ul><ul><li><a href="ref-flags.html">List of configuration flags</a></li></ul><ul><li><a href="ref-annot.html">List of annotations</a></li></ul></ul><ul><li><a href="amlib.html"><code>amlib</code></a></li></ul><ul><li><a href="advanced.html">Advanced topics</a></li><ul><li><a href="advanced-cycles.html">Type cycles</a></li></ul></ul><ul><li><a href="core.html"><code>ammer-core</code></a></li><ul><li><a href="core-api.html">Interface</a></li></ul><ul><li><a href="core-new-platform.html">Implementing new platforms</a></li></ul></ul></div> | ||
| </nav> | ||
| <main><h2>Type cycles</h2><p>In <a href="definition-link.html" title="Linking subdefinitions">linking subdefinitions</a>, it is recommended to link any library to all of its subdefinitions using the <a href="ref-annot.html#sub" title="List of annotations / @:ammer.sub"><code>@:ammer.sub</code></a> metadata. Why is this necessary?</p> | ||
| <p>Consider the following types:</p> | ||
| <div class="hl"><pre><i class="hl-com">// in file Foobar.hx</i><i class="hl-other"> | ||
| </i><a class="hll-meta" href="ref-annot.html#sub" title="List of annotations / @:ammer.sub"><i class="hl-metax">@:</i><i class="hl-meta">ammer</i><i class="hl-metax">.</i><i class="hl-meta">sub</i></a><i class="hl-metax">(</i><i class="hl-other">(_ </i><i class="hl-tyx">:</i><i class="hl-other"> </i><i class="hl-ty">FoobarStruct</i><i class="hl-other">)</i><i class="hl-metax">)</i><i class="hl-other"> | ||
| </i><a class="hll-meta" href="ref-annot.html#sub" title="List of annotations / @:ammer.sub"><i class="hl-metax">@:</i><i class="hl-meta">ammer</i><i class="hl-metax">.</i><i class="hl-meta">sub</i></a><i class="hl-metax">(</i><i class="hl-other">(_ </i><i class="hl-tyx">:</i><i class="hl-other"> </i><i class="hl-ty">FoobarSub</i><i class="hl-other">)</i><i class="hl-metax">)</i><i class="hl-other"> | ||
| </i><i class="hl-kw">class</i><i class="hl-other"> </i><i class="hl-decl">Foobar</i><i class="hl-other"> </i><i class="hl-kw">extends</i><i class="hl-other"> </i><a class="hll-ty" href="ref-def.html#library" title="ammer.def.* types / ammer.def.Library"><i class="hl-ty">ammer</i><i class="hl-tyx">.</i><i class="hl-ty">def</i><i class="hl-tyx">.</i><i class="hl-ty">Library</i></a><i class="hl-tyx"><</i><i class="hl-lit">"foobar"</i><i class="hl-tyx">></i><i class="hl-other"> { | ||
| </i><i class="hl-kw">public</i><i class="hl-other"> </i><i class="hl-kw">static</i><i class="hl-other"> </i><i class="hl-kw">function</i><i class="hl-other"> </i><i class="hl-decl">some_function</i><i class="hl-other">()</i><i class="hl-tyx">:</i><i class="hl-ty">FoobarStruct</i><i class="hl-other">; | ||
| } | ||
|
|
||
| </i><i class="hl-com">// in file FoobarStruct.hx</i><i class="hl-other"> | ||
| </i><i class="hl-kw">class</i><i class="hl-other"> </i><i class="hl-decl">FoobarStruct</i><i class="hl-other"> </i><i class="hl-kw">extends</i><i class="hl-other"> </i><a class="hll-ty" href="ref-def.html#struct" title="ammer.def.* types / ammer.def.Struct"><i class="hl-ty">ammer</i><i class="hl-tyx">.</i><i class="hl-ty">def</i><i class="hl-tyx">.</i><i class="hl-ty">Struct</i></a><i class="hl-tyx"><</i><i class="hl-lit">"foobar_t"</i><i class="hl-tyx">,</i><i class="hl-other"> </i><i class="hl-ty">Foobar</i><i class="hl-tyx">></i><i class="hl-other"> { | ||
| </i><i class="hl-com">// ...</i><i class="hl-other"> | ||
| } | ||
|
|
||
| </i><i class="hl-com">// in file FoobarSub.hx</i><i class="hl-other"> | ||
| </i><i class="hl-kw">class</i><i class="hl-other"> </i><i class="hl-decl">FoobarSub</i><i class="hl-other"> </i><i class="hl-kw">extends</i><i class="hl-other"> </i><a class="hll-ty" href="ref-def.html#sublibrary" title="ammer.def.* types / ammer.def.Sublibrary"><i class="hl-ty">ammer</i><i class="hl-tyx">.</i><i class="hl-ty">def</i><i class="hl-tyx">.</i><i class="hl-ty">Sublibrary</i></a><i class="hl-tyx"><</i><i class="hl-ty">Foobar</i><i class="hl-tyx">></i><i class="hl-other"> { | ||
| </i><i class="hl-kw">public</i><i class="hl-other"> </i><i class="hl-kw">static</i><i class="hl-other"> </i><i class="hl-kw">function</i><i class="hl-other"> </i><i class="hl-decl">another_function</i><i class="hl-other">()</i><i class="hl-tyx">:</i><i class="hl-ty">Void</i><i class="hl-other">; | ||
| }</i></pre></div><p>Between <code>Foobar</code> and <code>FoobarSub</code>, there is a two-way link:</p> | ||
| <ul> | ||
| <li><code>@:ammer.sub((_ : FoobarSub))</code> — Links the library to the subdefinition.</li> | ||
| <li><code>... extends ammer.def.Sublibrary<Foobar></code> — Links the subdefinition to the library.</li> | ||
| </ul> | ||
| <p>If the <code>@:ammer.sub((_ : FoobarSub))</code> annotation was omitted, then the following client code could cause a compilation failure:</p> | ||
| <div class="hl"><pre><i class="hl-other">Foobar</i><i class="hl-op">.</i><i class="hl-other">some_function(); | ||
| FoobarSub</i><i class="hl-op">.</i><i class="hl-other">another_function();</i></pre></div><p>This is because Haxe performs typing on demand: the <code>Foobar</code> module (in the file <code>Foobar.hx</code>) is not discovered and typed until the first time it is needed. This can happen if a type (and its static method) declared in that module is used, as in the first line.</p> | ||
| <p>However, <code>Foobar</code> is not a regular Haxe type: it is an <code>ammer</code>-annotated library definition. When an <code>ammer</code> library is typed, the following steps take place (simplified):</p> | ||
| <ul> | ||
| <li>A library context is established, containing the library configuration etc.</li> | ||
| <li>All fields of the library are eagerly typed. This may trigger transitive typing. In the example above, this leads Haxe to discover the <code>FoobarStruct</code> type, because it is used as the return type of one of the methods of <code>Foobar</code>.</li> | ||
| <li>The library is finalised by writing the required glue code into a file, which will later be compiled by a C compiler.</li> | ||
| </ul> | ||
| <p>Without the <code>@:ammer.sub((_ : FoobarSub))</code> annotation on <code>Foobar</code>, the first line of the client only causes the Haxe compiler to discover <code>Foobar</code> and <code>FoobarStruct</code>. When typing the second line (the call to <code>FoobarSub.another_function</code>), <code>FoobarSub</code> is discovered, but it cannot be added to <code>Foobar</code> anymore: the library was finalised and the glue code was already generated.</p> | ||
| <p>The safe recommendation is therefore to always use <a href="ref-annot.html#sub" title="List of annotations / @:ammer.sub"><code>@:ammer.sub</code></a>, even when other fields would cause the Haxe compiler to discover the subdefinitions.</p> | ||
| </main> | ||
| <a id="page-prev" href="advanced.html">« Previous: Advanced topics</a> | ||
| <a id="page-next" href="core.html">Next: <code>ammer-core</code> »</a> | ||
| <footer> | ||
| <a href="https://github.com/Aurel300/ammer/blob/gh-pages-src/content/07-advanced.md?plain=1#L5">Contribute to this page</a> | ||
| | <a href="https://github.com/Aurel300/ammer/" target="_blank"><code>ammer</code> on GitHub</a> | ||
| | © 2019-2023 Aurel Bílý | ||
| </footer> | ||
| </body></html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| <!DOCTYPE html><html><head> | ||
| <title>Advanced topics – ammer manual</title> | ||
| <meta charset="utf-8"> | ||
| <link rel="stylesheet" href="css/style.css" media="all"> | ||
| <link rel="stylesheet" href="css/highlight.css" media="all"> | ||
| <script src="search.js"></script> | ||
| </head><body> | ||
| <header><a href="index.html"><h1>ammer</h1></a></header> | ||
| <nav id="menu"> | ||
| <input autocomplete="off" tabindex="0" title="Click here to search" id="search" type="text" placeholder="Enter search term here"> | ||
| <label for="search"></label> | ||
| <div class="menu-split"></div> | ||
| <div class="menu-split show"><ul><li><a href="index.html">Introduction</a></li><ul><li><a href="intro-overview.html">Overview</a></li></ul><ul><li><a href="intro-terminology.html">Terminology</a></li></ul><ul><li><a href="intro-use.html">Why <code>ammer</code>?</a></li></ul><ul><li><a href="intro-installation.html">Installation</a></li></ul><ul><li><a href="intro-start.html">Getting started</a></li></ul></ul><ul><li><a href="definition.html">Definition</a></li><ul><li><a href="definition-library.html">Library definition</a></li><ul><li><a href="definition-library-functions.html">Functions</a></li></ul><ul><li><a href="definition-library-variables.html">Variables</a></li></ul><ul><li><a href="definition-sub.html">Sublibraries</a></li></ul></ul><ul><li><a href="definition-type.html">Datatypes</a></li><ul><li><a href="definition-type-opaque.html">Opaque types</a></li></ul><ul><li><a href="definition-type-struct.html">Structs</a></li></ul><ul><li><a href="definition-type-instance.html">Instance methods</a></li></ul><ul><li><a href="definition-type-enum.html">Enums</a></li></ul><ul><li><a href="definition-type-haxe.html">Haxe types</a></li></ul><ul><li><a href="definition-type-callbacks.html">Callbacks</a></li></ul><ul><li><a href="definition-link.html">Linking subdefinitions</a></li></ul></ul></ul><ul><li><a href="configuration.html">Configuration</a></li><ul><li><a href="configuration-providing.html">Providing flags</a></li></ul><ul><li><a href="configuration-project.html">Project-wide configuration</a></li></ul><ul><li><a href="configuration-library.html">Library configuration</a></li></ul></ul><ul><li><a href="target.html">Target details</a></li><ul><li><a href="target-feature-parity.html">Feature parity</a></li></ul><ul><li><a href="target-hxcpp.html">C++</a></li></ul><ul><li><a href="target-cs.html">C#</a></li></ul><ul><li><a href="target-eval.html">Eval</a></li></ul><ul><li><a href="target-hashlink.html">HashLink</a></li></ul><ul><li><a href="target-java.html">Java</a></li></ul><ul><li><a href="target-lua.html">Lua</a></li></ul><ul><li><a href="target-neko.html">Neko</a></li></ul><ul><li><a href="target-nodejs.html">Node.js</a></li></ul><ul><li><a href="target-python.html">Python</a></li></ul></ul><ul><li><a href="ref.html">Reference</a></li><ul><li><a href="ref-ffi.html">FFI types</a></li></ul><ul><li><a href="ref-def.html"><code>ammer.def.*</code> types</a></li></ul><ul><li><a href="ref-lib.html"><code>ammer.Lib</code></a></li></ul><ul><li><a href="ref-flags.html">List of configuration flags</a></li></ul><ul><li><a href="ref-annot.html">List of annotations</a></li></ul></ul><ul><li><a href="amlib.html"><code>amlib</code></a></li></ul><ul><li><a href="advanced.html">Advanced topics</a></li><ul><li><a href="advanced-cycles.html">Type cycles</a></li></ul></ul><ul><li><a href="core.html"><code>ammer-core</code></a></li><ul><li><a href="core-api.html">Interface</a></li></ul><ul><li><a href="core-new-platform.html">Implementing new platforms</a></li></ul></ul></div> | ||
| </nav> | ||
| <main><h2>Advanced topics</h2></main> | ||
| <a id="page-prev" href="amlib.html">« Previous: <code>amlib</code></a> | ||
| <a id="page-next" href="advanced-cycles.html">Next: Type cycles »</a> | ||
| <footer> | ||
| <a href="https://github.com/Aurel300/ammer/blob/gh-pages-src/content/07-advanced.md?plain=1#L2">Contribute to this page</a> | ||
| | <a href="https://github.com/Aurel300/ammer/" target="_blank"><code>ammer</code> on GitHub</a> | ||
| | © 2019-2023 Aurel Bílý | ||
| </footer> | ||
| </body></html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| <!DOCTYPE html><html><head> | ||
| <title>amlib – ammer manual</title> | ||
| <meta charset="utf-8"> | ||
| <link rel="stylesheet" href="css/style.css" media="all"> | ||
| <link rel="stylesheet" href="css/highlight.css" media="all"> | ||
| <script src="search.js"></script> | ||
| </head><body> | ||
| <header><a href="index.html"><h1>ammer</h1></a></header> | ||
| <nav id="menu"> | ||
| <input autocomplete="off" tabindex="0" title="Click here to search" id="search" type="text" placeholder="Enter search term here"> | ||
| <label for="search"></label> | ||
| <div class="menu-split"></div> | ||
| <div class="menu-split show"><ul><li><a href="index.html">Introduction</a></li><ul><li><a href="intro-overview.html">Overview</a></li></ul><ul><li><a href="intro-terminology.html">Terminology</a></li></ul><ul><li><a href="intro-use.html">Why <code>ammer</code>?</a></li></ul><ul><li><a href="intro-installation.html">Installation</a></li></ul><ul><li><a href="intro-start.html">Getting started</a></li></ul></ul><ul><li><a href="definition.html">Definition</a></li><ul><li><a href="definition-library.html">Library definition</a></li><ul><li><a href="definition-library-functions.html">Functions</a></li></ul><ul><li><a href="definition-library-variables.html">Variables</a></li></ul><ul><li><a href="definition-sub.html">Sublibraries</a></li></ul></ul><ul><li><a href="definition-type.html">Datatypes</a></li><ul><li><a href="definition-type-opaque.html">Opaque types</a></li></ul><ul><li><a href="definition-type-struct.html">Structs</a></li></ul><ul><li><a href="definition-type-instance.html">Instance methods</a></li></ul><ul><li><a href="definition-type-enum.html">Enums</a></li></ul><ul><li><a href="definition-type-haxe.html">Haxe types</a></li></ul><ul><li><a href="definition-type-callbacks.html">Callbacks</a></li></ul><ul><li><a href="definition-link.html">Linking subdefinitions</a></li></ul></ul></ul><ul><li><a href="configuration.html">Configuration</a></li><ul><li><a href="configuration-providing.html">Providing flags</a></li></ul><ul><li><a href="configuration-project.html">Project-wide configuration</a></li></ul><ul><li><a href="configuration-library.html">Library configuration</a></li></ul></ul><ul><li><a href="target.html">Target details</a></li><ul><li><a href="target-feature-parity.html">Feature parity</a></li></ul><ul><li><a href="target-hxcpp.html">C++</a></li></ul><ul><li><a href="target-cs.html">C#</a></li></ul><ul><li><a href="target-eval.html">Eval</a></li></ul><ul><li><a href="target-hashlink.html">HashLink</a></li></ul><ul><li><a href="target-java.html">Java</a></li></ul><ul><li><a href="target-lua.html">Lua</a></li></ul><ul><li><a href="target-neko.html">Neko</a></li></ul><ul><li><a href="target-nodejs.html">Node.js</a></li></ul><ul><li><a href="target-python.html">Python</a></li></ul></ul><ul><li><a href="ref.html">Reference</a></li><ul><li><a href="ref-ffi.html">FFI types</a></li></ul><ul><li><a href="ref-def.html"><code>ammer.def.*</code> types</a></li></ul><ul><li><a href="ref-lib.html"><code>ammer.Lib</code></a></li></ul><ul><li><a href="ref-flags.html">List of configuration flags</a></li></ul><ul><li><a href="ref-annot.html">List of annotations</a></li></ul></ul><ul><li><a href="amlib.html"><code>amlib</code></a></li></ul><ul><li><a href="advanced.html">Advanced topics</a></li><ul><li><a href="advanced-cycles.html">Type cycles</a></li></ul></ul><ul><li><a href="core.html"><code>ammer-core</code></a></li><ul><li><a href="core-api.html">Interface</a></li></ul><ul><li><a href="core-new-platform.html">Implementing new platforms</a></li></ul></ul></div> | ||
| </nav> | ||
| <main><h2><code>amlib</code></h2><p>TODO:</p> | ||
| <ul> | ||
| <li>standard layout of amlib</li> | ||
| <li>bakery defines<ul> | ||
| <li><code>ammer.bake</code></li> | ||
| <li><code>ammer.bake.mainType</code></li> | ||
| <li><code>ammer.bake.output</code></li> | ||
| <li><code>ammer.bake.rootToBin</code></li> | ||
| <li><code>ammer.bake.fileSource.*.name</code></li> | ||
| <li><code>ammer.bake.fileSource.*.downloadFrom</code></li> | ||
| <li><code>ammer.bake.fileSource.*.description</code></li> | ||
| <li><code>ammer.bake.fileSource.*.os</code></li> | ||
| <li><code>ammer.bake.fileSource.*.architectures</code></li> | ||
| <li><code>ammer.bake.fileSource.*.minVersion</code></li> | ||
| <li><code>ammer.bake.fileSource.*.maxVersion</code></li> | ||
| </ul> | ||
| </li> | ||
| <li>CI, GH action templates</li> | ||
| <li>examples of amlibs</li> | ||
| </ul> | ||
| </main> | ||
| <a id="page-prev" href="ref-annot.html">« Previous: List of annotations</a> | ||
| <a id="page-next" href="advanced.html">Next: Advanced topics »</a> | ||
| <footer> | ||
| <a href="https://github.com/Aurel300/ammer/blob/gh-pages-src/content/06-amlib.md?plain=1#L3">Contribute to this page</a> | ||
| | <a href="https://github.com/Aurel300/ammer/" target="_blank"><code>ammer</code> on GitHub</a> | ||
| | © 2019-2023 Aurel Bílý | ||
| </footer> | ||
| </body></html> |
Oops, something went wrong.