This is an automated email from the ASF dual-hosted git repository.
xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 03b4ec60a5ceaad3f5491635ef311bf26d88aa98
Author: raiden00pl <raide...@railab.me>
AuthorDate: Sat Nov 4 20:12:22 2023 +0100
Documentation: migrate "Running Applications from NSH" from wiki
link:
https://cwiki.apache.org/confluence/display/NUTTX/Running+Applications+from+NSH
---
Documentation/applications/nsh/index.rst | 1 +
Documentation/applications/nsh/running_apps.rst | 180 ++++++++++++++++++++++++
2 files changed, 181 insertions(+)
diff --git a/Documentation/applications/nsh/index.rst
b/Documentation/applications/nsh/index.rst
index 8f62f5cca4..f2b5d5608d 100644
--- a/Documentation/applications/nsh/index.rst
+++ b/Documentation/applications/nsh/index.rst
@@ -22,3 +22,4 @@ starts a given task instead of the main ``nsh`` application.
builtin.rst
installation.rst
login.rst
+ running_apps.rst
diff --git a/Documentation/applications/nsh/running_apps.rst
b/Documentation/applications/nsh/running_apps.rst
new file mode 100644
index 0000000000..b8aa0d646f
--- /dev/null
+++ b/Documentation/applications/nsh/running_apps.rst
@@ -0,0 +1,180 @@
+=============================
+Running Applications from NSH
+=============================
+
+This page describes current and planned features for the NuttX NuttShell (NSH).
+Think of this page as a roadmap. Most of the features have been implemented and
+incorporated into NSH; others are just ideas that are being tossed around
(noted
+as NOT implemented). The NSH document will be updated as new features are
included.
+
+There are currently be three ways to execute applications from NSH:
+
+#. Executing Builtin Applications
+
+ **Builtin Applications**
+ The current implementation of NSH allows for the execution
+ of "named" or "builtin" applications. The applications are simply task
entry points
+ in the common FLASH image that have names assigned to them. Simply entering
that name
+ from the NSH command line will cause the associated application to run.
+
+ See the NSH documentation for further details.
+
+ **Example**
+
+ For example:
+
+ .. code-block:: bash
+
+ NuttShell (NSH) NuttX-6.24
+ nsh> hello
+ Hello, World!!
+ nsh>
+
+ **Configuration Settings**
+
+ This functionality depends on these configuration settings:
+
+ * ``CONFIG_BUILTIN=y`` Enables NuttX support for builtin applications, and
+ * ``CONFIG_NSH_BUILTIN_APPS=y`` Enables NSH support for builtin
applications
+
+ In additional to other configuration needed by NSH.
+
+#. Executing Application from a File System
+
+ **OS Interfaces**
+
+ NuttX supports running applications that reside on a file system as well.
+ The standard interfaces used to do this include:
+
+ * ``execv()``
+ * ``execl()``
+ * ``posix_spawn()``
+
+
+ **Configuration Settings**
+
+ Execution of applications on a file system is currently supported by Nuttx.
+ This feature is enabled with:
+
+ * ``CONFIG_LIBC_EXECFUNCS=y`` Enable support for ``execv()``, ``execl()``,
+ and ``posix_spawn()``, and
+ * ``CONFIG_NSH_FILE_APPS=y`` Enable execution of programs in a file
system by NSH.
+
+ **Example**
+
+ When this feature is enabled, you will be able to do the following:
+
+ .. code-block:: bash
+
+ NuttShell (NSH) NuttX-6.24
+ nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard
+ nsh> ls -l /mnt/sdcard
+ /mnt/sdcard:
+ -rw-r--r-- 198 hello
+ nsh> /mnt/sdcard/hello
+ Hello, World!!
+ nsh>
+
+ **The PATH Variable**
+
+ Notice that the absolute path to the hello program was used. This can be
+ simplified by setting the following in your configuration:
+
+ * ``CONFIG_BINFMT_EXEPATH=y`` Enable use of the path variable to find
executable programs.
+
+
+ **Example**
+
+ Then, the example becomes:
+
+ .. code-block:: bash
+
+ NuttShell (NSH) NuttX-6.24
+ nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard
+ nsh> ls -l /mnt/sdcard
+ /mnt/sdcard:
+ -rw-r--r-- 198 hello
+ nsh> set PATH /mnt/sdcard
+ nsh> hello
+ Hello, World!!
+ nsh>
+
+ **Pre-initialized PATH Variables**
+
+ One final simplification: The initial PATH variable can be configured so
that
+ the PATH to your executable programs is already defined when NSH starts.
This
+ is down with:
+
+ * ``CONFIG_PATH_INITIAL="/mnt/sdcard"``
+
+ This functionality is already in place.
+
+#. Executing Builtin Applications from a File System
+
+ **Namespace Management**
+
+ NuttX supports a virtual file system (VFS) that may used to manage
namespaces.
+ Linux uses its VFS to manage nearly all named objects (pipes, locks, message
+ queues, etc.). And it is a good policy for NuttX to do this too. NuttX
already
+ does this for things like drivers and mountpoints. Why not extend this
mechanism
+ to handle named, builtin applications too?
+
+ **Proposed Configuration Options**
+
+ The following configuration options are planned:
+
+ * ``CONFIG_BUILTIN=y`` Will still be needed to enable NuttX support for
+ builtin applications, and
+ * ``CONFIG_NSH_BUILTIN_APPS=y`` Will still be needed enable to stimulate
+ programs to register themselves as builtin applications.
+
+ And in addition:
+
+ * ``CONFIG_FS_BINFS=y`` Enable the BINFS file system that is used to
access
+ builtin applications as files,
+ * ``CONFIG_LIBC_EXECFUNCS=y`` Enable support for ``execv()``,
``execl()``, and
+ ``posix_spawn()``,
+ * ``CONFIG_NSH_FILE_APPS=y`` Enable execution of programs in a file
system by NSH,
+ * ``CONFIG_BINFMT_EXEPATH=y`` Enable the (optional) use of the path
variable to
+ find executable programs, and
+ * ``CONFIG_PATH_INITIAL="/mnt/sdcard:/bin"`` Optional initial value of the
+ PATH variable.
+
+ **Example**
+
+ When this feature is enable, will will be able to do this (where
myapplication is
+ the name of some, arbitrary "built-in" application):
+
+ .. code-block:: bash
+
+ NuttShell (NSH) NuttX-6.24
+ nsh> mount -t binfs /bin
+ nsh> ls -l /bin
+ /bin:
+ -rw-r--r-- 0 myapplication
+ nsh> echo $PATH
+ /mnt/sdcard:/bin
+ nsh> myapplication
+ ... and your FLASH based application runs ...
+ nsh>
+
+ **Auto-Mounting BINFS**
+
+ BINFS, like any file system, could be mounted by an startup script
+ at ``/etc/init.d/rcS``.
+
+ But since BINFS may be used in many configurations that don't otherwise
+ need a startup script, perhaps some configurations would be helpful:
+
+ * ``CONFIG_NSH_AUTOMOUNT_BINFS=y`` Automatically mount the BINFS file
+ system on startup (**NOT implemented**)
+ * ``CONFIG_NSH_BINFS_MOUNTPOINT="/bin"`` The BINFS mountpoint (NOT
implemented).
+
+ Or perhaps a better thing to do would just be to make it easier to add a
+ startup script?
+
+ **Next Steps**
+
+ In the longer term, I would like to see an option to move most of the larger
+ NSH commands out of RAM and built them as standalone programs that can
reside,
+ for example, on an SD card (**NOT implemented**).
