mirror of
https://github.com/apache/nuttx.git
synced 2026-08-01 20:28:58 +00:00
Documentation: Update nxpkg and add nxstore guide.
Document nxpkg storage, repository metadata, lifecycle commands, recovery behavior, and transport trust limits. Add the companion nxstore guide, including installed-manifest launch behavior and the shared framebuffer supervisor-strip contract. Assisted-by: Claude:claude-sonnet-5 Assisted-by: OpenAI Codex:gpt-5.6-sol Signed-off-by: aviralgarg05 <gargaviral99@gmail.com>
This commit is contained in:
aviralgarg05
parent
2099ceda33
commit
e329da6718
2 changed files with 245 additions and 0 deletions
154
Documentation/applications/system/nxpkg/index.rst
Normal file
154
Documentation/applications/system/nxpkg/index.rst
Normal file
|
|
@ -0,0 +1,154 @@
|
|||
=========
|
||||
``nxpkg``
|
||||
=========
|
||||
|
||||
``nxpkg`` manages standalone Dynamic ELF application images in a small,
|
||||
versioned on-device store. It can synchronize a static package catalog,
|
||||
install or update a compatible payload, list available and installed
|
||||
packages, roll back to the previous installed version, and remove a package.
|
||||
|
||||
The implementation is intentionally small. It does not resolve dependencies
|
||||
or provide a general-purpose system package format.
|
||||
|
||||
Configuration
|
||||
=============
|
||||
|
||||
Enable ``CONFIG_SYSTEM_NXPKG``. The command name, task settings, and storage
|
||||
root are configured with:
|
||||
|
||||
* ``CONFIG_SYSTEM_NXPKG_PROGNAME``
|
||||
* ``CONFIG_SYSTEM_NXPKG_PRIORITY``
|
||||
* ``CONFIG_SYSTEM_NXPKG_STACKSIZE``
|
||||
* ``CONFIG_SYSTEM_NXPKG_ROOT``
|
||||
|
||||
The default storage root is ``/var/lib/nxpkg``. Mount persistent storage at
|
||||
``/var`` or select a board-appropriate persistent path, such as
|
||||
``/mnt/sdcard/nxpkg``, if installed packages must survive a reset. A
|
||||
``tmpfs``-backed root is useful for tests but is not persistent.
|
||||
|
||||
Dynamic ELF loading and the target's required binary-format support must also
|
||||
be enabled. Synchronizing or downloading from an HTTP URL requires
|
||||
``CONFIG_NETUTILS_WEBCLIENT`` and a working network configuration. Local
|
||||
filesystem sources work without the web client.
|
||||
|
||||
Commands
|
||||
========
|
||||
|
||||
The command-line interface is:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
nxpkg sync <index-source>
|
||||
nxpkg available
|
||||
nxpkg install <name>
|
||||
nxpkg update <name>
|
||||
nxpkg list
|
||||
nxpkg rollback <name>
|
||||
nxpkg remove <name>
|
||||
|
||||
``sync`` accepts either a local index path or an HTTP/HTTPS URL. ``install``
|
||||
selects the newest catalog entry whose architecture and compatibility strings
|
||||
match the running target. ``update`` uses the same operation and therefore
|
||||
installs the newest matching version. ``rollback`` swaps the current and
|
||||
previous installed versions.
|
||||
|
||||
Repository format
|
||||
=================
|
||||
|
||||
A repository is a directory of static files. No package-specific server is
|
||||
required. Its index contains a ``packages`` array, for example:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"packages": [
|
||||
{
|
||||
"name": "hello",
|
||||
"version": "1.0.0",
|
||||
"arch": "xtensa",
|
||||
"compat": "esp32s3-xiao",
|
||||
"artifact": "artifacts/xtensa/esp32s3/esp32s3-xiao/hello/1.0.0/hello",
|
||||
"sha256": "<64 hexadecimal characters>",
|
||||
"type": "elf"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
``name``, ``version``, ``arch``, ``compat``, ``artifact``, ``sha256``, and
|
||||
``type`` are required. Supported types are ``elf`` and ``shared-lib``.
|
||||
``description``, ``category``, ``icon``, and ``launch_args`` are optional
|
||||
metadata used by front ends. Relative artifact and icon paths are resolved
|
||||
from the synchronized index location.
|
||||
|
||||
The catalog may contain entries for several targets and versions. Version
|
||||
selection compares dot-separated numeric components numerically and other
|
||||
components lexically; it is not a complete Semantic Versioning
|
||||
implementation.
|
||||
|
||||
The repository export helper in ``apps/tools/export_pkg_repo.py`` copies
|
||||
built artifacts, calculates their SHA-256 digests, and writes the index:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
python3 apps/tools/export_pkg_repo.py /tmp/nxpkg-repo \
|
||||
--arch xtensa \
|
||||
--chip esp32s3 \
|
||||
--compat esp32s3-xiao \
|
||||
--package hello:1.0.0:elf:apps/bin/hello
|
||||
|
||||
The resulting directory can be served during local development with any
|
||||
static file server, for example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cd /tmp/nxpkg-repo
|
||||
python3 -m http.server 8000
|
||||
|
||||
Then synchronize the board from the development host:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
nsh> nxpkg sync http://192.0.2.1:8000/index.json
|
||||
nsh> nxpkg available
|
||||
nsh> nxpkg install hello
|
||||
nsh> nxpkg list
|
||||
|
||||
Replace the example address with one reachable from the target.
|
||||
|
||||
On-device layout
|
||||
================
|
||||
|
||||
Under ``CONFIG_SYSTEM_NXPKG_ROOT``, ``nxpkg`` stores:
|
||||
|
||||
* ``index.jsn``: the last synchronized catalog and the source used to resolve
|
||||
relative artifact and icon paths
|
||||
* ``instpkg.jsn``: the authoritative installed-package database
|
||||
* ``pkgs/<name>/<version>/``: versioned payload and manifest files
|
||||
* ``pkgs/<name>/current`` and ``previous``: convenience mirrors of the
|
||||
database state
|
||||
* ``tmp/``: bounded temporary downloads and atomic-write files
|
||||
|
||||
Install and update operations use per-package locks. A separate lock
|
||||
serializes changes to the shared installed database. An interrupted
|
||||
operation leaves transaction state that the next operation can clean up.
|
||||
|
||||
Security scope
|
||||
==============
|
||||
|
||||
The SHA-256 field detects accidental corruption only when the index itself is
|
||||
trusted. If both the catalog and artifact arrive over unauthenticated HTTP,
|
||||
an active attacker can replace both and provide a matching digest. Use an
|
||||
authenticated transport and a trusted endpoint for untrusted networks.
|
||||
|
||||
The current format does not include signed repository metadata or package
|
||||
signatures. Plain HTTP is therefore appropriate only for a trusted, isolated
|
||||
development network where that risk is explicitly accepted. Package
|
||||
compatibility checks are target-selection checks, not a security boundary.
|
||||
|
||||
Current limitations
|
||||
===================
|
||||
|
||||
``nxpkg`` does not currently provide dependency solving, repository metadata
|
||||
signatures, package signatures, or a policy engine. Filesystem constraints
|
||||
also apply to the selected storage root; for example, a short-name-only FAT
|
||||
configuration limits usable package and artifact names.
|
||||
91
Documentation/applications/system/nxstore/index.rst
Normal file
91
Documentation/applications/system/nxstore/index.rst
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
===========
|
||||
``nxstore``
|
||||
===========
|
||||
|
||||
``nxstore`` is an LVGL front end for :doc:`../nxpkg/index`. It displays the
|
||||
packages in the synchronized catalog, installs a selected package on a worker
|
||||
thread, launches installed Dynamic ELF applications, and supervises the one
|
||||
application currently using the display.
|
||||
|
||||
Configuration
|
||||
=============
|
||||
|
||||
Enable ``CONFIG_SYSTEM_NXSTORE``. It depends on
|
||||
``CONFIG_GRAPHICS_LVGL`` and ``CONFIG_SYSTEM_NXPKG``. Its principal options
|
||||
are:
|
||||
|
||||
* ``CONFIG_SYSTEM_NXSTORE_PROGNAME``
|
||||
* ``CONFIG_SYSTEM_NXSTORE_PRIORITY``
|
||||
* ``CONFIG_SYSTEM_NXSTORE_STACKSIZE``
|
||||
* ``CONFIG_SYSTEM_NXSTORE_FBDEVPATH``
|
||||
* ``CONFIG_SYSTEM_NXSTORE_INPUT_DEVPATH``
|
||||
|
||||
The framebuffer and input paths default to ``/dev/fb0`` and ``/dev/input0``.
|
||||
The board must provide LVGL-compatible display and input drivers. ``nxpkg``
|
||||
must use a writable storage root, and remote synchronization additionally
|
||||
requires the networking options described in the ``nxpkg`` documentation.
|
||||
|
||||
Starting the store
|
||||
==================
|
||||
|
||||
With no argument, ``nxstore`` opens the last catalog synchronized by
|
||||
``nxpkg``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
nsh> nxstore
|
||||
|
||||
An optional index URL asks the store to synchronize before drawing the list:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
nsh> nxstore http://192.0.2.1:8000/index.json
|
||||
|
||||
Transient network failures are retried for a bounded interval. If
|
||||
synchronization still fails, the UI reports the failure and uses the last
|
||||
valid cached catalog when one exists. Invalid metadata and local storage
|
||||
errors are not retried.
|
||||
|
||||
Interaction
|
||||
===========
|
||||
|
||||
Each catalog package appears once, using its newest compatible version.
|
||||
|
||||
* Tap an uninstalled package to install and launch it.
|
||||
* Tap an installed package to launch its current installed version.
|
||||
* Long-press an installed package to remove all its installed versions.
|
||||
* Tap ``Close`` on the running-application screen to request termination.
|
||||
|
||||
Installation runs outside the LVGL thread so progress remains visible. LVGL
|
||||
objects are updated only by the main UI thread. Launch arguments are read
|
||||
from the stored manifest for the current installed version, including after a
|
||||
rollback.
|
||||
|
||||
Application termination contract
|
||||
================================
|
||||
|
||||
The ``Close`` control sends ``SIGTERM`` to the launched process. A
|
||||
long-running application should install a signal handler that performs only
|
||||
an async-signal-safe action, such as setting a ``volatile sig_atomic_t`` flag,
|
||||
and then poll that flag from its main loop. The normal execution path should
|
||||
release framebuffer, input, and other resources before returning.
|
||||
|
||||
``nxstore`` does not force-delete an application that ignores ``SIGTERM``.
|
||||
Forceful task deletion can interrupt display, heap, or filesystem operations
|
||||
and leave the system in an unsafe state. Until the child exits, the store
|
||||
keeps the running-application screen visible and does not hand the display
|
||||
back to the package list.
|
||||
|
||||
The store and the launched application share one framebuffer. A
|
||||
framebuffer application must leave the top ``NXSTORE_BAR_HEIGHT`` pixels
|
||||
untouched so the supervisor bar remains visible. Include
|
||||
``<system/nxstore_chrome.h>`` instead of duplicating the current height.
|
||||
|
||||
Current limitations
|
||||
===================
|
||||
|
||||
Only one install worker and one supervised application are supported at a
|
||||
time. The launcher currently uses one fixed, generous stack size for all
|
||||
packages because the manifest format does not carry a per-application stack
|
||||
requirement. Applications that cannot reserve the supervisor strip are not
|
||||
currently suitable for launch from ``nxstore``.
|
||||
Loading…
Add table
Add a link
Reference in a new issue