From 0427c9eddbbef95ae0a47cf1ebeaefa520139811 Mon Sep 17 00:00:00 2001 From: Andrea Peruffo Date: Fri, 18 Oct 2024 11:57:47 +0100 Subject: [PATCH 1/6] use npm ci in GH actions --- .github/workflows/ci.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 0dcc90ea2..fad8ec7d1 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -69,7 +69,7 @@ jobs: - name: Test Docs working-directory: docs run: | - npm install + npm ci npm run test test-results: From 1746beb50e2d9c5b199df294add3470ea720d7a8 Mon Sep 17 00:00:00 2001 From: Andrea Peruffo Date: Fri, 18 Oct 2024 16:39:44 +0100 Subject: [PATCH 2/6] run npm audit fix --- docs/package-lock.json | 36 ++++++++++++++---------------------- 1 file changed, 14 insertions(+), 22 deletions(-) diff --git a/docs/package-lock.json b/docs/package-lock.json index bafecda9c..d5d156050 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -6005,8 +6005,9 @@ "license": "MIT" }, "node_modules/cookie": { - "version": "0.6.0", - "license": "MIT", + "version": "0.7.1", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.1.tgz", + "integrity": "sha512-6DnInpx7SJ2AK3+CTUE/ZM0vWTUboZCegxhC2xiIydHR9jNuTAASBrfEpHhiGOZw/nX51bHt6YQl8jsGo4y/0w==", "engines": { "node": ">= 0.6" } @@ -7543,15 +7544,16 @@ } }, "node_modules/express": { - "version": "4.21.0", - "license": "MIT", + "version": "4.21.1", + "resolved": "https://registry.npmjs.org/express/-/express-4.21.1.tgz", + "integrity": "sha512-YSFlK1Ee0/GC8QaO91tHcDxJiE/X4FbpAyQWkxAvG6AXCuR65YzK8ua6D9hvi/TzUfZMpc+BwuM1IPw8fmQBiQ==", "dependencies": { "accepts": "~1.3.8", "array-flatten": "1.1.1", "body-parser": "1.20.3", "content-disposition": "0.5.4", "content-type": "~1.0.4", - "cookie": "0.6.0", + "cookie": "0.7.1", "cookie-signature": "1.0.6", "debug": "2.6.9", "depd": "2.0.0", @@ -7662,13 +7664,6 @@ "version": "3.0.2", "license": "MIT" }, - "node_modules/fast-url-parser": { - "version": "1.1.3", - "license": "MIT", - "dependencies": { - "punycode": "^1.3.2" - } - }, "node_modules/fastq": { "version": "1.17.1", "license": "ISC", @@ -14060,10 +14055,6 @@ "node": ">= 0.10" } }, - "node_modules/punycode": { - "version": "1.4.1", - "license": "MIT" - }, "node_modules/pupa": { "version": "3.1.0", "license": "MIT", @@ -15107,22 +15098,23 @@ } }, "node_modules/serve-handler": { - "version": "6.1.5", - "license": "MIT", + "version": "6.1.6", + "resolved": "https://registry.npmjs.org/serve-handler/-/serve-handler-6.1.6.tgz", + "integrity": "sha512-x5RL9Y2p5+Sh3D38Fh9i/iQ5ZK+e4xuXRd/pGbM4D13tgo/MGwbttUk8emytcr1YYzBYs+apnUngBDFYfpjPuQ==", "dependencies": { "bytes": "3.0.0", "content-disposition": "0.5.2", - "fast-url-parser": "1.1.3", "mime-types": "2.1.18", "minimatch": "3.1.2", "path-is-inside": "1.0.2", - "path-to-regexp": "2.2.1", + "path-to-regexp": "3.3.0", "range-parser": "1.2.0" } }, "node_modules/serve-handler/node_modules/path-to-regexp": { - "version": "2.2.1", - "license": "MIT" + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-3.3.0.tgz", + "integrity": "sha512-qyCH421YQPS2WFDxDjftfc1ZR5WKQzVzqsp4n9M2kQhVOo/ByahFoUNJfl58kOcEGfQ//7weFTDhm+ss8Ecxgw==" }, "node_modules/serve-index": { "version": "1.9.1", From 1ae6db646e7995f76a723c81981f0010bf1be964 Mon Sep 17 00:00:00 2001 From: Andrea Peruffo Date: Fri, 18 Oct 2024 16:58:41 +0100 Subject: [PATCH 3/6] chore - improve the setup and namings --- docs/docs/index.md | 1 + docs/docs/usage/memory.md | 2 ++ docs/docusaurus.config.ts | 4 ++-- docs/src/pages/index.tsx | 2 +- 4 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/docs/index.md b/docs/docs/index.md index 8159beb9c..de69ea219 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -1,5 +1,6 @@ --- sidebar_position: 1 +sidebar_label: Docs --- ## Getting Started diff --git a/docs/docs/usage/memory.md b/docs/docs/usage/memory.md index 337a89547..27ac21c06 100644 --- a/docs/docs/usage/memory.md +++ b/docs/docs/usage/memory.md @@ -1,5 +1,7 @@ --- +id: Memory usage sidebar_position: 1 +sidebar_label: Memory usage --- ## Using the memory to share data diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 6dd7ac827..d4f19e8ce 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -68,7 +68,7 @@ const config: Config = { type: 'docSidebar', sidebarId: 'tutorialSidebar', position: 'left', - label: 'Tutorial', + label: 'Docs', }, { to: '/blog', label: 'Blog', position: 'left' }, { @@ -85,7 +85,7 @@ const config: Config = { title: 'Docs', items: [ { - label: 'Tutorial', + label: 'Docs', to: '/docs', }, ], diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx index 1f357ade7..377262c0a 100644 --- a/docs/src/pages/index.tsx +++ b/docs/src/pages/index.tsx @@ -21,7 +21,7 @@ function HomepageHeader() { - Get Started Tutorial + Get Started From 8fc794d2f231e21df69636ba774b4c26fc1c1b13 Mon Sep 17 00:00:00 2001 From: Andrea Peruffo Date: Fri, 18 Oct 2024 18:18:43 +0100 Subject: [PATCH 4/6] add all the docs section to the static site --- docs/docs/usage/host-functions.md | 93 +++++++++++++++++++ docs/docs/usage/linking.md | 92 ++++++++++++++++++ docs/docs/usage/logging.md | 24 +++++ .../docs-usage-host-functions.md.approved.txt | 10 ++ .../docs-usage-linking.md.approved.txt | 1 + .../docs-usage-logging.md.approved.txt | 1 + 6 files changed, 221 insertions(+) create mode 100644 docs/docs/usage/host-functions.md create mode 100644 docs/docs/usage/linking.md create mode 100644 docs/docs/usage/logging.md create mode 100644 docs/tests/approvals/docs-usage-host-functions.md.approved.txt create mode 100644 docs/tests/approvals/docs-usage-linking.md.approved.txt create mode 100644 docs/tests/approvals/docs-usage-logging.md.approved.txt diff --git a/docs/docs/usage/host-functions.md b/docs/docs/usage/host-functions.md new file mode 100644 index 000000000..a81705d78 --- /dev/null +++ b/docs/docs/usage/host-functions.md @@ -0,0 +1,93 @@ +--- +id: Host functions +sidebar_position: 1 +sidebar_label: Host functions +--- + +### Host Functions + +On its own, Wasm can't do anything but compute. It cannot affect the outside world. This might seem like a weakness +but it's actually Wasm's greatest strength. By default, programs are sandboxed and have no capabilities. If you want a program +to have capabilities, you must provide them. This puts you in the seat of the operating system. A module can +ask for a capability by listing an "import" function in it's bytecode format. You can fulfill this import with a host +function written in Java. Regardless of the language of the module, it can call this Java function when it needs. +If it helps, you can think of host functions like syscalls or a languages standard library but you decide what they +are and how they behave and it's written in Java. + +Let's download another example module to demonstrate this: + +```bash +curl https://raw.githubusercontent.com/dylibso/chicory/main/wasm-corpus/src/main/resources/compiled/host-function.wat.wasm > logger.wasm +``` + + + + +This module expects us to fulfil an import with the name `console.log` which will allow the module to log to the stdout. +Let's write that host function: + + + + +```java +import com.dylibso.chicory.runtime.Instance; +import com.dylibso.chicory.runtime.HostFunction; +import com.dylibso.chicory.wasm.types.ValueType; + +var func = new HostFunction( + "console", + "log", + (Instance instance, long... args) -> { // decompiled is: console_log(13, 0); + var len = (int) args[0]; + var offset = (int) args[1]; + var message = instance.memory().readString(offset, len); + println(message); + return null; + }, + List.of(ValueType.I32, ValueType.I32), + List.of()); +``` + +Again we're dealing with pointers here. The module calls `console.log` with the length of the string +and the pointer (offset) in its memory. We again use the `Memory` class but this time we're pulling a string +*out* of memory. We can then print that to stdout on behalf of our Wasm program. + +Note that the HostFunction needs 3 things: + +1. A lambda to call when the Wasm module invokes the import +2. The namespace and function name of the import (in our case it's console and log respectively) +3. The Wasm type signature (this function takes 2 i32s as arguments and returns nothing) + +Now we just need to pass this host function in during our instantiation phase: + +```java +import com.dylibso.chicory.wasm.Parser; +import com.dylibso.chicory.runtime.ExternalValues; +var hostFunctions = new ExternalValues(new HostFunction[] {func}); +var instance = Instance.builder(Parser.parse(new File("./logger.wasm"))).withExternalValues(hostFunctions).build(); +var logIt = instance.export("logIt"); +logIt.apply(); +// should print "Hello, World!" 10 times +``` + + diff --git a/docs/docs/usage/linking.md b/docs/docs/usage/linking.md new file mode 100644 index 000000000..3aef480fc --- /dev/null +++ b/docs/docs/usage/linking.md @@ -0,0 +1,92 @@ +--- +id: Linking +sidebar_position: 1 +sidebar_label: Linking +--- + +### Store and Instantiating Multiple Modules + +A [Store][spec] is an intermediate-level abstraction that collects Wasm function, global, memory, and table instances +as named entities. + +It simplifies creating instances when there are a lot of interdependencies, by collecting all the + +In the simplest case, it allows to register single host functions, globals, memories and tables: + + + +```java +import com.dylibso.chicory.runtime.Store; + +// instantiate the store +var store = new Store(); +// registers `console.log` in the store (see the previous section for the definition of `func`) +store.addFunction(func); +``` + +However, the store also automatically exposes the exports of a module to the other instances that are registered. + +```java +// registers the `instance` created earlier (see the previous section) with the name `logger` +store.register("logger", instance); +// now the exported function `logIt` can be imported by other modules as `logger.logIt` +``` + +There is also a shorthand method to instantiate a module and register the resulting instance: + +```java +var logger2 = store.instantiate("logger2", Parser.parse(new File("./logger.wasm"))); +``` + +This is equivalent to: + +```java +var external = store.toExternalValues(); +var m = Parser.parse(new File("./logger.wasm")); +var instance = Instance.builder(m).withExternalValues(external).build(); +store.register("logger2", instance); +``` + +Notice that registering two instances with the same name results in overwriting the +functions, globals, memories, tables with matching names. In this case, the new `logger2.logIt` function +overwrote the old `logger2.logIt` function. + +The current `Store` is a mutable object, not meant to be shared (it is not thread-safe). + +A `Store` _does not_ resolve interdependencies between modules in itself: if your set of modules +have interdependencies, you will have to instantiate and register them in the right order. + +[spec]: https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#store%E2%91%A0 + + diff --git a/docs/docs/usage/logging.md b/docs/docs/usage/logging.md new file mode 100644 index 000000000..ff22fe43a --- /dev/null +++ b/docs/docs/usage/logging.md @@ -0,0 +1,24 @@ +--- +id: Logging +sidebar_position: 1 +sidebar_label: Logging +--- + +### Logging + +For maximum compatibility and to avoid external dependencies we use, by default, the JDK Platform Logging (JEP 264). +You can configure it by providing a `logging.properties` using the `java.util.logging.config.file` property and [here](https://docs.oracle.com/cd/E57471_01/bigData.100/data_processing_bdd/src/rdp_logging_config.html) you can find the possible configurations. + +For more advanced configuration scenarios we encourage you to provide an alternative, compatible, adapter: + +- [slf4j](https://www.slf4j.org/manual.html#jep264) +- [log4j2](https://logging.apache.org/log4j/2.x/log4j-jpl.html) + +It's also possible to provide a custom `com.dylibso.chicory.log.Logger` implementation if JDK Platform Logging is not available or doesn't fit. + + diff --git a/docs/tests/approvals/docs-usage-host-functions.md.approved.txt b/docs/tests/approvals/docs-usage-host-functions.md.approved.txt new file mode 100644 index 000000000..03b47c4e3 --- /dev/null +++ b/docs/tests/approvals/docs-usage-host-functions.md.approved.txt @@ -0,0 +1,10 @@ +Hello, World! +Hello, World! +Hello, World! +Hello, World! +Hello, World! +Hello, World! +Hello, World! +Hello, World! +Hello, World! +Hello, World! diff --git a/docs/tests/approvals/docs-usage-linking.md.approved.txt b/docs/tests/approvals/docs-usage-linking.md.approved.txt new file mode 100644 index 000000000..c6cac6926 --- /dev/null +++ b/docs/tests/approvals/docs-usage-linking.md.approved.txt @@ -0,0 +1 @@ +empty diff --git a/docs/tests/approvals/docs-usage-logging.md.approved.txt b/docs/tests/approvals/docs-usage-logging.md.approved.txt new file mode 100644 index 000000000..c6cac6926 --- /dev/null +++ b/docs/tests/approvals/docs-usage-logging.md.approved.txt @@ -0,0 +1 @@ +empty From 9691719f4d157dc75053bf3cef418a1711b8b3e0 Mon Sep 17 00:00:00 2001 From: Andrea Peruffo Date: Fri, 18 Oct 2024 18:24:50 +0100 Subject: [PATCH 5/6] Remove pages in docs from the readme --- README.md | 339 +----------------------------------------------------- 1 file changed, 1 insertion(+), 338 deletions(-) diff --git a/README.md b/README.md index 616916fcd..443ee22d2 100644 --- a/README.md +++ b/README.md @@ -16,332 +16,7 @@ simplicity and safety in mind. See the [development section](#development) for a ## Getting Started (as a user) -### Install Dependency - -To use the runtime, you need to add the `com.dylibso.chicory:runtime` dependency -to your dependency management system. - -#### Maven - -```xml - - com.dylibso.chicory - runtime - 0.0.12 - -``` - -#### 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//cli-.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 -``` - - - - - -### 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 -``` - - - -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!) -``` - - - -> *Note*: Functions in Wasm can have multiple returns but here we're just taking the first returned value. - -### Memory and Complex Types - -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 -``` - - - -Build and instantiate this module: - -```java -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! -``` - - - -### Host Functions - -On its own, Wasm can't do anything but compute. It cannot affect the outside world. This might seem like a weakness -but it's actually Wasm's greatest strength. By default, programs are sandboxed and have no capabilities. If you want a program -to have capabilities, you must provide them. This puts you in the seat of the operating system. A module can -ask for a capability by listing an "import" function in it's bytecode format. You can fulfill this import with a host -function written in Java. Regardless of the language of the module, it can call this Java function when it needs. -If it helps, you can think of host functions like syscalls or a languages standard library but you decide what they -are and how they behave and it's written in Java. - -Let's download another example module to demonstrate this: - -```bash -curl https://raw.githubusercontent.com/dylibso/chicory/main/wasm-corpus/src/main/resources/compiled/host-function.wat.wasm > logger.wasm -``` - - - -This module expects us to fulfil an import with the name `console.log` which will allow the module to log to the stdout. -Let's write that host function: - - - - -```java -import com.dylibso.chicory.runtime.HostFunction; -import com.dylibso.chicory.wasm.types.ValueType; -var func = new HostFunction( - "console", - "log", - (Instance instance, long... args) -> { // decompiled is: console_log(13, 0); - var len = (int) args[0]; - var offset = (int) args[1]; - var message = instance.memory().readString(offset, len); - println(message); - return null; - }, - List.of(ValueType.I32, ValueType.I32), - List.of()); -``` - -Again we're dealing with pointers here. The module calls `console.log` with the length of the string -and the pointer (offset) in its memory. We again use the `Memory` class but this time we're pulling a string -*out* of memory. We can then print that to stdout on behalf of our Wasm program. - -Note that the HostFunction needs 3 things: - -1. A lambda to call when the Wasm module invokes the import -2. The namespace and function name of the import (in our case it's console and log respectively) -3. The Wasm type signature (this function takes 2 i32s as arguments and returns nothing) - -Now we just need to pass this host function in during our instantiation phase: - -```java -import com.dylibso.chicory.runtime.ExternalValues; -var hostFunctions = new ExternalValues(new HostFunction[] {func}); -var instance = Instance.builder(Parser.parse(new File("./logger.wasm"))).withExternalValues(hostFunctions).build(); -var logIt = instance.export("logIt"); -logIt.apply(); -// should print "Hello, World!" 10 times -``` - - - -### Store and Instantiating Multiple Modules - -A [Store][spec] is an intermediate-level abstraction that collects Wasm function, global, memory, and table instances -as named entities. - -It simplifies creating instances when there are a lot of interdependencies, by collecting all the - -In the simplest case, it allows to register single host functions, globals, memories and tables: - -```java -import com.dylibso.chicory.runtime.Store; - -// instantiate the store -var store = new Store(); -// registers `console.log` in the store (see the previous section for the definition of `func`) -store.addFunction(func); -``` - -However, the store also automatically exposes the exports of a module to the other instances that are registered. - -```java -// registers the `instance` created earlier (see the previous section) with the name `logger` -store.register("logger", instance); -// now the exported function `logIt` can be imported by other modules as `logger.logIt` -``` - -There is also a shorthand method to instantiate a module and register the resulting instance: - -```java -var logger2 = store.instantiate("logger2", Parser.parse(new File("./logger.wasm"))); -``` - -This is equivalent to: - -```java -var external = store.toExternalValues(); -var m = Parser.parse(new File("./logger.wasm")); -var instance = Instance.builder(m).withExternalValues(external).build(); -store.register("logger2", instance); -``` - -Notice that registering two instances with the same name results in overwriting the -functions, globals, memories, tables with matching names. In this case, the new `logger2.logIt` function -overwrote the old `logger2.logIt` function. - -The current `Store` is a mutable object, not meant to be shared (it is not thread-safe). - -A `Store` _does not_ resolve interdependencies between modules in itself: if your set of modules -have interdependencies, you will have to instantiate and register them in the right order. - -[spec]: https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#store%E2%91%A0 +To get started visit the [official documentation](https://chicory.dev/docs/). ## Development @@ -446,15 +121,3 @@ Basic steps: * `./scripts/compile-resources.sh` will recompile and regenerate the `resources/compiled` folders NOTE: The `install` target relies on the `wabt` library to compile the test suite. This is not currently released for ARM (e.g. new Macs with Apple Silicon). However, `wabt` is available from Homebrew, so `brew install wabt` before running `mvn clean install` should work. - -#### logging - -For maximum compatibility and to avoid external dependencies we use, by default, the JDK Platform Logging (JEP 264). -You can configure it by providing a `logging.properties` using the `java.util.logging.config.file` property and [here](https://docs.oracle.com/cd/E57471_01/bigData.100/data_processing_bdd/src/rdp_logging_config.html) you can find the possible configurations. - -For more advanced configuration scenarios we encourage you to provide an alternative, compatible, adapter: - -- [slf4j](https://www.slf4j.org/manual.html#jep264) -- [log4j2](https://logging.apache.org/log4j/2.x/log4j-jpl.html) - -It's also possible to provide a custom `com.dylibso.chicory.log.Logger` implementation if JDK Platform Logging is not available or doesn't fit. From 5fa2f5147b90292bb46bd232f463736df0d3d089 Mon Sep 17 00:00:00 2001 From: Andrea Peruffo Date: Fri, 18 Oct 2024 18:26:22 +0100 Subject: [PATCH 6/6] move instructions to build to contributing.md --- CONTRIBUTING.md | 13 +++++++++++++ README.md | 15 --------------- 2 files changed, 13 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 736405f97..3f685d802 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,6 +70,19 @@ All submissions, including submissions by project members, need to be reviewed a * Commits should be atomic and semantic. Please properly squash your pull requests before submitting them. Fixup commits can be used temporarily during the review process but things should be squashed at the end to have meaningful commits. * We typically squash and merge pull requests when they are approved. This tends to keep the commit history a little bit more tidy without placing undue burden on the developers. +### Building the Runtime + +Contributors and other advanced users may want to build the runtime from source. To do so, you'll need to have Maven installed. +`Java version 11+` required for a proper build. You can download and install [Java 11 Temurin](https://adoptium.net/temurin/releases/?version=11) + +Basic steps: + +* `mvn clean install` to run all of the project's tests and install the library in your local repo +* `mvn -Dquickly` to install the library skipping all tests +* `mvn -Ddev <...goals>` to disable linters and enforcers during development +* `mvn spotless:apply` to autoformat the code +* `./scripts/compile-resources.sh` will recompile and regenerate the `resources/compiled` folders + ### Continuous Integration Because we are all humans, and to ensure Chicory evolves in the right direction, all changes must pass continuous integration before being merged. The CI is based on GitHub Actions, which means that pull requests will receive automatic feedback. Please watch out for the results of these workflows to see if your PR passes all tests. diff --git a/README.md b/README.md index 443ee22d2..249dabde7 100644 --- a/README.md +++ b/README.md @@ -106,18 +106,3 @@ as interpreting bytecode can only be so fast. * [asmble](https://github.com/cretz/asmble) * [kwasm](https://github.com/jasonwyatt/KWasm) * [wazero](https://wazero.io/) - -### Building the Runtime - -Contributors and other advanced users may want to build the runtime from source. To do so, you'll need to have Maven installed. -`Java version 11+` required for a proper build. You can download and install [Java 11 Temurin](https://adoptium.net/temurin/releases/?version=11) - -Basic steps: - -* `mvn clean install` to run all of the project's tests and install the library in your local repo -* `mvn -Dquickly` to install the library skipping all tests -* `mvn -Ddev <...goals>` to disable linters and enforcers during development -* `mvn spotless:apply` to autoformat the code -* `./scripts/compile-resources.sh` will recompile and regenerate the `resources/compiled` folders - -NOTE: The `install` target relies on the `wabt` library to compile the test suite. This is not currently released for ARM (e.g. new Macs with Apple Silicon). However, `wabt` is available from Homebrew, so `brew install wabt` before running `mvn clean install` should work.