API Reference

This page contains the complete API reference for all modules in the ntxbuild package.

Build Module

Use the Build Module to manage the nuttxspace: create a configuration, build, clean and use general make commands.

Build system module for NuttX.

class ntxbuild.build.BaseBuilder(nuttxspace_path: Path | None = None, nuttx_dir: str = 'nuttx', apps_dir: str = 'nuttx-apps')

Bases: ABC

abstract build(parallel: int | None = None) → CompletedProcess

Build the NuttX project.

Parameters:

parallel – Number of parallel jobs to use for building. If None, uses default parallelism. Defaults to None.

Returns:

The result of the build command.

Check the returncode attribute to determine success (0) or failure.

Return type:

subprocess.CompletedProcess

property build_tool: BuildTool

Get the build tool used by the builder.

abstract clean() → CompletedProcess

Clean build artifacts.

Removes object files and other build artifacts, but preserves configuration files.

Returns:

The result of the clean command.

Check the returncode attribute to determine success (0) or failure.

Return type:

subprocess.CompletedProcess

abstract distclean() → CompletedProcess | None

Perform a distclean on the NuttX project.

This removes all generated files including configuration files. Note: Not all build tools support distclean.

Returns:

The result of the distclean command,

or None if not supported. May raise RuntimeError if not available.

Return type:

subprocess.CompletedProcess or None

abstract initialize(board: str, defconfig: str, extra_args: list[str] = []) → int

Run NuttX setup commands.

Configures NuttX for the specified board and defconfig.

Parameters:

• board – The board name (e.g., “stm32f4discovery”).

• defconfig – The defconfig name (e.g., “nsh”).

• extra_args – Additional arguments to pass to the configuration. Defaults to empty list.

Returns:

Exit code of the configuration. Returns 0 on success.

Return type:

int

supress_stderr(enable: bool) → None

Suppress stderr output from commands.

Controls whether stderr from subsequent commands should be suppressed or displayed.

Parameters:

enable – If True, suppress stderr. If False, show stderr.

supress_stdout(enable: bool) → None

Suppress stdout output from commands.

Controls whether stdout from subsequent commands should be suppressed or displayed.

Parameters:

enable – If True, suppress stdout. If False, show stdout.

class ntxbuild.build.BuildTool(value)

Bases: str, Enum

Enumeration of build tools.

This enum defines the available build tools that can be used with NuttX build system.

CMAKE = 'cmake'

MAKE = 'make'

class ntxbuild.build.CMakeAction(value)

Bases: str, Enum

Enumeration of CMake actions.

BUILD = '--build'

BUILD_PATH = '-B'

CLEAN = 'clean'

TARGET = '--target'

class ntxbuild.build.CMakeBuilder(nuttxspace_path: Path, apps_dir: str = 'nuttx-apps', nuttx_dir: str = 'nuttx', build_dir: str = 'build')

Bases: BaseBuilder

Main builder class for NuttX projects using CMake.

This class allows you to trigger CMake commands, setup NuttX for a board:config, build, clean, etc.

DEFAULT_BUILD_DIR = 'build'

NINJA_FLAG = '-GNinja'

NXTMPDIR_FLAG = '-DNXTMPDIR=on'

build(parallel: int | None = None) → CompletedProcess

Build the NuttX project using CMake.

Parameters:

parallel – Number of parallel jobs to use for building. If None, uses default CMake parallelism. Defaults to None.

Returns:

The result of the build command.

Check the returncode attribute to determine success (0) or failure.

Return type:

subprocess.CompletedProcess

clean() → CompletedProcess

Clean build artifacts using CMake.

Removes object files and other build artifacts, but preserves configuration files.

Returns:

The result of the clean command.

Check the returncode attribute to determine success (0) or failure.

Return type:

subprocess.CompletedProcess

cmake(command: str) → CompletedProcess

Run any CMake command inside NuttX directory.

Parameters:

command – The CMake command to run. It can be any CMake command. Multiple arguments can be space-separated.

Returns:

The result of the CMake command.

Check the returncode attribute to determine success (0) or failure.

