Merge pull request #332 from moonbitlang/update-docs

docs: update

docs/manual-zh/src/module/version.md

@@ -7,7 +7,7 @@
 ```json
 {
   "name": "example",
-  "version": "1.0.0",
+  "version": "0.1.0",
   ...
 }
 ```

docs/manual/book.toml

@@ -21,3 +21,7 @@ language = "en"
 multilingual = false
 src = "src"
 title = "Moon Manual"
+
+[output.html.fold]
+enable = true
+level = 0

docs/manual/src/SUMMARY.md

@@ -2,4 +2,30 @@
 
 - [Tutorial](./tutorial.md)
 - [Moon Commands](./commands.md)
+- [Module Configuration](./module.md)
+  - [name](./module/name.md)
+  - [version](./module/version.md)
+  - [deps](./module/deps.md)
+  - [readme](./module/readme.md)
+  - [repository](./module/repository.md)
+  - [license](./module/license.md)
+  - [keywords](./module/keywords.md)
+  - [description](./module/description.md)
+  - [source](./module/source.md)
+  - [warn-list](./package/warnings.md)
+  - [alert-list](./package/alerts.md)
+- [Package Configuration](./package.md)
+  - [name](./package/name.md)
+  - [is-main](./package/is-main.md)
+  - [import](./package/import.md)
+  - [test-import](./package/test-import.md)
+  - [wbtest-import](./package/wbtest-import.md)
+  - [link](./package/link.md)
+    - [wasm](./package/link/wasm.md)
+    - [wasm-gc](./package/link/wasm-gc.md)
+    - [js](./package/link/js.md)
+  - [warn-list](./package/warnings.md)
+  - [alert-list](./package/alerts.md)
+  - [targets](./package/conditional-compilation.md)
+  - [pre-build](./package/pre-build.md)
 - [JSON Schema](./json_schema.md)

docs/manual/src/module.md

@@ -0,0 +1,3 @@
+# Module Configuration
+
+moon uses the `moon.mod.json` file to identify and describe a module.

docs/manual/src/module/deps.md

@@ -0,0 +1,14 @@
+# Deps
+
+The `deps` field is used to specify the dependencies of the module.
+
+It is automatically managed by commands like `moon add` and `moon remove`.
+
+```json
+{
+  "name": "username/hello",
+  "deps": {
+    "moonbitlang/x": "0.4.6"
+  }
+}
+```

docs/manual/src/module/description.md

