diff --git a/docs/src/6-contributing.md b/docs/src/6-contributing.md index 001d6337..a99ddc09 100644 --- a/docs/src/6-contributing.md +++ b/docs/src/6-contributing.md @@ -83,6 +83,18 @@ cargo xtask generate-fixtures --wasm cargo xtask test-wasm ``` +#### Wasm Stdlib + +The tree-sitter Wasm stdlib can be built via xtask: + +```sh +cargo xtask build-wasm-stdlib +``` + +This command looks for the [Wasi SDK][wasi_sdk] indicated by the `TREE_SITTER_WASI_SDK_PATH` +environment variable. If you don't have the binary, it can be downloaded from wasi-sdk's [releases][wasi-sdk-releases] +page. + ### Debugging The test script has a number of useful flags. You can list them all by running `cargo xtask test -h`. @@ -220,4 +232,6 @@ and the tree-sitter module is fetched from [here][js url]. This, along with the [pypi]: https://pypi.org [rust]: https://rustup.rs [ts repo]: https://github.com/tree-sitter/tree-sitter +[wasi_sdk]: https://github.com/WebAssembly/wasi-sdk +[wasi-sdk-releases]: https://github.com/WebAssembly/wasi-sdk/releases [web-ts]: https://www.npmjs.com/package/web-tree-sitter diff --git a/docs/src/cli/build.md b/docs/src/cli/build.md index 0ad4a922..6863f926 100644 --- a/docs/src/cli/build.md +++ b/docs/src/cli/build.md @@ -18,7 +18,9 @@ will attempt to build the parser in the current working directory. ### `-w/--wasm` -Compile the parser as a Wasm module. +Compile the parser as a Wasm module. This command looks for the [Wasi SDK][wasi_sdk] indicated by the `TREE_SITTER_WASI_SDK_PATH` +environment variable. If you don't have the binary, the CLI will attempt to download it for you to `/tree-sitter/wasi-sdk/`, where +`` is resolved according to the [XDG base directory][XDG] or Window's [Known_Folder_Locations][Known_Folder]. ### `-o/--output` @@ -36,3 +38,7 @@ in the external scanner does so using their allocator. ### `-0/--debug` Compile the parser with debug flags enabled. This is useful when debugging issues that require a debugger like `gdb` or `lldb`. + +[Known_Folder]: https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid +[wasi_sdk]: https://github.com/WebAssembly/wasi-sdk +[XDG]: https://specifications.freedesktop.org/basedir/latest/ diff --git a/docs/src/cli/generate.md b/docs/src/cli/generate.md index c373b1e2..6175381f 100644 --- a/docs/src/cli/generate.md +++ b/docs/src/cli/generate.md @@ -52,8 +52,9 @@ Report conflicts in a JSON format. The path to the JavaScript runtime executable to use when generating the parser. The default is `node`. Note that you can also set this with `TREE_SITTER_JS_RUNTIME`. Starting from version 0.26.0, you can -also pass in `native` to use the native QuickJS runtime that comes bundled with the CLI. This avoids -the dependency on a JavaScript runtime entirely. +also pass in `native` to use the experimental native QuickJS runtime that comes bundled with the CLI. +This avoids the dependency on a JavaScript runtime entirely. The native QuickJS runtime is compatible +with ESM as well as with CommonJS in strict mode. If your grammar depends on `npm` to install dependencies such as base grammars, the native runtime can be used *after* running `npm install`. ### `--disable-optimization` diff --git a/docs/src/cli/parse.md b/docs/src/cli/parse.md index 178d97b5..f18c2edb 100644 --- a/docs/src/cli/parse.md +++ b/docs/src/cli/parse.md @@ -45,7 +45,7 @@ The graphs are constructed with [graphviz dot][dot], and the output is written t ### `--wasm` -Compile and run the parser as a Wasm module. +Compile and run the parser as a Wasm module (only if the tree-sitter CLI was built with `--features=wasm`). ### `--dot` diff --git a/docs/src/cli/test.md b/docs/src/cli/test.md index 401bcd39..f8b8a02d 100644 --- a/docs/src/cli/test.md +++ b/docs/src/cli/test.md @@ -55,7 +55,7 @@ The graphs are constructed with [graphviz dot][dot], and the output is written t ### `--wasm` -Compile and run the parser as a Wasm module. +Compile and run the parser as a Wasm module (only if the tree-sitter CLI was built with `--features=wasm`). ### `--open-log` diff --git a/docs/src/using-parsers/7-abi-versions.md b/docs/src/using-parsers/7-abi-versions.md index 30b6dcdf..34347938 100644 --- a/docs/src/using-parsers/7-abi-versions.md +++ b/docs/src/using-parsers/7-abi-versions.md @@ -1,8 +1,9 @@ # ABI versions -Parsers generated with tree-sitter have an associated ABI version. This version establishes hard compatibility boundaries between the generated parser and the tree-sitter library. +Parsers generated with tree-sitter have an associated ABI version, which establishes hard compatibility boundaries +between the generated parser and the tree-sitter library. -A given version of the tree-sitter library is only able to load parsers which have certain ABI versions: +A given version of the tree-sitter library is only able to load parsers generated with supported ABI versions: | tree-sitter version | Min parser ABI version | Max parser ABI version | |---------------------|------------------------|------------------------| @@ -14,7 +15,8 @@ A given version of the tree-sitter library is only able to load parsers which ha | >=0.20.3, <=0.24 | 13 | 14 | | >=0.25 | 13 | 15 | -By default, the tree-sitter CLI will generate parsers using the latest available ABI for that version. Grammar authors can specify an older ABI (within the constraints _of the CLI_, which may be stricter than the library!) via the `--abi` option to the `generate` command: -``` -tree-sitter generate --abi= -``` +By default, the tree-sitter CLI will generate parsers using the latest available ABI for that version, but an older ABI (supported by the CLI) can be selected by passing the [`--abi` option][abi_option] to the `generate` command. + +Note that the ABI version range supported by the CLI can be smaller than for the library: When a new ABI version is released, older versions will be phased out over a deprecation period, which starts with no longer being able to generate parsers with the oldest ABI version. + +[abi_option]: ../cli/generate.md#--abi-version