Return type:

subprocess.CompletedProcess

distclean() → None

Perform a distclean on the NuttX project using CMake.

Note: Distclean is not available on CMake builds. This method raises a RuntimeError to indicate that ‘clean’ should be used instead.

Raises:

RuntimeError – Always raised, as distclean is not available for CMake builds.

initialize(board: str, defconfig: str, extra_args: list[str] = []) → int

Run NuttX setup commands using CMake.

Configures NuttX for the specified board and defconfig using CMake. This method sets up the build directory and configuration.

Parameters:

• board – The board name (e.g., “stm32f4discovery”).

• defconfig – The defconfig name (e.g., “nsh”).

• extra_args – Additional CMake arguments to pass to the configuration. Currently not used in the implementation. Defaults to empty list.

Returns:

Exit code of the CMake configuration. Returns 0 on success.

Return type:

int

ninja_backend(enable: bool) → None

Enable or disable Ninja generator for CMake.

Parameters:

enable – If True, use Ninja generator. If False, use default.

use_nxtmpdir(enable: bool) → None

Enable or disable using the NuttX tmpdir for the build.

Parameters:

enable – If True, use the NuttX tmpdir for the build. If False, use the default build directory.

class ntxbuild.build.MakeAction(value)

Bases: str, Enum

Enumeration of make targets.

This enum defines the available make targets that can be used with NuttX.

ALL = 'all'

APPS_CLEAN = 'apps_clean'

BOOTLOADER = 'bootloader'

CLEAN = 'clean'

CLEAN_BOOTLOADER = 'clean_bootloader'

CRYPTO = 'crypto/'

DISTCLEAN = 'distclean'

FLASH = 'flash'

HOST_INFO = 'host_info'

OLDCONFIG = 'oldconfig'

OLDDEFCONFIG = 'olddefconfig'

SCHED_CLEAN = 'sched_clean'

class ntxbuild.build.MakeBuilder(nuttxspace_path: Path, apps_dir: str = 'nuttx-apps', nuttx_dir: str = 'nuttx')

Bases: BaseBuilder

Main builder class for NuttX projects.

This class allows you to trigger make commands, setup NuttX for a board:config, build, distclean, clean, etc.

build(parallel: int | None = None) → CompletedProcess

Build the NuttX project using Make.

Parameters:

parallel – Number of parallel jobs to use for building. If None, uses default make parallelism. Defaults to None.

Returns:

The result of the build command.

Check the returncode attribute to determine success (0) or failure.

Return type:

subprocess.CompletedProcess

clean() → CompletedProcess

Clean build artifacts using Make.

Removes object files and other build artifacts, but preserves configuration files.

Returns:

The result of the clean command.

Check the returncode attribute to determine success (0) or failure.

Return type:

subprocess.CompletedProcess

distclean() → CompletedProcess

Perform a distclean on the NuttX project using Make.

This removes all generated files including configuration files.

Returns:

The result of the distclean command.

Check the returncode attribute to determine success (0) or failure.

Return type:

subprocess.CompletedProcess

initialize(board: str, defconfig: str, extra_args: list[str] = []) → int

Run NuttX setup commands in the NuttX directory using Make.

Configures NuttX for the specified board and defconfig by running the configure.sh script. This method validates the environment before attempting configuration.

Parameters:

• board – The board name (e.g., “stm32f4discovery”).

• defconfig – The defconfig name (e.g., “nsh”).

• extra_args – Additional arguments to pass to configure.sh. Defaults to empty list.

Returns:

Exit code of the configure script. Returns 0 on success,

1 on validation failure or exception, or the configure script’s exit code if it fails.

Return type:

int

make(command: str) → CompletedProcess

Run any make command inside NuttX directory.

Parameters:

command – The make command to run. It can be any make command, such as “all”, “clean”, “distclean”, etc. Multiple arguments can be space-separated.

Returns:

The result of the make command.

Check the returncode attribute to determine success (0) or failure.

Return type:

subprocess.CompletedProcess

