acassis commented on code in PR #18875: URL: https://github.com/apache/nuttx/pull/18875#discussion_r3241358377
########## Documentation/applications/system/nxpkg/index.rst: ########## @@ -0,0 +1,225 @@ +========= +``nxpkg`` +========= + +``nxpkg`` is a small local-first package helper for Dynamic ELF content on +NuttX. In its current form it focuses on a narrow executable-package flow: + +- read package metadata from a local repository index +- verify package compatibility for the current runtime +- verify the staged artifact with SHA-256 +- install the payload into a versioned on-device store +- record installed package state and expose it through ``list`` + +This first documentation page describes the current MVP only. Follow-up work +such as repository sync, dependency solving, shared-library packaging, and +rollback/update execution is intentionally out of scope for this initial +application-level slice. + +Overview +======== + +``nxpkg`` is intended to work with NuttX systems that already support Dynamic +ELF loading. The current implementation assumes that: + +- ELF payloads are produced separately from the base firmware image +- package metadata is available locally on the target +- the repository index can be written under ``/etc/nxpkg`` +- the package store and cache live under a writable ``/var`` hierarchy + +The package lifecycle handled by the current MVP is intentionally simple: + +1. load ``index.json`` from the local repository +2. select the latest matching package entry by name +3. verify runtime compatibility against the current arch/board identity +4. stage the package payload +5. verify the SHA-256 digest from the manifest +6. copy the payload into the versioned package store +7. update installed package metadata and ``current`` / ``previous`` pointers + +Current Commands +================ + +The first ``nxpkg`` slice provides the following command surface: + +- ``nxpkg install <name>`` +- ``nxpkg list`` +- ``nxpkg help`` + +The command parser also reserves ``update`` and ``rollback`` subcommands, but +they are not implemented in this initial unit. + +On-Device Layout +================ + +The current implementation uses the following default paths: + +- repository metadata: ``/etc/nxpkg/index.json`` +- installed package database: ``/var/lib/nxpkg/installed.json`` +- package payload store: ``/var/lib/nxpkg/pkgs`` +- temporary staging area: ``/var/cache/nxpkg/pkg`` + +Each manifest entry currently describes: + +- package name +- package version +- target architecture +- target board compatibility string +- payload artifact path +- SHA-256 digest +- payload type + +The first validated payload type is executable ELF content. + +Configuration +============= + +Enable ``nxpkg`` in ``menuconfig`` with: + +- ``CONFIG_SYSTEM_NXPKG`` + +The application also selects: + +- ``CONFIG_NETUTILS_CJSON`` + +Useful runtime prerequisites for the current MVP are: + +- Dynamic ELF support enabled in the target configuration +- ``CONFIG_FS_TMPFS`` if the validation target uses ``tmpfs``-backed ``/etc`` + and ``/var`` mounts for the first local repository flow +- a writable ``/etc`` mount for the local repository index +- a writable ``/var`` mount for the package store/cache + +The command name, task priority, and stack size can be adjusted with: + +- ``CONFIG_SYSTEM_NXPKG_PROGNAME`` +- ``CONFIG_SYSTEM_NXPKG_PRIORITY`` +- ``CONFIG_SYSTEM_NXPKG_STACKSIZE`` + +Basic Usage +=========== + +Running ``nxpkg`` without a subcommand prints the usage line:: + + nsh> nxpkg + Usage: nxpkg <install|update|list|rollback|help> [args] + +To inspect installed package state:: + + nsh> nxpkg list + +The local install path expects a repository index at ``/etc/nxpkg/index.json``. +For the initial validation flow described below, the index is copied from the +ELF ROMFS fixture generated at build time. + +Generating a Local Repository +============================= + +The current ``nxpkg`` workflow expects a repository directory containing an +``index.json`` file plus the payload artifacts referenced by that index. A +host-side helper script is available in ``apps/tools/export_pkg_repo.py`` to +generate this layout from built artifacts. + +For example, after building the ``hello`` ELF payload, the following command +exports a repository for the XIAO validation target:: + + python3 apps/tools/export_pkg_repo.py /tmp/nxpkg-repo \ + --arch xtensa \ + --compat esp32s3-xiao \ + --package hello:1.0.0:elf:apps/bin/hello + +This produces a repository layout like:: + + /tmp/nxpkg-repo/ + ├── index.json + └── artifacts/ + └── esp32s3-xiao/ + └── hello/ + └── 1.0.0/ + └── hello + Review Comment: Please fix to follow what we discussed -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
