pw_build_mcuxpresso

Pigweed AI summary: The "pw_build_mcuxpresso" module provides helper utilities for building a target based on an NXP MCUXpresso SDK. The GN build files for the MCUXpresso SDK are located in "third_party/mcuxpresso". The module allows users to include or exclude components from the SDK and provides options for introducing dependencies. The "mcuxpresso_builder" utility is used to generate rules for the Bazel build system. To use the MCUXpresso SDK with the Bazel build system,

The pw_build_mcuxpresso module provides helper utilities for building a target based on an NXP MCUXpresso SDK.

The GN build files live in third_party/mcuxpresso but are documented here. The rationale for keeping the build files in third_party is that code depending on an MCUXpresso SDK can clearly see that their dependency is on third party, not pigweed code.

Using an MCUXpresso SDK

Pigweed AI summary: An MCUXpresso SDK is made up of various components, each with its own sources, headers, preprocessor defines, and dependencies. These components are described in an XML "manifest" file included in the SDK package. To use the SDK in a Pigweed project, the necessary components must be combined into a library that can be relied upon. This library will include all the sources, headers, and preprocessor defines for the components and their dependencies. Optional components will include their required dependencies, and if

An MCUXpresso SDK consists of a number of components, each of which has a set of sources, headers, preprocessor defines, and dependencies on other components. These are all described in an XML “manifest” file included in the SDK package.

To use the SDK within a Pigweed project, the set of components you need must be combined into a library that you can depend on. This library will include all of the sources and headers, along with necessary preprocessor defines, for those components and their dependencies.

Optional components

Pigweed AI summary: The paragraph explains that when including optional components, all of their required dependencies will also be included. However, if the optional dependencies of the components are not satisfied by the set of components included, the library generation will fail with an error.

Including components will include all of their required dependencies. Where the components you include have optional dependencies, they must be satisfied by the set of components you include otherwise the library generation will fail with an error.

Excluding components

Pigweed AI summary: Components can be excluded from the generated source set to suppress errors about optional dependencies that are not needed in the project or to prevent unwanted component dependencies from being introduced.

Components can be excluded from the generated source set, for example to suppress errors about optional dependencies your project does not need, or to prevent an unwanted component dependency from being introduced into your project.

mcuxpresso_builder

Pigweed AI summary: The "mcuxpresso_builder" is a utility that is installed in the environment and is used by the GN build scripts in "third_party/mcuxpresso" or directly by the user to generate rules for the Bazel build. The usage of this utility is documented for each build system in the relevant section.

mcuxpresso_builder is a utility installed into the environment that is used by the GN build scripts in third_party/mcuxpresso, or directly by you to generate rules for the Bazel build.

Usage is documented for each build system in the relevant section.

The GN build

Pigweed AI summary: The GN build system allows you to use an MCUxpresso SDK within a Pigweed project. To do this, you need to create one or more "pw_source_set" targets that you can depend on in your executable targets. These source sets are defined using the "pw_mcuxpresso_sdk" template, where you provide the path to the manifest XML and the names of the components you want to include. You can also exclude components by providing a list to the "exclude" argument. The generated

Using an MCUxpresso SDK within a Pigweed project that uses the GN Build system involves the creation of one or more pw_source_set targets you can depend on in your executable targets.

These source sets sets are defined using the pw_mcuxpresso_sdk template. Provide the path to the manifest XML, along with the names of the components you wish to include.

import("$dir_pw_third_party/mcuxpresso/mcuxpresso.gni")

pw_mcuxpresso_sdk("sample_project_sdk") {
  manifest = "$dir_pw_third_party/mcuxpresso/evkmimxrt595/EVK-MIMXRT595_manifest_v3_8.xml"
  include = [
    "component.serial_manager_uart.MIMXRT595S",
    "project_template.evkmimxrt595.MIMXRT595S",
    "utility.debug_console.MIMXRT595S",
  ]
}

pw_executable("hello_world") {
  sources = [ "hello_world.cc" ]
  deps = [ ":sample_project_sdk" ]
}

To exclude components, provide the list to exclude as an argument to the template. For example to replace the FreeRTOS kernel bundled with the MCUXpresso SDK with the Pigweed third-party target:

