Info regarding `std` and `no_std` incomplete or missing

Content request

There doesn’t seem to be a thorough explanation how exactly std and no_std relate to the Wasm binary, neither in the tutorials nor the docs, and some of the hints on this topic seem very confusing to me. I apologize for the long issue.

In Add a Pallet, we get the following:

It is important to note that the Substrate runtime compiles to both a native Rust std binary and a WebAssembly (Wasm) binary. For more information about compiling std and no_std features, see XXX.

It’s unfortunate that the link is missing (link to line). Where was this supposed to point?

That’s all the info we get from Add a Pallet. The Build a proof of existence dApp tutorial has the following to say:

1. Add the macro required to build both the native Rust binary (std) and the WebAssembly (no_std) binary.

#![cfg_attr(not(feature = "std"), no_std)]

All of the pallets used in a runtime must be set to compile with the no_std features.

As a minor complaint, “no_std features” sounds wrong: std is a feature; no_std is an attribute used in Rust and doesn’t really add any functionality. Other than that, the association of Wasm with no_std sounds ok, until you take a look into the runtime code:

#![cfg_attr(not(feature = "std"), no_std)]
// `construct_runtime!` does a lot of recursion and requires us to increase the limit to 256.
#![recursion_limit = "256"]

// Make the WASM binary available.
#[cfg(feature = "std")]
include!(concat!(env!("OUT_DIR"), "/wasm_binary.rs"));

// ...

The Wasm binary was just associated with no_std, why is it now exclusively included if std is enabled? From a stackexchange question, I gather the following: When cargo build is called for the runtime, first the build.rs builds a Wasm binary of the runtime (with no_std), then the runtime is built with std enabled and includes the Wasm binary.

But this doesn’t really answer all of my questions. So I suggest that the following questions be answered/details pointed out:

• What happens exactly when we run cargo build?
• (Provided that my guess from above is correct) If I want a native (std) build, why is the Wasm binary (no_std) built and included? Why not just do a native build?
• How can I build only the no_std Wasm binary? Is there any purpose to doing that?

It’s quite confusing to me that the Wasm binary, one of the defining features of substrate, is not explained in detail anywhere in the tutorials or the docs. I basically got stuck in the second tutorial trying to understand this.

If you could help me with answers to these questions, I would be perfectly happy to work them into the docs myself.

Are you willing to help with this request?

Maybe (please elaborate above)

[sacha-l]

Did some digging and found some helpful context here here and here. Leaving this issue open as we write new docs that capture the information shared here.

[lisa-parity]

I got stuck trying to sort out exactly the same question. I’m working on some draft documentation for this topic, but I’m going to need some technical assistance because the current doc (which I took a stab at fixing and failed) seems contradictory. @shawntabrizi can you provide some detail around how this works or suggest someone I should reach out to?