system/nxpkg: add a basic package lifecycle helper

[aviralgarg05]

Note: Please adhere to Contributing Guidelines.

Summary

This adds the first nxpkg application under system/nxpkg.

nxpkg is a small local-first package helper for Dynamic ELF applications. In
this initial form, it reads package metadata from a local repository index,
verifies compatibility and SHA-256 integrity for a staged payload, installs the
payload into a versioned on-device store, and records installed package state so
it can be queried later with list.

The goal of this initial slice is to provide a small, usable package lifecycle
helper for Dynamic ELF content without trying to solve the full package
management problem in one change.

This PR includes:

• the nxpkg command entry point and subcommand dispatch
• the local metadata/store foundation
• the first local install / list flow
• compatibility checks for the current arch/board identity
• transaction-state handling
• integrity verification for staged payloads
• the runtime fixes needed to make the metadata path stable on target

This PR intentionally does not include:

• board-side validation/config changes in nuttx
• network/repository sync logic
• update / rollback execution
• shared-library packaging flow
• crypto-subsystem migration for hashing

Those items will follow in later PRs.

Impact

User impact:

• adds a new nxpkg command in nuttx-apps
• provides an initial local-first package lifecycle helper for executable ELF payloads

Build impact:

• adds a new application under system/nxpkg
• depends on NETUTILS_CJSON

Runtime impact:

• introduces local metadata parsing, package-store handling, and install-state persistence
• keeps the current scope limited to local install / list

Compatibility impact:

• none for existing applications unless CONFIG_SYSTEM_NXPKG is enabled

Testing

Host used for build:

• OS: macOS 26.5 arm64
• compiler: xtensa-esp-elf-gcc (crosstool-NG esp-14.2.0_20241119) 14.2.0

Target used for verification:

• arch: xtensa
• board/config used during runtime verification: esp32s3-xiao:elf
• board: Seeed XIAO ESP32S3 Sense

Verification performed:

• build validation of the nxpkg application path in the active XIAO ELF worktree
• runtime validation together with the corresponding nuttx validation branch

Runtime flow verified on hardware:

1. boot to NSH over USB CDC
2. confirm nxpkg builtin is present and prints usage
3. run elf
4. run the ROMFS-backed local package fixture script
5. verify nxpkg install hello
6. verify nxpkg list

ROMFS-backed fixture script used for the package-path validation:

mount -t tmpfs /etc
mount -t tmpfs /var
mkdir /etc/nxpkg
cp /mnt/elf/romfs/index.json /etc/nxpkg/index.json
nxpkg install hello
nxpkg list

Relevant runtime transcript captured during validation:

nsh> nxpkg
Usage: nxpkg <install|update|list|rollback|help> [args]

nsh> elf
... ELF test payloads completed and returned to nsh>

nsh> source /mnt/elf/romfs/pkgtest.nsh
nxpkg: info: layout prepared
nxpkg: info: loading index from /etc/nxpkg/index.json
nxpkg: info: index read complete (213 bytes)
nxpkg: info: cJSON_Parse returned success
nxpkg: info: parsed manifest hello 1.0.0
nxpkg: info: selected hello version 1.0.0
nxpkg: info: artifact source /mnt/elf/romfs/hello
nxpkg: info: artifact copied to staging
nxpkg: info: sha256 verified
nxpkg: info: payload staged at /var/lib/nxpkg/pkgs/hello/1.0.0/hello
nxpkg: info: manifest written
nxpkg: info: compatibility check passed
nxpkg: info: installed metadata updated
nxpkg: info: installed hello version 1.0.0
hello current=1.0.0 previous=- type=elf arch=xtensa compat=esp32s3-xiao versions=1.0.0

nsh> nxpkg list
hello current=1.0.0 previous=- type=elf arch=xtensa compat=esp32s3-xiao versions=1.0.0

Observed runtime result:

• nxpkg install completed successfully for the local hello ELF payload
• nxpkg list reported the installed package state correctly on target

[linguini1]

Please follow the PR template and include more testing information. How did you verify the runtime path?

Can you explain a little more about what nxpkg does?

[linguini1]

Just use fprintf instead of custom functions.

[aviralgarg05]

Thanks for the review.