ntxbuild.build.nuttx_builder(nuttxspace_path: Path, apps_dir: str = 'nuttx-apps', build_tool: BuildTool = make)

Wrapper function used to select between the Make and CMake builders.

Parameters:

• nuttxspace_path – Path to the NuttX repository workspace.

• apps_dir – Name of the NuttX apps directory within the workspace. Defaults to “nuttx-apps”.

• build_tool – Build tool to use (Make or CMake). Defaults to Make.

Returns:

An instance of the appropriate builder class

based on the build_tool parameter.

Return type:

MakeBuilder or CMakeBuilder

Raises:

ValueError – If an unsupported build tool is specified.

Configuration Module

Apply Kconfig changes and manage NuttX configurations using the Configuration Module.

Configuration management for NuttX builds.

This module provides classes and utilities for managing Kconfig-based configuration for NuttX builds, including reading, modifying, and merging configuration options.

class ntxbuild.config.ConfigManager(nuttxspace_path: Path, apps_dir: str = 'nuttx-apps', nuttx_dir: str = 'nuttx', build_tool: BuildTool = make, build_dir: str = 'build')

Bases: object

Manages NuttX build configurations.

This class provides methods to read, modify, and manage Kconfig options for NuttX builds.

CONFIG_FILE = '.config'

KCONFIG_FILE = 'Kconfig'

kconfig_apply_changes() → int

kconfig_disable(config: str) → int

kconfig_enable(config: str) → int

kconfig_menuconfig() → int

kconfig_merge_config_file(source_file: str) → int

kconfig_read(config: str) → str

kconfig_set_str(config: str, value: str) → int

kconfig_set_value(config: str, value: str) → int

class ntxbuild.config.KconfigEnvironmentContext(bindir: Path, appsbindir: Path, appsdir: Path, externaldir: Path, kconfig_config: Path = PosixPath('.config'))

Bases: object

Context manager for Kconfig environment variables.

Manages the environment variables required by Kconfiglib to properly resolve paths in the NuttX build system. These variables are set before Kconfig operations and restored afterward to avoid interfering with other build system operations.

bindir

Path to the NuttX binary directory.

Type:

pathlib.Path

appsbindir

Path to the NuttX apps binary directory.

Type:

pathlib.Path

appsdir

Path to the NuttX apps directory.

Type:

pathlib.Path

externaldir

Path to the external directory.

Type:

pathlib.Path

kconfig_config

Path to the Kconfig configuration file (e.g., .config).

Type:

pathlib.Path

appsbindir: Path

appsdir: Path

bindir: Path

externaldir: Path

kconfig_config: Path = PosixPath('.config')

scoped_environment()

Temporarily set Kconfig environment variables and restore them.

class ntxbuild.config.KconfigParser(kconfig_file: Path, config_file: Path, warn: bool = False)

Bases: Kconfig

Parser for NuttX Kconfig files.

Extends kconfiglib.Kconfig to provide NuttX-specific initialization and environment management. Handles setting up environment variables, loading an existing .config and managing the working directory while performing kconfig operations.

Parameters:

• nuttxspace_path – Path to the NuttX workspace containing the NuttX source and apps directories.

• build_dir – Name of the build directory (default: “build”).

• apps_dir – Name of the apps directory within the workspace.

• nuttx_dir – Name of the NuttX source directory within the workspace.

• build_tool – BuildTool value indicating Make or CMake usage.

• warn – Whether to enable kconfiglib warnings (default: False).

choices

comments

config_header

config_prefix

const_syms

defconfig_list

defined_syms

env_vars

filename

header_header

kconfig_apply_changes() → int

Apply Kconfig changes by writing the configuration.

This method writes the current Kconfig state to .config file. kconfiglib automatically handles dependency resolution.

Returns:

Returns 0 on success, non-zero on failure.

Return type:

int

kconfig_disable(config: str) → int

Disable a Kconfig option.

Parameters:

config – The name of the Kconfig option to disable. The “CONFIG_” prefix is optional and will be removed if present.

Returns:

Returns 0 on success, non-zero on failure.

Return type:

int

Raises:

