From 77b3a17f1771708f4b1be393c59e7935a4fb445d Mon Sep 17 00:00:00 2001 From: Li Junchen Date: Fri, 20 Sep 2024 17:38:32 +0800 Subject: [PATCH 1/2] docs: add pkg and mod configurations --- docs/manual/book.toml | 4 ++ docs/manual/src/SUMMARY.md | 26 ++++++++ docs/manual/src/module.md | 3 + docs/manual/src/module/deps.md | 14 +++++ docs/manual/src/module/description.md | 9 +++ docs/manual/src/module/keywords.md | 9 +++ docs/manual/src/module/license.md | 9 +++ docs/manual/src/module/name.md | 21 +++++++ docs/manual/src/module/readme.md | 3 + docs/manual/src/module/repository.md | 3 + docs/manual/src/module/source.md | 27 ++++++++ docs/manual/src/module/version.md | 13 ++++ docs/manual/src/package.md | 3 + docs/manual/src/package/alerts.md | 9 +++ .../src/package/conditional-compilation.md | 35 +++++++++++ docs/manual/src/package/import.md | 3 + docs/manual/src/package/is-main.md | 8 +++ docs/manual/src/package/link.md | 15 +++++ docs/manual/src/package/link/js.md | 38 +++++++++++ docs/manual/src/package/link/wasm-gc.md | 3 + docs/manual/src/package/link/wasm.md | 63 +++++++++++++++++++ docs/manual/src/package/name.md | 3 + docs/manual/src/package/pre-build.md | 34 ++++++++++ docs/manual/src/package/test-import.md | 3 + docs/manual/src/package/warnings.md | 45 +++++++++++++ docs/manual/src/package/wbtest-import.md | 3 + 26 files changed, 406 insertions(+) create mode 100644 docs/manual/src/module.md create mode 100644 docs/manual/src/module/deps.md create mode 100644 docs/manual/src/module/description.md create mode 100644 docs/manual/src/module/keywords.md create mode 100644 docs/manual/src/module/license.md create mode 100644 docs/manual/src/module/name.md create mode 100644 docs/manual/src/module/readme.md create mode 100644 docs/manual/src/module/repository.md create mode 100644 docs/manual/src/module/source.md create mode 100644 docs/manual/src/module/version.md create mode 100644 docs/manual/src/package.md create mode 100644 docs/manual/src/package/alerts.md create mode 100644 docs/manual/src/package/conditional-compilation.md create mode 100644 docs/manual/src/package/import.md create mode 100644 docs/manual/src/package/is-main.md create mode 100644 docs/manual/src/package/link.md create mode 100644 docs/manual/src/package/link/js.md create mode 100644 docs/manual/src/package/link/wasm-gc.md create mode 100644 docs/manual/src/package/link/wasm.md create mode 100644 docs/manual/src/package/name.md create mode 100644 docs/manual/src/package/pre-build.md create mode 100644 docs/manual/src/package/test-import.md create mode 100644 docs/manual/src/package/warnings.md create mode 100644 docs/manual/src/package/wbtest-import.md diff --git a/docs/manual/book.toml b/docs/manual/book.toml index 79fd56eb..2f11e8ad 100644 --- a/docs/manual/book.toml +++ b/docs/manual/book.toml @@ -21,3 +21,7 @@ language = "en" multilingual = false src = "src" title = "Moon Manual" + +[output.html.fold] +enable = true +level = 0 diff --git a/docs/manual/src/SUMMARY.md b/docs/manual/src/SUMMARY.md index 48ffc3c5..d1b8965f 100644 --- a/docs/manual/src/SUMMARY.md +++ b/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) diff --git a/docs/manual/src/module.md b/docs/manual/src/module.md new file mode 100644 index 00000000..d4595af9 --- /dev/null +++ b/docs/manual/src/module.md @@ -0,0 +1,3 @@ +# Module Configuration + +moon uses the `moon.mod.json` file to identify and describe a module. diff --git a/docs/manual/src/module/deps.md b/docs/manual/src/module/deps.md new file mode 100644 index 00000000..21f807a4 --- /dev/null +++ b/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" + } +} +``` \ No newline at end of file diff --git a/docs/manual/src/module/description.md b/docs/manual/src/module/description.md new file mode 100644 index 00000000..3e2c891d --- /dev/null +++ b/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." +} + diff --git a/docs/manual/src/module/keywords.md b/docs/manual/src/module/keywords.md new file mode 100644 index 00000000..0d4c3678 --- /dev/null +++ b/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"] +} +``` \ No newline at end of file diff --git a/docs/manual/src/module/license.md b/docs/manual/src/module/license.md new file mode 100644 index 00000000..4bb6d421 --- /dev/null +++ b/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" +} +``` diff --git a/docs/manual/src/module/name.md b/docs/manual/src/module/name.md new file mode 100644 index 00000000..4cee24f0 --- /dev/null +++ b/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", + ... +} +``` \ No newline at end of file diff --git a/docs/manual/src/module/readme.md b/docs/manual/src/module/readme.md new file mode 100644 index 00000000..48767606 --- /dev/null +++ b/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. diff --git a/docs/manual/src/module/repository.md b/docs/manual/src/module/repository.md new file mode 100644 index 00000000..f00accd5 --- /dev/null +++ b/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. diff --git a/docs/manual/src/module/source.md b/docs/manual/src/module/source.md new file mode 100644 index 00000000..ed5e2f97 --- /dev/null +++ b/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": "." +} +``` \ No newline at end of file diff --git a/docs/manual/src/module/version.md b/docs/manual/src/module/version.md new file mode 100644 index 00000000..dd5869b1 --- /dev/null +++ b/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": "1.0.0", + ... +} +``` diff --git a/docs/manual/src/package.md b/docs/manual/src/package.md new file mode 100644 index 00000000..5b6acef9 --- /dev/null +++ b/docs/manual/src/package.md @@ -0,0 +1,3 @@ +# Package Configuration + +moon uses the `moon.pkg.json` file to identify and describe a package. diff --git a/docs/manual/src/package/alerts.md b/docs/manual/src/package/alerts.md new file mode 100644 index 00000000..c9612a79 --- /dev/null +++ b/docs/manual/src/package/alerts.md @@ -0,0 +1,9 @@ +# Alert List + +Disable user preset alerts. + +```json +{ + "alert-list": "-alert_1-alert_2" +} +``` diff --git a/docs/manual/src/package/conditional-compilation.md b/docs/manual/src/package/conditional-compilation.md new file mode 100644 index 00000000..67fcc5ff --- /dev/null +++ b/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"]] + } +} +``` diff --git a/docs/manual/src/package/import.md b/docs/manual/src/package/import.md new file mode 100644 index 00000000..e6914995 --- /dev/null +++ b/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. diff --git a/docs/manual/src/package/is-main.md b/docs/manual/src/package/is-main.md new file mode 100644 index 00000000..150f5f7e --- /dev/null +++ b/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. diff --git a/docs/manual/src/package/link.md b/docs/manual/src/package/link.md new file mode 100644 index 00000000..4fd2803d --- /dev/null +++ b/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. diff --git a/docs/manual/src/package/link/js.md b/docs/manual/src/package/link/js.md new file mode 100644 index 00000000..0a5d2bec --- /dev/null +++ b/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" + } + } + } + ``` diff --git a/docs/manual/src/package/link/wasm-gc.md b/docs/manual/src/package/link/wasm-gc.md new file mode 100644 index 00000000..9f949ff7 --- /dev/null +++ b/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. diff --git a/docs/manual/src/package/link/wasm.md b/docs/manual/src/package/link/wasm.md new file mode 100644 index 00000000..dbf237d2 --- /dev/null +++ b/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" + } + } + } + ``` \ No newline at end of file diff --git a/docs/manual/src/package/name.md b/docs/manual/src/package/name.md new file mode 100644 index 00000000..311773ef --- /dev/null +++ b/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. diff --git a/docs/manual/src/package/pre-build.md b/docs/manual/src/package/pre-build.md new file mode 100644 index 00000000..bdd77178 --- /dev/null +++ b/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 + #| +``` \ No newline at end of file diff --git a/docs/manual/src/package/test-import.md b/docs/manual/src/package/test-import.md new file mode 100644 index 00000000..ced480f1 --- /dev/null +++ b/docs/manual/src/package/test-import.md @@ -0,0 +1,3 @@ +# test-import + +The `test-import` field is used to specify other packages that the black-box test package of this package depends on. diff --git a/docs/manual/src/package/warnings.md b/docs/manual/src/package/warnings.md new file mode 100644 index 00000000..b562e4d6 --- /dev/null +++ b/docs/manual/src/package/warnings.md @@ -0,0 +1,45 @@ +# Warning List + +This is used to disable specific preset compiler warning numbers. + +For example, in the following configuration, `-2` disables the warning number 2 (Unused variable). + +```json +{ + "warn-list": "-2", +} +``` + +You can use `moonc build-package -warn-help` to see the list of preset compiler warning numbers. + +``` +$ moonc -v +v0.1.20240914+b541585d3 + +$ moonc build-package -warn-help +Available warnings: + 1 Unused function. + 2 Unused variable. + 3 Unused type declaration. + 4 Redundant case in a pattern matching (unused match case). + 5 Unused function argument. + 6 Unused constructor. + 7 Unused module declaration. + 8 Unused struct field. + 10 Unused generic type variable. + 11 Partial pattern matching. + 12 Unreachable code. + 13 Unresolved type variable. + 14 Lowercase type name. + 15 Unused mutability. + 16 Parser inconsistency. + 18 Useless loop expression. + 19 Top-level declaration is not left aligned. + 20 Invalid pragma + 21 Some arguments of constructor are omitted in pattern. + 22 Ambiguous block. + 23 Useless try expression. + 24 Useless error type. + 26 Useless catch all. + A all warnings +``` \ No newline at end of file diff --git a/docs/manual/src/package/wbtest-import.md b/docs/manual/src/package/wbtest-import.md new file mode 100644 index 00000000..685e4b23 --- /dev/null +++ b/docs/manual/src/package/wbtest-import.md @@ -0,0 +1,3 @@ +# wbtest-import + +The `wbtest-import` field is used to specify other packages that the white-box test package of this package depends on. From b3ddd44898477d6fdda6592c7f92ee2bec64c7f6 Mon Sep 17 00:00:00 2001 From: Li Junchen Date: Fri, 20 Sep 2024 17:39:02 +0800 Subject: [PATCH 2/2] docs: tweak version example --- docs/manual-zh/src/module/version.md | 2 +- docs/manual/src/module/version.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/manual-zh/src/module/version.md b/docs/manual-zh/src/module/version.md index f5410382..a5050c16 100644 --- a/docs/manual-zh/src/module/version.md +++ b/docs/manual-zh/src/module/version.md @@ -7,7 +7,7 @@ ```json { "name": "example", - "version": "1.0.0", + "version": "0.1.0", ... } ``` diff --git a/docs/manual/src/module/version.md b/docs/manual/src/module/version.md index dd5869b1..cecf1b75 100644 --- a/docs/manual/src/module/version.md +++ b/docs/manual/src/module/version.md @@ -7,7 +7,7 @@ This field is optional. For modules published to [mooncakes.io](https://mooncake ```json { "name": "example", - "version": "1.0.0", + "version": "0.1.0", ... } ```