Merge branch 'dev'

azure/docsite/api/api-c-con/index.html

@@ -342,7 +342,7 @@ <h3 id="io_setreset">io_setreset</h3>
 <p>For windowed consoles only.</p>
 <p>Sets or resets (clears) a chunky graphics "pixel".  Each character cell can also be a 2x3 grid of graphic "pixels".  In other words, the terminal window has pixel dimensions of width<em>2 x height</em>3.</p>
 <p>The color will be set to the defaults if the impacted cell is not a graphics cell.  If it is an existing graphics cell, the colors don't change.</p>
-<p>See the terminal-window io_canvas example.</p>
+<p>See the <code>stdio-canvas</code> example.</p>
 <pre><code>#include &lt;twr_io.h&gt;
 
 bool io_setreset(struct IoConsoleWindow* iow, int x, int y, bool isset);

azure/docsite/examples/examples-more/index.html

@@ -133,7 +133,6 @@ <h1>More</h1>
 <p>Some other examples include:</p>
 <ul>
 <li><code>function-calls</code> demos the different types of parameters that can be passed to a C function</li>
-<li><code>tests-user</code> demos using the <code>struct IoWindow</code> (aka terminal) with interactive tests</li>
 <li><code>tests</code> are the tiny-wasm-runtime unit tests</li>
 </ul>
 <p><strong>All Examples Live &amp; Source</strong></p>

azure/docsite/examples/examples-overview/index.html

@@ -180,6 +180,11 @@ <h1>Examples Overview</h1>
 <td><a href="../examples-libcxx/">tests-libcxx</a></td>
 </tr>
 <tr>
+<td>tests-user</td>
+<td>"cli" for tests using libc++ and <code>&lt;canvas&gt;</code></td>
+<td><a href="/examples/dist/tests-user/index.html">tests-user</a></td>
+</tr>
+<tr>
 <td>more</td>
 <td>Demo of function calls, units tests</td>
 <td><a href="../examples-more/">more</a></td>

azure/docsite/gettingstarted/installation/index.html

@@ -136,8 +136,8 @@ <h1>Installation</h1>
 <pre><code>   npm install tiny-wasm-runtime
 </code></pre>
 <ul>
-<li><code>git clone</code> will copy the built libraries (lib-js, lib-c) as well as the source, examples, docs and VS Code settings.</li>
-<li><code>npm install</code> will copy the minimum necessary to build your software: built libraries (lib-js, lib-c) and the examples.</li>
+<li><code>git clone</code> will copy the built libraries (lib-js, lib-c), include, as well as the source, examples, docs and VS Code settings.</li>
+<li><code>npm install</code> will copy the minimum necessary to build your software: built libraries (lib-js, lib-c), include and the examples.</li>
 </ul>
 <p>Either will work.</p>
 <p><strong>Installs for your C/C++ code</strong></p>

azure/docsite/gettingstarted/keyconcepts/index.html

@@ -130,15 +130,28 @@
 
                 <h1>Key Concepts</h1>
 
+<h2>Overview</h2>
+
+<p>Your project will consist of HTML (and related JavaScript or Typescript) and C or C++ compiled into a ".wasm" binary file and loaded as a Web Assembly module. </p>
+<p>You will call C functions (or C++ with ' extern "C" ' linkage) in the .wasm module from your JavaScript.  You can also call JavaScript functions from your C/C++ code, but this is less common.</p>
+<p>There is no direct equivalent to a C "main".  Instead, a wasm module provides exported C functions that you can call from JavaScript/TypeScript.  A wasm module is more like a runtime loaded dynamic library.</p>
+<p>On the JavaScript side you will use the tiny-wasm-runtime JavaScript/TypeScript class <code>twrWasmModule</code> or <code>twrWasmModuleAsync</code> to load the .wasm module, and then call C functions in it (more details are in the <a href="../../api/api-typescript/">TypeScript/Javascript API section</a>).</p>
+<p>You're C/C++ code can be non-blocking or blocking.  Blocking means that it "takes a long time" to return.   For example, if you want to send mouse events to C code, have the code process them then return, this would be non-blocking.  Alternately, if your C code is a big loop that never returns, that would be very blocking.   You can use the tiny-wasm-runtime class <code>twrWasmModuleAsync</code> to execute blocking code from JavaScript.  The example <a href="../../examples/examples-maze/">maze</a> demonstrates both non-blocking and blocking C calls.</p>
+<p>Here are some examples of different types of C/C++ code:</p>
+<ul>
+<li>If you're C/C++ code does not have any direct user interface built in, it can do its calculations and return.  The <a href="../../examples/examples-fft/">FFT</a> is an example of this.  </li>
+<li>If your C/C++ code uses a classic C "UI", where it gets keys from stdin and sends the results to stdout, you can direct stdin and stdout to a <code>&lt;div&gt;</code> or <code>&lt;canvas&gt;</code> tag.  This is explained in the <a href="../stdio/">stdio</a> section.</li>
+<li>Your C/C++ code could be sent events from JavaScript (such mouse, key, timer, or other). This is done by simply calling a C function with the events as parameters.  The C/C++ code could then generate no output, could render to a <code>&lt;div&gt;</code> or <code>&lt;canvas&gt;</code> using stdio type C/C++ functions, or it could render to a <code>&lt;canvas&gt;</code> using 2D drawing APIs that correspond to JavaScript canvas 2D draw operations.  (<a href="../../examples/examples-balls/">Balls</a>) is an example.</li>
+</ul>
 <h2>Steps to integrate C code with JavaScript code</h2>
 
 <p>Here are the general steps to integrate your C with your JavaScript:</p>
 <ol>
 <li><a href="../compiler-opts/">Compile your C code</a> with clang and link with wasm-ld to create the <code>.wasm</code> file.</li>
 <li>On the JavaScript side you:<ol>
 <li>Access tiny-wasm-runtime "ES" modules in the normal way with <code>import</code>. </li>