pw_mcuxpresso_sdk("freertos_project_sdk") {
  // manifest and includes ommitted for clarity
  exclude = [ "middleware.freertos-kernel.MIMXRT595S" ]
  public_deps = [ "$dir_pw_third_party/freertos" ]
}

Introducing dependencies

Pigweed AI summary: The paragraph discusses how dependencies can be added to a generated source set by passing arguments to the template. It also mentions that additional arguments can be passed to enhance the source set. The example given shows how the "project_template" component can be replaced with a customized source set. To resolve circular dependencies, two configs are generated with preprocessor defines and include paths. The provided code block demonstrates the usage of these concepts in a project.

As seen above, the generated source set can have dependencies added by passing the public_deps (or deps) arguments to the template.

You can also pass the allow_circular_includes_from, configs, and public_configs arguments to augment the generated source set.

For example it is very common to replace the project_template component with a source set of your own that provides modified copies of the files from the SDK.

To resolve circular dependencies, in addition to the generated source set, two configs named with the __defines and __includes suffixes on the template name are generated, to provide the preprocessor defines and include paths that the source set uses.

pw_mcuxpresso_sdk("my_project_sdk") {
  manifest = "$dir_pw_third_party/mcuxpresso/evkmimxrt595/EVK-MIMXRT595_manifest_v3_8.xml"
  include = [
    "component.serial_manager_uart.MIMXRT595S",
    "utility.debug_console.MIMXRT595S",
  ]
  public_deps = [ ":my_project_config" ]
  allow_circular_includes_from = [ ":my_project_config" ]
}

pw_source_set("my_project_config") {
  sources = [ "board.c", "clock_config.c", "pin_mux.c" ]
  public = [ "board.h", "clock_config.h", "pin_mux.h "]
  public_configs = [
    ":my_project_sdk__defines",
    ":my_project_sdk__includes"
  ]
}

mcuxpresso_builder

Pigweed AI summary: The "mcuxpresso_builder" utility is used for the GN build and is typically invoked by the "pw_mcuxpresso_sdk" template. It is only necessary to interact with "mcuxpresso_builder" directly if you are customizing something. The "gn" subcommand generates a GN scope that describes the components included and excluded in the build. The "--prefix" option specifies the location of the SDK files in GN.

For the GN build, this utility is invoked by the pw_mcuxpresso_sdk template. You should only need to interact with mcuxpresso_builder directly if you are doing something custom.

The gn subcommand outputs a GN scope describing the result of expanding the set of included and excluded components.

The --prefix option specifies the GN location of the SDK files.

mcuxpresso_builder gn /path/to/manifest.xml \
    --include project_template.evkmimxrt595.MIMXRT595S \
    --include utility.debug_console.MIMXRT595S \
    --include component.serial_manager_uart.MIMXRT595S \
    --exclude middleware.freertos-kernel.MIMXRT595S \
    --prefix //path/to/sdk

The Bazel build

Pigweed AI summary: To use an MCUxpresso SDK within a Pigweed project that uses the Bazel build system, you need to use the "mcuxpresso_builder" tool directly and place its output in "BUILD" or "BUILD.bazel" files yourself. You need to provide the path to the manifest XML, the name of the "cc_library" to create, and the names of the components you want to include or exclude. After generating the output, you should place it in a "BUILD" file

To use an MCUxpresso SDK within a Pigweed project that uses tha Bazel build system, you must use the mcuxpresso_builder tool directly and place its output in BUILD or BUILD.bazel files yourself.

Provide the path to the manifest XML, the --name of the cc_library to create, along with the names of the components you wish to --include or --exclude.

mcuxpresso_builder bazel /path/to/manifest.xml \
    --name example_sdk \
    --include project_template.evkmimxrt595.MIMXRT595S \
    --include utility.debug_console.MIMXRT595S \
    --include component.serial_manager_uart.MIMXRT595S \
    --exclude middleware.freertos-kernel.MIMXRT595S

Place the resulting output in a BUILD file, and then modify your WORKSPACE to associate this build file with the path to the MCUxpresso SDK checkout.

new_local_repository(
    name = "mcuxpresso_sdk",
    build_file = "//third_party/mcuxpresso_sdk/BUILD",
    path = "third_party/evkmimxrt595/sdk",
)

To add other dependencies, compiler definitions, etc. it is recommended that you do so by creating a new target, and add a dependency to it, rather than modifying the generated targets.