Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +moonThis document contains the help content for the moon command-line program.
Command Overview:
+moon↴moon new↴moon build↴moon check↴moon run↴moon test↴moon clean↴moon fmt↴moon doc↴moon info↴moon add↴moon remove↴moon install↴moon tree↴moon login↴moon register↴moon publish↴moon update↴moon coverage↴moon coverage report↴moon coverage clean↴moon generate-build-matrix↴moon upgrade↴moon shell-completion↴moon version↴moonUsage: moon <COMMAND>
new — Create a new MoonBit modulebuild — Build the current packagecheck — Check the current package, but don't build object filesrun — Run a main packagetest — Test the current packageclean — Remove the target directoryfmt — Format source codedoc — Generate documentationinfo — Generate public interface (.mbti) files for all packages in the moduleadd — Add a dependencyremove — Remove a dependencyinstall — Install dependenciestree — Display the dependency treelogin — Log in to your accountregister — Register an account at mooncakes.iopublish — Publish the current packageupdate — Update the package registry indexcoverage — Code coverage utilitiesgenerate-build-matrix — Generate build matrix for benchmarking (legacy feature)upgrade — Upgrade toolchainsshell-completion — Generate shell completion for bash/elvish/fish/pwsh/zsh to stdoutversion — Print version information and exitmoon newCreate a new MoonBit module
+Usage: moon new [OPTIONS] [PACKAGE_NAME]
<PACKAGE_NAME> — The name of the package--lib — Create a library package instead of an executable
--path <PATH> — Output path of the package
--user <USER> — The user name of the package
--name <NAME> — The name part of the package
--license <LICENSE> — The license of the package
Default value: Apache-2.0
--no-license — Do not set a license for the package
moon buildBuild the current package
+Usage: moon build [OPTIONS]
--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
-w, --watch — Monitor the file system and automatically build artifacts
moon checkCheck the current package, but don't build object files
+Usage: moon check [OPTIONS]
--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--output-json — Output in json format
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
-w, --watch — Monitor the file system and automatically check files
moon runRun a main package
+Usage: moon run [OPTIONS] <PACKAGE_OR_MBT_FILE> [ARGS]...
<PACKAGE_OR_MBT_FILE> — The package or .mbt file to run<ARGS> — The arguments provided to the program to be run--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
--build-only — Only build, do not run the code
moon testTest the current package
+Usage: moon test [OPTIONS]
--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--release — run test at release compiled mode
-p, --package <PACKAGE> — Run test in the specified package
-f, --file <FILE> — Run test in the specified file. Only valid when --package is also specified
-i, --index <INDEX> — Run only the index-th test in the file. Only valid when --file is also specified
-u, --update — Update the test snapshot
-l, --limit <LIMIT> — Limit of expect test update passes to run, in order to avoid infinite loops
Default value: 256
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
--build-only — Only build, do not run the tests
--no-parallelize — Run the tests in a target backend sequentially
--test-failure-json — Print failure message in JSON format
moon cleanRemove the target directory
+Usage: moon clean
moon fmtFormat source code
+Usage: moon fmt [OPTIONS]
--check — Check only and don't change the source code--sort-input — Sort input filesmoon docGenerate documentation
+Usage: moon doc [OPTIONS]
--serve — Start a web server to serve the documentation
-b, --bind <BIND> — The address of the server
Default value: 127.0.0.1
-p, --port <PORT> — The port of the server
Default value: 3000
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
moon infoGenerate public interface (.mbti) files for all packages in the module
Usage: moon info [OPTIONS]
--frozen — Do not sync dependencies, assuming local dependencies are up-to-datemoon addAdd a dependency
+Usage: moon add <PACKAGE_PATH>
<PACKAGE_PATH> — The package path to addmoon removeRemove a dependency
+Usage: moon remove <PACKAGE_PATH>
<PACKAGE_PATH> — The package path to removemoon installInstall dependencies
+Usage: moon install
moon treeDisplay the dependency tree
+Usage: moon tree
moon loginLog in to your account
+Usage: moon login
moon registerRegister an account at mooncakes.io
+Usage: moon register
moon publishPublish the current package
+Usage: moon publish [OPTIONS]
--frozen — Do not sync dependencies, assuming local dependencies are up-to-datemoon updateUpdate the package registry index
+Usage: moon update
moon coverageCode coverage utilities
+Usage: moon coverage <COMMAND>
report — Generate code coverage reportclean — Clean up coverage artifactsmoon coverage reportGenerate code coverage report
+Usage: moon coverage report [args]... [COMMAND]
<args> — Arguments to pass to the coverage utility-h, --help — Show help for the coverage utilitymoon coverage cleanClean up coverage artifacts
+Usage: moon coverage clean
moon generate-build-matrixGenerate build matrix for benchmarking (legacy feature)
+Usage: moon generate-build-matrix [OPTIONS] --output-dir <OUT_DIR>
-n <NUMBER> — Set all of drow, dcol, mrow, mcol to the same value--drow <DIR_ROWS> — Number of directory rows--dcol <DIR_COLS> — Number of directory columns--mrow <MOD_ROWS> — Number of module rows--mcol <MOD_COLS> — Number of module columns-o, --output-dir <OUT_DIR> — The output directorymoon upgradeUpgrade toolchains
+Usage: moon upgrade [OPTIONS]
-f, --force — Force upgrademoon shell-completionGenerate shell completion for bash/elvish/fish/pwsh/zsh to stdout
+Usage: moon shell-completion [OPTIONS]
Discussion:
+Enable tab completion for Bash, Elvish, Fish, Zsh, or PowerShell
+The script is output on stdout, allowing one to re-direct the
+output to the file of their choosing. Where you place the file
+will depend on which shell, and which operating system you are
+using. Your particular configuration may also determine where
+these scripts need to be placed.
The completion scripts won't update itself, so you may need to
+periodically run this command to get the latest completions.
+Or you may put `eval "$(moon shell-completion --shell <SHELL>)"`
+in your shell's rc file to always load newest completions on startup.
+Although it's considered not as efficient as having the completions
+script installed.
+
+Here are some common set ups for the three supported shells under
+Unix and similar operating systems (such as GNU/Linux).
+
+Bash:
+
+Completion files are commonly stored in `/etc/bash_completion.d/` for
+system-wide commands, but can be stored in
+`~/.local/share/bash-completion/completions` for user-specific commands.
+Run the command:
+
+ $ mkdir -p ~/.local/share/bash-completion/completions
+ $ moon shell-completion --shell bash >> ~/.local/share/bash-completion/completions/moon
+
+This installs the completion script. You may have to log out and
+log back in to your shell session for the changes to take effect.
+
+Bash (macOS/Homebrew):
+
+Homebrew stores bash completion files within the Homebrew directory.
+With the `bash-completion` brew formula installed, run the command:
+
+ $ mkdir -p $(brew --prefix)/etc/bash_completion.d
+ $ moon shell-completion --shell bash > $(brew --prefix)/etc/bash_completion.d/moon.bash-completion
+
+Fish:
+
+Fish completion files are commonly stored in
+`$HOME/.config/fish/completions`. Run the command:
+
+ $ mkdir -p ~/.config/fish/completions
+ $ moon shell-completion --shell fish > ~/.config/fish/completions/moon.fish
+
+This installs the completion script. You may have to log out and
+log back in to your shell session for the changes to take effect.
+
+Elvish:
+
+Elvish completions are commonly stored in a single `completers` module.
+A typical module search path is `~/.config/elvish/lib`, and
+running the command:
+
+ $ moon shell-completion --shell elvish >> ~/.config/elvish/lib/completers.elv
+
+will install the completions script. Note that use `>>` (append)
+instead of `>` (overwrite) to prevent overwriting the existing completions
+for other commands. Then prepend your rc.elv with:
+
+ `use completers`
+
+to load the `completers` module and enable completions.
+
+Zsh:
+
+ZSH completions are commonly stored in any directory listed in
+your `$fpath` variable. To use these completions, you must either
+add the generated script to one of those directories, or add your
+own to this list.
+
+Adding a custom directory is often the safest bet if you are
+unsure of which directory to use. First create the directory; for
+this example we'll create a hidden directory inside our `$HOME`
+directory:
+
+ $ mkdir ~/.zfunc
+
+Then add the following lines to your `.zshrc` just before
+`compinit`:
+
+ fpath+=~/.zfunc
+
+Now you can install the completions script using the following
+command:
+
+ $ moon shell-completion --shell zsh > ~/.zfunc/_moon
+
+You must then open a new zsh session, or simply run
+
+ $ . ~/.zshrc
+
+for the new completions to take effect.
+
+Custom locations:
+
+Alternatively, you could save these files to the place of your
+choosing, such as a custom directory inside your $HOME. Doing so
+will require you to add the proper directives, such as `source`ing
+inside your login script. Consult your shells documentation for
+how to add such directives.
+
+PowerShell:
+
+The powershell completion scripts require PowerShell v5.0+ (which
+comes with Windows 10, but can be downloaded separately for windows 7
+or 8.1).
+
+First, check if a profile has already been set
+
+ PS C:\> Test-Path $profile
+
+If the above command returns `False` run the following
+
+ PS C:\> New-Item -path $profile -type file -force
+
+Now open the file provided by `$profile` (if you used the
+`New-Item` command it will be
+`${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1`
+
+Next, we either save the completions file into our profile, or
+into a separate file and source it inside our profile. To save the
+completions into our profile simply use
+
+ PS C:\> moon shell-completion --shell powershell >>
+ ${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
+
+This discussion is taken from `rustup completions` command with some changes.
+--shell <SHELL> — The shell to generate completion for
Default value: <your shell>
Possible values: bash, elvish, fish, powershell, zsh
moon versionPrint version information and exit
+Usage: moon version [OPTIONS]
--all — Print all version information--json — Print version information in JSON format--no-path — Do not print the path
+This document was generated automatically by
+clap-markdown.
+
Moon is the build system for the MoonBit language, currently based on the n2 project. Moon supports parallel and incremental builds. Additionally, moon also supports managing and building third-party packages on mooncakes.io
+Before you begin with this tutorial, make sure you have installed the following:
+MoonBit CLI Tools: Download it from the https://www.moonbitlang.com/download/. This command line tool is needed for creating and managing MoonBit projects.
+Use moon help to view the usage instructions.
$ moon help
+...
+MoonBit Language plugin in Visual Studio Code: You can install it from the VS Code marketplace. This plugin provides a rich development environment for MoonBit, including functionalities like syntax highlighting, code completion, and more.
+Once you have these prerequisites fulfilled, let's start by creating a new MoonBit module.
+To create a new module, enter the moon new command in the terminal, and you will see the module creation wizard. By using all the default values, you can create a new module named username/hello in the my-project directory.
$ moon new
+Enter the path to create the project (. for current directory): my-project
+Select the create mode: exec
+Enter your username: username
+Enter your project name: hello
+Enter your license: Apache-2.0
+Created my-project
+++If you want use all default values, you can use
+moon new my-projectto create a new module namedusername/helloin themy-projectdirectory.
After creating the new module, your directory structure should resemble the following:
+my-project
+├── LICENSE
+├── README.md
+├── moon.mod.json
+└── src
+ ├── lib
+ │ ├── hello.mbt
+ │ ├── hello_test.mbt
+ │ └── moon.pkg.json
+ └── main
+ ├── main.mbt
+ └── moon.pkg.json
+Here's a brief explanation of the directory structure:
+moon.mod.json is used to identify a directory as a MoonBit module. It contains the module's metadata, such as the module name, version, etc. source specifies the source directory of the module. The default value is src.
{
+ "name": "username/hello",
+ "version": "0.1.0",
+ "readme": "README.md",
+ "repository": "",
+ "license": "Apache-2.0",
+ "keywords": [],
+ "description": "",
+ "source": "src"
+}
+lib and main directories: These are the packages within the module. Each package can contain multiple .mbt files, which are the source code files for the MoonBit language. However, regardless of how many .mbt files a package has, they all share a common moon.pkg.json file. lib/*_test.mbt are separate test files in the lib package, these files are for blackbox test, so private members of the lib package cannot be accessed directly.
moon.pkg.json is package descriptor. It defines the properties of the package, such as whether it is the main package and the packages it imports.
main/moon.pkg.json:
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib"
+ ]
+}
+Here, "is_main: true" declares that the package needs to be linked by the build system into a wasm file.
lib/moon.pkg.json:
{}
+This file is empty. Its purpose is simply to inform the build system that this folder is a package.
+Our username/hello module contains two packages: username/hello/lib and username/hello/main.
The username/hello/lib package contains hello.mbt and hello_test.mbt files:
hello.mbt
pub fn hello() -> String {
+ "Hello, world!"
+}
+hello_test.mbt
test "hello" {
+ if @lib.hello() != "Hello, world!" {
+ fail!("@lib.hello() != \"Hello, world!\"")
+ }
+}
+The username/hello/main package contains a main.mbt file:
fn main {
+ println(@lib.hello())
+}
+To execute the program, specify the file system's path to the username/hello/main package in the moon run command:
$ moon run ./src/main
+Hello, world!
+You can also omit ./
$ moon run src/main
+Hello, world!
+You can test using the moon test command:
$ moon test
+Total tests: 1, passed: 1, failed: 0.
+In the MoonBit's build system, a module's name is used to reference its internal packages.
+To import the username/hello/lib package in src/main/main.mbt, you need to specify it in src/main/moon.pkg.json:
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib"
+ ]
+}
+Here, username/hello/lib specifies importing the username/hello/lib package from the username/hello module, so you can use @lib.hello() in main/main.mbt.
Note that the package name imported in src/main/moon.pkg.json is username/hello/lib, and @lib is used to refer to this package in src/main/main.mbt. The import here actually generates a default alias for the package name username/hello/lib. In the following sections, you will learn how to customize the alias for a package.
First, create a new directory named fib under lib:
mkdir src/lib/fib
+Now, you can create new files under src/lib/fib:
a.mbt:
pub fn fib(n : Int) -> Int {
+ match n {
+ 0 => 0
+ 1 => 1
+ _ => fib(n - 1) + fib(n - 2)
+ }
+}
+b.mbt:
pub fn fib2(num : Int) -> Int {
+ fn aux(n, acc1, acc2) {
+ match n {
+ 0 => acc1
+ 1 => acc2
+ _ => aux(n - 1, acc2, acc1 + acc2)
+ }
+ }
+
+ aux(num, 0, 1)
+}
+moon.pkg.json:
{}
+After creating these files, your directory structure should look like this:
+my-project
+├── LICENSE
+├── README.md
+├── moon.mod.json
+└── src
+ ├── lib
+ │ ├── fib
+ │ │ ├── a.mbt
+ │ │ ├── b.mbt
+ │ │ └── moon.pkg.json
+ │ ├── hello.mbt
+ │ ├── hello_test.mbt
+ │ └── moon.pkg.json
+ └── main
+ ├── main.mbt
+ └── moon.pkg.json
+In the src/main/moon.pkg.json file, import the username/hello/lib/fib package and customize its alias to my_awesome_fibonacci:
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib",
+ {
+ "path": "username/hello/lib/fib",
+ "alias": "my_awesome_fibonacci"
+ }
+ ]
+}
+This line imports the fib package, which is part of the lib package in the hello module. After doing this, you can use the fib package in main/main.mbt. Replace the file content of main/main.mbt to:
fn main {
+ let a = @my_awesome_fibonacci.fib(10)
+ let b = @my_awesome_fibonacci.fib2(11)
+ println("fib(10) = \{a}, fib(11) = \{b}")
+
+ println(@lib.hello())
+}
+To execute your program, specify the path to the main package:
$ moon run ./src/main
+fib(10) = 55, fib(11) = 89
+Hello, world!
+Let's add some tests to verify our fib implementation. Add the following content in src/lib/fib/a.mbt:
src/lib/fib/a.mbt
test {
+ assert_eq!(fib(1), 1)
+ assert_eq!(fib(2), 1)
+ assert_eq!(fib(3), 2)
+ assert_eq!(fib(4), 3)
+ assert_eq!(fib(5), 5)
+}
+This code tests the first five terms of the Fibonacci sequence. test { ... } defines an inline test block. The code inside an inline test block is executed in test mode.
Inline test blocks are discarded in non-test compilation modes (moon build and moon run), so they won't cause the generated code size to bloat.
Besides inline tests, MoonBit also supports stand-alone test files. Source files ending in _test.mbt are considered test files for blackbox tests. For example, inside the src/lib/fib directory, create a file named fib_test.mbt and paste the following code:
src/lib/fib/fib_test.mbt
test {
+ assert_eq!(@fib.fib(1), 1)
+ assert_eq!(@fib.fib2(2), 1)
+ assert_eq!(@fib.fib(3), 2)
+ assert_eq!(@fib.fib2(4), 3)
+ assert_eq!(@fib.fib(5), 5)
+}
+Notice that the test code uses @fib to refer to the username/hello/lib/fib package. The build system automatically creates a new package for blackbox tests by using the files that end with _test.mbt. This new package will import the current package automatically, allowing you to use @lib in the test code.
Finally, use the moon test command, which scans the entire project, identifies, and runs all inline tests as well as files ending with _test.mbt. If everything is normal, you will see:
$ moon test
+Total tests: 3, passed: 3, failed: 0.
+$ moon test -v
+test username/hello/lib/hello_test.mbt::hello ok
+test username/hello/lib/fib/a.mbt::0 ok
+test username/hello/lib/fib/fib_test.mbt::0 ok
+Total tests: 3, passed: 3, failed: 0.
+moon uses the moon.mod.json file to identify and describe a module.
The deps field is used to specify the dependencies of the module.
It is automatically managed by commands like moon add and moon remove.
{
+ "name": "username/hello",
+ "deps": {
+ "moonbitlang/x": "0.4.6"
+ }
+}
+The description field is used to specify the description of the module.
{
+ "description": "This is a description of the module."
+}
+
+The readme field is used to specify the path to the module's README file.
The keywords field is used to specify the keywords for the module.
{
+ "keywords": ["example", "test"]
+}
+The license field is used to specify the license of the module. The license type must comply with the SPDX License List.
{
+ "license": "MIT"
+}
+The name field is used to specify the name of the module, and it is required.
{
+ "name": "example",
+ ...
+}
+The module name can contain letters, numbers, _, -, and /.
For modules published to mooncakes.io, the module name must begin with the username. For example:
+{
+ "name": "moonbitlang/core",
+ ...
+}
+The repository field is used to specify the URL of the module's repository.
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.
{
+ "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.
{
+ "source": null
+}
+{
+ "source": ""
+}
+{
+ "source": "."
+}
+The version field is used to specify the version of the module.
This field is optional. For modules published to mooncakes.io, the version number must follow the Semantic Versioning 2.0.0 specification.
+{
+ "name": "example",
+ "version": "0.1.0",
+ ...
+}
+moon uses the moon.pkg.json file to identify and describe a package.
Disable user preset alerts.
+{
+ "alert-list": "-alert_1-alert_2"
+}
+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:
+"wasm", "wasm-gc", and "js""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:
+{
+ "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"]]
+ }
+}
+The import field is used to specify other packages that a package depends on.
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:
wasm and wasm-gc backends, a standalone WebAssembly module will be generated.js backend, a standalone JavaScript file will be generated.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.
{
+ "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.
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.
{
+ "link": {
+ "js": {
+ "exports": [
+ "hello"
+ ]
+ }
+ }
+}
+The format option is used to specify the output format of the JavaScript module.
The currently supported formats are:
+esmcjsiifeFor example, the following configuration sets the output format of the current package to ES Module.
+{
+ "link": {
+ "js": {
+ "format": "esm"
+ }
+ }
+}
+The link options for the wasm-gc backend are similar to those for the wasm backend, except there is no heap-start-address option.
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.
{
+ "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.
+{
+ "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.
{
+ "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.
{
+ "link": {
+ "wasm": {
+ "export-memory-name": "memory"
+ }
+ }
+}
+The package name is not configurable; it is determined by the directory name of the package.
+ +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.
{
+ "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
+ #|
+The test-import field is used to specify other packages that the black-box test package of this package depends on.
This is used to disable specific preset compiler warning numbers.
+For example, in the following configuration, -2 disables the warning number 2 (Unused variable).
{
+ "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
+The wbtest-import field is used to specify other packages that the white-box test package of this package depends on.
Moon is the build system for the MoonBit language, currently based on the n2 project. Moon supports parallel and incremental builds. Additionally, moon also supports managing and building third-party packages on mooncakes.io
+Before you begin with this tutorial, make sure you have installed the following:
+MoonBit CLI Tools: Download it from the https://www.moonbitlang.com/download/. This command line tool is needed for creating and managing MoonBit projects.
+Use moon help to view the usage instructions.
$ moon help
+...
+MoonBit Language plugin in Visual Studio Code: You can install it from the VS Code marketplace. This plugin provides a rich development environment for MoonBit, including functionalities like syntax highlighting, code completion, and more.
+Once you have these prerequisites fulfilled, let's start by creating a new MoonBit module.
+To create a new module, enter the moon new command in the terminal, and you will see the module creation wizard. By using all the default values, you can create a new module named username/hello in the my-project directory.
$ moon new
+Enter the path to create the project (. for current directory): my-project
+Select the create mode: exec
+Enter your username: username
+Enter your project name: hello
+Enter your license: Apache-2.0
+Created my-project
+++If you want use all default values, you can use
+moon new my-projectto create a new module namedusername/helloin themy-projectdirectory.
After creating the new module, your directory structure should resemble the following:
+my-project
+├── LICENSE
+├── README.md
+├── moon.mod.json
+└── src
+ ├── lib
+ │ ├── hello.mbt
+ │ ├── hello_test.mbt
+ │ └── moon.pkg.json
+ └── main
+ ├── main.mbt
+ └── moon.pkg.json
+Here's a brief explanation of the directory structure:
+moon.mod.json is used to identify a directory as a MoonBit module. It contains the module's metadata, such as the module name, version, etc. source specifies the source directory of the module. The default value is src.
{
+ "name": "username/hello",
+ "version": "0.1.0",
+ "readme": "README.md",
+ "repository": "",
+ "license": "Apache-2.0",
+ "keywords": [],
+ "description": "",
+ "source": "src"
+}
+lib and main directories: These are the packages within the module. Each package can contain multiple .mbt files, which are the source code files for the MoonBit language. However, regardless of how many .mbt files a package has, they all share a common moon.pkg.json file. lib/*_test.mbt are separate test files in the lib package, these files are for blackbox test, so private members of the lib package cannot be accessed directly.
moon.pkg.json is package descriptor. It defines the properties of the package, such as whether it is the main package and the packages it imports.
main/moon.pkg.json:
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib"
+ ]
+}
+Here, "is_main: true" declares that the package needs to be linked by the build system into a wasm file.
lib/moon.pkg.json:
{}
+This file is empty. Its purpose is simply to inform the build system that this folder is a package.
+Our username/hello module contains two packages: username/hello/lib and username/hello/main.
The username/hello/lib package contains hello.mbt and hello_test.mbt files:
hello.mbt
pub fn hello() -> String {
+ "Hello, world!"
+}
+hello_test.mbt
test "hello" {
+ if @lib.hello() != "Hello, world!" {
+ fail!("@lib.hello() != \"Hello, world!\"")
+ }
+}
+The username/hello/main package contains a main.mbt file:
fn main {
+ println(@lib.hello())
+}
+To execute the program, specify the file system's path to the username/hello/main package in the moon run command:
$ moon run ./src/main
+Hello, world!
+You can also omit ./
$ moon run src/main
+Hello, world!
+You can test using the moon test command:
$ moon test
+Total tests: 1, passed: 1, failed: 0.
+In the MoonBit's build system, a module's name is used to reference its internal packages.
+To import the username/hello/lib package in src/main/main.mbt, you need to specify it in src/main/moon.pkg.json:
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib"
+ ]
+}
+Here, username/hello/lib specifies importing the username/hello/lib package from the username/hello module, so you can use @lib.hello() in main/main.mbt.
Note that the package name imported in src/main/moon.pkg.json is username/hello/lib, and @lib is used to refer to this package in src/main/main.mbt. The import here actually generates a default alias for the package name username/hello/lib. In the following sections, you will learn how to customize the alias for a package.
First, create a new directory named fib under lib:
mkdir src/lib/fib
+Now, you can create new files under src/lib/fib:
a.mbt:
pub fn fib(n : Int) -> Int {
+ match n {
+ 0 => 0
+ 1 => 1
+ _ => fib(n - 1) + fib(n - 2)
+ }
+}
+b.mbt:
pub fn fib2(num : Int) -> Int {
+ fn aux(n, acc1, acc2) {
+ match n {
+ 0 => acc1
+ 1 => acc2
+ _ => aux(n - 1, acc2, acc1 + acc2)
+ }
+ }
+
+ aux(num, 0, 1)
+}
+moon.pkg.json:
{}
+After creating these files, your directory structure should look like this:
+my-project
+├── LICENSE
+├── README.md
+├── moon.mod.json
+└── src
+ ├── lib
+ │ ├── fib
+ │ │ ├── a.mbt
+ │ │ ├── b.mbt
+ │ │ └── moon.pkg.json
+ │ ├── hello.mbt
+ │ ├── hello_test.mbt
+ │ └── moon.pkg.json
+ └── main
+ ├── main.mbt
+ └── moon.pkg.json
+In the src/main/moon.pkg.json file, import the username/hello/lib/fib package and customize its alias to my_awesome_fibonacci:
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib",
+ {
+ "path": "username/hello/lib/fib",
+ "alias": "my_awesome_fibonacci"
+ }
+ ]
+}
+This line imports the fib package, which is part of the lib package in the hello module. After doing this, you can use the fib package in main/main.mbt. Replace the file content of main/main.mbt to:
fn main {
+ let a = @my_awesome_fibonacci.fib(10)
+ let b = @my_awesome_fibonacci.fib2(11)
+ println("fib(10) = \{a}, fib(11) = \{b}")
+
+ println(@lib.hello())
+}
+To execute your program, specify the path to the main package:
$ moon run ./src/main
+fib(10) = 55, fib(11) = 89
+Hello, world!
+Let's add some tests to verify our fib implementation. Add the following content in src/lib/fib/a.mbt:
src/lib/fib/a.mbt
test {
+ assert_eq!(fib(1), 1)
+ assert_eq!(fib(2), 1)
+ assert_eq!(fib(3), 2)
+ assert_eq!(fib(4), 3)
+ assert_eq!(fib(5), 5)
+}
+This code tests the first five terms of the Fibonacci sequence. test { ... } defines an inline test block. The code inside an inline test block is executed in test mode.
Inline test blocks are discarded in non-test compilation modes (moon build and moon run), so they won't cause the generated code size to bloat.
Besides inline tests, MoonBit also supports stand-alone test files. Source files ending in _test.mbt are considered test files for blackbox tests. For example, inside the src/lib/fib directory, create a file named fib_test.mbt and paste the following code:
src/lib/fib/fib_test.mbt
test {
+ assert_eq!(@fib.fib(1), 1)
+ assert_eq!(@fib.fib2(2), 1)
+ assert_eq!(@fib.fib(3), 2)
+ assert_eq!(@fib.fib2(4), 3)
+ assert_eq!(@fib.fib(5), 5)
+}
+Notice that the test code uses @fib to refer to the username/hello/lib/fib package. The build system automatically creates a new package for blackbox tests by using the files that end with _test.mbt. This new package will import the current package automatically, allowing you to use @lib in the test code.
Finally, use the moon test command, which scans the entire project, identifies, and runs all inline tests as well as files ending with _test.mbt. If everything is normal, you will see:
$ moon test
+Total tests: 3, passed: 3, failed: 0.
+$ moon test -v
+test username/hello/lib/hello_test.mbt::hello ok
+test username/hello/lib/fib/a.mbt::0 ok
+test username/hello/lib/fib/fib_test.mbt::0 ok
+Total tests: 3, passed: 3, failed: 0.
+moonThis document contains the help content for the moon command-line program.
Command Overview:
+moon↴moon new↴moon build↴moon check↴moon run↴moon test↴moon clean↴moon fmt↴moon doc↴moon info↴moon add↴moon remove↴moon install↴moon tree↴moon login↴moon register↴moon publish↴moon update↴moon coverage↴moon coverage report↴moon coverage clean↴moon generate-build-matrix↴moon upgrade↴moon shell-completion↴moon version↴moonUsage: moon <COMMAND>
new — Create a new MoonBit modulebuild — Build the current packagecheck — Check the current package, but don't build object filesrun — Run a main packagetest — Test the current packageclean — Remove the target directoryfmt — Format source codedoc — Generate documentationinfo — Generate public interface (.mbti) files for all packages in the moduleadd — Add a dependencyremove — Remove a dependencyinstall — Install dependenciestree — Display the dependency treelogin — Log in to your accountregister — Register an account at mooncakes.iopublish — Publish the current packageupdate — Update the package registry indexcoverage — Code coverage utilitiesgenerate-build-matrix — Generate build matrix for benchmarking (legacy feature)upgrade — Upgrade toolchainsshell-completion — Generate shell completion for bash/elvish/fish/pwsh/zsh to stdoutversion — Print version information and exitmoon newCreate a new MoonBit module
+Usage: moon new [OPTIONS] [PACKAGE_NAME]
<PACKAGE_NAME> — The name of the package--lib — Create a library package instead of an executable
--path <PATH> — Output path of the package
--user <USER> — The user name of the package
--name <NAME> — The name part of the package
--license <LICENSE> — The license of the package
Default value: Apache-2.0
--no-license — Do not set a license for the package
moon buildBuild the current package
+Usage: moon build [OPTIONS]
--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
-w, --watch — Monitor the file system and automatically build artifacts
moon checkCheck the current package, but don't build object files
+Usage: moon check [OPTIONS]
--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--output-json — Output in json format
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
-w, --watch — Monitor the file system and automatically check files
moon runRun a main package
+Usage: moon run [OPTIONS] <PACKAGE_OR_MBT_FILE> [ARGS]...
<PACKAGE_OR_MBT_FILE> — The package or .mbt file to run<ARGS> — The arguments provided to the program to be run--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
--build-only — Only build, do not run the code
moon testTest the current package
+Usage: moon test [OPTIONS]
--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--release — run test at release compiled mode
-p, --package <PACKAGE> — Run test in the specified package
-f, --file <FILE> — Run test in the specified file. Only valid when --package is also specified
-i, --index <INDEX> — Run only the index-th test in the file. Only valid when --file is also specified
-u, --update — Update the test snapshot
-l, --limit <LIMIT> — Limit of expect test update passes to run, in order to avoid infinite loops
Default value: 256
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
--build-only — Only build, do not run the tests
--no-parallelize — Run the tests in a target backend sequentially
--test-failure-json — Print failure message in JSON format
moon cleanRemove the target directory
+Usage: moon clean
moon fmtFormat source code
+Usage: moon fmt [OPTIONS]
--check — Check only and don't change the source code--sort-input — Sort input filesmoon docGenerate documentation
+Usage: moon doc [OPTIONS]
--serve — Start a web server to serve the documentation
-b, --bind <BIND> — The address of the server
Default value: 127.0.0.1
-p, --port <PORT> — The port of the server
Default value: 3000
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
moon infoGenerate public interface (.mbti) files for all packages in the module
Usage: moon info [OPTIONS]
--frozen — Do not sync dependencies, assuming local dependencies are up-to-datemoon addAdd a dependency
+Usage: moon add <PACKAGE_PATH>
<PACKAGE_PATH> — The package path to addmoon removeRemove a dependency
+Usage: moon remove <PACKAGE_PATH>
<PACKAGE_PATH> — The package path to removemoon installInstall dependencies
+Usage: moon install
moon treeDisplay the dependency tree
+Usage: moon tree
moon loginLog in to your account
+Usage: moon login
moon registerRegister an account at mooncakes.io
+Usage: moon register
moon publishPublish the current package
+Usage: moon publish [OPTIONS]
--frozen — Do not sync dependencies, assuming local dependencies are up-to-datemoon updateUpdate the package registry index
+Usage: moon update
moon coverageCode coverage utilities
+Usage: moon coverage <COMMAND>
report — Generate code coverage reportclean — Clean up coverage artifactsmoon coverage reportGenerate code coverage report
+Usage: moon coverage report [args]... [COMMAND]
<args> — Arguments to pass to the coverage utility-h, --help — Show help for the coverage utilitymoon coverage cleanClean up coverage artifacts
+Usage: moon coverage clean
moon generate-build-matrixGenerate build matrix for benchmarking (legacy feature)
+Usage: moon generate-build-matrix [OPTIONS] --output-dir <OUT_DIR>
-n <NUMBER> — Set all of drow, dcol, mrow, mcol to the same value--drow <DIR_ROWS> — Number of directory rows--dcol <DIR_COLS> — Number of directory columns--mrow <MOD_ROWS> — Number of module rows--mcol <MOD_COLS> — Number of module columns-o, --output-dir <OUT_DIR> — The output directorymoon upgradeUpgrade toolchains
+Usage: moon upgrade [OPTIONS]
-f, --force — Force upgrademoon shell-completionGenerate shell completion for bash/elvish/fish/pwsh/zsh to stdout
+Usage: moon shell-completion [OPTIONS]
Discussion:
+Enable tab completion for Bash, Elvish, Fish, Zsh, or PowerShell
+The script is output on stdout, allowing one to re-direct the
+output to the file of their choosing. Where you place the file
+will depend on which shell, and which operating system you are
+using. Your particular configuration may also determine where
+these scripts need to be placed.
The completion scripts won't update itself, so you may need to
+periodically run this command to get the latest completions.
+Or you may put `eval "$(moon shell-completion --shell <SHELL>)"`
+in your shell's rc file to always load newest completions on startup.
+Although it's considered not as efficient as having the completions
+script installed.
+
+Here are some common set ups for the three supported shells under
+Unix and similar operating systems (such as GNU/Linux).
+
+Bash:
+
+Completion files are commonly stored in `/etc/bash_completion.d/` for
+system-wide commands, but can be stored in
+`~/.local/share/bash-completion/completions` for user-specific commands.
+Run the command:
+
+ $ mkdir -p ~/.local/share/bash-completion/completions
+ $ moon shell-completion --shell bash >> ~/.local/share/bash-completion/completions/moon
+
+This installs the completion script. You may have to log out and
+log back in to your shell session for the changes to take effect.
+
+Bash (macOS/Homebrew):
+
+Homebrew stores bash completion files within the Homebrew directory.
+With the `bash-completion` brew formula installed, run the command:
+
+ $ mkdir -p $(brew --prefix)/etc/bash_completion.d
+ $ moon shell-completion --shell bash > $(brew --prefix)/etc/bash_completion.d/moon.bash-completion
+
+Fish:
+
+Fish completion files are commonly stored in
+`$HOME/.config/fish/completions`. Run the command:
+
+ $ mkdir -p ~/.config/fish/completions
+ $ moon shell-completion --shell fish > ~/.config/fish/completions/moon.fish
+
+This installs the completion script. You may have to log out and
+log back in to your shell session for the changes to take effect.
+
+Elvish:
+
+Elvish completions are commonly stored in a single `completers` module.
+A typical module search path is `~/.config/elvish/lib`, and
+running the command:
+
+ $ moon shell-completion --shell elvish >> ~/.config/elvish/lib/completers.elv
+
+will install the completions script. Note that use `>>` (append)
+instead of `>` (overwrite) to prevent overwriting the existing completions
+for other commands. Then prepend your rc.elv with:
+
+ `use completers`
+
+to load the `completers` module and enable completions.
+
+Zsh:
+
+ZSH completions are commonly stored in any directory listed in
+your `$fpath` variable. To use these completions, you must either
+add the generated script to one of those directories, or add your
+own to this list.
+
+Adding a custom directory is often the safest bet if you are
+unsure of which directory to use. First create the directory; for
+this example we'll create a hidden directory inside our `$HOME`
+directory:
+
+ $ mkdir ~/.zfunc
+
+Then add the following lines to your `.zshrc` just before
+`compinit`:
+
+ fpath+=~/.zfunc
+
+Now you can install the completions script using the following
+command:
+
+ $ moon shell-completion --shell zsh > ~/.zfunc/_moon
+
+You must then open a new zsh session, or simply run
+
+ $ . ~/.zshrc
+
+for the new completions to take effect.
+
+Custom locations:
+
+Alternatively, you could save these files to the place of your
+choosing, such as a custom directory inside your $HOME. Doing so
+will require you to add the proper directives, such as `source`ing
+inside your login script. Consult your shells documentation for
+how to add such directives.
+
+PowerShell:
+
+The powershell completion scripts require PowerShell v5.0+ (which
+comes with Windows 10, but can be downloaded separately for windows 7
+or 8.1).
+
+First, check if a profile has already been set
+
+ PS C:\> Test-Path $profile
+
+If the above command returns `False` run the following
+
+ PS C:\> New-Item -path $profile -type file -force
+
+Now open the file provided by `$profile` (if you used the
+`New-Item` command it will be
+`${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1`
+
+Next, we either save the completions file into our profile, or
+into a separate file and source it inside our profile. To save the
+completions into our profile simply use
+
+ PS C:\> moon shell-completion --shell powershell >>
+ ${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
+
+This discussion is taken from `rustup completions` command with some changes.
+--shell <SHELL> — The shell to generate completion for
Default value: <your shell>
Possible values: bash, elvish, fish, powershell, zsh
moon versionPrint version information and exit
+Usage: moon version [OPTIONS]
--all — Print all version information--json — Print version information in JSON format--no-path — Do not print the path
+This document was generated automatically by
+clap-markdown.
+
moon uses the moon.mod.json file to identify and describe a module.
The name field is used to specify the name of the module, and it is required.
{
+ "name": "example",
+ ...
+}
+The module name can contain letters, numbers, _, -, and /.
For modules published to mooncakes.io, the module name must begin with the username. For example:
+{
+ "name": "moonbitlang/core",
+ ...
+}
+The version field is used to specify the version of the module.
This field is optional. For modules published to mooncakes.io, the version number must follow the Semantic Versioning 2.0.0 specification.
+{
+ "name": "example",
+ "version": "0.1.0",
+ ...
+}
+The deps field is used to specify the dependencies of the module.
It is automatically managed by commands like moon add and moon remove.
{
+ "name": "username/hello",
+ "deps": {
+ "moonbitlang/x": "0.4.6"
+ }
+}
+The readme field is used to specify the path to the module's README file.
The repository field is used to specify the URL of the module's repository.
The license field is used to specify the license of the module. The license type must comply with the SPDX License List.
{
+ "license": "MIT"
+}
+The keywords field is used to specify the keywords for the module.
{
+ "keywords": ["example", "test"]
+}
+The description field is used to specify the description of the module.
{
+ "description": "This is a description of the module."
+}
+
+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.
{
+ "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.
{
+ "source": null
+}
+{
+ "source": ""
+}
+{
+ "source": "."
+}
+This is used to disable specific preset compiler warning numbers.
+For example, in the following configuration, -2 disables the warning number 2 (Unused variable).
{
+ "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
+Disable user preset alerts.
+{
+ "alert-list": "-alert_1-alert_2"
+}
+moon uses the moon.pkg.json file to identify and describe a package.
The package name is not configurable; it is determined by the directory name of the package.
+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:
wasm and wasm-gc backends, a standalone WebAssembly module will be generated.js backend, a standalone JavaScript file will be generated.The import field is used to specify other packages that a package depends on.
The test-import field is used to specify other packages that the black-box test package of this package depends on.
The wbtest-import field is used to specify other packages that the white-box test package of this package depends on.
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.
{
+ "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.
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.
{
+ "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.
+{
+ "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.
{
+ "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.
{
+ "link": {
+ "wasm": {
+ "export-memory-name": "memory"
+ }
+ }
+}
+The link options for the wasm-gc backend are similar to those for the wasm backend, except there is no heap-start-address option.
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.
{
+ "link": {
+ "js": {
+ "exports": [
+ "hello"
+ ]
+ }
+ }
+}
+The format option is used to specify the output format of the JavaScript module.
The currently supported formats are:
+esmcjsiifeFor example, the following configuration sets the output format of the current package to ES Module.
+{
+ "link": {
+ "js": {
+ "format": "esm"
+ }
+ }
+}
+This is used to disable specific preset compiler warning numbers.
+For example, in the following configuration, -2 disables the warning number 2 (Unused variable).
{
+ "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
+Disable user preset alerts.
+{
+ "alert-list": "-alert_1-alert_2"
+}
+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:
+"wasm", "wasm-gc", and "js""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:
+{
+ "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"]]
+ }
+}
+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.
{
+ "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
+ #|
+Moon is the build system for the MoonBit language, currently based on the n2 project. Moon supports parallel and incremental builds. Additionally, moon also supports managing and building third-party packages on mooncakes.io
+Before you begin with this tutorial, make sure you have installed the following:
+MoonBit CLI Tools: Download it from the https://www.moonbitlang.com/download/. This command line tool is needed for creating and managing MoonBit projects.
+Use moon help to view the usage instructions.
$ moon help
+...
+MoonBit Language plugin in Visual Studio Code: You can install it from the VS Code marketplace. This plugin provides a rich development environment for MoonBit, including functionalities like syntax highlighting, code completion, and more.
+Once you have these prerequisites fulfilled, let's start by creating a new MoonBit module.
+To create a new module, enter the moon new command in the terminal, and you will see the module creation wizard. By using all the default values, you can create a new module named username/hello in the my-project directory.
$ moon new
+Enter the path to create the project (. for current directory): my-project
+Select the create mode: exec
+Enter your username: username
+Enter your project name: hello
+Enter your license: Apache-2.0
+Created my-project
+++If you want use all default values, you can use
+moon new my-projectto create a new module namedusername/helloin themy-projectdirectory.
After creating the new module, your directory structure should resemble the following:
+my-project
+├── LICENSE
+├── README.md
+├── moon.mod.json
+└── src
+ ├── lib
+ │ ├── hello.mbt
+ │ ├── hello_test.mbt
+ │ └── moon.pkg.json
+ └── main
+ ├── main.mbt
+ └── moon.pkg.json
+Here's a brief explanation of the directory structure:
+moon.mod.json is used to identify a directory as a MoonBit module. It contains the module's metadata, such as the module name, version, etc. source specifies the source directory of the module. The default value is src.
{
+ "name": "username/hello",
+ "version": "0.1.0",
+ "readme": "README.md",
+ "repository": "",
+ "license": "Apache-2.0",
+ "keywords": [],
+ "description": "",
+ "source": "src"
+}
+lib and main directories: These are the packages within the module. Each package can contain multiple .mbt files, which are the source code files for the MoonBit language. However, regardless of how many .mbt files a package has, they all share a common moon.pkg.json file. lib/*_test.mbt are separate test files in the lib package, these files are for blackbox test, so private members of the lib package cannot be accessed directly.
moon.pkg.json is package descriptor. It defines the properties of the package, such as whether it is the main package and the packages it imports.
main/moon.pkg.json:
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib"
+ ]
+}
+Here, "is_main: true" declares that the package needs to be linked by the build system into a wasm file.
lib/moon.pkg.json:
{}
+This file is empty. Its purpose is simply to inform the build system that this folder is a package.
+Our username/hello module contains two packages: username/hello/lib and username/hello/main.
The username/hello/lib package contains hello.mbt and hello_test.mbt files:
hello.mbt
pub fn hello() -> String {
+ "Hello, world!"
+}
+hello_test.mbt
test "hello" {
+ if @lib.hello() != "Hello, world!" {
+ fail!("@lib.hello() != \"Hello, world!\"")
+ }
+}
+The username/hello/main package contains a main.mbt file:
fn main {
+ println(@lib.hello())
+}
+To execute the program, specify the file system's path to the username/hello/main package in the moon run command:
$ moon run ./src/main
+Hello, world!
+You can also omit ./
$ moon run src/main
+Hello, world!
+You can test using the moon test command:
$ moon test
+Total tests: 1, passed: 1, failed: 0.
+In the MoonBit's build system, a module's name is used to reference its internal packages.
+To import the username/hello/lib package in src/main/main.mbt, you need to specify it in src/main/moon.pkg.json:
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib"
+ ]
+}
+Here, username/hello/lib specifies importing the username/hello/lib package from the username/hello module, so you can use @lib.hello() in main/main.mbt.
Note that the package name imported in src/main/moon.pkg.json is username/hello/lib, and @lib is used to refer to this package in src/main/main.mbt. The import here actually generates a default alias for the package name username/hello/lib. In the following sections, you will learn how to customize the alias for a package.
First, create a new directory named fib under lib:
mkdir src/lib/fib
+Now, you can create new files under src/lib/fib:
a.mbt:
pub fn fib(n : Int) -> Int {
+ match n {
+ 0 => 0
+ 1 => 1
+ _ => fib(n - 1) + fib(n - 2)
+ }
+}
+b.mbt:
pub fn fib2(num : Int) -> Int {
+ fn aux(n, acc1, acc2) {
+ match n {
+ 0 => acc1
+ 1 => acc2
+ _ => aux(n - 1, acc2, acc1 + acc2)
+ }
+ }
+
+ aux(num, 0, 1)
+}
+moon.pkg.json:
{}
+After creating these files, your directory structure should look like this:
+my-project
+├── LICENSE
+├── README.md
+├── moon.mod.json
+└── src
+ ├── lib
+ │ ├── fib
+ │ │ ├── a.mbt
+ │ │ ├── b.mbt
+ │ │ └── moon.pkg.json
+ │ ├── hello.mbt
+ │ ├── hello_test.mbt
+ │ └── moon.pkg.json
+ └── main
+ ├── main.mbt
+ └── moon.pkg.json
+In the src/main/moon.pkg.json file, import the username/hello/lib/fib package and customize its alias to my_awesome_fibonacci:
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib",
+ {
+ "path": "username/hello/lib/fib",
+ "alias": "my_awesome_fibonacci"
+ }
+ ]
+}
+This line imports the fib package, which is part of the lib package in the hello module. After doing this, you can use the fib package in main/main.mbt. Replace the file content of main/main.mbt to:
fn main {
+ let a = @my_awesome_fibonacci.fib(10)
+ let b = @my_awesome_fibonacci.fib2(11)
+ println("fib(10) = \{a}, fib(11) = \{b}")
+
+ println(@lib.hello())
+}
+To execute your program, specify the path to the main package:
$ moon run ./src/main
+fib(10) = 55, fib(11) = 89
+Hello, world!
+Let's add some tests to verify our fib implementation. Add the following content in src/lib/fib/a.mbt:
src/lib/fib/a.mbt
test {
+ assert_eq!(fib(1), 1)
+ assert_eq!(fib(2), 1)
+ assert_eq!(fib(3), 2)
+ assert_eq!(fib(4), 3)
+ assert_eq!(fib(5), 5)
+}
+This code tests the first five terms of the Fibonacci sequence. test { ... } defines an inline test block. The code inside an inline test block is executed in test mode.
Inline test blocks are discarded in non-test compilation modes (moon build and moon run), so they won't cause the generated code size to bloat.
Besides inline tests, MoonBit also supports stand-alone test files. Source files ending in _test.mbt are considered test files for blackbox tests. For example, inside the src/lib/fib directory, create a file named fib_test.mbt and paste the following code:
src/lib/fib/fib_test.mbt
test {
+ assert_eq!(@fib.fib(1), 1)
+ assert_eq!(@fib.fib2(2), 1)
+ assert_eq!(@fib.fib(3), 2)
+ assert_eq!(@fib.fib2(4), 3)
+ assert_eq!(@fib.fib(5), 5)
+}
+Notice that the test code uses @fib to refer to the username/hello/lib/fib package. The build system automatically creates a new package for blackbox tests by using the files that end with _test.mbt. This new package will import the current package automatically, allowing you to use @lib in the test code.
Finally, use the moon test command, which scans the entire project, identifies, and runs all inline tests as well as files ending with _test.mbt. If everything is normal, you will see:
$ moon test
+Total tests: 3, passed: 3, failed: 0.
+$ moon test -v
+test username/hello/lib/hello_test.mbt::hello ok
+test username/hello/lib/fib/a.mbt::0 ok
+test username/hello/lib/fib/fib_test.mbt::0 ok
+Total tests: 3, passed: 3, failed: 0.
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +moonThis document contains the help content for the moon command-line program.
Command Overview:
+moon↴moon new↴moon build↴moon check↴moon run↴moon test↴moon clean↴moon fmt↴moon doc↴moon info↴moon add↴moon remove↴moon install↴moon tree↴moon login↴moon register↴moon publish↴moon update↴moon coverage↴moon coverage report↴moon coverage clean↴moon generate-build-matrix↴moon upgrade↴moon shell-completion↴moon version↴moonUsage: moon <COMMAND>
new — Create a new MoonBit modulebuild — Build the current packagecheck — Check the current package, but don't build object filesrun — Run a main packagetest — Test the current packageclean — Remove the target directoryfmt — Format source codedoc — Generate documentationinfo — Generate public interface (.mbti) files for all packages in the moduleadd — Add a dependencyremove — Remove a dependencyinstall — Install dependenciestree — Display the dependency treelogin — Log in to your accountregister — Register an account at mooncakes.iopublish — Publish the current packageupdate — Update the package registry indexcoverage — Code coverage utilitiesgenerate-build-matrix — Generate build matrix for benchmarking (legacy feature)upgrade — Upgrade toolchainsshell-completion — Generate shell completion for bash/elvish/fish/pwsh/zsh to stdoutversion — Print version information and exitmoon newCreate a new MoonBit module
+Usage: moon new [OPTIONS] [PACKAGE_NAME]
<PACKAGE_NAME> — The name of the package--lib — Create a library package instead of an executable
--path <PATH> — Output path of the package
--user <USER> — The user name of the package
--name <NAME> — The name part of the package
--license <LICENSE> — The license of the package
Default value: Apache-2.0
--no-license — Do not set a license for the package
moon buildBuild the current package
+Usage: moon build [OPTIONS]
--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
-w, --watch — Monitor the file system and automatically build artifacts
moon checkCheck the current package, but don't build object files
+Usage: moon check [OPTIONS]
--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--output-json — Output in json format
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
-w, --watch — Monitor the file system and automatically check files
moon runRun a main package
+Usage: moon run [OPTIONS] <PACKAGE_OR_MBT_FILE> [ARGS]...
<PACKAGE_OR_MBT_FILE> — The package or .mbt file to run<ARGS> — The arguments provided to the program to be run--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
--build-only — Only build, do not run the code
moon testTest the current package
+Usage: moon test [OPTIONS]
--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--release — run test at release compiled mode
-p, --package <PACKAGE> — Run test in the specified package
-f, --file <FILE> — Run test in the specified file. Only valid when --package is also specified
-i, --index <INDEX> — Run only the index-th test in the file. Only valid when --file is also specified
-u, --update — Update the test snapshot
-l, --limit <LIMIT> — Limit of expect test update passes to run, in order to avoid infinite loops
Default value: 256
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
--build-only — Only build, do not run the tests
--no-parallelize — Run the tests in a target backend sequentially
--test-failure-json — Print failure message in JSON format
moon cleanRemove the target directory
+Usage: moon clean
moon fmtFormat source code
+Usage: moon fmt [OPTIONS]
--check — Check only and don't change the source code--sort-input — Sort input filesmoon docGenerate documentation
+Usage: moon doc [OPTIONS]
--serve — Start a web server to serve the documentation
-b, --bind <BIND> — The address of the server
Default value: 127.0.0.1
-p, --port <PORT> — The port of the server
Default value: 3000
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
moon infoGenerate public interface (.mbti) files for all packages in the module
Usage: moon info [OPTIONS]
--frozen — Do not sync dependencies, assuming local dependencies are up-to-datemoon addAdd a dependency
+Usage: moon add <PACKAGE_PATH>
<PACKAGE_PATH> — The package path to addmoon removeRemove a dependency
+Usage: moon remove <PACKAGE_PATH>
<PACKAGE_PATH> — The package path to removemoon installInstall dependencies
+Usage: moon install
moon treeDisplay the dependency tree
+Usage: moon tree
moon loginLog in to your account
+Usage: moon login
moon registerRegister an account at mooncakes.io
+Usage: moon register
moon publishPublish the current package
+Usage: moon publish [OPTIONS]
--frozen — Do not sync dependencies, assuming local dependencies are up-to-datemoon updateUpdate the package registry index
+Usage: moon update
moon coverageCode coverage utilities
+Usage: moon coverage <COMMAND>
report — Generate code coverage reportclean — Clean up coverage artifactsmoon coverage reportGenerate code coverage report
+Usage: moon coverage report [args]... [COMMAND]
<args> — Arguments to pass to the coverage utility-h, --help — Show help for the coverage utilitymoon coverage cleanClean up coverage artifacts
+Usage: moon coverage clean
moon generate-build-matrixGenerate build matrix for benchmarking (legacy feature)
+Usage: moon generate-build-matrix [OPTIONS] --output-dir <OUT_DIR>
-n <NUMBER> — Set all of drow, dcol, mrow, mcol to the same value--drow <DIR_ROWS> — Number of directory rows--dcol <DIR_COLS> — Number of directory columns--mrow <MOD_ROWS> — Number of module rows--mcol <MOD_COLS> — Number of module columns-o, --output-dir <OUT_DIR> — The output directorymoon upgradeUpgrade toolchains
+Usage: moon upgrade [OPTIONS]
-f, --force — Force upgrademoon shell-completionGenerate shell completion for bash/elvish/fish/pwsh/zsh to stdout
+Usage: moon shell-completion [OPTIONS]
Discussion:
+Enable tab completion for Bash, Elvish, Fish, Zsh, or PowerShell
+The script is output on stdout, allowing one to re-direct the
+output to the file of their choosing. Where you place the file
+will depend on which shell, and which operating system you are
+using. Your particular configuration may also determine where
+these scripts need to be placed.
The completion scripts won't update itself, so you may need to
+periodically run this command to get the latest completions.
+Or you may put `eval "$(moon shell-completion --shell <SHELL>)"`
+in your shell's rc file to always load newest completions on startup.
+Although it's considered not as efficient as having the completions
+script installed.
+
+Here are some common set ups for the three supported shells under
+Unix and similar operating systems (such as GNU/Linux).
+
+Bash:
+
+Completion files are commonly stored in `/etc/bash_completion.d/` for
+system-wide commands, but can be stored in
+`~/.local/share/bash-completion/completions` for user-specific commands.
+Run the command:
+
+ $ mkdir -p ~/.local/share/bash-completion/completions
+ $ moon shell-completion --shell bash >> ~/.local/share/bash-completion/completions/moon
+
+This installs the completion script. You may have to log out and
+log back in to your shell session for the changes to take effect.
+
+Bash (macOS/Homebrew):
+
+Homebrew stores bash completion files within the Homebrew directory.
+With the `bash-completion` brew formula installed, run the command:
+
+ $ mkdir -p $(brew --prefix)/etc/bash_completion.d
+ $ moon shell-completion --shell bash > $(brew --prefix)/etc/bash_completion.d/moon.bash-completion
+
+Fish:
+
+Fish completion files are commonly stored in
+`$HOME/.config/fish/completions`. Run the command:
+
+ $ mkdir -p ~/.config/fish/completions
+ $ moon shell-completion --shell fish > ~/.config/fish/completions/moon.fish
+
+This installs the completion script. You may have to log out and
+log back in to your shell session for the changes to take effect.
+
+Elvish:
+
+Elvish completions are commonly stored in a single `completers` module.
+A typical module search path is `~/.config/elvish/lib`, and
+running the command:
+
+ $ moon shell-completion --shell elvish >> ~/.config/elvish/lib/completers.elv
+
+will install the completions script. Note that use `>>` (append)
+instead of `>` (overwrite) to prevent overwriting the existing completions
+for other commands. Then prepend your rc.elv with:
+
+ `use completers`
+
+to load the `completers` module and enable completions.
+
+Zsh:
+
+ZSH completions are commonly stored in any directory listed in
+your `$fpath` variable. To use these completions, you must either
+add the generated script to one of those directories, or add your
+own to this list.
+
+Adding a custom directory is often the safest bet if you are
+unsure of which directory to use. First create the directory; for
+this example we'll create a hidden directory inside our `$HOME`
+directory:
+
+ $ mkdir ~/.zfunc
+
+Then add the following lines to your `.zshrc` just before
+`compinit`:
+
+ fpath+=~/.zfunc
+
+Now you can install the completions script using the following
+command:
+
+ $ moon shell-completion --shell zsh > ~/.zfunc/_moon
+
+You must then open a new zsh session, or simply run
+
+ $ . ~/.zshrc
+
+for the new completions to take effect.
+
+Custom locations:
+
+Alternatively, you could save these files to the place of your
+choosing, such as a custom directory inside your $HOME. Doing so
+will require you to add the proper directives, such as `source`ing
+inside your login script. Consult your shells documentation for
+how to add such directives.
+
+PowerShell:
+
+The powershell completion scripts require PowerShell v5.0+ (which
+comes with Windows 10, but can be downloaded separately for windows 7
+or 8.1).
+
+First, check if a profile has already been set
+
+ PS C:\> Test-Path $profile
+
+If the above command returns `False` run the following
+
+ PS C:\> New-Item -path $profile -type file -force
+
+Now open the file provided by `$profile` (if you used the
+`New-Item` command it will be
+`${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1`
+
+Next, we either save the completions file into our profile, or
+into a separate file and source it inside our profile. To save the
+completions into our profile simply use
+
+ PS C:\> moon shell-completion --shell powershell >>
+ ${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
+
+This discussion is taken from `rustup completions` command with some changes.
+--shell <SHELL> — The shell to generate completion for
Default value: <your shell>
Possible values: bash, elvish, fish, powershell, zsh
moon versionPrint version information and exit
+Usage: moon version [OPTIONS]
--all — Print all version information--json — Print version information in JSON format--no-path — Do not print the path
+This document was generated automatically by
+clap-markdown.
+
moon 是 MoonBit 语言的构建系统，目前基于 n2 项目。moon 支持并行构建和增量构建，此外它还支持管理和构建 mooncakes.io 上的第三方包。
在开始之前，请确保安装好以下内容：
+MoonBit CLI 工具: 从这里下载。该命令行工具用于创建和管理 MoonBit 项目。
+使用 moon help 命令可查看使用说明。
$ moon help
+...
+Moonbit Language Visual Studio Code 插件: 可以从 VS Code 市场安装。该插件为 MoonBit 提供了丰富的开发环境，包括语法高亮、代码补全、交互式除错和测试等功能。
+安装完成后，让我们开始创建一个新的 MoonBit 模块。
+使用 moon new 创建一个新项目，默认的配置是：
$ moon new
+Enter the path to create the project (. for current directory): my-project
+Select the create mode: exec
+Enter your username: username
+Enter your project name: hello
+Enter your license: Apache-2.0
+Created my-project
+这会在 my-project 下创建一个名为 username/hello 的新模块。上述过程也可以使用 moon new my-project 代替。
上一步所创建的模块目录结构如下所示：
+my-project
+├── LICENSE
+├── README.md
+├── moon.mod.json
+└── src
+ ├── lib
+ │ ├── hello.mbt
+ │ ├── hello_test.mbt
+ │ └── moon.pkg.json
+ └── main
+ ├── main.mbt
+ └── moon.pkg.json
+这里简单解释一下目录结构：
+moon.mod.json 用来标记这个目录是一个模块。它包含了模块的元信息，例如模块名、版本等。
{
+ "name": "username/hello",
+ "version": "0.1.0",
+ "readme": "README.md",
+ "repository": "",
+ "license": "Apache-2.0",
+ "keywords": [],
+ "description": "",
+ "source": "src"
+}
+source 字段指定了模块的源代码目录，默认值是 src。该字段存在的原因是因为 MoonBit 模块中的包名与文件路径相关。例如，当前模块名为 username/hello，而其中一个包所在目录为 lib/moon.pkg.json，那么在导入该包时，需要写包的全名为 username/hello/lib。有时，为了更好地组织项目结构，我们想把源码放在 src 目录下，例如 src/lib/moon.pkg.json，这时需要使用 username/hello/src/lib 导入该包。但一般来说我们并不希望 src 出现在包的路径中，此时可以通过指定 "source": "src" 来忽略 src 这层目录，便可使用 username/hello/lib 导入该包。
src/lib 和 src/main 目录：这是模块内的包。每个包可以包含多个 .mbt 文件，这些文件是 MoonBit 语言的源代码文件。但是，无论一个包有多少 .mbt 文件，它们都共享一个 moon.pkg.json 文件。lib/*_test.mbt 是 lib 包中的独立测试文件，这些文件用于黑盒测试，无法直接访问 lib 包的私有成员。
moon.pkg.json 是包描述文件。它定义了包的属性，例如，是否是 main 包，所导入的其他包。
main/moon.pkg.json:
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib"
+ ]
+}
+这里，"is_main: true" 表示这个包需要被链接成目标文件。在 wasm/wasm-gc 后端，会被链接成一个 wasm 文件，在 js 后端，会被链接成一个 js 文件。
lib/moon.pkg.json:
{}
+这个文件只是为了告诉构建系统当前目录是一个包。
+我们的 username/hello 模块包含两个包：username/hello/lib 和 username/hello/main。
包 username/hello/lib 包含 hello.mbt 和 hello_test.mbt 文件：
hello.mbt
pub fn hello() -> String {
+ "Hello, world!"
+}
+hello_test.mbt
test "hello" {
+ if @lib.hello() != "Hello, world!" {
+ fail!("@lib.hello() != \"Hello, world!\"")
+ }
+}
+包 username/hello/main 只包含一个 main.mbt 文件：
fn main {
+ println(@lib.hello())
+}
+为了执行程序，需要在 moon run 命令中指定 username/hello/main 包的文件系统路径：
$ moon run ./src/main
+Hello, world!
+你也可以省略 ./
$ moon run src/main
+Hello, world!
+你可以使用 moon test 命令进行测试：
$ moon test
+Total tests: 1, passed: 1, failed: 0.
+在 MoonBit 的构建系统中，模块名用于引用其内部包。
+如果想在 src/main/main.mbt 中使用 username/hello/lib 包，你需要在 src/main/moon.pkg.json 中指定：
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib"
+ ]
+}
+这里，username/hello/lib 指定了从 username/hello 模块导入 username/hello/lib 包，所以你可以在 main/main.mbt 中使用 @lib.hello()。
注意，src/main/moon.pkg.json 中导入的包名是 username/hello/lib，在 src/main/main.mbt 中使用 @lib 来引用这个包。这里的导入实际上为包名 username/hello/lib 生成了一个默认别名。在接下来的章节中，你将学习如何为包自定义别名。
首先，在 lib 下创建一个名为 fib 的新目录：
mkdir src/lib/fib
+现在，你可以在 src/lib/fib 下创建新文件：
a.mbt:
pub fn fib(n : Int) -> Int {
+ match n {
+ 0 => 0
+ 1 => 1
+ _ => fib(n - 1) + fib(n - 2)
+ }
+}
+b.mbt:
pub fn fib2(num : Int) -> Int {
+ fn aux(n, acc1, acc2) {
+ match n {
+ 0 => acc1
+ 1 => acc2
+ _ => aux(n - 1, acc2, acc1 + acc2)
+ }
+ }
+
+ aux(num, 0, 1)
+}
+moon.pkg.json:
{}
+在创建完这些文件后，你的目录结构应该如下所示：
+my-project
+├── LICENSE
+├── README.md
+├── moon.mod.json
+└── src
+ ├── lib
+ │ ├── fib
+ │ │ ├── a.mbt
+ │ │ ├── b.mbt
+ │ │ └── moon.pkg.json
+ │ ├── hello.mbt
+ │ ├── hello_test.mbt
+ │ └── moon.pkg.json
+ └── main
+ ├── main.mbt
+ └── moon.pkg.json
+在 src/main/moon.pkg.json 文件中，导入 username/hello/lib/fib 包，并自定义别名为 my_awesome_fibonacci：
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib",
+ {
+ "path": "username/hello/lib/fib",
+ "alias": "my_awesome_fibonacci"
+ }
+ ]
+}
+这行导入了 username/hello/lib/fib 包。导入后，你可以在 main/main.mbt 中使用 fib 包了。
将 main/main.mbt 的文件内容替换为：
fn main {
+ let a = @my_awesome_fibonacci.fib(10)
+ let b = @my_awesome_fibonacci.fib2(11)
+ println("fib(10) = \{a}, fib(11) = \{b}")
+
+ println(@lib.hello())
+}
+为了执行程序，需要在 moon run 命令中指定 username/hello/main 包的文件系统路径：
$ moon run ./src/main
+fib(10) = 55, fib(11) = 89
+Hello, world!
+让我们添加一些测试来验证我们的 fib 实现。在 src/lib/fib/a.mbt 中添加以下内容：
src/lib/fib/a.mbt
test {
+ assert_eq!(fib(1), 1)
+ assert_eq!(fib(2), 1)
+ assert_eq!(fib(3), 2)
+ assert_eq!(fib(4), 3)
+ assert_eq!(fib(5), 5)
+}
+这些代码测试了斐波那契数列的前五项。test { ... } 定义了一个内联测试块。内联测试块中的代码在测试模式下执行。
内联测试块在非测试模式下（moon build 和 moon run）会被丢弃，因此不会导致生成的代码大小膨胀。
除了内联测试，MoonBit 还支持独立测试文件。以 _test.mbt 结尾的源文件被认为是黑盒测试的测试文件。例如，在 src/lib/fib 目录中，创建一个名为 fib_test.mbt 的文件，并粘贴以下代码：
src/lib/fib/fib_test.mbt
test {
+ assert_eq!(@fib.fib(1), 1)
+ assert_eq!(@fib.fib2(2), 1)
+ assert_eq!(@fib.fib(3), 2)
+ assert_eq!(@fib.fib2(4), 3)
+ assert_eq!(@fib.fib(5), 5)
+}
+注意，构建系统会自动为以 _test.mbt 结尾的文件创建一个新的包，用于黑盒测试，并且自动导入当前包。因此，在测试块中需要使用 @fib 来引用 username/hello/lib/fib 包，而不需要在 moon.pkg.json 中显式地导入该包。
最后，使用 moon test 命令，它会扫描整个项目，识别并运行所有内联测试以及以 _test.mbt 结尾的文件。如果一切正常，你会看到：
$ moon test
+Total tests: 3, passed: 3, failed: 0.
+$ moon test -v
+test username/hello/lib/hello_test.mbt::hello ok
+test username/hello/lib/fib/a.mbt::0 ok
+test username/hello/lib/fib/fib_test.mbt::0 ok
+Total tests: 3, passed: 3, failed: 0.
+moon 使用 moon.mod.json 文件来识别、描述一个模块。
deps 字段用于指定模块的依赖。
由 moon add、moon remove 等命令自动管理。
{
+ "name": "username/hello",
+ "deps": {
+ "moonbitlang/x": "0.4.6"
+ }
+}
+description 字段用于指定模块的描述。
{
+ "description": "This is a description of the module."
+}
+readme 字段用于指定模块的 README 文件路径。
keywords 字段用于指定模块的关键词。
{
+ "keywords": ["example", "test"]
+}
+license 字段用于指定模块的许可证。许可证类型必须符合 SPDX 许可证列表。
{
+ "license": "MIT"
+}
+name 字段用于指定模块的名称，必须指定。
{
+ "name": "example",
+ ...
+}
+模块名可以包含字母、数字、_、-、/。
对于发布到 mooncakes.io 的模块，模块名必须以用户名开头，例如：
+{
+ "name": "moonbitlang/core",
+ ...
+}
+repository 字段用于指定模块的仓库地址。
source 字段用于指定模块的源码目录。
它必须为当前 moon.mod.json 文件所在目录的子目录。且必须为相对路径
当使用 moon new 命令创建模块时，会自动生成一个 src 目录，并且 source 字段的默认值为 src。
{
+ "source": "src"
+}
+当 source 字段不存在，或者其值为 null 或空字符串 "" 时，相当于设置 "source": "."。这表示源码目录为该 moon.mod.json 文件所在的目录。
{
+ "source": null
+}
+{
+ "source": ""
+}
+{
+ "source": "."
+}
+version 字段用于指定模块的版本。
该字段为可选项，对于发布到 mooncakes.io 的模块，版本号必须符合 语义化版本 2.0.0 规范。
+{
+ "name": "example",
+ "version": "0.1.0",
+ ...
+}
+moon 使用 moon.pkg.json 文件来识别、描述一个包。
关闭用户预设 alter。
+{
+ "alert-list": "-alert_1-alert_2"
+}
+条件编译的最小单位是文件。
+在条件编译表达式中，支持三种逻辑操作符：and、or 和 not，其中 or 操作符可以省略不写。
例如，["or", "wasm", "wasm-gc"] 可以简写为 ["wasm", "wasm-gc"]。
条件表达式中的条件可以分为后端和优化级别：
+"wasm"、"wasm-gc" 和 "js""debug" 和 "release"条件表达式支持嵌套。
+如果一个文件未在 "targets" 中列出，它将默认在所有条件下编译。
示例：
+{
+ "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"]]
+ }
+}
+import 字段用于指定一个包所依赖的其他包。
is-main 字段用于指定一个包是否需要被链接成一个可执行的文件。
链接所生成的产物与后端相关，当该字段为 true 时：
wasm 和 wasm-gc 后端，将会生成一个可以独立运行的 WebAssembly 模块。js 后端，将会生成一个可以独立运行的 JavaScript 文件。moon 默认只会链接 is-main 为 true 的包，如果需要链接其他包，可以通过 link 选项指定。
link 选项用于指定链接选项，它的值可以为布尔值或一个对象。
link 值为 true 时，表示需要链接该包。构建时所指定的后端不同，产物也不同。
{
+ "link": true
+}
+link 值为对象时，表示需要链接该包，并且可以指定链接选项，详细配置请查看对应后端的子页面。
exports 选项用于指定 JavaScript 模块的导出函数名。
例如，如下配置将当前包中的 hello 函数导出为 JavaScript 模块的 hello 函数。在 JavaScript 宿主中，可以通过 hello 函数来调用当前包中的 hello 函数。
{
+ "link": {
+ "js": {
+ "exports": [
+ "hello"
+ ]
+ }
+ }
+}
+format 选项用于指定 JavaScript 模块的输出格式。
目前支持的格式有：
+esmcjsiife例如，如下配置将当前包的输出格式指定为 ES Module。
+{
+ "link": {
+ "js": {
+ "format": "esm"
+ }
+ }
+}
+wasm-gc 后端与 wasm 后端的链接选项类似，只不过没有 heap-start-address 选项。
exports 选项用于指定 wasm 后端导出的函数名。
例如，如下配置将当前包中的 hello 函数导出为 wasm 模块的 hello 函数, foo 函数导出为 wasm 模块的 foo 函数。在 wasm 宿主中，可以通过 hello 和 bar 函数来调用当前包中的 hello 和 foo 函数。
{
+ "link": {
+ "wasm": {
+ "exports": [
+ "hello",
+ "foo:bar"
+ ]
+ },
+ }
+}
+heap-start-address 选项用于指定 moonc 编译到 wasm 后端时能够使用的线性内存的起始地址。
例如，如下配置将线性内存的起始地址设置为 1024。
+{
+ "link": {
+ "wasm": {
+ "heap-start-address": 1024
+ },
+ }
+}
+import-memory 选项用于指定 wasm 模块导入的线性内存。
例如，如下配置将 wasm 模块导入的线性内存指定为 env 模块的 memory 变量。
{
+ "link": {
+ "wasm": {
+ "import-memory": {
+ "module": "env",
+ "name": "memory"
+ }
+ },
+ }
+}
+export-memory-name 选项用于指定 wasm 模块导出的线性内存名称。
{
+ "link": {
+ "wasm": {
+ "export-memory-name": "memory"
+ },
+ }
+}
+包名不可配置，它由包的目录名决定。
+ +字段 "pre-build" 用于指定预构建命令，预构建命令会在 moon check|build|test 等构建命令之前执行。
"pre-build"是一个数组，数组中的每个元素是一个对象，对象中包含 input，output 和 command 三个字段，input 和 output 可以是字符串或者字符串数组，command 是字符串，command 中可以使用任意命令行命令，以及 $input，$output 变量，分别代表输入文件、输出文件，如果是数组默认使用空格分割。
目前内置了一个特殊命令 :embed，用于将文件转换为 MoonBit 源码，--text 参数用于嵌入文本文件，--binary 用于嵌入二进制文件，--text 为默认值，可省略不写。--name 用于指定生成的变量名，默认值为 resource。命令的执行目录为当前 moon.pkg.json 所在目录。
{
+ "pre-build": [
+ {
+ "input": "a.txt",
+ "output": "a.mbt",
+ "command": ":embed -i $input -o $output"
+ }
+ ]
+}
+如果当前包目录下的 a.txt 的内容为
hello,
+world
+执行 moon build 后，在此 moon.pkg.json 所在目录下生成如下 a.mbt 文件
let resource : String =
+ #|hello,
+ #|world
+ #|
+test-import 字段用于指定该包对应的黑盒测试包所依赖的其他包。
关闭对应的编译器预设警告编号。
+例如，如下配置中 -2 代表关闭编号为 2(Unused variable) 的警告
{
+ "warn-list": "-2",
+}
+可用 moonc build-package -warn-help 查看编译器预设的警告编号
$ 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
+wbtest-import 字段用于指定该包对应的白盒测试包所依赖的其他包。
moon 是 MoonBit 语言的构建系统，目前基于 n2 项目。moon 支持并行构建和增量构建，此外它还支持管理和构建 mooncakes.io 上的第三方包。
在开始之前，请确保安装好以下内容：
+MoonBit CLI 工具: 从这里下载。该命令行工具用于创建和管理 MoonBit 项目。
+使用 moon help 命令可查看使用说明。
$ moon help
+...
+Moonbit Language Visual Studio Code 插件: 可以从 VS Code 市场安装。该插件为 MoonBit 提供了丰富的开发环境，包括语法高亮、代码补全、交互式除错和测试等功能。
+安装完成后，让我们开始创建一个新的 MoonBit 模块。
+使用 moon new 创建一个新项目，默认的配置是：
$ moon new
+Enter the path to create the project (. for current directory): my-project
+Select the create mode: exec
+Enter your username: username
+Enter your project name: hello
+Enter your license: Apache-2.0
+Created my-project
+这会在 my-project 下创建一个名为 username/hello 的新模块。上述过程也可以使用 moon new my-project 代替。
上一步所创建的模块目录结构如下所示：
+my-project
+├── LICENSE
+├── README.md
+├── moon.mod.json
+└── src
+ ├── lib
+ │ ├── hello.mbt
+ │ ├── hello_test.mbt
+ │ └── moon.pkg.json
+ └── main
+ ├── main.mbt
+ └── moon.pkg.json
+这里简单解释一下目录结构：
+moon.mod.json 用来标记这个目录是一个模块。它包含了模块的元信息，例如模块名、版本等。
{
+ "name": "username/hello",
+ "version": "0.1.0",
+ "readme": "README.md",
+ "repository": "",
+ "license": "Apache-2.0",
+ "keywords": [],
+ "description": "",
+ "source": "src"
+}
+source 字段指定了模块的源代码目录，默认值是 src。该字段存在的原因是因为 MoonBit 模块中的包名与文件路径相关。例如，当前模块名为 username/hello，而其中一个包所在目录为 lib/moon.pkg.json，那么在导入该包时，需要写包的全名为 username/hello/lib。有时，为了更好地组织项目结构，我们想把源码放在 src 目录下，例如 src/lib/moon.pkg.json，这时需要使用 username/hello/src/lib 导入该包。但一般来说我们并不希望 src 出现在包的路径中，此时可以通过指定 "source": "src" 来忽略 src 这层目录，便可使用 username/hello/lib 导入该包。
src/lib 和 src/main 目录：这是模块内的包。每个包可以包含多个 .mbt 文件，这些文件是 MoonBit 语言的源代码文件。但是，无论一个包有多少 .mbt 文件，它们都共享一个 moon.pkg.json 文件。lib/*_test.mbt 是 lib 包中的独立测试文件，这些文件用于黑盒测试，无法直接访问 lib 包的私有成员。
moon.pkg.json 是包描述文件。它定义了包的属性，例如，是否是 main 包，所导入的其他包。
main/moon.pkg.json:
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib"
+ ]
+}
+这里，"is_main: true" 表示这个包需要被链接成目标文件。在 wasm/wasm-gc 后端，会被链接成一个 wasm 文件，在 js 后端，会被链接成一个 js 文件。
lib/moon.pkg.json:
{}
+这个文件只是为了告诉构建系统当前目录是一个包。
+我们的 username/hello 模块包含两个包：username/hello/lib 和 username/hello/main。
包 username/hello/lib 包含 hello.mbt 和 hello_test.mbt 文件：
hello.mbt
pub fn hello() -> String {
+ "Hello, world!"
+}
+hello_test.mbt
test "hello" {
+ if @lib.hello() != "Hello, world!" {
+ fail!("@lib.hello() != \"Hello, world!\"")
+ }
+}
+包 username/hello/main 只包含一个 main.mbt 文件：
fn main {
+ println(@lib.hello())
+}
+为了执行程序，需要在 moon run 命令中指定 username/hello/main 包的文件系统路径：
$ moon run ./src/main
+Hello, world!
+你也可以省略 ./
$ moon run src/main
+Hello, world!
+你可以使用 moon test 命令进行测试：
$ moon test
+Total tests: 1, passed: 1, failed: 0.
+在 MoonBit 的构建系统中，模块名用于引用其内部包。
+如果想在 src/main/main.mbt 中使用 username/hello/lib 包，你需要在 src/main/moon.pkg.json 中指定：
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib"
+ ]
+}
+这里，username/hello/lib 指定了从 username/hello 模块导入 username/hello/lib 包，所以你可以在 main/main.mbt 中使用 @lib.hello()。
注意，src/main/moon.pkg.json 中导入的包名是 username/hello/lib，在 src/main/main.mbt 中使用 @lib 来引用这个包。这里的导入实际上为包名 username/hello/lib 生成了一个默认别名。在接下来的章节中，你将学习如何为包自定义别名。
首先，在 lib 下创建一个名为 fib 的新目录：
mkdir src/lib/fib
+现在，你可以在 src/lib/fib 下创建新文件：
a.mbt:
pub fn fib(n : Int) -> Int {
+ match n {
+ 0 => 0
+ 1 => 1
+ _ => fib(n - 1) + fib(n - 2)
+ }
+}
+b.mbt:
pub fn fib2(num : Int) -> Int {
+ fn aux(n, acc1, acc2) {
+ match n {
+ 0 => acc1
+ 1 => acc2
+ _ => aux(n - 1, acc2, acc1 + acc2)
+ }
+ }
+
+ aux(num, 0, 1)
+}
+moon.pkg.json:
{}
+在创建完这些文件后，你的目录结构应该如下所示：
+my-project
+├── LICENSE
+├── README.md
+├── moon.mod.json
+└── src
+ ├── lib
+ │ ├── fib
+ │ │ ├── a.mbt
+ │ │ ├── b.mbt
+ │ │ └── moon.pkg.json
+ │ ├── hello.mbt
+ │ ├── hello_test.mbt
+ │ └── moon.pkg.json
+ └── main
+ ├── main.mbt
+ └── moon.pkg.json
+在 src/main/moon.pkg.json 文件中，导入 username/hello/lib/fib 包，并自定义别名为 my_awesome_fibonacci：
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib",
+ {
+ "path": "username/hello/lib/fib",
+ "alias": "my_awesome_fibonacci"
+ }
+ ]
+}
+这行导入了 username/hello/lib/fib 包。导入后，你可以在 main/main.mbt 中使用 fib 包了。
将 main/main.mbt 的文件内容替换为：
fn main {
+ let a = @my_awesome_fibonacci.fib(10)
+ let b = @my_awesome_fibonacci.fib2(11)
+ println("fib(10) = \{a}, fib(11) = \{b}")
+
+ println(@lib.hello())
+}
+为了执行程序，需要在 moon run 命令中指定 username/hello/main 包的文件系统路径：
$ moon run ./src/main
+fib(10) = 55, fib(11) = 89
+Hello, world!
+让我们添加一些测试来验证我们的 fib 实现。在 src/lib/fib/a.mbt 中添加以下内容：
src/lib/fib/a.mbt
test {
+ assert_eq!(fib(1), 1)
+ assert_eq!(fib(2), 1)
+ assert_eq!(fib(3), 2)
+ assert_eq!(fib(4), 3)
+ assert_eq!(fib(5), 5)
+}
+这些代码测试了斐波那契数列的前五项。test { ... } 定义了一个内联测试块。内联测试块中的代码在测试模式下执行。
内联测试块在非测试模式下（moon build 和 moon run）会被丢弃，因此不会导致生成的代码大小膨胀。
除了内联测试，MoonBit 还支持独立测试文件。以 _test.mbt 结尾的源文件被认为是黑盒测试的测试文件。例如，在 src/lib/fib 目录中，创建一个名为 fib_test.mbt 的文件，并粘贴以下代码：
src/lib/fib/fib_test.mbt
test {
+ assert_eq!(@fib.fib(1), 1)
+ assert_eq!(@fib.fib2(2), 1)
+ assert_eq!(@fib.fib(3), 2)
+ assert_eq!(@fib.fib2(4), 3)
+ assert_eq!(@fib.fib(5), 5)
+}
+注意，构建系统会自动为以 _test.mbt 结尾的文件创建一个新的包，用于黑盒测试，并且自动导入当前包。因此，在测试块中需要使用 @fib 来引用 username/hello/lib/fib 包，而不需要在 moon.pkg.json 中显式地导入该包。
最后，使用 moon test 命令，它会扫描整个项目，识别并运行所有内联测试以及以 _test.mbt 结尾的文件。如果一切正常，你会看到：
$ moon test
+Total tests: 3, passed: 3, failed: 0.
+$ moon test -v
+test username/hello/lib/hello_test.mbt::hello ok
+test username/hello/lib/fib/a.mbt::0 ok
+test username/hello/lib/fib/fib_test.mbt::0 ok
+Total tests: 3, passed: 3, failed: 0.
+moonThis document contains the help content for the moon command-line program.
Command Overview:
+moon↴moon new↴moon build↴moon check↴moon run↴moon test↴moon clean↴moon fmt↴moon doc↴moon info↴moon add↴moon remove↴moon install↴moon tree↴moon login↴moon register↴moon publish↴moon update↴moon coverage↴moon coverage report↴moon coverage clean↴moon generate-build-matrix↴moon upgrade↴moon shell-completion↴moon version↴moonUsage: moon <COMMAND>
new — Create a new MoonBit modulebuild — Build the current packagecheck — Check the current package, but don't build object filesrun — Run a main packagetest — Test the current packageclean — Remove the target directoryfmt — Format source codedoc — Generate documentationinfo — Generate public interface (.mbti) files for all packages in the moduleadd — Add a dependencyremove — Remove a dependencyinstall — Install dependenciestree — Display the dependency treelogin — Log in to your accountregister — Register an account at mooncakes.iopublish — Publish the current packageupdate — Update the package registry indexcoverage — Code coverage utilitiesgenerate-build-matrix — Generate build matrix for benchmarking (legacy feature)upgrade — Upgrade toolchainsshell-completion — Generate shell completion for bash/elvish/fish/pwsh/zsh to stdoutversion — Print version information and exitmoon newCreate a new MoonBit module
+Usage: moon new [OPTIONS] [PACKAGE_NAME]
<PACKAGE_NAME> — The name of the package--lib — Create a library package instead of an executable
--path <PATH> — Output path of the package
--user <USER> — The user name of the package
--name <NAME> — The name part of the package
--license <LICENSE> — The license of the package
Default value: Apache-2.0
--no-license — Do not set a license for the package
moon buildBuild the current package
+Usage: moon build [OPTIONS]
--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
-w, --watch — Monitor the file system and automatically build artifacts
moon checkCheck the current package, but don't build object files
+Usage: moon check [OPTIONS]
--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--output-json — Output in json format
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
-w, --watch — Monitor the file system and automatically check files
moon runRun a main package
+Usage: moon run [OPTIONS] <PACKAGE_OR_MBT_FILE> [ARGS]...
<PACKAGE_OR_MBT_FILE> — The package or .mbt file to run<ARGS> — The arguments provided to the program to be run--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
--build-only — Only build, do not run the code
moon testTest the current package
+Usage: moon test [OPTIONS]
--std — Enable the standard library (default)
--nostd — Disable the standard library
-g, --debug — Emit debug information
--target <TARGET> — Select output target
Possible values: wasm, wasm-gc, js, native, all
--serial — Handle the selected targets sequentially
--enable-coverage — Enable coverage instrumentation
--sort-input — Sort input files
--output-wat — Output WAT instead of WASM
-d, --deny-warn — Treat all warnings as errors
--no-render — Don't render diagnostics from moonc (don't pass '-error-format json' to moonc)
--release — run test at release compiled mode
-p, --package <PACKAGE> — Run test in the specified package
-f, --file <FILE> — Run test in the specified file. Only valid when --package is also specified
-i, --index <INDEX> — Run only the index-th test in the file. Only valid when --file is also specified
-u, --update — Update the test snapshot
-l, --limit <LIMIT> — Limit of expect test update passes to run, in order to avoid infinite loops
Default value: 256
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
--build-only — Only build, do not run the tests
--no-parallelize — Run the tests in a target backend sequentially
--test-failure-json — Print failure message in JSON format
moon cleanRemove the target directory
+Usage: moon clean
moon fmtFormat source code
+Usage: moon fmt [OPTIONS]
--check — Check only and don't change the source code--sort-input — Sort input filesmoon docGenerate documentation
+Usage: moon doc [OPTIONS]
--serve — Start a web server to serve the documentation
-b, --bind <BIND> — The address of the server
Default value: 127.0.0.1
-p, --port <PORT> — The port of the server
Default value: 3000
--frozen — Do not sync dependencies, assuming local dependencies are up-to-date
moon infoGenerate public interface (.mbti) files for all packages in the module
Usage: moon info [OPTIONS]
--frozen — Do not sync dependencies, assuming local dependencies are up-to-datemoon addAdd a dependency
+Usage: moon add <PACKAGE_PATH>
<PACKAGE_PATH> — The package path to addmoon removeRemove a dependency
+Usage: moon remove <PACKAGE_PATH>
<PACKAGE_PATH> — The package path to removemoon installInstall dependencies
+Usage: moon install
moon treeDisplay the dependency tree
+Usage: moon tree
moon loginLog in to your account
+Usage: moon login
moon registerRegister an account at mooncakes.io
+Usage: moon register
moon publishPublish the current package
+Usage: moon publish [OPTIONS]
--frozen — Do not sync dependencies, assuming local dependencies are up-to-datemoon updateUpdate the package registry index
+Usage: moon update
moon coverageCode coverage utilities
+Usage: moon coverage <COMMAND>
report — Generate code coverage reportclean — Clean up coverage artifactsmoon coverage reportGenerate code coverage report
+Usage: moon coverage report [args]... [COMMAND]
<args> — Arguments to pass to the coverage utility-h, --help — Show help for the coverage utilitymoon coverage cleanClean up coverage artifacts
+Usage: moon coverage clean
moon generate-build-matrixGenerate build matrix for benchmarking (legacy feature)
+Usage: moon generate-build-matrix [OPTIONS] --output-dir <OUT_DIR>
-n <NUMBER> — Set all of drow, dcol, mrow, mcol to the same value--drow <DIR_ROWS> — Number of directory rows--dcol <DIR_COLS> — Number of directory columns--mrow <MOD_ROWS> — Number of module rows--mcol <MOD_COLS> — Number of module columns-o, --output-dir <OUT_DIR> — The output directorymoon upgradeUpgrade toolchains
+Usage: moon upgrade [OPTIONS]
-f, --force — Force upgrademoon shell-completionGenerate shell completion for bash/elvish/fish/pwsh/zsh to stdout
+Usage: moon shell-completion [OPTIONS]
Discussion:
+Enable tab completion for Bash, Elvish, Fish, Zsh, or PowerShell
+The script is output on stdout, allowing one to re-direct the
+output to the file of their choosing. Where you place the file
+will depend on which shell, and which operating system you are
+using. Your particular configuration may also determine where
+these scripts need to be placed.
The completion scripts won't update itself, so you may need to
+periodically run this command to get the latest completions.
+Or you may put `eval "$(moon shell-completion --shell <SHELL>)"`
+in your shell's rc file to always load newest completions on startup.
+Although it's considered not as efficient as having the completions
+script installed.
+
+Here are some common set ups for the three supported shells under
+Unix and similar operating systems (such as GNU/Linux).
+
+Bash:
+
+Completion files are commonly stored in `/etc/bash_completion.d/` for
+system-wide commands, but can be stored in
+`~/.local/share/bash-completion/completions` for user-specific commands.
+Run the command:
+
+ $ mkdir -p ~/.local/share/bash-completion/completions
+ $ moon shell-completion --shell bash >> ~/.local/share/bash-completion/completions/moon
+
+This installs the completion script. You may have to log out and
+log back in to your shell session for the changes to take effect.
+
+Bash (macOS/Homebrew):
+
+Homebrew stores bash completion files within the Homebrew directory.
+With the `bash-completion` brew formula installed, run the command:
+
+ $ mkdir -p $(brew --prefix)/etc/bash_completion.d
+ $ moon shell-completion --shell bash > $(brew --prefix)/etc/bash_completion.d/moon.bash-completion
+
+Fish:
+
+Fish completion files are commonly stored in
+`$HOME/.config/fish/completions`. Run the command:
+
+ $ mkdir -p ~/.config/fish/completions
+ $ moon shell-completion --shell fish > ~/.config/fish/completions/moon.fish
+
+This installs the completion script. You may have to log out and
+log back in to your shell session for the changes to take effect.
+
+Elvish:
+
+Elvish completions are commonly stored in a single `completers` module.
+A typical module search path is `~/.config/elvish/lib`, and
+running the command:
+
+ $ moon shell-completion --shell elvish >> ~/.config/elvish/lib/completers.elv
+
+will install the completions script. Note that use `>>` (append)
+instead of `>` (overwrite) to prevent overwriting the existing completions
+for other commands. Then prepend your rc.elv with:
+
+ `use completers`
+
+to load the `completers` module and enable completions.
+
+Zsh:
+
+ZSH completions are commonly stored in any directory listed in
+your `$fpath` variable. To use these completions, you must either
+add the generated script to one of those directories, or add your
+own to this list.
+
+Adding a custom directory is often the safest bet if you are
+unsure of which directory to use. First create the directory; for
+this example we'll create a hidden directory inside our `$HOME`
+directory:
+
+ $ mkdir ~/.zfunc
+
+Then add the following lines to your `.zshrc` just before
+`compinit`:
+
+ fpath+=~/.zfunc
+
+Now you can install the completions script using the following
+command:
+
+ $ moon shell-completion --shell zsh > ~/.zfunc/_moon
+
+You must then open a new zsh session, or simply run
+
+ $ . ~/.zshrc
+
+for the new completions to take effect.
+
+Custom locations:
+
+Alternatively, you could save these files to the place of your
+choosing, such as a custom directory inside your $HOME. Doing so
+will require you to add the proper directives, such as `source`ing
+inside your login script. Consult your shells documentation for
+how to add such directives.
+
+PowerShell:
+
+The powershell completion scripts require PowerShell v5.0+ (which
+comes with Windows 10, but can be downloaded separately for windows 7
+or 8.1).
+
+First, check if a profile has already been set
+
+ PS C:\> Test-Path $profile
+
+If the above command returns `False` run the following
+
+ PS C:\> New-Item -path $profile -type file -force
+
+Now open the file provided by `$profile` (if you used the
+`New-Item` command it will be
+`${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1`
+
+Next, we either save the completions file into our profile, or
+into a separate file and source it inside our profile. To save the
+completions into our profile simply use
+
+ PS C:\> moon shell-completion --shell powershell >>
+ ${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
+
+This discussion is taken from `rustup completions` command with some changes.
+--shell <SHELL> — The shell to generate completion for
Default value: <your shell>
Possible values: bash, elvish, fish, powershell, zsh
moon versionPrint version information and exit
+Usage: moon version [OPTIONS]
--all — Print all version information--json — Print version information in JSON format--no-path — Do not print the path
+This document was generated automatically by
+clap-markdown.
+
moon 使用 moon.mod.json 文件来识别、描述一个模块。
name 字段用于指定模块的名称，必须指定。
{
+ "name": "example",
+ ...
+}
+模块名可以包含字母、数字、_、-、/。
对于发布到 mooncakes.io 的模块，模块名必须以用户名开头，例如：
+{
+ "name": "moonbitlang/core",
+ ...
+}
+version 字段用于指定模块的版本。
该字段为可选项，对于发布到 mooncakes.io 的模块，版本号必须符合 语义化版本 2.0.0 规范。
+{
+ "name": "example",
+ "version": "0.1.0",
+ ...
+}
+deps 字段用于指定模块的依赖。
由 moon add、moon remove 等命令自动管理。
{
+ "name": "username/hello",
+ "deps": {
+ "moonbitlang/x": "0.4.6"
+ }
+}
+readme 字段用于指定模块的 README 文件路径。
repository 字段用于指定模块的仓库地址。
license 字段用于指定模块的许可证。许可证类型必须符合 SPDX 许可证列表。
{
+ "license": "MIT"
+}
+keywords 字段用于指定模块的关键词。
{
+ "keywords": ["example", "test"]
+}
+description 字段用于指定模块的描述。
{
+ "description": "This is a description of the module."
+}
+source 字段用于指定模块的源码目录。
它必须为当前 moon.mod.json 文件所在目录的子目录。且必须为相对路径
当使用 moon new 命令创建模块时，会自动生成一个 src 目录，并且 source 字段的默认值为 src。
{
+ "source": "src"
+}
+当 source 字段不存在，或者其值为 null 或空字符串 "" 时，相当于设置 "source": "."。这表示源码目录为该 moon.mod.json 文件所在的目录。
{
+ "source": null
+}
+{
+ "source": ""
+}
+{
+ "source": "."
+}
+关闭对应的编译器预设警告编号。
+例如，如下配置中 -2 代表关闭编号为 2(Unused variable) 的警告
{
+ "warn-list": "-2",
+}
+可用 moonc build-package -warn-help 查看编译器预设的警告编号
$ 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
+关闭用户预设 alter。
+{
+ "alert-list": "-alert_1-alert_2"
+}
+moon 使用 moon.pkg.json 文件来识别、描述一个包。
包名不可配置，它由包的目录名决定。
+is-main 字段用于指定一个包是否需要被链接成一个可执行的文件。
链接所生成的产物与后端相关，当该字段为 true 时：
wasm 和 wasm-gc 后端，将会生成一个可以独立运行的 WebAssembly 模块。js 后端，将会生成一个可以独立运行的 JavaScript 文件。import 字段用于指定一个包所依赖的其他包。
test-import 字段用于指定该包对应的黑盒测试包所依赖的其他包。
wbtest-import 字段用于指定该包对应的白盒测试包所依赖的其他包。
moon 默认只会链接 is-main 为 true 的包，如果需要链接其他包，可以通过 link 选项指定。
link 选项用于指定链接选项，它的值可以为布尔值或一个对象。
link 值为 true 时，表示需要链接该包。构建时所指定的后端不同，产物也不同。
{
+ "link": true
+}
+link 值为对象时，表示需要链接该包，并且可以指定链接选项，详细配置请查看对应后端的子页面。
exports 选项用于指定 wasm 后端导出的函数名。
例如，如下配置将当前包中的 hello 函数导出为 wasm 模块的 hello 函数, foo 函数导出为 wasm 模块的 foo 函数。在 wasm 宿主中，可以通过 hello 和 bar 函数来调用当前包中的 hello 和 foo 函数。
{
+ "link": {
+ "wasm": {
+ "exports": [
+ "hello",
+ "foo:bar"
+ ]
+ },
+ }
+}
+heap-start-address 选项用于指定 moonc 编译到 wasm 后端时能够使用的线性内存的起始地址。
例如，如下配置将线性内存的起始地址设置为 1024。
+{
+ "link": {
+ "wasm": {
+ "heap-start-address": 1024
+ },
+ }
+}
+import-memory 选项用于指定 wasm 模块导入的线性内存。
例如，如下配置将 wasm 模块导入的线性内存指定为 env 模块的 memory 变量。
{
+ "link": {
+ "wasm": {
+ "import-memory": {
+ "module": "env",
+ "name": "memory"
+ }
+ },
+ }
+}
+export-memory-name 选项用于指定 wasm 模块导出的线性内存名称。
{
+ "link": {
+ "wasm": {
+ "export-memory-name": "memory"
+ },
+ }
+}
+wasm-gc 后端与 wasm 后端的链接选项类似，只不过没有 heap-start-address 选项。
exports 选项用于指定 JavaScript 模块的导出函数名。
例如，如下配置将当前包中的 hello 函数导出为 JavaScript 模块的 hello 函数。在 JavaScript 宿主中，可以通过 hello 函数来调用当前包中的 hello 函数。
{
+ "link": {
+ "js": {
+ "exports": [
+ "hello"
+ ]
+ }
+ }
+}
+format 选项用于指定 JavaScript 模块的输出格式。
目前支持的格式有：
+esmcjsiife例如，如下配置将当前包的输出格式指定为 ES Module。
+{
+ "link": {
+ "js": {
+ "format": "esm"
+ }
+ }
+}
+关闭对应的编译器预设警告编号。
+例如，如下配置中 -2 代表关闭编号为 2(Unused variable) 的警告
{
+ "warn-list": "-2",
+}
+可用 moonc build-package -warn-help 查看编译器预设的警告编号
$ 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
+关闭用户预设 alter。
+{
+ "alert-list": "-alert_1-alert_2"
+}
+条件编译的最小单位是文件。
+在条件编译表达式中，支持三种逻辑操作符：and、or 和 not，其中 or 操作符可以省略不写。
例如，["or", "wasm", "wasm-gc"] 可以简写为 ["wasm", "wasm-gc"]。
条件表达式中的条件可以分为后端和优化级别：
+"wasm"、"wasm-gc" 和 "js""debug" 和 "release"条件表达式支持嵌套。
+如果一个文件未在 "targets" 中列出，它将默认在所有条件下编译。
示例：
+{
+ "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"]]
+ }
+}
+字段 "pre-build" 用于指定预构建命令，预构建命令会在 moon check|build|test 等构建命令之前执行。
"pre-build"是一个数组，数组中的每个元素是一个对象，对象中包含 input，output 和 command 三个字段，input 和 output 可以是字符串或者字符串数组，command 是字符串，command 中可以使用任意命令行命令，以及 $input，$output 变量，分别代表输入文件、输出文件，如果是数组默认使用空格分割。
目前内置了一个特殊命令 :embed，用于将文件转换为 MoonBit 源码，--text 参数用于嵌入文本文件，--binary 用于嵌入二进制文件，--text 为默认值，可省略不写。--name 用于指定生成的变量名，默认值为 resource。命令的执行目录为当前 moon.pkg.json 所在目录。
{
+ "pre-build": [
+ {
+ "input": "a.txt",
+ "output": "a.mbt",
+ "command": ":embed -i $input -o $output"
+ }
+ ]
+}
+如果当前包目录下的 a.txt 的内容为
hello,
+world
+执行 moon build 后，在此 moon.pkg.json 所在目录下生成如下 a.mbt 文件
let resource : String =
+ #|hello,
+ #|world
+ #|
+moon 是 MoonBit 语言的构建系统，目前基于 n2 项目。moon 支持并行构建和增量构建，此外它还支持管理和构建 mooncakes.io 上的第三方包。
在开始之前，请确保安装好以下内容：
+MoonBit CLI 工具: 从这里下载。该命令行工具用于创建和管理 MoonBit 项目。
+使用 moon help 命令可查看使用说明。
$ moon help
+...
+Moonbit Language Visual Studio Code 插件: 可以从 VS Code 市场安装。该插件为 MoonBit 提供了丰富的开发环境，包括语法高亮、代码补全、交互式除错和测试等功能。
+安装完成后，让我们开始创建一个新的 MoonBit 模块。
+使用 moon new 创建一个新项目，默认的配置是：
$ moon new
+Enter the path to create the project (. for current directory): my-project
+Select the create mode: exec
+Enter your username: username
+Enter your project name: hello
+Enter your license: Apache-2.0
+Created my-project
+这会在 my-project 下创建一个名为 username/hello 的新模块。上述过程也可以使用 moon new my-project 代替。
上一步所创建的模块目录结构如下所示：
+my-project
+├── LICENSE
+├── README.md
+├── moon.mod.json
+└── src
+ ├── lib
+ │ ├── hello.mbt
+ │ ├── hello_test.mbt
+ │ └── moon.pkg.json
+ └── main
+ ├── main.mbt
+ └── moon.pkg.json
+这里简单解释一下目录结构：
+moon.mod.json 用来标记这个目录是一个模块。它包含了模块的元信息，例如模块名、版本等。
{
+ "name": "username/hello",
+ "version": "0.1.0",
+ "readme": "README.md",
+ "repository": "",
+ "license": "Apache-2.0",
+ "keywords": [],
+ "description": "",
+ "source": "src"
+}
+source 字段指定了模块的源代码目录，默认值是 src。该字段存在的原因是因为 MoonBit 模块中的包名与文件路径相关。例如，当前模块名为 username/hello，而其中一个包所在目录为 lib/moon.pkg.json，那么在导入该包时，需要写包的全名为 username/hello/lib。有时，为了更好地组织项目结构，我们想把源码放在 src 目录下，例如 src/lib/moon.pkg.json，这时需要使用 username/hello/src/lib 导入该包。但一般来说我们并不希望 src 出现在包的路径中，此时可以通过指定 "source": "src" 来忽略 src 这层目录，便可使用 username/hello/lib 导入该包。
src/lib 和 src/main 目录：这是模块内的包。每个包可以包含多个 .mbt 文件，这些文件是 MoonBit 语言的源代码文件。但是，无论一个包有多少 .mbt 文件，它们都共享一个 moon.pkg.json 文件。lib/*_test.mbt 是 lib 包中的独立测试文件，这些文件用于黑盒测试，无法直接访问 lib 包的私有成员。
moon.pkg.json 是包描述文件。它定义了包的属性，例如，是否是 main 包，所导入的其他包。
main/moon.pkg.json:
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib"
+ ]
+}
+这里，"is_main: true" 表示这个包需要被链接成目标文件。在 wasm/wasm-gc 后端，会被链接成一个 wasm 文件，在 js 后端，会被链接成一个 js 文件。
lib/moon.pkg.json:
{}
+这个文件只是为了告诉构建系统当前目录是一个包。
+我们的 username/hello 模块包含两个包：username/hello/lib 和 username/hello/main。
包 username/hello/lib 包含 hello.mbt 和 hello_test.mbt 文件：
hello.mbt
pub fn hello() -> String {
+ "Hello, world!"
+}
+hello_test.mbt
test "hello" {
+ if @lib.hello() != "Hello, world!" {
+ fail!("@lib.hello() != \"Hello, world!\"")
+ }
+}
+包 username/hello/main 只包含一个 main.mbt 文件：
fn main {
+ println(@lib.hello())
+}
+为了执行程序，需要在 moon run 命令中指定 username/hello/main 包的文件系统路径：
$ moon run ./src/main
+Hello, world!
+你也可以省略 ./
$ moon run src/main
+Hello, world!
+你可以使用 moon test 命令进行测试：
$ moon test
+Total tests: 1, passed: 1, failed: 0.
+在 MoonBit 的构建系统中，模块名用于引用其内部包。
+如果想在 src/main/main.mbt 中使用 username/hello/lib 包，你需要在 src/main/moon.pkg.json 中指定：
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib"
+ ]
+}
+这里，username/hello/lib 指定了从 username/hello 模块导入 username/hello/lib 包，所以你可以在 main/main.mbt 中使用 @lib.hello()。
注意，src/main/moon.pkg.json 中导入的包名是 username/hello/lib，在 src/main/main.mbt 中使用 @lib 来引用这个包。这里的导入实际上为包名 username/hello/lib 生成了一个默认别名。在接下来的章节中，你将学习如何为包自定义别名。
首先，在 lib 下创建一个名为 fib 的新目录：
mkdir src/lib/fib
+现在，你可以在 src/lib/fib 下创建新文件：
a.mbt:
pub fn fib(n : Int) -> Int {
+ match n {
+ 0 => 0
+ 1 => 1
+ _ => fib(n - 1) + fib(n - 2)
+ }
+}
+b.mbt:
pub fn fib2(num : Int) -> Int {
+ fn aux(n, acc1, acc2) {
+ match n {
+ 0 => acc1
+ 1 => acc2
+ _ => aux(n - 1, acc2, acc1 + acc2)
+ }
+ }
+
+ aux(num, 0, 1)
+}
+moon.pkg.json:
{}
+在创建完这些文件后，你的目录结构应该如下所示：
+my-project
+├── LICENSE
+├── README.md
+├── moon.mod.json
+└── src
+ ├── lib
+ │ ├── fib
+ │ │ ├── a.mbt
+ │ │ ├── b.mbt
+ │ │ └── moon.pkg.json
+ │ ├── hello.mbt
+ │ ├── hello_test.mbt
+ │ └── moon.pkg.json
+ └── main
+ ├── main.mbt
+ └── moon.pkg.json
+在 src/main/moon.pkg.json 文件中，导入 username/hello/lib/fib 包，并自定义别名为 my_awesome_fibonacci：
{
+ "is_main": true,
+ "import": [
+ "username/hello/lib",
+ {
+ "path": "username/hello/lib/fib",
+ "alias": "my_awesome_fibonacci"
+ }
+ ]
+}
+这行导入了 username/hello/lib/fib 包。导入后，你可以在 main/main.mbt 中使用 fib 包了。
将 main/main.mbt 的文件内容替换为：
fn main {
+ let a = @my_awesome_fibonacci.fib(10)
+ let b = @my_awesome_fibonacci.fib2(11)
+ println("fib(10) = \{a}, fib(11) = \{b}")
+
+ println(@lib.hello())
+}
+为了执行程序，需要在 moon run 命令中指定 username/hello/main 包的文件系统路径：
$ moon run ./src/main
+fib(10) = 55, fib(11) = 89
+Hello, world!
+让我们添加一些测试来验证我们的 fib 实现。在 src/lib/fib/a.mbt 中添加以下内容：
src/lib/fib/a.mbt
test {
+ assert_eq!(fib(1), 1)
+ assert_eq!(fib(2), 1)
+ assert_eq!(fib(3), 2)
+ assert_eq!(fib(4), 3)
+ assert_eq!(fib(5), 5)
+}
+这些代码测试了斐波那契数列的前五项。test { ... } 定义了一个内联测试块。内联测试块中的代码在测试模式下执行。
内联测试块在非测试模式下（moon build 和 moon run）会被丢弃，因此不会导致生成的代码大小膨胀。
除了内联测试，MoonBit 还支持独立测试文件。以 _test.mbt 结尾的源文件被认为是黑盒测试的测试文件。例如，在 src/lib/fib 目录中，创建一个名为 fib_test.mbt 的文件，并粘贴以下代码：
src/lib/fib/fib_test.mbt
test {
+ assert_eq!(@fib.fib(1), 1)
+ assert_eq!(@fib.fib2(2), 1)
+ assert_eq!(@fib.fib(3), 2)
+ assert_eq!(@fib.fib2(4), 3)
+ assert_eq!(@fib.fib(5), 5)
+}
+注意，构建系统会自动为以 _test.mbt 结尾的文件创建一个新的包，用于黑盒测试，并且自动导入当前包。因此，在测试块中需要使用 @fib 来引用 username/hello/lib/fib 包，而不需要在 moon.pkg.json 中显式地导入该包。
最后，使用 moon test 命令，它会扫描整个项目，识别并运行所有内联测试以及以 _test.mbt 结尾的文件。如果一切正常，你会看到：
$ moon test
+Total tests: 3, passed: 3, failed: 0.
+$ moon test -v
+test username/hello/lib/hello_test.mbt::hello ok
+test username/hello/lib/fib/a.mbt::0 ok
+test username/hello/lib/fib/fib_test.mbt::0 ok
+Total tests: 3, passed: 3, failed: 0.
+