• KeyError – If the config option does not exist.

• ValueError – If the config option cannot be disabled (e.g., not assignable or wrong symbol type).

kconfig_enable(config: str) → int

Enable a Kconfig option.

Parameters:

config – The name of the Kconfig option to enable. The “CONFIG_” prefix is optional and will be removed if present.

Returns:

Returns 0 on success, non-zero on failure.

Return type:

int

Raises:

• KeyError – If the config option does not exist.

• ValueError – If the config option cannot be enabled (e.g., not assignable or wrong symbol type).

kconfig_filenames

kconfig_merge_config_file(source_file: str) → int

Merge a Kconfig file into the current configuration.

Merges configuration options from a source file into the current Kconfig state using kconfiglib’s load_config method. The merged configuration is not automatically written to disk; call kconfig_apply_changes() to persist changes.

Parameters:

source_file – Path to the source configuration file to merge.

Returns:

Always returns 0. The actual merge result is available

from load_config but is not currently exposed.

Return type:

int

Raises:

ValueError – If source_file is not provided or is empty.

kconfig_read(config: str) → str

Read the current state of a Kconfig option.

Parameters:

config – The name of the Kconfig option to read. The “CONFIG_” prefix is optional and will be removed if present.

Returns:

The current value of the Kconfig option. Returns “y”, “n”, “m”

for bool/tristate options, or the string/int/hex value for other types. Returns empty string if not set.

Return type:

str

Raises:

KeyError – If the config option does not exist.

kconfig_set_str(config: str, value: str) → int

Set a string Kconfig option value.

Parameters:

• config – The name of the Kconfig option. The “CONFIG_” prefix is optional and will be removed if present.

• value – The string value to set.

Returns:

Returns 0 on success, non-zero on failure.

Return type:

int

Raises:

• KeyError – If the config option does not exist.

• ValueError – If the config option is not a STRING type.

kconfig_set_value(config: str, value: str) → int

Set a numerical Kconfig option value.

Sets the value for INT or HEX type Kconfig options. For HEX options, the value must be prefixed with “0x”. For INT options, hexadecimal values are not allowed.

Parameters:

• config – The name of the Kconfig option. The “CONFIG_” prefix is optional and will be removed if present.

• value – The numerical value to set as a string. Must be convertible to int. For HEX options, must start with “0x”.

Returns:

Returns 0 on success, non-zero on failure.

Return type:

int

Raises:

• AssertionError – If value is not a string.

• ValueError – If the value cannot be converted to an integer, if the config option is not INT or HEX type, if the symbol is assignable (should use enable/disable instead), if INT type receives hexadecimal value, or if HEX type doesn’t have “0x” prefix.

• KeyError – If the config option does not exist.

linenr

m

menus

missing_syms

modules

n

named_choices

srctree

syms

top_node

unique_choices

unique_defined_syms

variables

warn

warn_assign_override

warn_assign_redun

warn_assign_undef

warn_to_stderr

warnings

y

ntxbuild.config.kconfig_chdir(f)

Decorator to manage environment variables for Kconfig operations.

This decorator ensures that environment variables are properly set before Kconfig operations and restored afterward. This is necessary because: - NuttX build system uses environment variables to determine the source

tree and apps directory

• We should not interfere with other modules using the build system

• Leaving these variables set causes path-related issues

The decorator sets the environment, executes the wrapped method, and restores the environment regardless of success or failure.

ntxbuild.config.scoped_working_directory(path: Path)

Temporarily switch process working directory and restore it.

Environment Data Module

This module helps in setting up and retrieving necessary environment variables for building NuttX projects.

ntxbuild.env_data.append_to_general_section(env_file: Path, key: str, value: str) → None

Append a key-value pair to the general section of the environment file.

Parameters:

• env_file – Path to the environment file.

• key – Key to append.

• value – Value to append.

ntxbuild.env_data.clear_ntx_env(nuttxspace_path: Path) → None

Remove the environment INI file if it exists.

ntxbuild.env_data.create_base_env_file(nuttxspace_path: Path, apps_dir: str, build_tool: str = 'make') → None

