Add custom platform configuration

[AlixANNERAUD]

Hello,
This PR adds support for custom platforms by setting the environment variables WAMR_SHARED_PLATFORM_CONFIG and WAMR_BUILD_PLATFORM, which propagate to the WAMR build scripts.

[lum1n0us]

May I ask how to use this feature?

[AlixANNERAUD]

As described in the porting guide, the WAMR_BUILD_PLATFORM (which contains the platform name) and/or WAMR_SHARED_PLATFORM_CONFIG (which is the path to the custom platform CMake file, later translated to SHARED_PLATFORM_CONFIG define) can be specified. This allows the crate user to specify a custom platform and potentially a private custom platform API. Additionally, the ESP-IDF build system can be enabled or disabled manually using the esp-idf feature. This is necessary because the ESP-IDF build procedure differs from the regular one (build internally by esp-idf-sys), which could disrupt the use of a custom platform.

[lum1n0us]

Does it mean the compilation command will be something like CARGO_CFG_TARGET_OS=espidf cargo build cargo build --target=espidf?

[lum1n0us]

I am confused here. I though ESP-IDF building should use stuff in product-mini/platforms/esp-idf/ in wamr repo. But the panic! seems suggest another way?

[AlixANNERAUD]

This is handled by the esp-idf-sys crate (refer to Cargo.toml). Since the WAMR esp-idf build script is designed to build WAMR as an esp-idf component, we cannot use the regular build.rs due to missing libc / esp-idf dependencies.

[lum1n0us]

IIUC, the new code suggests the build.rs should quit as soon as possible when realizing it is for an esp-idf build.

If so, is_espidf means cargo --target=espidf and host platform is espidf.

Then we might want to check if the value env::var("WAMR_BUILD_PLATFORM").unwrap() == "esp-idf" instead of if WAMR_BULD_PLATFORM is defined only. I guess it could be something else.

In order to avoid crossing compilation, might like

if is_espidf || env::var("WAMR_BUILD_PLATFORM").unwrap() == "esp-idf"

SHARED_PLATFORM_CONFIG is assumed to match WAMR_BUILD_PLATFORM. So I guess we can ignore it.

Please correct me, if I am wrong.

[AlixANNERAUD]

The build script should exit immediately since we still need to generate bindings.rs themselves (which are the same for every platform), which is performed at the end of the build script. However, the underneath linked functions are different and depend on the platform.

When building for ESP-IDF, the host platform is Linux, macOS, or Windows, but the target is espidf (e.g., xtensa-esp32-espidf, riscv-espc3-espidf etc.).

WAMR_BUILD_PLATFORM and SHARED_PLATFORM_CONFIG should not be defined when building for ESP-IDF since it doesn't make sense to declare them; everything is handled by esp-idf-sys.

For more clarity, here are the different possible build scenarios:

Target	Feature	Env	Compile?
esp-idf	esp-idf	None	Yes
esp-idf	None	WAMR_BUILD_PLATFORM / SHARED_PLATFORM_CONFIG	No: WAMR provided build script is intended to be build as an esp-idf component
others	None	None	Yes
others	None	WAMR_BUILD_PLATFORM / SHARED_PLATFORM_CONFIG	Yes
others	esp-idf	None	No: doesn’t make any sense

[lum1n0us]

The build script should exit immediately since we still need to generate

should -> should not?

[lum1n0us]

IIUC, when the target is esp-idf, we can ignore WAMR_BUILD_PLATFORM and SHARE_PPLATFORM_CONFIG. Because L31~L64 is protected by if !is_espidf condition. So we can skip cmake compilation and goto bindings generation.

[lum1n0us]

This is not for esp-idf. right? It is for other new-os.

So we are using env::var to operate cmake compilation options. Good to learn.

[lum1n0us]

like macos, windows, android, those are OSes can be represented by CARGO_CFG_TARGET_OS(https://doc.rust-lang.org/reference/conditional-compilation.html#target_os), and those platform configuration files (shared_platform.cmake) are listed in WAMR repo(core/shared/platform/XXX/. No need to create).

Therefore, I am thinking that maybe we can set both WAMR_BUILD_PLATFORM and WAMR_SHARE_PLATFORM_CONIG for those OSes.

For example, create a pre-defined dict which keys are possible values(and WAMR supported) of target_os and values are paths for correspond shared_platform.cmake. And firstly use user defined env variables(allow overwrite). If not set, use pre-defined dict.

After above, I guess users can use wamr-rust-sdk in other OSes.

[AlixANNERAUD]

Any updates ?

[lum1n0us]

IIUC, when the target is esp-idf, we can ignore WAMR_BUILD_PLATFORM and SHARE_PPLATFORM_CONFIG.

Is that correct?

So, current protection is enough.

  let no_espidf = env::var("CARGO_CFG_TARGET_OS").unwrap() != "espidf";
  // because the ESP-IDF build procedure differs from the regular one (build internally by esp-idf-sys),
  if no_espidf {
    // ...   
  }

  // bindgen ...

If so, all we need is to involve WAMR_BUILD_PLATFORM and SHARE_PPLATFORM_CONFIG. I can create a new PR to implement it.

[AlixANNERAUD]

IIUC, when the target is esp-idf, we can ignore WAMR_BUILD_PLATFORM and SHARE_PPLATFORM_CONFIG.

Is that correct?

So, current protection is enough.

  let no_espidf = env::var("CARGO_CFG_TARGET_OS").unwrap() != "espidf";
  // because the ESP-IDF build procedure differs from the regular one (build internally by esp-idf-sys),
  if no_espidf {
    // ...   
  }

  // bindgen ...

If so, all we need is to involve. I can create a new PR to implement it.

The current protection is sufficient on its own; however, we should inform or warn the user that there may be an issue when setting WAMR_BUILD_PLATFORM and SHARE_PLATFORM_CONFIG with ESP-IDF to avoid any confusion.

That said, I'm not sure why you want to create another PR, since everything related to WAMR_BUILD_PLATFORM and SHARE_PLATFORM_CONFIG is already included here.

[lum1n0us]

The current protection is sufficient on its own; however, we should inform or warn the user that there may be an issue when setting WAMR_BUILD_PLATFORM and SHARE_PLATFORM_CONFIG with ESP-IDF to avoid any confusion.

In this case, you are right.

That said, I'm not sure why you want to create another PR, since everything related to WAMR_BUILD_PLATFORM and SHARE_PLATFORM_CONFIG is already included here.

Just in case if u don't want to spend too much time on it since it's been a long time and still need some work.

[AlixANNERAUD]

The current protection is sufficient on its own; however, we should inform or warn the user that there may be an issue when setting WAMR_BUILD_PLATFORM and SHARE_PLATFORM_CONFIG with ESP-IDF to avoid any confusion.

In this case, you are right.

That said, I'm not sure why you want to create another PR, since everything related to WAMR_BUILD_PLATFORM and SHARE_PLATFORM_CONFIG is already included here.

Just in case if u don't want to spend too much time on it since it's been a long time and still need some work.

What do you mean when you say it still needs some work?

[lum1n0us]

rebase to resolve conflict