133 lines
4.7 KiB
ReStructuredText
133 lines
4.7 KiB
ReStructuredText
.. _module-pw_build_mcuxpresso:
|
|
|
|
-------------------
|
|
pw_build_mcuxpresso
|
|
-------------------
|
|
|
|
The ``pw_build_mcuxpresso`` module provides helper utilizies 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
|
|
=======================
|
|
An MCUXpresso SDK consists of a number of components, each of which has a set
|
|
of sources, headers, pre-processor 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 ``pw_source_set`` that you can depend on. This source set will
|
|
include all of the sources and headers, along with necessary pre-processor
|
|
defines, for those components and their dependencies.
|
|
|
|
The source set is defined using the ``pw_mcuxpresso_sdk`` template, providing
|
|
the path to the ``manifest`` XML, along with the names of the components you
|
|
wish to ``include``.
|
|
|
|
.. code-block:: text
|
|
|
|
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" ]
|
|
}
|
|
|
|
Where the components you include have optional dependencies, they must be
|
|
satisfied by the set of components you include otherwise the GN generation will
|
|
fail with an error.
|
|
|
|
Excluding components
|
|
--------------------
|
|
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.
|
|
|
|
This is accomplished by providing the list of components 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:
|
|
|
|
.. code-block:: text
|
|
|
|
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
|
|
------------------------
|
|
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 pre-processor defines and include paths that
|
|
the source set uses.
|
|
|
|
.. code-block:: text
|
|
|
|
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
|
|
==================
|
|
``mcuxpresso_builder`` is a utility that contains the backend scripts used by
|
|
the GN build scripts in ``third_party/mcuxpresso``. You should only need to
|
|
interact with ``mcuxpresso_builder`` directly if you are doing something custom.
|
|
|
|
project
|
|
-------
|
|
This command 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.
|
|
|
|
.. code-block:: bash
|
|
|
|
mcuxpresso_builder project /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
|