Save environment configuration to an INI file.

Parameters:

• nuttxspace_path – Path to the NuttX workspace directory.

• apps_dir – Name of the NuttX apps directory.

• build_tool – Build tool name (default: ‘make’).

ntxbuild.env_data.load_ntx_env(nuttxspace_path: Path) → ConfigParser

Load environment configuration from the INI file.

Parameters:

nuttxspace_path – Path to the NuttX workspace directory.

Returns:

A ConfigParser object containing the

environment configuration. The ‘general’ section contains: - ‘nuttxspace_path’ (str) - ‘nuttx_dir’ (str) - ‘apps_dir’ (str) - ‘build_tool’ (str)

Return type:

configparser.ConfigParser

Raises:

• FileNotFoundError – If the .ntxenv file does not exist.

• RuntimeError – If the file cannot be read or is missing required sections.

ntxbuild.env_data.remove_from_general_section(env_file: Path, key: str) → None

Remove a key from the general section of the environment file.

Parameters:

• env_file – Path to the environment file.

• key – Key to remove.

CLI Module

Use the CLI Module to parse command line arguments and execute commands. This generally should not be used but the API is available anyway.

Command-line interface for ntxbuild.

ntxbuild.cli.get_builder()

Get a builder instance from the current environment.

Loads the environment configuration and creates an appropriate builder (MakeBuilder or CMakeBuilder) based on the configured build tool.

Returns:

A builder instance configured for

the current NuttX workspace.

Return type:

MakeBuilder or CMakeBuilder

Raises:

click.ClickException – If environment validation fails.

ntxbuild.cli.prepare_env(start: bool = False, build_tool: BuildTool = make) → SectionProxy

Prepare and validate the NuttX environment.

Loads the environment from .ntxenv file if it exists, or initializes a new environment if start is True. Validates that the current directory matches the stored environment.

Must be executed by CLI commands.

Parameters:

• start – If True, allows initializing a new environment. If False, requires an existing .ntxenv file. Defaults to False.

• build_tool – Build tool to use (Make or CMake). Defaults to Make.

Returns:

A configparser section proxy containing:

• nuttxspace_path: Path to the NuttX workspace

• nuttx_dir: Name of the NuttX OS directory

• apps_dir: Name of the NuttX apps directory

• build_tool: Build tool to use (Make or CMake)

Return type:

configparser.SectionProxy

Raises:

click.ClickException – If environment validation fails or .ntxenv is not found when start is False.

Setup Module

This contains helper funtions to setup the ntxbuild environment, such as downloading the NuttX source code.

NuttX environment setup module.

This module provides functions to download and set up the NuttX OS and NuttX Apps repositories from their GitHub sources.

ntxbuild.setup.download_nuttx_apps_repo(source: str = 'https://github.com/apache/nuttx-apps.git', destination: Path | None = None, depth: int = 1, single_branch: bool = True, branch_name: str = 'master') → None

Download NuttX Apps repository from GitHub.

Clones the NuttX Apps repository to the specified destination or to a “nuttx-apps” subdirectory in the current working directory if no destination is provided.

Parameters:

• source – URL of the NuttX Apps repository to clone. Defaults to the official Apache NuttX Apps repository.

• destination – Path where the repository should be cloned. If None, clones to “nuttx-apps” in the current directory. Defaults to None.

• depth – Depth for shallow clone. 1 means only the latest commit. Defaults to 1.

• single_branch – If True, clone only the specified branch. Defaults to True.

• branch_name – Name of the branch to clone. Defaults to “master”.

Raises:

• git.exc.GitCommandError – If the git clone operation fails.

• git.exc.InvalidGitRepositoryError – If the destination path already exists and is not a valid git repository.

ntxbuild.setup.download_nuttx_repo(source: str = 'https://github.com/apache/nuttx.git', destination: Path | None = None, depth: int = 1, single_branch: bool = True, branch_name: str = 'master') → None

Download NuttX repository from GitHub.

Clones the NuttX OS repository to the specified destination or to a “nuttx” subdirectory in the current working directory if no destination is provided.

