Write user documentation for Rust contracts by jakelang · Pull Request #129 · ewasm/testnet

jakelang · 2018-12-04T23:16:09Z

Closes #131.

axic · 2018-12-05T20:58:12Z

Rebased.

It doesn't need its own header

Add links to some other Ewasm docs

lrettig

Made a few tweaks, added some links, and added a couple of comments. Overall looks great!

lrettig · 2018-12-11T15:00:26Z

rust.md

+
+### 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.


Could you give a specific example of something that is unavailable or not optimized for use?

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.

I might drop this line since nobody actually needs to read about that for this purpose

Agree--where in doubt, keep it simple

lrettig · 2018-12-11T15:00:49Z

rust.md

+
+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.


Could you demonstrate how to run wasm-chisel here so these instructions are complete?

axic · 2018-12-11T18:39:24Z

rust.md

+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

jakelang · 2018-12-11T18:52:44Z

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 · 2018-12-11T18:59:34Z

rust.md

+#### 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.

jakelang · 2018-12-11T19:04:18Z

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> .

lrettig · 2018-12-27T13:12:54Z

Just took another look, still some pending requested changes here

jakelang · 2019-05-24T19:11:36Z

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

axic · 2019-05-25T00:45:33Z

The longer we wait, the less readme will be needed as chisel will incorporate a lot 😆

jakelang force-pushed the rust branch from 032b300 to 75a3a13 Compare December 4, 2018 23:18

jakelang requested a review from lrettig December 4, 2018 23:19

axic mentioned this pull request Dec 5, 2018

Some misc README cleanup #102

Open

jakelang mentioned this pull request Dec 5, 2018

Import clang kickstart guide #132

Merged

Write documentation for Rust contracts

e300e14

axic force-pushed the rust branch from 75a3a13 to e300e14 Compare December 5, 2018 20:57

Lane Rettig added 3 commits December 11, 2018 21:33

Add Rust to list of other languages

569550f

It doesn't need its own header

Wasm shouldn't be capitalized

f64c5b4

Some minor improvements

ed854ab

Add links to some other Ewasm docs

lrettig requested changes Dec 11, 2018

View reviewed changes

axic reviewed Dec 11, 2018

View reviewed changes


		### 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.


		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.

Conversation

jakelang commented Dec 4, 2018 • edited by axic Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

axic commented Dec 5, 2018

Uh oh!

lrettig left a comment

Choose a reason for hiding this comment

Uh oh!

lrettig Dec 11, 2018

Choose a reason for hiding this comment

Uh oh!

jakelang Dec 21, 2018

Choose a reason for hiding this comment

Uh oh!

lrettig Dec 27, 2018

Choose a reason for hiding this comment

Uh oh!

lrettig Dec 11, 2018

Choose a reason for hiding this comment

Uh oh!

axic Dec 11, 2018

Choose a reason for hiding this comment

Uh oh!

jakelang commented Dec 11, 2018 via email

Uh oh!

axic Dec 11, 2018

Choose a reason for hiding this comment

Uh oh!

jakelang commented Dec 11, 2018 via email

Uh oh!

lrettig commented Dec 27, 2018

Uh oh!

jakelang commented May 24, 2019

Uh oh!

axic commented May 25, 2019

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jakelang commented Dec 4, 2018 •

edited by axic

Loading