More initial docs

.github/workflows/ci.yaml

@@ -97,6 +97,25 @@ jobs:
         env:
           JBANG_REPO: "${{ github.workspace }}/repository"
 
+      # Test docs index
+      - name: jbang
+        uses: jbangdev/jbang-action@36d4a384d215d91c2c7e74014a486cedfe09d760 # tag=v0.119.0
+        with:
+          script: docs/docs/index.md
+        env:
+          JBANG_REPO: "${{ github.workspace }}/repository"
+      - name: compare results
+        run: diff -r ./readmes/index/expected ./readmes/index/current
+      # Test docs memory
+      - name: jbang
+        uses: jbangdev/jbang-action@36d4a384d215d91c2c7e74014a486cedfe09d760 # tag=v0.119.0
+        with:
+          script: docs/docs/usage/memory.md
+        env:
+          JBANG_REPO: "${{ github.workspace }}/repository"
+      - name: compare results
+        run: diff -r ./readmes/memory/expected ./readmes/memory/current
+
   test-results:
     name: Test Results
     runs-on: ubuntu-latest

docs-lib/pom.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>com.dylibso.chicory</groupId>
+    <artifactId>chicory</artifactId>
+    <version>999-SNAPSHOT</version>
+    <relativePath>../pom.xml</relativePath>
+  </parent>
+  <artifactId>docs-lib</artifactId>
+  <packaging>jar</packaging>
+  <name>Chicory - Docs Lib</name>
+  <description>INTERNAL USAGE ONLY - utils to verify the docs</description>
+
+</project>

docs-lib/src/main/java/docs/FileOps.java

@@ -0,0 +1,41 @@
+package docs;
+
+import java.io.File;
+import java.io.FileWriter;
+import java.io.PrintWriter;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.StandardCopyOption;
+
+public final class FileOps {
+
+    private FileOps() {}
+
+    public static void copyFromWasmCorpus(String sourceName, String destName) throws Exception {
+        var dest = new File(".").toPath().resolve(destName);
+        if (dest.toFile().exists()) {
+            dest.toFile().delete();
+        }
+        Files.copy(
+                new File(".")
+                        .toPath()
+                        .resolve("wasm-corpus")
+                        .resolve("src")
+                        .resolve("main")
+                        .resolve("resources")
+                        .resolve("compiled")
+                        .resolve(sourceName),
+                dest,
+                StandardCopyOption.REPLACE_EXISTING);
+    }
+
+    public static void writeResult(String folder, String name, String content) throws Exception {
+        var dir = new File(".").toPath().resolve(folder);
+        dir.toFile().mkdirs();
+        FileWriter fileWriter = new FileWriter(dir.resolve(name).toFile(), StandardCharsets.UTF_8);
+        PrintWriter printWriter = new PrintWriter(fileWriter);
+        printWriter.print(content);
+        printWriter.flush();
+        printWriter.close();
+    }
+}

docs/docs/index.md

@@ -2,12 +2,110 @@
 sidebar_position: 1
 ---
 
-# Chicory
+## Getting Started
 
-Chicory is a JVM native WebAssembly runtime. It allows you to run WebAssembly programs with
-zero native dependencies or JNI. Chicory can run Wasm anywhere that the JVM can go. It is designed with
-simplicity and safety in mind.
+### Install Dependency
 
