examples: New app to build Rust with Cargo

Build Rust applictions with cargo is the most commn way,
and it's more easy to cooporate with Rust ecosystem.

This example shows how to use cargo to build a simple hello world
application.

And please notice that you need to install nighly version of rustc
to support this feature, any version after rust-lang/rust#127755
is merged, can use NuttX as cargo target directly.

Build
-----

To build hello_rust_cargo application, you can use any target that based
on RISCV32IMAC, for example:
```
cmake -B build -DBOARD_CONFIG=rv-virt:nsh -GNinja .
```

And disable ARCH_FPU in menuconfig, since the hard coded target triple
in this demo is `riscv32imac`.

Signed-off-by: Huang Qi <[email protected]>

CMakeLists.txt

@@ -33,6 +33,7 @@ if(CONFIG_APPS_DIR)
   list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR}/cmake)
   include(nuttx_add_luamod)
   include(nuttx_add_wamrmod)
+  include(nuttx_add_rust)
   nuttx_add_library(apps)
   if(NOT EXISTS {NUTTX_APPS_BINDIR}/dummy.c)
     file(TOUCH ${NUTTX_APPS_BINDIR}/dummy.c)

cmake/nuttx_add_rust.cmake

@@ -0,0 +1,165 @@
+# ##############################################################################
+# cmake/nuttx_add_rust.cmake
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  The ASF licenses this
+# file to you under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License.  You may obtain a copy of
+# the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations under
+# the License.
+#
+# ##############################################################################
+
+include(nuttx_parse_function_args)
+
+# ~~~
+# Convert architecture type to Rust NuttX target
+#
+# Supported architectures:
+#   - armv7a: armv7a-nuttx-eabi, armv7a-nuttx-eabihf
+#   - thumbv6m: thumbv6m-nuttx-eabi
+#   - thumbv7a: thumbv7a-nuttx-eabi, thumbv7a-nuttx-eabihf
+#   - thumbv7m: thumbv7m-nuttx-eabi
+#   - thumbv7em: thumbv7em-nuttx-eabihf
+#   - thumbv8m.main: thumbv8m.main-nuttx-eabi, thumbv8m.main-nuttx-eabihf
+#   - thumbv8m.base: thumbv8m.base-nuttx-eabi, thumbv8m.base-nuttx-eabihf
+#   - riscv32: riscv32imc/imac/imafc-unknown-nuttx-elf
+#   - riscv64: riscv64imac/imafdc-unknown-nuttx-elf
+#
+# Inputs:
+#   ARCHTYPE - Architecture type (e.g. thumbv7m, riscv32)
+#   ABITYPE  - ABI type (e.g. eabi, eabihf)
+#   CPUTYPE  - CPU type (e.g. cortex-m4, sifive-e20)
+#
+# Output:
+#   OUTPUT   - Rust target triple (e.g. riscv32imac-unknown-nuttx-elf,
+#             thumbv7m-nuttx-eabi, thumbv7em-nuttx-eabihf)
+# ~~~
+
+function(nuttx_rust_target_triple ARCHTYPE ABITYPE CPUTYPE OUTPUT)
+  if(ARCHTYPE MATCHES "thumb")
+    if(ARCHTYPE MATCHES "thumbv8m")
+      # Extract just the base architecture type (thumbv8m.main or thumbv8m.base)
+      if(ARCHTYPE MATCHES "thumbv8m.main")
+        set(ARCH_BASE "thumbv8m.main")
+      elseif(ARCHTYPE MATCHES "thumbv8m.base")
+        set(ARCH_BASE "thumbv8m.base")
+      else()
+        # Otherwise determine if we should use thumbv8m.main or thumbv8m.base
+        # based on CPU type
+        if(CPUTYPE MATCHES "cortex-m23")
+          set(ARCH_BASE "thumbv8m.base")
+        else()
+          set(ARCH_BASE "thumbv8m.main")
+        endif()
+      endif()
+      set(TARGET_TRIPLE "${ARCH_BASE}-nuttx-${ABITYPE}")
+    else()
+      set(TARGET_TRIPLE "${ARCHTYPE}-nuttx-${ABITYPE}")
+    endif()
+  elseif(ARCHTYPE STREQUAL "riscv32")
+    if(CPUTYPE STREQUAL "sifive-e20")
+      set(TARGET_TRIPLE "riscv32imc-unknown-nuttx-elf")
+    elseif(CPUTYPE STREQUAL "sifive-e31")
+      set(TARGET_TRIPLE "riscv32imac-unknown-nuttx-elf")
+    elseif(CPUTYPE STREQUAL "sifive-e76")
+      set(TARGET_TRIPLE "riscv32imafc-unknown-nuttx-elf")
+    else()
+      set(TARGET_TRIPLE "riscv32imc-unknown-nuttx-elf")
+    endif()
+  elseif(ARCHTYPE STREQUAL "riscv64")
+    if(CPUTYPE STREQUAL "sifive-s51")
+      set(TARGET_TRIPLE "riscv64imac-unknown-nuttx-elf")
+    elseif(CPUTYPE STREQUAL "sifive-u54")
+      set(TARGET_TRIPLE "riscv64imafdc-unknown-nuttx-elf")
+    else()
+      set(TARGET_TRIPLE "riscv64imac-unknown-nuttx-elf")
+    endif()
+  endif()
+  set(${OUTPUT}
+      ${TARGET_TRIPLE}
+      PARENT_SCOPE)
+endfunction()
+
+# ~~~
+# nuttx_add_rust
+#
+# Description:
+#   Build a Rust crate and add it as a static library to the NuttX build system
+#
+# Example:
+#  nuttx_add_rust(
+#    CRATE_NAME
+#    hello
+#    CRATE_PATH
+#    ${CMAKE_CURRENT_SOURCE_DIR}/hello
+#  )
+# ~~~
+
+function(nuttx_add_rust)
+
+  # parse arguments into variables
+  nuttx_parse_function_args(
+    FUNC
+    nuttx_add_rust
+    ONE_VALUE
+    CRATE_NAME
+    CRATE_PATH
+    REQUIRED
+    CRATE_NAME
+    CRATE_PATH
+    ARGN
+    ${ARGN})
+
+  # Determine build profile based on CONFIG_DEBUG_FULLOPT
+  if(CONFIG_DEBUG_FULLOPT)
+    set(RUST_PROFILE "release")
+  else()
+    set(RUST_PROFILE "debug")
+  endif()
+
+  # Get the Rust target triple
+  nuttx_rust_target_triple(${LLVM_ARCHTYPE} ${LLVM_ABITYPE} ${LLVM_CPUTYPE}
+                           RUST_TARGET)
+
+  # Set up build directory in current binary dir
+  set(RUST_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/${CRATE_NAME})
+  set(RUST_LIB_PATH
+      ${RUST_BUILD_DIR}/${RUST_TARGET}/${RUST_PROFILE}/lib${CRATE_NAME}.a)
+
+  # Create build directory
+  file(MAKE_DIRECTORY ${RUST_BUILD_DIR})
+
+  # Add a custom command to build the Rust crate
+  add_custom_command(
+    OUTPUT ${RUST_LIB_PATH}
+    COMMAND
+      cargo build --${RUST_PROFILE} -Zbuild-std=std,panic_abort --manifest-path
+      ${CRATE_PATH}/Cargo.toml --target ${RUST_TARGET} --target-dir
+      ${RUST_BUILD_DIR}
+    COMMENT "Building Rust crate ${CRATE_NAME}"
+    VERBATIM)
+
+  # Add a custom target that depends on the built library
+  add_custom_target(${CRATE_NAME}_build ALL DEPENDS ${RUST_LIB_PATH})
+
+  # Add imported library target
+  add_library(${CRATE_NAME} STATIC IMPORTED GLOBAL)
+  set_target_properties(${CRATE_NAME} PROPERTIES IMPORTED_LOCATION
+                                                 ${RUST_LIB_PATH})
+
+  # Add the Rust library to NuttX build
+  nuttx_add_extra_library(${RUST_LIB_PATH})
+
+  # Ensure the Rust library is built before linking
+  add_dependencies(${CRATE_NAME} ${CRATE_NAME}_build)
+
+endfunction()