-<li>Add a <code>&lt;div id=twr_iodiv&gt;</code> to your HTML (<a href="../stdio/">see stdio</a>)</li>
-<li>Use <code>new twrWasmModule()</code>, followed by a call to <code>loadWasm()</code>, then <code>callC()</code>.</li>
+<li>Add a <code>&lt;div id=twr_iodiv&gt;</code> or <code>&lt;canvas id=twr_iocanvas&gt;</code> to your HTML (<a href="../stdio/">see stdio</a>)</li>
+<li>Use <code>new twrWasmModule()</code>, followed by a call to <code>loadWasm()</code>, then one or more <code>callC()</code>.</li>
 <li>Alternately, use <code>twrWasmModuleAsync()</code> -- which is interchangeable with twrWasmModule, but proxies through a worker thread, and adds blocking support, including blocking char input.</li>
 </ol>
 </li>
@@ -155,7 +168,7 @@ <h2>Passing strings, arrayBuffers, etc</h2>
 </ul>
 <p>Some module functions (such as <code>getString</code>) take or return an "index:number".  Here index means an index into WebAssembly.Memory.  As far as your C code is concerned, this is a pointer.</p>
 <p>Recalled that an arrayBuffer can be created and accessed using classes like <code>Uint8Array</code> or <code>Float32Array</code>.</p>
-<p>See the examples "function-calls" and "fft".</p>
+<p>It is helpful to look at the <a href="../../examples/examples-overview/">examples</a>.</p>
 
             </div>
           </div><footer>

azure/docsite/gettingstarted/stdio/index.html

@@ -131,14 +131,14 @@
                 <h1>Stdio</h1>
 
 <h2>Use div or canvas tag</h2>
-<p>Standard input and output can be directed to a <code>&lt;div&gt;</code> or to a <code>&lt;canvas&gt;</code> HTML tag.  A <code>&lt;div&gt;</code> is used for streamed character input and output, and a <code>&lt;canvas&gt;</code> is used for sending characters or simple graphics to windowed input and output.  In the windowed mode, the position of characters in a "terminal" style window can be specified.</p>
+<p>Standard input and output can be directed to a <code>&lt;div&gt;</code> or to a <code>&lt;canvas&gt;</code> HTML tag.  A <code>&lt;div&gt;</code> is used for streamed character input and output, and a <code>&lt;canvas&gt;</code> is used for sending characters or simple graphics to windowed input and output.  In the windowed mode, the position of characters in a "terminal" style window can be specified.  In windowed mode, you can use functions that output to stdout or input from stdin, as well as functions that use x,y coordinates, colors, etc.</p>
 <ul>
 <li><code>&lt;div id="twr_iodiv"&gt;</code> will be used for <code>stdin</code> and <code>stdout</code> if found.</li>
 <li><code>&lt;canvas id="twr_iocanvas"&gt;</code> will be used for <code>stdin</code> and <code>stdout</code> if it exists and no div found. </li>
 <li>if neither of the above <code>&lt;div&gt;</code> or <code>&lt;canvas&gt;</code> is defined in your HTML, then <code>stdout</code> is sent to the debug console in your browser. And <code>stdin</code> is not available.</li>
 <li>If you use <code>twrWasmModule</code> options, a fourth <code>null</code> options is available.</li>
 </ul>
-<p>Unicode characters and symbols are supported in <code>stdout</code> and <code>stdin</code> (see <a href="../../api/api-localization/">localization</a>).</p>
+<p>Unicode characters and symbols are supported in <code>stdout</code> and <code>stdin</code> and windowed i/o (see <a href="../../api/api-localization/">localization</a>).</p>
 <p>The window console also supports chunky (low res) graphics (each character cell can be used as a 2x3 graphic array). </p>
 <p><code>stderr</code> streams to the browser's debug console.</p>
 <h2>Examples</h2>
@@ -153,15 +153,20 @@ <h2>Examples</h2>
 </thead>
 <tbody>
 <tr>
-<td>char in/out with <code>&lt;div&gt;</code></td>
+<td>stdin and stdout to <code>&lt;div&gt;</code></td>
 <td><a href="/examples/dist/stdio-div/index.html">View square demo</a></td>
 <td><a href="https://github.com/twiddlingbits/tiny-wasm-runtime/tree/main/examples/stdio-div">Source</a></td>
 </tr>
 <tr>
