Write user documentation for Rust contracts #129
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Rebased. |
added 3 commits
December 11, 2018 21:33
It doesn't need its own header
Add links to some other Ewasm docs
lrettig
requested changes
Dec 11, 2018
|
|
||
| ### Minimize the use of the standard library | ||
|
|
||
| Many constructs in Rust's standard library are not optimized for usage in Ewasm, or are outright unavailable due to dependence on a native syscall interface. |
There was a problem hiding this comment.
Could you give a specific example of something that is unavailable or not optimized for use?
There was a problem hiding this comment.
Examples are below. As for something that is unavailable due to syscalls, most collections can simply use a custom allocator. So I might drop this line since nobody actually needs to read about that for this purpose.
There was a problem hiding this comment.
I might drop this line since nobody actually needs to read about that for this purpose
Agree--where in doubt, keep it simple
|
|
||
| The Rust compiler, at the moment, does not have fine-grained control over the imports and exports generated other than by their identifiers in the source. As a result, unnecessary exports must be removed and malformed imports corrected. | ||
|
|
||
| This can be done using an automated tool such as [wasm-chisel](https://github.com/wasmx/wasm-chisel), or by hand in the `.wast` file produced by disassembling the Wasm binary. |
There was a problem hiding this comment.
Could you demonstrate how to run wasm-chisel here so these instructions are complete?
axic
reviewed
Dec 11, 2018
| The simplest way to slim down Rust-generated binaries is by enabling certain compiler optimizations: | ||
|
|
||
| * Enabling `lto`, or link-time optimizations, allows the compiler to prune or inline parts of the code at link-time. | ||
| * Setting `opt-level` to `'s'` tells the compiler to optimize for binary size rather than speed. `opt-level = 'z'` will optimize more aggressively for size, although at the cost of performance. |
There was a problem hiding this comment.
Note:
error: the optimizations s or z are only accepted on the nightly compiler
|
Are you sure? As of a week ago, I am almost certain that I successfully
built on stable.
…On Tue, Dec 11, 2018, 13:39 Alex Beregszaszi ***@***.*** wrote:
***@***.**** commented on this pull request.
------------------------------
In rust.md
<#129 (comment)>:
> +```
+Once this is done, `cargo build` will compile the project to WebAssembly by default.
+
+### Optimizing Ewasm binaries
+
+By default, the Rust compiler can generate huge WebAssembly binaries, even in release mode.
+These include lots of unnecessary cruft and are not suitable for use as Ewasm contracts.
+
+The following steps will show how to optimize for size and remove unnecessary code segments from the resulting Wasm binary.
+
+#### Compiler optimizations
+
+The simplest way to slim down Rust-generated binaries is by enabling certain compiler optimizations:
+
+* Enabling `lto`, or link-time optimizations, allows the compiler to prune or inline parts of the code at link-time.
+* Setting `opt-level` to `'s'` tells the compiler to optimize for binary size rather than speed. `opt-level = 'z'` will optimize more aggressively for size, although at the cost of performance.
Note:
error: the optimizations s or z are only accepted on the nightly compiler
—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
<#129 (review)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AHEQh2wEYg2ZPkOfQzmCSyn_vkl1xeLnks5u3_vegaJpZM4ZBsUV>
.
|
axic
reviewed
Dec 11, 2018
| #### Using [wasm-snip](https://github.com/rustwasm/wasm-snip) | ||
|
|
||
| The Rust compiler, by default, includes panicking and formatting code in generated binaries. For the purpose of Ewasm contracts, this is useless. | ||
| Using the `wasm-snip` tool, it is possible to replace the function bodies of such code with a single `unreachable` opcode, further shrinking the binary size. |
There was a problem hiding this comment.
wasm-snip requires a run of wasm-gc afterwards, iirc.
|
IIRC this is only to remove functions transitively called by the panicking
infrastructure, which doesn't matter in the case of ewasm contracts.
…On Tue, Dec 11, 2018, 13:59 Alex Beregszaszi ***@***.*** wrote:
***@***.**** commented on this pull request.
------------------------------
In rust.md
<#129 (comment)>:
> +The simplest way to slim down Rust-generated binaries is by enabling certain compiler optimizations:
+
+* Enabling `lto`, or link-time optimizations, allows the compiler to prune or inline parts of the code at link-time.
+* Setting `opt-level` to `'s'` tells the compiler to optimize for binary size rather than speed. `opt-level = 'z'` will optimize more aggressively for size, although at the cost of performance.
+
+Enable these options in the `release` profile by adding the following to `Cargo.toml`:
+```toml
+[profile.release]
+lto = true
+opt-level = 's'
+```
+
+#### Using [wasm-snip](https://github.com/rustwasm/wasm-snip)
+
+The Rust compiler, by default, includes panicking and formatting code in generated binaries. For the purpose of Ewasm contracts, this is useless.
+Using the `wasm-snip` tool, it is possible to replace the function bodies of such code with a single `unreachable` opcode, further shrinking the binary size.
wasm-snip requires a run of wasm-gc afterwards, iirc.
—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
<#129 (review)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AHEQh5rZT4f3HHQrdQsZQeNEVTi9hlANks5u4ACYgaJpZM4ZBsUV>
.
|
|
Just took another look, still some pending requested changes here |
|
I don't feel like i have the bandwidth to finish this right now. Does anyone want to help out on this? cc @lrettig @ewasm/rust |
|
The longer we wait, the less readme will be needed as chisel will incorporate a lot 😆 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Closes #131.