examples/rust/.gitignore

@@ -0,0 +1 @@
+/Kconfig

examples/rust/CMakeLists.txt

@@ -0,0 +1,24 @@
+# ##############################################################################
+# apps/examples/rust/CMakeLists.txt
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  The ASF licenses this
+# file to you under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License.  You may obtain a copy of
+# the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations under
+# the License.
+#
+# ##############################################################################
+
+nuttx_add_subdirectory()
+nuttx_generate_kconfig(MENUDESC "Rust Examples")

examples/rust/Make.defs

@@ -0,0 +1,23 @@
+############################################################################
+# apps/examples/rust/Make.defs
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+############################################################################
+
+include $(wildcard $(APPDIR)/examples/rust/*/Make.defs)

examples/rust/Makefile

@@ -0,0 +1,25 @@
+############################################################################
+# apps/examples/rust/Makefile
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+############################################################################
+
+MENUDESC = "Rust Examples"
+
+include $(APPDIR)/Directory.mk

examples/rust/hello/.gitignore

@@ -0,0 +1 @@
+target

examples/rust/hello/CMakeLists.txt

@@ -0,0 +1,31 @@
+# ##############################################################################
+# apps/examples/rust/hello/CMakeLists.txt
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  The ASF licenses this
+# file to you under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License.  You may obtain a copy of
+# the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations under
+# the License.
+#
+# ##############################################################################
+
+if(CONFIG_EXAMPLES_HELLO_RUST_CARGO)
+
+  # Build the Rust crate using nuttx_add_rust
+  nuttx_add_rust(CRATE_NAME hello CRATE_PATH ${CMAKE_CURRENT_SOURCE_DIR})
+
+  nuttx_add_application(
+    NAME ${CONFIG_EXAMPLES_HELLO_RUST_CARGO_PROGNAME} STACKSIZE
+    ${CONFIG_EXAMPLES_HELLO_STACKSIZE} PRIORITY
+    ${CONFIG_EXAMPLES_HELLO_PRIORITY})
+
+endif() # CONFIG_EXAMPLES_HELLO_RUST_CARGO

examples/rust/hello/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "hello"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["staticlib"]
+
+[profile.dev]
+panic = "abort"
+
+# Special hanlding for the panic! macro, can be removed once
+# the libstd port for NuttX is complete.
+[profile.release]
+panic = "abort"
+lto = true
+
+[dependencies]
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
+tokio = { version = "1", features = ["rt"] }

examples/rust/hello/Kconfig

@@ -0,0 +1,29 @@
+#
+# For a description of the syntax of this configuration file,
+# see the file kconfig-language.txt in the NuttX tools repository.
+#
+
+config EXAMPLES_HELLO_RUST_CARGO
+	tristate "\"Hello, Rust!\" example with Cargo"
+	default n
+	---help---
+		Enable the \"Hello, Rust!\" example using Cargo to build.
+
+if EXAMPLES_HELLO_RUST_CARGO
+
+config EXAMPLES_HELLO_RUST_CARGO_PROGNAME
+	string "Program name"
+	default "hello_rust_cargo"
+	---help---
+		This is the name of the program that will be used when the
+		program is installed.
+
+config EXAMPLES_HELLO_RUST_CARGO_PRIORITY
+	int "Hello Rust task priority"
+	default 100
+
+config EXAMPLES_HELLO_RUST_CARGO_STACKSIZE
+	int "Hello Rust stack size"
+	default DEFAULT_TASK_STACKSIZE
+
+endif

examples/rust/hello/Make.defs

@@ -0,0 +1,26 @@
+############################################################################
+# apps/examples/hello_rust_cargo/Make.defs
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+############################################################################
+
+include $(APPDIR)/tools/Rust.mk
+
+ifneq ($(CONFIG_EXAMPLES_HELLO_RUST_CARGO),)
+CONFIGURED_APPS += $(APPDIR)/examples/rust/hello
+EXTRA_LIBS += $(call RUST_GET_BINDIR,hello,$(APPDIR)/examples/rust)
+endif