-<td>"terminal" in/out with a <code>&lt;canvas&gt;</code></td>
-<td><a href="/examples/dist/stdio-canvas/index.html">View mini-term demo</a></td>
+<td>simple "terminal" via <code>&lt;canvas&gt;</code></td>
+<td><a href="/examples/dist/stdio-canvas/index.html">View hello world demo</a></td>
 <td><a href="https://github.com/twiddlingbits/tiny-wasm-runtime/tree/main/examples/stdio-canvas">Source</a></td>
 </tr>
+<tr>
+<td>"cli" with a <code>&lt;canvas&gt;</code> stdio</td>
+<td><a href="/examples/dist/tests-user/index.html">View CLI demo using libc++</a></td>
+<td><a href="https://github.com/twiddlingbits/tiny-wasm-runtime/tree/main/examples/tests-user">Source</a></td>
+</tr>
 </tbody>
 </table>
 <h2>IO Console Docs</h2>

azure/docsite/index.html

@@ -223,7 +223,7 @@ <h2 id="view-live-demos">View Live Demos</h2>
 <td><a href="https://github.com/twiddlingbits/tiny-wasm-runtime/tree/main/examples/stdio-canvas">Source</a></td>
 </tr>
 <tr>
-<td>Mini-Terminal (interactive console using libc++)</td>
+<td>Mini-Terminal ("cli" using libc++ and <code>&lt;canvas&gt;</code>)</td>
 <td><a href="/examples/dist/tests-user/index.html">View console</a></td>
 <td><a href="https://github.com/twiddlingbits/tiny-wasm-runtime/tree/main/examples/tests-user">Source</a></td>
 </tr>
@@ -306,5 +306,5 @@ <h2 id="post-feedback">Post Feedback</h2>
 
 <!--
 MkDocs version : 1.5.3
-Build Date UTC : 2024-06-13 13:00:56.429605+00:00
+Build Date UTC : 2024-06-14 00:48:56.086121+00:00
 -->

azure/docsite/sitemap.xml

@@ -2,132 +2,132 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://twiddlingbits.dev/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/api/api-c-con/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/api/api-c-d2d/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/api/api-c-general/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/api/api-c-stdlib/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/api/api-libc%2B%2B/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/api/api-localization/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/api/api-typescript/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/examples/examples-balls/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/examples/examples-fft/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/examples/examples-helloworld/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/examples/examples-libcxx/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/examples/examples-maze/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/examples/examples-more/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/examples/examples-overview/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/examples/examples-stdio-canvas/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/examples/examples-stdio-div/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/gettingstarted/compiler-opts/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/gettingstarted/firstwasm/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/gettingstarted/installation/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/gettingstarted/keyconcepts/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/gettingstarted/stdio/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/more/building/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/more/debugging/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/more/production/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://twiddlingbits.dev/more/wasm-problem/</loc>
-         <lastmod>2024-06-13</lastmod>
+         <lastmod>2024-06-14</lastmod>
          <changefreq>daily</changefreq>
     </url>
 </urlset>

docs/api/api-c-con.md

@@ -223,7 +223,7 @@ Sets or resets (clears) a chunky graphics "pixel".  Each character cell can also
 
 The color will be set to the defaults if the impacted cell is not a graphics cell.  If it is an existing graphics cell, the colors don't change.
 
-See the terminal-window io_canvas example.
+See the `stdio-canvas` example.
 
 ~~~
 #include <twr_io.h>

docs/examples/examples-more.md

@@ -3,7 +3,6 @@
 Some other examples include:
 
 - `function-calls` demos the different types of parameters that can be passed to a C function
-- `tests-user` demos using the `struct IoWindow` (aka terminal) with interactive tests
 - `tests` are the tiny-wasm-runtime unit tests
 
 

docs/examples/examples-overview.md

@@ -15,6 +15,7 @@ Each of these examples are designed to illustrate how to use a feature of tiny-w
 | maze | This is an old Win32 program ported to wasm<br>and demos the 2D Draw APIs | [maze](examples-maze.md) |
 | fft | A demo of calling a C library to perform an FFT<br>that is graphed in Typescript | [fft](examples-fft.md) |
 | tests-libcxx | Smoke test for libc++.  Shows how to use libc++. | [tests-libcxx](examples-libcxx.md) |
+|tests-user | "cli" for tests using libc++ and `<canvas>` | [tests-user](/examples/dist/tests-user/index.html) |
 | more | Demo of function calls, units tests | [more](examples-more.md) |
 
 

docs/gettingstarted/installation.md

@@ -7,8 +7,8 @@ or
    npm install tiny-wasm-runtime
 ~~~
 
-- `git clone` will copy the built libraries (lib-js, lib-c) as well as the source, examples, docs and VS Code settings.
-- `npm install` will copy the minimum necessary to build your software: built libraries (lib-js, lib-c) and the examples.
+- `git clone` will copy the built libraries (lib-js, lib-c), include, as well as the source, examples, docs and VS Code settings.
+- `npm install` will copy the minimum necessary to build your software: built libraries (lib-js, lib-c), include and the examples.
 
 Either will work.