# Application Architecture

## Overview

This guide explains the architecture of NXP Matter applications with the CMake build
system for FreeRTOS platforms, using an in-tree example to illustrate core
concepts. It also provides insights into customization options for developers
working on out-of-tree applications.

> **Important**: This guide covers Matter development for FreeRTOS-based platforms using **MCUX SDK** only.
>
> **For Zephyr-based Matter development**, refer to the [Matter Zephyr documentation](https://github.com/NXP/matter/blob/release/v1.6.0/docs/platforms/nxp/nxp_zephyr_guide.md).

> **Note**: All file paths referenced in this document are relative to the Matter repository root, which is typically installed under `mcuxsdk/middleware/matter/` in your NXP MCUX SDK installation.

## Application build system architecture

NXP Matter applications rely on two main build systems: GN and CMake. The
architecture is designed to streamline the integration and the customization of
Matter into different applications.

- **GN build system** : GN is used to compile the Matter stack and platform libraries, and generates the CHIP libraries that are linked to the application.
- **CMake build system** : CMake is used to configure and compile the
  application and the NXP SDK, and link the libraries to generate the final
  executable. The CMake build system uses Kconfig to configure system options.
  All related information can be found in the
  [NXP MCUX Build And Configuration System](https://mcuxpresso.nxp.com/mcuxsdk/latest/html/develop/build_system/index.html).

### Matter stack and NXP platform port libraries

Below is a detailed description of CMake/Kconfig files used to generate the
Matter stack & NXP port libraries.

- `config/nxp/chip-cmake-freertos/CMakeLists.txt` : CMake wrapper, which maps the CMake configuration on GN configuration and generate the `CHIP`
  libraries for NXP FreeRTOS platforms. With this CMake file, Matter can be
  integrated as an
  [external module of the NXP MCUX SDK](https://mcuxpresso.nxp.com/mcuxsdk/latest/html/develop/sdk/integration.html#integrate-other-cmake-build-system).
- `config/nxp/cmake/common.cmake` : The CMake file, common to Zephyr and FreeRTOS
  platforms, is used to configure GN arguments based on CMake configuration.

- `config/nxp/chip-cmake-freertos/Kconfig` : Kconfig file, which defines Matter
  Kconfig symbols common to NXP FreeRTOS platforms.
- `config/nxp/chip-cmake-freertos/Kconfig.defaults` : The role of this Kconfig
  is to override the default values of Kconfig symbols. These values are tuned for
  Matter requirements.
- `config/nxp/cmake/Kconfig.matter.common` : The Kconfig file is used to define
  Matter Kconfig symbols common across Matter platforms.
- `config/nxp/cmake/Kconfig.matter.nxp` : The Kconfig file is used to define Matter
  Kconfig symbols common to NXP platforms.

### Application

To describe the CMake architecture for the NXP applications, the
`thermostat` example is provided as a reference application.

- `examples/thermostat/nxp/CMakeLists.txt` : Application CMake list file
  common to NXP FreeRTOS platforms. This CMakeLists.txt is used as the
  entry-point to build the application.
- `examples/thermostat/nxp/Kconfig` : Application Kconfig file used as
  the entry-point Kconfig. This file can be used to define application-specific Kconfig symbols.
- `examples/thermostat/nxp/prj.conf` : Application `prj.conf` used to
  set or unset Kconfig symbols specific to the application. This file is
  automatically loaded by the application's CMakeLists.txt.
- `examples/platform/nxp/common/app_common.cmake` : Application CMake file for
  building files that are common across applications. This file can be
  included from the application CMakeLists.txt, this adds common
  application files to the build based on the Kconfig enabled.
- `examples/platform/nxp/common/Kconfig` : Application Kconfig file used to
  define Kconfig symbols common across applications.
- `examples/platform/nxp/config/prj_<flavour>.conf` : A custom `prj.conf` file
  used to set or unset Kconfig symbols for a specific application
  configuration. The name of the `prj_<flavour>.conf` can be provided in the
  build command line with the `-DCONF_FILE_NAME` variable, to add the
  configuration file to the build. To view the full list of supported
  `prj_<flavour>.conf` and how to use them, you can refer to the
  [List the project information](./../getting_started/getting_started.md#list-the-project-information)
  section.

#### Overview on application CMakeLists.txt

Below are the key points on how the NXP application CMakeLists.txt is designed.
This architecture is common to both in-tree and out-of-tree
applications.

- `CHIP` libraries are loaded as an external module of the NXP MCUX SDK. This
  is done by appending to the `EXTRA_MCUX_MODULES` list the path to the
  `config/nxp/chip-cmake-freertos/CMakeLists.txt`. This enables the build
  system to automatically load and link the module library to the application.
- NXP MCUX SDK is loaded by the application using the `find_package` CMake
  function, which enables CMake to automatically find the location where the
  SDK was installed. More information can be found in
  [McuxSDK CMake Package](https://mcuxpresso.nxp.com/mcuxsdk/latest/html/develop/sdk/integration.html#mcuxsdk-cmake-package).
- The application includes `examples/platform/nxp/common/app_common.cmake` to
  add common application files.
- The application includes
  `third_party/nxp/nxp_matter_support/examples/platform/<platform_family>/nxp_sdk_reconfig.cmake`.
  This CMake file is used to reconfigure the SDK to adapt to Matter
  requirements. For it to be correctly processed by CMake, this file
  must be included before creating the CMake `project()`.
- When creating the CMake `project()`, the build system will automatically
  create the application target `app` and link Matter libraries and the SDK
  libraries (`McuxSDK`) to it.
- Application source files and include directories are directly added to
  the target `app` with `target_sources` and `target_include_directories`.