Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Split init into init and build #216

Merged
merged 7 commits into from
Jul 30, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,10 @@ visiting that repo!

## 🎙️ Commands

- [`init`](docs/init.md): [**Deprecated**] Initialize an npm wasm pkg from a rustwasm crate
- [`build`](docs/build.md): Generate an npm wasm pkg from a rustwasm crate
- [`init`](docs/init.md): Generate an npm wasm pkg from a rustwasm crate
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like this line wasn't removed despite having added the deprecated tag

- [`pack`](docs/pack-and-publish.md): Create a tarball of your rustwasm pkg
- [`publish`](docs/publish.md): Publish your rustwasm pkg to a registry
- [`pack` and `publish`](docs/pack-and-publish.md): Create a tarball of your rustwasm pkg and/or publish to a registry

## 📝 Logging

Expand Down Expand Up @@ -89,7 +90,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`.
Expand Down
73 changes: 73 additions & 0 deletions docs/build.md
Original file line number Diff line number Diff line change
@@ -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`. |
33 changes: 5 additions & 28 deletions docs/init.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# wasm-pack init
# wasm-pack init(Deprecated)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: space before (


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

Expand Down Expand Up @@ -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
Loading