1.. _module-pw_build_mcuxpresso: 2 3------------------- 4pw_build_mcuxpresso 5------------------- 6 7The ``pw_build_mcuxpresso`` module provides helper utilizies for building a 8target based on an NXP MCUXpresso SDK. 9 10The GN build files live in ``third_party/mcuxpresso`` but are documented here. 11The rationale for keeping the build files in ``third_party`` is that code 12depending on an MCUXpresso SDK can clearly see that their dependency is on 13third party, not pigweed code. 14 15Using an MCUXpresso SDK 16======================= 17An MCUXpresso SDK consists of a number of components, each of which has a set 18of sources, headers, pre-processor defines, and dependencies on other 19components. These are all described in an XML "manifest" file included in the 20SDK package. 21 22To use the SDK within a Pigweed project, the set of components you need must be 23combined into a ``pw_source_set`` that you can depend on. This source set will 24include all of the sources and headers, along with necessary pre-processor 25defines, for those components and their dependencies. 26 27The source set is defined using the ``pw_mcuxpresso_sdk`` template, providing 28the path to the ``manifest`` XML, along with the names of the components you 29wish to ``include``. 30 31.. code-block:: text 32 33 import("$dir_pw_third_party/mcuxpresso/mcuxpresso.gni") 34 35 pw_mcuxpresso_sdk("sample_project_sdk") { 36 manifest = "$dir_pw_third_party/mcuxpresso/evkmimxrt595/EVK-MIMXRT595_manifest_v3_8.xml" 37 include = [ 38 "component.serial_manager_uart.MIMXRT595S", 39 "project_template.evkmimxrt595.MIMXRT595S", 40 "utility.debug_console.MIMXRT595S", 41 ] 42 } 43 44 pw_executable("hello_world") { 45 sources = [ "hello_world.cc" ] 46 deps = [ ":sample_project_sdk" ] 47 } 48 49Where the components you include have optional dependencies, they must be 50satisfied by the set of components you include otherwise the GN generation will 51fail with an error. 52 53Excluding components 54-------------------- 55Components can be excluded from the generated source set, for example to 56suppress errors about optional dependencies your project does not need, or to 57prevent an unwanted component dependency from being introduced into your 58project. 59 60This is accomplished by providing the list of components to ``exclude`` as an 61argument to the template. 62 63For example to replace the FreeRTOS kernel bundled with the MCUXpresso SDK with 64the Pigweed third-party target: 65 66.. code-block:: text 67 68 pw_mcuxpresso_sdk("freertos_project_sdk") { 69 // manifest and includes ommitted for clarity 70 exclude = [ "middleware.freertos-kernel.MIMXRT595S" ] 71 public_deps = [ "$dir_pw_third_party/freertos" ] 72 } 73 74Introducing dependencies 75------------------------ 76As seen above, the generated source set can have dependencies added by passing 77the ``public_deps`` (or ``deps``) arguments to the template. 78 79You can also pass the ``allow_circular_includes_from``, ``configs``, and 80``public_configs`` arguments to augment the generated source set. 81 82For example it is very common to replace the ``project_template`` component with 83a source set of your own that provides modified copies of the files from the 84SDK. 85 86To resolve circular dependencies, in addition to the generated source set, two 87configs named with the ``__defines`` and ``__includes`` suffixes on the template 88name are generated, to provide the pre-processor defines and include paths that 89the source set uses. 90 91.. code-block:: text 92 93 pw_mcuxpresso_sdk("my_project_sdk") { 94 manifest = "$dir_pw_third_party/mcuxpresso/evkmimxrt595/EVK-MIMXRT595_manifest_v3_8.xml" 95 include = [ 96 "component.serial_manager_uart.MIMXRT595S", 97 "utility.debug_console.MIMXRT595S", 98 ] 99 public_deps = [ ":my_project_config" ] 100 allow_circular_includes_from = [ ":my_project_config" ] 101 } 102 103 pw_source_set("my_project_config") { 104 sources = [ "board.c", "clock_config.c", "pin_mux.c" ] 105 public = [ "board.h", "clock_config.h", "pin_mux.h "] 106 public_configs = [ 107 ":my_project_sdk__defines", 108 ":my_project_sdk__includes" 109 ] 110 } 111 112mcuxpresso_builder 113================== 114``mcuxpresso_builder`` is a utility that contains the backend scripts used by 115the GN build scripts in ``third_party/mcuxpresso``. You should only need to 116interact with ``mcuxpresso_builder`` directly if you are doing something custom. 117 118project 119------- 120This command outputs a GN scope describing the result of expanding the set of 121included and excluded components. 122 123The ``--prefix`` option specifies the GN location of the SDK files. 124 125.. code-block:: bash 126 127 mcuxpresso_builder project /path/to/manifest.xml \ 128 --include project_template.evkmimxrt595.MIMXRT595S \ 129 --include utility.debug_console.MIMXRT595S \ 130 --include component.serial_manager_uart.MIMXRT595S \ 131 --exclude middleware.freertos-kernel.MIMXRT595S \ 132 --prefix //path/to/sdk 133