Parameters:

• source – URL of the NuttX repository to clone. Defaults to the official Apache NuttX repository.

• destination – Path where the repository should be cloned. If None, clones to “nuttx” in the current directory. Defaults to None.

• depth – Depth for shallow clone. 1 means only the latest commit. Defaults to 1.

• single_branch – If True, clone only the specified branch. Defaults to True.

• branch_name – Name of the branch to clone. Defaults to “master”.

Raises:

• git.exc.GitCommandError – If the git clone operation fails.

• git.exc.InvalidGitRepositoryError – If the destination path already exists and is not a valid git repository.

Toolchains Module

This contains helper funtions to manage toolchains, such as installing and listing them.

Toolchain management functions for NuttX builds.

This module provides classes and functions for installing, managing, and configuring toolchains for NuttX development. It handles downloading, extracting, and managing toolchain installations from various sources.

class ntxbuild.toolchains.ManagePath(toolchain_location: Path = PosixPath('/home/docs/ntxenv/toolchains'))

Bases: object

Manages toolchain PATH environment variable.

This class handles adding toolchain binary directories to the system PATH environment variable. It discovers installed toolchains and provides methods to manage their availability in the current environment.

add_all_toolchains_to_path()

Add all installed toolchains to the PATH environment variable.

Iterates through all installed toolchains and adds their binary directories to the system PATH.

add_toolchain_to_path(toolchain_name: str)

Add a specific toolchain’s binary directory to PATH.

Finds the toolchain’s bin directory and prepends it to the PATH environment variable. If the directory is already in PATH, it is not added again.

Parameters:

toolchain_name – Name of the toolchain to add to PATH.

Raises:

• AssertionError – If the toolchain is not found in the toolchain location, or if adding to PATH fails.

• ValueError – If the toolchain name does not match any known toolchain.

• RuntimeError – If the toolchain directory structure is invalid or the bin directory cannot be found.

property installed_toolchains: List[ToolchainName]

Get the list of installed toolchains.

Returns:

List of ToolchainName enum values for

toolchains that are currently installed.

Return type:

List[ToolchainName]

property supported_toolchains: List[str]

Get the list of supported toolchain names.

Returns:

List of all supported toolchain names as strings.

Return type:

List[str]

class ntxbuild.toolchains.Toolchain(name: str, url: str | None = None, nuttx_version: str | None = None)

Bases: object

Represents a toolchain configuration.

This dataclass stores information about a toolchain including its name, download URL, associated NuttX version, and binary directory path.

name

Name of the toolchain.

Type:

str

url

URL to download the toolchain archive. Defaults to None.

Type:

str | None

nuttx_version

NuttX version this toolchain is associated with. Defaults to None.

Type:

str | None

name: str

nuttx_version: str | None = None

url: str | None = None

class ntxbuild.toolchains.ToolchainFileParser(toolchain_file_path: Path | None = None)

Bases: object

Parser for toolchain configuration files.

This class reads and parses toolchain configuration files (toolchains.ini) to extract toolchain information including names, URLs, and associated NuttX versions.

property latest_version: str | None

Get the latest NuttX version from the toolchain configurations.

Returns:

The latest NuttX version string, or None if no

toolchains are available.

Return type:

Optional[str]

property toolchains: List[Toolchain]

Get the list of parsed toolchains.

Returns:

List of Toolchain objects parsed from the

configuration file.

Return type:

List[Toolchain]

class ntxbuild.toolchains.ToolchainInstaller(toolchain_name: str, nuttx_version: str | None = None, toolchain_file_path: Path | None = None)

Bases: ToolchainFileParser

Installer for NuttX toolchains.

This class handles downloading and installing toolchains from remote URLs. It supports various archive formats and manages the installation process including extraction and directory structure setup.

install(location: Path = PosixPath('/home/docs/ntxenv/toolchains'))

Install the toolchain to the specified location.

Downloads the toolchain archive, extracts it, and sets up the directory structure. The toolchain will be installed in a subdirectory named after the toolchain.

