1.. _module-pw_build_mcuxpresso: 2 3=================== 4pw_build_mcuxpresso 5=================== 6.. pigweed-module:: 7 :name: pw_build_mcuxpresso 8 9The ``pw_build_mcuxpresso`` module provides helper utilities for building a 10target based on an NXP MCUXpresso SDK. 11 12The GN build files live in ``third_party/mcuxpresso`` but are documented here. 13The rationale for keeping the build files in ``third_party`` is that code 14depending on an MCUXpresso SDK can clearly see that their dependency is on 15third party, not pigweed code. 16 17----------------------- 18Using an MCUXpresso SDK 19----------------------- 20An MCUXpresso SDK consists of a number of components, each of which has a set 21of sources, headers, preprocessor defines, and dependencies on other 22components. These are all described in an XML "manifest" file included in the 23SDK package. 24 25To use the SDK within a Pigweed project, the set of components you need must be 26combined into a library that you can depend on. This library will include all of 27the sources and headers, along with necessary preprocessor defines, for those 28components and their dependencies. 29 30Optional components 31=================== 32Including components will include all of their required dependencies. Where the 33components you include have optional dependencies, they must be satisfied by the 34set of components you include otherwise the library generation will fail with an 35error. 36 37Excluding components 38==================== 39Components can be excluded from the generated source set, for example to 40suppress errors about optional dependencies your project does not need, or to 41prevent an unwanted component dependency from being introduced into your 42project. 43 44mcuxpresso_builder 45================== 46``mcuxpresso_builder`` is a utility installed into the environment that is used 47by the GN build scripts in ``third_party/mcuxpresso``, or directly by you to 48generate rules for the Bazel build. 49 50Usage is documented for each build system in the relevant section. 51 52------------ 53The GN build 54------------ 55Using an MCUxpresso SDK within a Pigweed project that uses the GN Build system 56involves the creation of one or more ``pw_source_set`` targets you can depend on 57in your executable targets. 58 59These source sets sets are defined using the ``pw_mcuxpresso_sdk`` template. 60Provide the path to the ``manifest`` XML, along with the names of the components 61you wish to ``include``. 62 63For boards with multiple cores, pass the specific core to filter components for 64in ``device_core``. 65 66.. code-block:: text 67 68 import("$dir_pw_third_party/mcuxpresso/mcuxpresso.gni") 69 70 pw_mcuxpresso_sdk("sample_project_sdk") { 71 manifest = "$dir_pw_third_party/mcuxpresso/evkmimxrt595/EVK-MIMXRT595_manifest_v3_13.xml" 72 include = [ 73 "component.serial_manager_uart.MIMXRT595S", 74 "project_template.evkmimxrt595.MIMXRT595S", 75 "utility.debug_console.MIMXRT595S", 76 ] 77 device_core = "cm33_MIMXRT595S" 78 } 79 80 pw_executable("hello_world") { 81 sources = [ "hello_world.cc" ] 82 deps = [ ":sample_project_sdk" ] 83 } 84 85To exclude components, provide the list to ``exclude`` as an argument to the 86template. For example to replace the FreeRTOS kernel bundled with the MCUXpresso 87SDK with the Pigweed third-party target: 88 89.. code-block:: text 90 91 pw_mcuxpresso_sdk("freertos_project_sdk") { 92 // manifest and includes ommitted for clarity 93 exclude = [ "middleware.freertos-kernel.MIMXRT595S" ] 94 public_deps = [ "$dir_pw_third_party/freertos" ] 95 } 96 97Introducing dependencies 98======================== 99As seen above, the generated source set can have dependencies added by passing 100the ``public_deps`` (or ``deps``) arguments to the template. 101 102You can also pass the ``allow_circular_includes_from``, ``configs``, and 103``public_configs`` arguments to augment the generated source set. 104 105For example it is very common to replace the ``project_template`` component with 106a source set of your own that provides modified copies of the files from the 107SDK. 108 109To resolve circular dependencies, in addition to the generated source set, two 110configs named with the ``__defines`` and ``__includes`` suffixes on the template 111name are generated, to provide the preprocessor defines and include paths that 112the source set uses. 113 114.. code-block:: text 115 116 pw_mcuxpresso_sdk("my_project_sdk") { 117 manifest = "$dir_pw_third_party/mcuxpresso/evkmimxrt595/EVK-MIMXRT595_manifest_v3_13.xml" 118 include = [ 119 "component.serial_manager_uart.MIMXRT595S", 120 "utility.debug_console.MIMXRT595S", 121 ] 122 public_deps = [ ":my_project_config" ] 123 allow_circular_includes_from = [ ":my_project_config" ] 124 } 125 126 pw_source_set("my_project_config") { 127 sources = [ "board.c", "clock_config.c", "pin_mux.c" ] 128 public = [ "board.h", "clock_config.h", "pin_mux.h "] 129 public_configs = [ 130 ":my_project_sdk__defines", 131 ":my_project_sdk__includes" 132 ] 133 } 134 135mcuxpresso_builder 136================== 137For the GN build, this utility is invoked by the ``pw_mcuxpresso_sdk`` template. 138You should only need to interact with ``mcuxpresso_builder`` directly if you are 139doing something custom. 140 141The ``gn`` subcommand outputs a GN scope describing the result of expanding the 142set of included and excluded components. 143 144The ``--prefix`` option specifies the GN location of the SDK files. 145 146.. code-block:: bash 147 148 mcuxpresso_builder gn /path/to/manifest.xml \ 149 --include project_template.evkmimxrt595.MIMXRT595S \ 150 --include utility.debug_console.MIMXRT595S \ 151 --include component.serial_manager_uart.MIMXRT595S \ 152 --exclude middleware.freertos-kernel.MIMXRT595S \ 153 --device-core cm33_MIMXRT595S \ 154 --prefix //path/to/sdk 155 156--------------- 157The Bazel build 158--------------- 159To use an MCUxpresso SDK within a Pigweed project that uses tha Bazel build 160system, you must use the ``mcuxpresso_builder`` tool directly and place its 161output in ``BUILD`` or ``BUILD.bazel`` files yourself. 162 163Provide the path to the manifest XML, the ``--name`` of the ``cc_library`` to 164create, along with the names of the components you wish to ``--include`` or 165``--exclude``. 166 167.. code-block:: bash 168 169 mcuxpresso_builder bazel /path/to/manifest.xml \ 170 --name example_sdk \ 171 --include project_template.evkmimxrt595.MIMXRT595S \ 172 --include utility.debug_console.MIMXRT595S \ 173 --include component.serial_manager_uart.MIMXRT595S \ 174 --exclude middleware.freertos-kernel.MIMXRT595S \ 175 --device-core cm33_MIMXRT595S 176 177 178Place the resulting output in a ``BUILD`` file, and then modify your 179``WORKSPACE`` to associate this build file with the path to the MCUxpresso SDK 180checkout. 181 182.. code-block:: python 183 184 new_local_repository( 185 name = "mcuxpresso_sdk", 186 build_file = "//third_party/mcuxpresso_sdk/BUILD", 187 path = "third_party/evkmimxrt595/sdk", 188 ) 189 190To add other dependencies, compiler definitions, etc. it is recommended that 191you do so by creating a new target, and add a dependency to it, rather than 192modifying the generated targets. 193