I’ve updated the PR description to follow the template, added more detail about what nxpkg does, and included the runtime validation steps and target used for testing.

I also pushed a small follow-up change to address the fprintf feedback and removed the temporary debug-only logging.

For a bit of context, this PR is also part of my GSoC work, and I’m intentionally submitting it in smaller scoped pieces so the basic app-side nxpkg tool can be reviewed early, while the related board-side work and later features come in follow-up PRs.

Please take another look when you get a chance.

[linguini1]

Thanks for the review.

I’ve updated the PR description to follow the template, added more detail about what nxpkg does, and included the runtime validation steps and target used for testing.

I also pushed a small follow-up change to address the fprintf feedback and removed the temporary debug-only logging.

For a bit of context, this PR is also part of my GSoC work, and I’m intentionally submitting it in smaller scoped pieces so the basic app-side nxpkg tool can be reviewed early, while the related board-side work and later features come in follow-up PRs.

Please take another look when you get a chance.

Looks better! Just an FYI, the contributing guide states a "zero trust approach to testing". This means that you should include full log output from your tests, not just a verbal description of your steps (although that's good to include alongside the logs)

[aviralgarg05]

Thanks, that is helpful. I have updated the PR description again and added the ROMFS-backed fixture script plus the relevant runtime transcript from the XIAO board validation, so the testing section now includes concrete command/output alongside the step summary.

[cederom]

• Thank you @aviralgarg05 this is very nice and demanded feature!
• We should start from documentation to know what is the concept, architecture, and then implementation flow in the first place! :-)
• I would suggest FreeBSD following pkg [1] organization which is similar in name and functionality (also smaller and simpler than apt, pacman, etc). We may use nxpkg in place of pkg below:
  • Configuration is plaintext at /etc/pkg/ and then nuttx.conf.
  • Package database is in /var/db/pkg/local.sqlite.
  • Package cache is in /var/cache/pkg.
  • Each package knows its dependency packages, and pkg is able to solve them. There are also "flavors" that is each package can have different feature set enabled/disabled, but this is story for future here, we just need to keep it in mind when designing architecture.
  • BSD systems are divided into BASE and USERLAND. This may come handy for NuttX too because BASE could be the static firmware images built for specific platform, and then USEDLAND would provide packages for that platform. This clear separation assures clean and elegant implementations.
    • BASE is located in /.
    • USERLAND is mounted at /usr/local when BASE is ready.
    • BASE can work without USERLAND.
    • BASE is common to all releases and platforms providing minimal common feature set.
    • This allows to have static BASE at / with USERLAND mounted from anywhere (i.e. network or separate partition) at /usr/local.
    • Breaking USERLAND never breaks BASE, so you can easily fix stuff when in pinch.
    • This BSD is different approach from Linux where is base and packages are intermixed, and I would love this approach in NuttX distribution :-)

I will start a thread on the dev@ mailing list for this purpose. I think there should be a draft documentation that is easy to edit, maybe asf confluence wiki? :-)

[1] https://man.freebsd.org/cgi/man.cgi?query=pkg

[aviralgarg05]

Thanks @cederom , this is very helpful.

The BASE vs USERLAND separation is a very useful way to think about it, and I agree that the concept/architecture should be written down clearly as the work grows.

I’ll follow the dev@ discussion and keep the next steps aligned with that broader design direction, while continuing to keep the current implementation in small reviewable pieces.

[acassis]

@aviralgarg05 Please submit an initial Documentation to nxpkg to be included at Applications section of the nuttx/Documentation/

[aviralgarg05]

I’ve pushed the latest updates to the nxpkg app PR and re-verified the corrected /etc + /var runtime flow on the XIAO board.

I also submitted the initial nuttx documentation page here, as requested:

• apache/nuttx#18875

The current hardware-verified flow for the app PR is now:

• mount -t tmpfs /etc
• mount -t tmpfs /var
• mkdir /etc/nxpkg
• cp /mnt/elf/romfs/index.json /etc/nxpkg/index.json
• nxpkg install hello
• nxpkg list

[acassis]

Suggestion: NuttX Package Manager 'nxpkg'

Why tristate? I think the nxpkg itself couldn't be a module, not sure. @xiaoxiang781216 what do you think?