Write user documentation for Rust contracts

[jakelang]

Closes #131.

[axic]

Rebased.

[jakelang]

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 <[email protected] wrote:

@axic commented on this pull request.

In rust.md https://github.com/ewasm/testnet/pull/129#discussion_r240740004:

+``` +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 https://github.com/ewasm/testnet/pull/129#pullrequestreview-183839712, or mute the thread https://github.com/notifications/unsubscribe-auth/AHEQh2wEYg2ZPkOfQzmCSyn_vkl1xeLnks5u3_vegaJpZM4ZBsUV .

[jakelang]

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 <[email protected] wrote:

@axic commented on this pull request.

In rust.md https://github.com/ewasm/testnet/pull/129#discussion_r240747707:

+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 + +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 https://github.com/ewasm/testnet/pull/129#pullrequestreview-183849006, or mute the thread https://github.com/notifications/unsubscribe-auth/AHEQh5rZT4f3HHQrdQsZQeNEVTi9hlANks5u4ACYgaJpZM4ZBsUV .

[lrettig]

Just took another look, still some pending requested changes here

[jakelang]

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]

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