Documentation: add initial nxpkg application page

[aviralgarg05]

Note: Please adhere to Contributing Guidelines.

Summary

Add an initial nxpkg application page under Documentation/applications/system.

This documents the current MVP scope of nxpkg, the on-device /etc + /var
layout used by the current implementation, the configuration knobs, the local
repository generation helper, and the XIAO ESP32S3 runtime validation flow used
for the first app-side slice.

This documentation change is the follow-up requested during review of the
companion nuttx-apps PR:

• apache/nuttx-apps#3474

Impact

• adds a new Applications page for nxpkg
• documents the current MVP, storage layout, local repository flow, and validated runtime path
• no runtime or build behavior changes in nuttx itself

Testing

Host used for documentation checks:

• OS: macOS 26.5 arm64
• Python: 3.9

Companion app/runtime target used for the documented validation flow:

• arch: xtensa
• board/config: esp32s3-xiao:elf
• board: Seeed XIAO ESP32S3 Sense

Documentation verification performed:

• python3 -m docutils.core --strict --halt=warning Documentation/applications/system/nxpkg/index.rst /tmp/nxpkg-doc.html
• PATH=/Users/aviralgarg/Library/Python/3.9/bin:$PATH make html from Documentation/

Companion runtime flow verified on hardware and documented in the page:

1. boot to NSH over USB CDC
2. run nxpkg and confirm usage output
3. run elf
4. run source /mnt/elf/romfs/pkgtest.nsh
5. verify nxpkg install hello
6. verify nxpkg list

Exact ROMFS-backed validation script used on the board:

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 observed output from the documented runtime flow:

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

[cederom]

/etc/nxpkg/nxpkg.conf ? :-)

[cederom]

/var/db/nxpkg/local.json for local installed packages?
/var/db/nxpkg/repo.json for storage of packages available on repo?
:-)

[cederom]

/var/cache/nxpkg/ for local store of fetched *.nxpkg files?

This way nxpkg clean would just remove this location content in order to free up space?

[cederom]

/tmp/nxpkg for staging?

By staging you mean unpack, process, move to target location?

[cederom]

Thank you @aviralgarg05 :-) My comments in the code :-)

Alternatively we may just use top level /usr/local:

• /usr/local/etc/nxpkg/ to keep all configurations here:
  • nxpkg.conf package manager configuration.
  • pkg_installed.json for installed packages.
  • pkg_repo.json for information about packages on the repo configured in nxpkg.conf.
• Then /usr/local/nxpkg/ to keep:
  • cache/ to store packages.
  • stage/ for staging.
• All packages, libraries, configs would use /usr/local prefix (i.e. /usr/local/bin, /usr/local/lib, etc).
• This would allow keeping everything under /usr/local that may be mounted from external storage, provide kind of BASE and USERLAND spaces separation, also keep nxpkg files more right?

What do you think @acassis ? :-)

[acassis]

Please fix to follow what we discussed