@@ -0,0 +1,9 @@
+# Description
+
+The `description` field is used to specify the description of the module.
+
+```json
+{
+  "description": "This is a description of the module."
+}
+

docs/manual/src/module/keywords.md

@@ -0,0 +1,9 @@
+# Keywords
+
+The `keywords` field is used to specify the keywords for the module.
+
+```json
+{
+  "keywords": ["example", "test"]
+}
+```

docs/manual/src/module/license.md

@@ -0,0 +1,9 @@
+# License
+
+The `license` field is used to specify the license of the module. The license type must comply with the [SPDX License List](https://spdx.org/licenses/).
+
+```json
+{
+  "license": "MIT"
+}
+```

docs/manual/src/module/name.md

@@ -0,0 +1,21 @@
+# Module Name
+
+The `name` field is used to specify the name of the module, and it is required.
+
+```json
+{
+  "name": "example",
+  ...
+}
+```
+
+The module name can contain letters, numbers, `_`, `-`, and `/`.
+
+For modules published to [mooncakes.io](https://mooncakes.io), the module name must begin with the username. For example:
+
+```json
+{
+  "name": "moonbitlang/core",
+  ...
+}
+```

docs/manual/src/module/readme.md

@@ -0,0 +1,3 @@
+# README
+
+The `readme` field is used to specify the path to the module's README file.

docs/manual/src/module/repository.md

@@ -0,0 +1,3 @@
+# Repository
+
+The `repository` field is used to specify the URL of the module's repository.

docs/manual/src/module/source.md

@@ -0,0 +1,27 @@
+# Source directory
+
+The `source` field is used to specify the source directory of the module.
+
+It must be a subdirectory of the directory where the `moon.mod.json` file is located and must be a relative path.
+
+When creating a module using the `moon new` command, a `src` directory will be automatically generated, and the default value of the `source` field will be `src`.
+
+```json
+{
+  "source": "src"
+}
+```
+
+When the `source` field does not exist, or its value is `null` or an empty string `""`, it is equivalent to setting `"source": "."`. This means that the source directory is the same as the directory where the `moon.mod.json` file is located.
+
+```json
+{
+  "source": null
+}
+{
+  "source": ""
+}
+{
+  "source": "."
+}
+```

docs/manual/src/module/version.md

@@ -0,0 +1,13 @@
+# Version
+
+The `version` field is used to specify the version of the module.
+
+This field is optional. For modules published to [mooncakes.io](https://mooncakes.io), the version number must follow the [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) specification.
+
+```json
+{
+  "name": "example",
+  "version": "0.1.0",
+  ...
+}
+```

docs/manual/src/package.md

@@ -0,0 +1,3 @@
+# Package Configuration
+
+moon uses the `moon.pkg.json` file to identify and describe a package.

docs/manual/src/package/alerts.md

@@ -0,0 +1,9 @@
+# Alert List
+
+Disable user preset alerts.
+
+```json
+{
+  "alert-list": "-alert_1-alert_2"
+}
+```

docs/manual/src/package/conditional-compilation.md

@@ -0,0 +1,35 @@
+# Conditional Compilation
+
+The smallest unit of conditional compilation is a file.
+
+In a conditional compilation expression, three logical operators are supported: `and`, `or`, and `not`, where the `or` operator can be omitted.
+
+For example, `["or", "wasm", "wasm-gc"]` can be simplified to `["wasm", "wasm-gc"]`.
+
+Conditions in the expression can be categorized into backends and optimization levels:
+
+- **Backend conditions**: `"wasm"`, `"wasm-gc"`, and `"js"`
+- **Optimization level conditions**: `"debug"` and `"release"`
+
+Conditional expressions support nesting.
+
+If a file is not listed in `"targets"`, it will be compiled under all conditions by default.
+
+Example:
+
+```json
+{
+    "targets": {
+        "only_js.mbt": ["js"],
+        "only_wasm.mbt": ["wasm"],
+        "only_wasm_gc.mbt": ["wasm-gc"],
+        "all_wasm.mbt": ["wasm", "wasm-gc"],
+        "not_js.mbt": ["not", "js"],
+        "only_debug.mbt": ["debug"],
+        "js_and_release.mbt": ["and", ["js"], ["release"]],
+        "js_only_test.mbt": ["js"],
+        "js_or_wasm.mbt": ["js", "wasm"],
+        "wasm_release_or_js_debug.mbt": ["or", ["and", "wasm", "release"], ["and", "js", "debug"]]
+    }
+}
+```

docs/manual/src/package/import.md

@@ -0,0 +1,3 @@
+# import
+
+The `import` field is used to specify other packages that a package depends on.

docs/manual/src/package/is-main.md

@@ -0,0 +1,8 @@
+# is-main
+
+The `is-main` field is used to specify whether a package needs to be linked into an executable file.
+
+The output of the linking process depends on the backend. When this field is set to `true`:
+
+- For the `wasm` and `wasm-gc` backends, a standalone WebAssembly module will be generated.
+- For the `js` backend, a standalone JavaScript file will be generated.

docs/manual/src/package/link.md

@@ -0,0 +1,15 @@
+# Link Options
+
+By default, moon only links packages where `is-main` is set to `true`. If you need to link other packages, you can specify this with the `link` option.
+
+The `link` option is used to specify link options, and its value can be either a boolean or an object.
+
+- When the `link` value is `true`, it indicates that the package should be linked. The output will vary depending on the backend specified during the build.
+
+  ```json
+  {
+    "link": true
+  }
+  ```
+
+- When the `link` value is an object, it indicates that the package should be linked, and you can specify link options. For detailed configuration, please refer to the subpage for the corresponding backend.

docs/manual/src/package/link/js.md

@@ -0,0 +1,38 @@
+# JS Backend Link Options
+
+#### Configurable Options
+
+- The `exports` option is used to specify the function names to export in the JavaScript module.
+
+  For example, in the following configuration, the `hello` function from the current package is exported as the `hello` function in the JavaScript module. In the JavaScript host, the `hello` function can be called to invoke the `hello` function from the current package.
+
+  ```json
+  {
+    "link": {
+      "js": {
+        "exports": [
+          "hello"
+        ]
+      }
+    }
+  }
+  ```
+
+- The `format` option is used to specify the output format of the JavaScript module.
+
+  The currently supported formats are:
+  - `esm`
+  - `cjs`
+  - `iife`
+
+  For example, the following configuration sets the output format of the current package to ES Module.
+
+  ```json
+  {
+    "link": {
+      "js": {
+        "format": "esm"
+      }
+    }
+  }
+  ```

docs/manual/src/package/link/wasm-gc.md

@@ -0,0 +1,3 @@
+# wasm-gc Backend Link Options
+
+The link options for the `wasm-gc` backend are similar to those for the `wasm` backend, except there is no `heap-start-address` option.

docs/manual/src/package/link/wasm.md

@@ -0,0 +1,63 @@
+# wasm Backend Link Options
+
+#### Configurable Options
+
+- The `exports` option is used to specify the function names exported by the `wasm` backend.
+
+  For example, in the following configuration, the `hello` function from the current package is exported as the `hello` function in the `wasm` module, and the `foo` function is exported as the `bar` function in the `wasm` module. In the `wasm` host, the `hello` and `bar` functions can be called to invoke the `hello` and `foo` functions from the current package.
+
+  ```json
+  {
+    "link": {
+      "wasm": {
+        "exports": [
+          "hello",
+          "foo:bar"
+        ]
+      }
+    }
+  }
+  ```
+
+- The `heap-start-address` option is used to specify the starting address of the linear memory that can be used when compiling to the `wasm` backend.
+
+  For example, the following configuration sets the starting address of the linear memory to 1024.
+
+  ```json
+  {
+    "link": {
+      "wasm": {
+        "heap-start-address": 1024
+      }
+    }
+  }
+  ```
+
+- The `import-memory` option is used to specify the linear memory imported by the `wasm` module.
+
+  For example, the following configuration specifies that the linear memory imported by the `wasm` module is the `memory` variable from the `env` module.
+
+  ```json
+  {
+    "link": {
+      "wasm": {
+        "import-memory": {
+          "module": "env",
+          "name": "memory"
+        }
+      }
+    }
+  }
+  ```
+
+- The `export-memory-name` option is used to specify the name of the linear memory exported by the `wasm` module.
+
+  ```json
+  {
+    "link": {
+      "wasm": {
+        "export-memory-name": "memory"
+      }
+    }
+  }
+  ```

docs/manual/src/package/name.md

@@ -0,0 +1,3 @@
+# Name
+
+The package name is not configurable; it is determined by the directory name of the package.

docs/manual/src/package/pre-build.md

@@ -0,0 +1,34 @@
+# Pre-build
+
+The `"pre-build"` field is used to specify pre-build commands, which will be executed before build commands such as `moon check|build|test`.
+
+`"pre-build"` is an array, where each element is an object containing `input`, `output`, and `command` fields. The `input` and `output` fields can be strings or arrays of strings, while the `command` field is a string. In the `command`, you can use any shell commands, as well as the `$input` and `$output` variables, which represent the input and output files, respectively. If these fields are arrays, they will be joined with spaces by default.
+
+Currently, there is a built-in special command `:embed`, which converts files into MoonBit source code. The `--text` parameter is used to embed text files, and `--binary` is used for binary files. `--text` is the default and can be omitted. The `--name` parameter is used to specify the generated variable name, with `resource` being the default. The command is executed in the directory where the `moon.pkg.json` file is located.
+
+```json
+{
+  "pre-build": [
+    {
+      "input": "a.txt",
+      "output": "a.mbt",
+      "command": ":embed -i $input -o $output"
+    }
+  ]
+}
+```
+
+If the content of `a.txt` in the current package directory is:
+```
+hello,
+world
+```
+
+After running `moon build`, the following `a.mbt` file will be generated in the directory where the `moon.pkg.json` is located:
+
+```
+let resource : String =
+  #|hello,
+  #|world
+  #|
+```