-## Getting Started
+To use the runtime, you need to add the `com.dylibso.chicory:runtime` dependency
+to your dependency management system.
+
+#### Maven
+
+```xml
+<dependency>
+  <groupId>com.dylibso.chicory</groupId>
+  <artifactId>runtime</artifactId>
+  <version>0.0.12</version>
+</dependency>
+```
+
+#### Gradle
+
+```groovy
+implementation 'com.dylibso.chicory:runtime:0.0.12'
+```
+
+### Install the CLI (experimental)
+
+The Chicory CLI is available for download on Maven at the link:
+
+```
+https://repo1.maven.org/maven2/com/dylibso/chicory/cli/<version>/cli-<version>.sh
+```
+
+you can download the latest version and use it locally with few lines:
+
+```bash
+export VERSION=$(wget -q -O - https://api.github.com/repos/dylibso/chicory/tags --header "Accept: application/json" | jq -r '.[0].name')
+wget -O chicory https://repo1.maven.org/maven2/com/dylibso/chicory/cli/${VERSION}/cli-${VERSION}.sh
+chmod a+x chicory
+./chicory
+```
+
+<!--
+```java
+//DEPS com.dylibso.chicory:docs-lib:999-SNAPSHOT
+//DEPS com.dylibso.chicory:runtime:999-SNAPSHOT
+```
+-->
+
+### Loading and Instantiating Code
+
+First your Wasm module must be loaded from disk and then "instantiated". Let's [download a test module](https://raw.githubusercontent.com/dylibso/chicory/main/wasm-corpus/src/main/resources/compiled/iterfact.wat.wasm) .
+This module contains some code to compute factorial:
+
+Download from the link or with curl:
+
+```bash
+curl https://raw.githubusercontent.com/dylibso/chicory/main/wasm-corpus/src/main/resources/compiled/iterfact.wat.wasm > factorial.wasm
+```
+
+<!--
+```java
+docs.FileOps.copyFromWasmCorpus("iterfact.wat.wasm", "factorial.wasm");
+```
+-->
+
+Now let's load this module and instantiate it:
+
+```java
+import com.dylibso.chicory.runtime.ExportFunction;
+import com.dylibso.chicory.wasm.types.Value;
+import com.dylibso.chicory.wasm.Module;
+import com.dylibso.chicory.wasm.Parser;
+import com.dylibso.chicory.runtime.Instance;
+import java.io.File;
+
+// point this to your path on disk
+Module module = Parser.parse(new File("./factorial.wasm"));
+Instance instance = Instance.builder(module).build();
+```
+
+You can think of the `module` as the inert code and the `instance` as a virtual machine
+loaded with the code and ready to execute.
+
+### Invoking an Export Function
+
+Wasm modules, like all code modules, can export functions to the outside
+world. This module exports a function called `"iterFact"`. We can get a handle to this function using `Instance#export(String)`:
+
+```java
+ExportFunction iterFact = instance.export("iterFact");
+```
+
+iterFact can be invoked with the `apply()` method. We must map any java types to a wasm type and do the reverse
+when we want to go back to Java. This export function takes an `i32` argument. We can use a method like `Value#asInt()`
+on the return value to get back the Java integer:
+
+```java
+long result = iterFact.apply(5)[0];
+System.out.println("Result: " + result); // should print 120 (5!)
+```
+
+<!--
+```java
+docs.FileOps.writeResult("readmes/index/current", "factorial.result", "" + result);
+```
+-->
 
-... go on from here ...
+> *Note*: Functions in Wasm can have multiple returns but here we're just taking the first returned value.

docs/docs/usage/memory.md

@@ -0,0 +1,74 @@
+---
+sidebar_position: 1
+---
+
+## Using the memory to share data
+
+Wasm only understands basic integer and float primitives. So passing more complex types across the boundary involves
+passing pointers. To read, write, or allocate memory in a module, Chicory gives you the `Memory` class. Let's look at an
+example where we have a module `count_vowels.wasm`, written in rust, that takes a string input and counts the number of vowels
+in the string:
+
+```bash
+curl https://raw.githubusercontent.com/dylibso/chicory/main/wasm-corpus/src/main/resources/compiled/count_vowels.rs.wasm > count_vowels.wasm
+```
+
+<!--
+```java
+//DEPS com.dylibso.chicory:docs-lib:999-SNAPSHOT
+//DEPS com.dylibso.chicory:runtime:999-SNAPSHOT
+```
+-->
+
+<!--
+```java
+docs.FileOps.copyFromWasmCorpus("count_vowels.rs.wasm", "count_vowels.wasm");
+```
+-->
+
+Build and instantiate this module:
+
+```java
+import com.dylibso.chicory.runtime.ExportFunction;
+import com.dylibso.chicory.runtime.Instance;
+import com.dylibso.chicory.wasm.Parser;
+
+Instance instance = Instance.builder(Parser.parse(new File("./count_vowels.wasm"))).build();
+ExportFunction countVowels = instance.export("count_vowels");
+```
+
+To pass it a string, we first need to put the string in the module's memory. To make this easier and safe,
+the module gives us some extra exports to allow us to allocate and deallocate memory:
+
+```java
+ExportFunction alloc = instance.export("alloc");
+ExportFunction dealloc = instance.export("dealloc");
+```
+
+Let's allocate Wasm memory for a string and put in the instance's memory. We can do this with `Memory#put`:
+
+```java
+import com.dylibso.chicory.runtime.Memory;
+Memory memory = instance.memory();
+String message = "Hello, World!";
+int len = message.getBytes().length;
+// allocate {len} bytes of memory, this returns a pointer to that memory
+int ptr = (int) alloc.apply(len)[0];
+// We can now write the message to the module's memory:
+memory.writeString(ptr, message);
+```
+
+Now we can call `countVowels` with this pointer to the string. It will do it's job and return the count. We will
+call `dealloc` to free that memory in the module. Though the module could do this itself if you want:
+
+```java
+var result = countVowels.apply(ptr, len)[0];
+dealloc.apply(ptr, len);
+assert(3L == result); // 3 vowels in Hello, World!
+```
+
+<!--
+```java
+docs.FileOps.writeResult("readmes/memory/current", "countVowels.result", "" + result);
+```
+-->