Parameters:

location – Base directory where the toolchain should be installed. Defaults to DEFAULT_TOOLCHAIN_LOCATION.

Returns:

The path where the toolchain was installed.

Return type:

Path

Raises:

• AssertionError – If location is not a Path object.

• FileExistsError – If the toolchain directory already exists.

• RuntimeError – If downloading or extracting the toolchain fails.

property nuttx_version: str

Get the NuttX version.

Returns:

The NuttX version associated with this toolchain installation.

Return type:

str

property toolchain_name: str

Get the toolchain name.

Returns:

The name of the toolchain being installed.

Return type:

str

class ntxbuild.toolchains.ToolchainName(value)

Bases: str, Enum

Enumeration of supported toolchain names.

This enum defines all available toolchain names that can be installed and managed by the toolchain system.

CLANG_ARM_NONE_EABI

Clang ARM none EABI toolchain.

GCC_AARCH64_NONE_ELF

GCC AArch64 none ELF toolchain.

GCC_ARM_NONE_EABI

GCC ARM none EABI toolchain.

XTENSA_ESP_ELF

Xtensa ESP ELF toolchain.

RISCV_NONE_ELF

RISC-V none ELF toolchain.

CLANG_ARM_NONE_EABI = 'clang-arm-none-eabi'

GCC_AARCH64_NONE_ELF = 'gcc-aarch64-none-elf'

GCC_ARM_NONE_EABI = 'gcc-arm-none-eabi'

RISCV_NONE_ELF = 'riscv-none-elf'

XTENSA_ESP_ELF = 'xtensa-esp-elf'

Utilities Module

Utility functions for NuttX builds.

This module provides utility functions for running commands, managing build artifacts, and handling NuttX workspace operations.

ntxbuild.utils.cleanup_tmp_copies(copied_paths: List[str]) → None

Clean up temporary copies of nuttxspace.

Removes temporary directories created by copy_nuttxspace_to_tmp. This operation is safe and will log warnings for any paths that cannot be removed, but will not raise exceptions.

Parameters:

copied_paths – List of paths to temporary directories to remove.

ntxbuild.utils.copy_nuttxspace_to_tmp(nuttxspace_path: str, num_copies: int, target_dir: str = '/tmp') → List[str]

Copy nuttxspace to target directory for parallel builds.

Creates lightweight copies of the nuttxspace directory, excluding unnecessary files like .git directories, .vscode, and other hidden files (except .ntxenv and .config). Useful for parallel build testing.

Parameters:

• nuttxspace_path – Path to the original nuttxspace directory.

• num_copies – Number of copies to create.

• target_dir – Target directory for copies. Defaults to “/tmp”.

Returns:

List of paths to the copied directories in the target

directory. Each copy is created in a unique temporary directory.

Return type:

List[str]

Raises:

• FileNotFoundError – If the nuttxspace_path does not exist.

• OSError – If copying fails or target directory cannot be created.

ntxbuild.utils.find_nuttx_root(start_path: Path) → Tuple[Path, Path]

Find the NuttX root directory.

Searches UPWARD from the start path to find a directory containing both the NuttX OS directory and the NuttX Apps directory.

Parameters:

start_path – Path to start searching from (searches upward).

Returns:

Path to the NuttX workspace root directory

and the NuttX Apps directory if found.

Return type:

Tuple[Path, Path]

Raises:

FileNotFoundError – If the NuttX workspace is not found in the directory tree above the start path.

ntxbuild.utils.get_build_artifacts(build_dir: str) → List[str]

Get list of build artifacts.

Recursively searches a build directory for common build artifact file types (.o, .a, .elf, .bin, .hex).

Parameters:

build_dir – Path to the build directory to search.

Returns:

List of paths to build artifact files found in the

directory tree. Returns empty list if directory doesn’t exist or contains no matching files.

Return type:

List[str]

ntxbuild.utils.run_bash_script(script_path: str, args: List[str] | None = None, cwd: str | None = None, no_stdout: bool = False, no_stderr: bool = False) → int

