Quick Start

ntxbuild must be used in a directory that contains the NuttX directory with the kernel and the apps directory with applications (nuttx-apps).

1. Prepare the source code

NuttX requires two repositories for building: nuttx and nuttx-apps. You should clone those from Github inside a directory usually named nuttxspace or simply use the install command to quickly download both repositories.

# Create the workspace
mkdir nuttxspace

# Navigate to the workspace
cd nuttxspace

# Use ntxbuild install to quickly fetch the repositories
ntxbuild install
🚀 Downloading NuttX and Apps repositories...
✅ Installation completed successfully.

2. Initialize Your NuttX Environment

The start command sets up the entire NuttX environment to a board and a defconfig. Below the environment is configured to the nsh defconfig of the simulation.

# Navigate to your NuttX workspace
cd nuttxspace

# Initialize with board and defconfig (sim:nsh)
ntxbuild start sim nsh

3. Build Your Project

To build the project, use the build command, which supports parallel build jobs.

# Build with default settings
ntxbuild build

# Or, build with parallel jobs
ntxbuild build --parallel 8

4. Configure Your Build

You can execute configuration changes using menuconfig or even set custom config options directly from the terminal.

# Run menuconfig
ntxbuild menuconfig

# Set Kconfig values
ntxbuild kconfig --set-value CONFIG_DEBUG=y
ntxbuild kconfig --set-str CONFIG_APP_NAME="MyApp"

Using Python

Alternatively, you can automate your builds using a Python script instead of the CLI.

from pathlib import Path
from ntxbuild.build import MakeBuilder

current_dir = Path.cwd()

# Use the Makefile-based builder
# First parameter is the nuttxspace path, second is the apps directory name
builder = MakeBuilder(current_dir, "nuttx-apps")
# Initialize the board/defconfig
setup_result = builder.initialize("sim", "nsh")

# Execute the build with 10 parallel jobs
builder.build(parallel=10)

# You can now clean the environment if needed
builder.distclean()

View Available Boards and Configs

It is possible to quickly see a table of available boards for a SoC or defconfigs for a board.

For the board list, provide the SoC name as in boards/<arch>/<soc>.

$ ntxbuild list boards qemu
╒═════════════╕
│ Boards      │
╞═════════════╡
│ qemu-armv7a │
├─────────────┤
│ qemu-armv7r │
├─────────────┤
│ qemu-armv8a │
├─────────────┤
│ qemu-i486   │
╘═════════════╛
Total boards: 4

$ ntxbuild list boards esp32c6
╒═════════════════╕
│ Boards          │
╞═════════════════╡
│ esp32c6-devkitc │
├─────────────────┤
│ esp32c6-devkitm │
├─────────────────┤
│ esp32c6-xiao    │
╘═════════════════╛
Total boards: 3

To view defconfigs, use the board name under boards/<arch>/<soc>/<board>.

$ ntxbuild list defconfigs esp32c6-devkitc
╒══════════════════════╤════════════════════╕
│ Defconfigs           │ Defconfigs         │
╞══════════════════════╪════════════════════╡
│ adc                  │ bmp180             │
├──────────────────────┼────────────────────┤
│ buttons              │ capture            │
├──────────────────────┼────────────────────┤
│ crypto               │ efuse              │
├──────────────────────┼────────────────────┤
│ gpio                 │ i2c                │
|──────────────────────┼────────────────────┤
[...]
|──────────────────────┼────────────────────┤
│ twai                 │ ulp                │
├──────────────────────┼────────────────────┤
│ usbconsole           │ watchdog           │
├──────────────────────┼────────────────────┤
│ wifi                 │                    │
╘══════════════════════╧════════════════════╛
╒═════════╤═════════════════╤════════╤═════════╤════════════════════════════════╕
│   Total │ Board           │ Arch   │ Soc     │ Path (nuttx/boards/)           │
╞═════════╪═════════════════╪════════╪═════════╪════════════════════════════════╡
│      37 │ esp32c6-devkitc │ risc-v │ esp32c6 │ risc-v/esp32c6/esp32c6-devkitc │
╘═════════╧═════════════════╧════════╧═════════╧════════════════════════════════╛

Downloading Toolchains

To visualize currently available toolchains, execute the toolchain list command:

$ ntxbuild toolchain list
Available toolchains:
  - clang-arm-none-eabi
  - gcc-aarch64-none-elf
  - gcc-arm-none-eabi
  - xtensa-esp-elf
  - riscv-none-elf
Installed toolchains:
  - xtensa-esp-elf

To install, execute the toolchain install command using any of the toolchains from the list above.

$ ntxbuild toolchain install gcc-arm-none-eabi
Installing toolchain gcc-arm-none-eabi for NuttX v12.12.0
✅ Toolchain gcc-arm-none-eabi installed successfully
Installation directory: /home/user/ntxenv/toolchains
Note: Toolchains are sourced automatically during build.

NOTE: Toolchains are automatically appended to PATH when building from the CLI.

NOTE: Toolchains are installed to ~/ntxenv/toolchains.