docs/docusaurus.config.ts

@@ -118,6 +118,7 @@ const config: Config = {
     prism: {
       theme: prismThemes.github,
       darkTheme: prismThemes.dracula,
+      additionalLanguages: ['java'],
     },
   } satisfies Preset.ThemeConfig,
 };

docs/src/components/HomepageFeatures/index.tsx

@@ -21,7 +21,7 @@ const FeatureList: FeatureItem[] = [
   },
   {
     title: 'Easy integration',
-    Svg: require('@site/static/img/easy-integration.svg').default,
+    Svg: require('@site/static/img/pure-java.svg').default,
     description: (
       <>
         Integrating Chicory in your project is smooth and only requires a few steps.

docs/src/css/custom.css

@@ -6,26 +6,25 @@
 
 /* You can override the default Infima variables here. */
 :root {
-  --ifm-color-primary: #514154;
+  --ifm-color-primary: #4a7c99; /* Adjusted to a teal color */
   --ifm-color-primary-dark: #2a202b;
-  --ifm-color-primary-darker: #120d13;
+  --ifm-color-primary-darker: #1f2e3d; /* Darkened to contrast with the lighter colors */
   --ifm-color-primary-darkest: #000000;
-  --ifm-color-primary-light: #503a54;
-  --ifm-color-primary-lighter: #644869;
-  --ifm-color-primary-lightest: #916798;
+  --ifm-color-primary-light: #6ea5bd; /* A lighter tone for readability */
+  --ifm-color-primary-lighter: #88b2c7; /* A softer shade */
+  --ifm-color-primary-lightest: #9cc4d4; /* Very light for accents */
   --ifm-code-font-size: 95%;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
 }
 
-/* TODO: FIXME the dark view palette */
-/* For readability concerns, you should choose a lighter palette in dark mode. */
+/* Dark mode adjustments */
 [data-theme='dark'] {
-  --ifm-color-primary: #25c2a0;
-  --ifm-color-primary-dark: #21af90;
-  --ifm-color-primary-darker: #1fa588;
-  --ifm-color-primary-darkest: #1a8870;
-  --ifm-color-primary-light: #29d5b0;
-  --ifm-color-primary-lighter: #32d8b4;
-  --ifm-color-primary-lightest: #4fddbf;
-  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
+  --ifm-color-primary: #209683; /* Muted teal color */
+  --ifm-color-primary-dark: #1b7a6a; /* A bit darker but still within the same hue */
+  --ifm-color-primary-darker: #176f61; /* Darker tone for depth */
+  --ifm-color-primary-darkest: #13564e; /* Deepest tone for contrast */
+  --ifm-color-primary-light: #27a792; /* Softened light version */
+  --ifm-color-primary-lighter: #3cb7a2; /* Lighter for accents */
+  --ifm-color-primary-lightest: #57c6b3; /* Lightest, slightly muted */
+  --docusaurus-highlighted-code-line-bg: rgba(255, 255, 255, 0.2); /* Soft highlight */
 }

docs/src/pages/index.module.css

@@ -21,3 +21,8 @@
   align-items: center;
   justify-content: center;
 }
+
+.underConstruction {
+  height: 30%;
+  max-height: 500px;
+}

docs/src/pages/index.tsx

@@ -16,6 +16,7 @@ function HomepageHeader() {
           {siteConfig.title}
         </Heading>
         <p className="hero__subtitle">{siteConfig.tagline}</p>
+        <img className={styles.underConstruction} src="img/site_under_construction_no_bg.png"/>
         <div className={styles.buttons}>
           <Link
             className="button button--secondary button--lg"