From d0ac2fa3cd403842bb451ce7f9bf416532df7197 Mon Sep 17 00:00:00 2001 From: csmoe <35686186+csmoe@users.noreply.github.com> Date: Tue, 17 Jul 2018 17:19:50 +0800 Subject: [PATCH] cmd(init/build): update docs --- README.md | 5 ++-- docs/build.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++ docs/init.md | 31 +++------------------- 3 files changed, 80 insertions(+), 29 deletions(-) create mode 100644 docs/build.md diff --git a/README.md b/README.md index 7beef6e..e26e08e 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,8 @@ visiting that repo! ## 🎙️ Commands -- [`init`](docs/init.md): Generate an npm wasm pkg from a rustwasm crate +- [`init`](docs/init.md): Initialize an npm wasm pkg from a rustwasm crate +- [`build`](docs/build.md): Generate an npm wasm pkg from a rustwasm crate - [`pack`](docs/pack.md): Create a tarball of your rustwasm pkg - [`publish`](docs/publish.md): Publish your rustwasm pkg to a registry @@ -90,7 +91,7 @@ check out our [contribution policy]. ``` 5. Install this tool: `cargo install wasm-pack` -6. Run `wasm-pack init`, optionally, pass a path to a dir or a scope (see above for details) +6. Run `wasm-pack build`, optionally, pass a path to a dir or a scope (see above for details) 7. This tool generates files in a `pkg` dir 8. To publish to npm, run `wasm-pack publish`. You may need to login to the registry you want to publish to. You can login using `wasm-pack login`. diff --git a/docs/build.md b/docs/build.md new file mode 100644 index 0000000..5fe9b62 --- /dev/null +++ b/docs/build.md @@ -0,0 +1,73 @@ +# wasm-pack build + +The `wasm-pack build` command creates the files neccessary for JavaScript +interoperability and for publishing a package to npm. This involves compiling +your code to wasm and generating a pkg folder. This pkg folder will contain the +wasm binary, a JS wrapper file, your `README`, and a `package.json` file. + +## Path + +The `wasm-pack build` command can be given an optional path argument, e.g.: + +``` +wasm-pack build examples/js-hello-world +``` + +This path should point to a directory that contains a `Cargo.toml` file. If no +path is given, the `build` command will run in the current directory. + +## Debug + +The init command accepts an optional `--debug` argument. This will build the +output package using cargo's +[default non-release profile][cargo-profile-sections-documentation]. Building +this way is faster but applies few optimizations to the output, and enables +debug assertions and other runtime correctness checks. + +The exact meaning of this flag may evolve as the platform matures. + +[cargo-profile-sections-documentation]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-profile-sections + +## Target + +The `build` command accepts a `--target` argument. This will customize the output files +to align with a particular type of JS module. This allows wasm-pack to generate either +ES6 modules or CommonJS modules for use in browser and in NodeJS. Defaults to `browser`. +The options are: + +``` +wasm-pack build --target nodejs +``` + +| Option | Description | +|-----------|-----------------------------------------------------------------------------------------------------------------| +| `nodejs` | Outputs JS that uses CommonJS modules, for use with a `require` statement. | +| `browser` | Outputs JS that uses ES6 modules, primarily for use with `import` statements and/or bundlers such as `webpack`. | + +## Scope + +The init command also accepts an optional `--scope` argument. This will scope +your package name, which is useful if your package name might conflict with +something in the public registry. For example: + +``` +wasm-pack build examples/js-hello-world --scope test +``` + +This command would create a `package.json` file for a package called +`@test/js-hello-world`. For more information about scoping, you can refer to +the npm documentation [here][npm-scope-documentation]. + +[npm-scope-documentation]: https://docs.npmjs.com/misc/scope + +## Mode + +The `build` command accepts an optional `--mode` argument. +``` +wasm-pack build examples/js-hello-world --mode no-install +``` + +| Option | Description | +|---------------|------------------------------------------------------------------------------------------| +| `no-install` | `wasm-pack init` implicitly and create wasm binding without installing `wasm-bindgen`. | +| `normal` | do all the stuffs of `no-install` with installed `wasm-bindgen`. | diff --git a/docs/init.md b/docs/init.md index 91355c7..62cf418 100644 --- a/docs/init.md +++ b/docs/init.md @@ -1,9 +1,9 @@ # wasm-pack init The `wasm-pack init` command creates the files neccessary for JavaScript -interoperability and for publishing a package to npm. This involves compiling -your code to wasm and generating a pkg folder. This pkg folder will contain the -wasm binary, a JS wrapper file, your `README`, and a `package.json` file. +interoperability and for publishing a package to npm. This involves +generating a pkg folder. This pkg folder will contain the +`README` and a `package.json` file. ## Path @@ -46,27 +46,4 @@ This command would create a `package.json` file for a package called `@test/js-hello-world`. For more information about scoping, you can refer to the npm documentation [here][npm-scope-documentation]. -## Debug - -The init command accepts an optional `--debug` argument. This will build the -output package using cargo's -[default non-release profile][cargo-profile-sections-documentation]. Building -this way is faster but applies few optimizations to the output, and enables -debug assertions and other runtime correctness checks. - -The exact meaning of this flag may evolve as the platform matures. - -[npm-scope-documentation]: https://docs.npmjs.com/misc/scope -[cargo-profile-sections-documentation]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-profile-sections - -## Skipping build - -The init command accepts an optional `--skip-build` argument. - -This will deactivate those steps: -- installing wasm target (via cargo) -- compiling the code to wasm -- installing wasm-bindgen (via rustup) -- running wasm-bindgen on the built wasm - -Basically it will remains only the steps that update the metadata of `package.json`. +[npm-scope-documentation]: https://docs.npmjs.com/misc/scope \ No newline at end of file