Run a bash script using subprocess.call and return exit code.

Executes a bash script with optional arguments. Output can be suppressed for stdout and/or stderr.

Parameters:

• script_path – Path to the bash script to execute.

• args – List of additional arguments to pass to the script. Defaults to None.

• cwd – Working directory for the script execution. Defaults to None (current directory).

• no_stdout – If True, suppress stdout output. Defaults to False.

• no_stderr – If True, suppress stderr output. Defaults to False.

Returns:

Exit code of the script execution. Returns 0 on success,

non-zero on failure.

Return type:

int

ntxbuild.utils.run_make_command(cmd: List[str], cwd: str | None = None, no_stdout: bool = False, no_stderr: bool = False) → Popen

Run a make command with real-time output using Popen.

Executes a make command and displays output in real-time, preserving control characters for proper terminal formatting. Uses subprocess.Popen to stream output as it becomes available.

Parameters:

• cmd – Command to run as a list of strings (e.g., [“make”, “all”]).

• cwd – Working directory for the command. Defaults to None (current directory).

• no_stdout – If True, suppress stdout output. Defaults to False.

• no_stderr – If True, suppress stderr output. Defaults to False.

Returns:

The process object with returncode attribute.

Check returncode to determine success (0) or failure (non-zero).

Return type:

subprocess.Popen

NuttX Module

Utilities for discovering and representing NuttX boards and defconfigs. This module provides small data classes to represent boards under <nuttxspace>/nuttx/boards.

Helpers to discover boards and defconfigs inside a NuttX repository.

This module defines small data classes that represent defconfig directories and board directories under the NuttX source tree (typically <nuttxspace>/nuttx/boards/<arch>/<soc>/<board>/configs/<defconfig>/defconfig).

The classes are intentionally lightweight and used by the CLI and other higher-level helpers to enumerate available boards and defconfigs.

class ntxbuild.nuttx.Board(path: pathlib.Path, name: str = None, arch: str = None, soc: str = None, cmake: bool = False, defconfigs: list[ntxbuild.nuttx.Defconfig] = <factory>)

Bases: object

arch: str = None

cmake: bool = False

defconfigs: list[Defconfig]

Representation of a NuttX board directory.

The expected layout for path is: …/boards/<arch>/<soc>/<board>.

If only the Path is provided, the other files are inferred from it.

path

Path to the board directory.

name

Board name (inferred from path.stem if not provided).

arch

Architecture name (inferred from path.parents[1].stem if not provided).

soc

SoC/chip name (inferred from path.parents[0].stem if not provided).

cmake

Whether the board supports CMake.

defconfigs

List of Defconfig objects found under the configs/ subdirectory.

get_defconfig(name: str)

Iterate available defconfigs and return the one with the given name.

name: str = None

path: Path

print_defconfig_summary()

Print the defconfigs for the board.

soc: str = None

class ntxbuild.nuttx.Defconfig(path: pathlib.Path, name: str = None)

Bases: object

property content

Return the text content of the defconfig file.

Returns:

The defconfig file contents as a string.

name: str = None

Representation of a defconfig directory.

path

Path to the defconfig directory (the folder that contains the file named defconfig).

name

Optional explicit name for the defconfig. If not provided, the directory name (path.stem) is used.

path: Path

class ntxbuild.nuttx.NuttxBoardExplorer(nuttx_path: Path)

Bases: object

Helper to search for boards inside a NuttX repository. User must set filtering criteria before searching and retrieve results via the boards property.

Parameters:

nuttx_path – Path to the root of the NuttX repository (the folder that contains the boards/ subdirectory).

property boards: list

print_board_summary()

Print the board summary.

set_arch(arch: str)

Filter search results by architecture name.

Example filter pattern produced: <arch>/*/*/configs.

set_board(board: str)

Filter search results by board name.

Example filter pattern produced: */*/<board>/configs.

set_soc(soc: str)

Filter search results by SoC/chip name.

Example filter pattern produced: */<soc>/*/configs.

Module contents

NuttX Build System Assistant

A Python package to assist with NuttX build system operations.