Undocumented Cargo.toml features

[VorpalBlade]

The README only documents a handful of the features (native, pio, binstart and libstart). However, there are several more:

• std
• alloc_handler
• panic_handler

While I can guess roughly about what these do, it would be nice to have documentation on them. For example, should I use alloc_handler here or the alloc feature in esp-idf-svc? What is the difference?

[ivmarkov]

You are right about lack of enough documentation (btw - we gladly accept PRs, including for documentation!).

Yet, you are also asking a generic Rust "what is the difference between std vs no_std" question. Let me try to address it:

If you are opting out from std (i.e. the std feature is not enabled - and note that it IS enabled by default, as the cases where you might not want std enabled with the esp-idf-* crates are niche, if existing at all), then you must provide yourself a) an alloc-handler and b) a panic-handler. The respective two features just provide these two handlers for you. The alloc-handler feature implements a Rust allocator (needed by the Rust alloc module which will be used when the alloc feature is enabled) which is just based on ESP IDF's malloc/free libc code. The panic handler in turn just calls the ESP IDF panic handler.

This old Rust bug is containing a nice and more elaborated info on the generic question you are asking: https://github.com/rust-lang/rust/issues/66740

[VorpalBlade]

You are right that I'm new to embedded and no-std rust (though I have done that sort of things in C before). In the case of the HALs and related crates it wasn't clear to me where they are 1) enabling feature that use alloc/std 2) providing things that allow std/alloc to work. 3) providing things that allow non-std to work (i.e. replace things that std/alloc would normally provide).