system/nxpkg: add a basic package lifecycle helper by aviralgarg05 · Pull Request #3474 · apache/nuttx-apps

aviralgarg05 · 2026-05-11T06:36:50Z

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:

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

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

mkdir /data
mount -t tmpfs /data
mkdir /data/repo
cp /mnt/elf/romfs/index.json /data/repo/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: installed hello version 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 · 2026-05-11T08:03:22Z

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 · 2026-05-11T08:30:05Z

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 · 2026-05-11T11:34:39Z

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 · 2026-05-11T12:36:16Z

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 · 2026-05-11T13:42:44Z

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 · 2026-05-11T17:37:17Z

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 · 2026-05-12T11:50:22Z

+#define PKG_REPO_DIR          "/data/repo"
+#define PKG_REPO_INDEX        "/data/repo/index.json"
+#define PKG_REPO_INSTALLED    "/data/repo/installed.json"
+#define PKG_STORE_DIR         "/data/pkgs"
+#define PKG_TMP_DIR           "/data/tmp"
+#define PKG_TMP_PKG_DIR       "/data/tmp/pkg"


@aviralgarg05 I agree with @cederom some of these files should be moved to /etc/nxpkg and others to /var/ (where /var is a TMPFS mounted partition that will be lost after reboot)

acassis · 2026-05-12T11:52:09Z

+  if (strcmp(manifest->arch, pkg_runtime_arch()) != 0)
+    {
+      return -EXDEV;
+    }
+
+  if (strcmp(manifest->compat, pkg_runtime_compat()) != 0)
+    {
+      return -EXDEV;
+    }


If you return different errno here, it could be easier to track the root cause of the issue later

acassis · 2026-05-12T11:53:25Z

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

aviralgarg05 added 4 commits May 11, 2026 12:02

system/pkg: add lifecycle helper skeleton

075c826

system/pkg: add metadata and store foundation

e260c75

system/pkg: add local install and list path

fa22ef6

system/nxpkg: rename package helper and keep runtime fixes

e0d6b58

github-actions Bot added Size: XL Area: System labels May 11, 2026

linguini1 requested changes May 11, 2026

View reviewed changes

system/nxpkg: drop temporary debug logs and simplify usage

7ccf43e

aviralgarg05 requested a review from linguini1 May 11, 2026 08:30

acassis self-requested a review May 12, 2026 11:46

acassis reviewed May 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

system/nxpkg: add a basic package lifecycle helper#3474

system/nxpkg: add a basic package lifecycle helper#3474
aviralgarg05 wants to merge 5 commits into
apache:masterfrom
aviralgarg05:gsoc/nxpkg-app-pr1

aviralgarg05 commented May 11, 2026 •

edited

Loading

Uh oh!

linguini1 commented May 11, 2026 •

edited

Loading

Uh oh!

linguini1 left a comment •

edited

Loading

Uh oh!

aviralgarg05 commented May 11, 2026

Uh oh!

linguini1 commented May 11, 2026

Uh oh!

aviralgarg05 commented May 11, 2026

Uh oh!

cederom commented May 11, 2026 •

edited

Loading

Uh oh!

aviralgarg05 commented May 11, 2026

Uh oh!

acassis May 12, 2026

Uh oh!

acassis May 12, 2026

Uh oh!

acassis commented May 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

aviralgarg05 commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Impact

Testing

Uh oh!

linguini1 commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

linguini1 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aviralgarg05 commented May 11, 2026

Uh oh!

linguini1 commented May 11, 2026

Uh oh!

aviralgarg05 commented May 11, 2026

Uh oh!

cederom commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aviralgarg05 commented May 11, 2026

Uh oh!

acassis May 12, 2026

Choose a reason for hiding this comment

Uh oh!

acassis May 12, 2026

Choose a reason for hiding this comment

Uh oh!

acassis commented May 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aviralgarg05 commented May 11, 2026 •

edited

Loading

linguini1 commented May 11, 2026 •

edited

Loading

linguini1 left a comment •

edited

Loading

cederom commented May 11, 2026 •

edited

Loading