Google Git
Sign in
apache / nuttx-website / refs/heads/asf-site / . / content / docs / 12.10.0 / applications / nsh / running_apps.html
blob: 9d5eeb9ee8951885b5fd5af668fbf457a8e66567 [file] [log] [blame]
<!--
Documentation/_templates/layout.html
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership. The
ASF licenses this file to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance with the
License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE html>
<html class="writer-html5" lang="en">
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Running Applications from NSH &mdash; NuttX latest documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../../_static/css/theme.css" />
<link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
<link rel="stylesheet" type="text/css" href="../../_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css" />
<link rel="stylesheet" type="text/css" href="../../_static/custom.css" />
<link rel="shortcut icon" href="../../_static/favicon.ico"/>
<script src="../../_static/jquery.js"></script>
<script src="../../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
<script src="../../_static/doctools.js"></script>
<script src="../../_static/sphinx_highlight.js"></script>
<script src="../../_static/clipboard.min.js"></script>
<script src="../../_static/copybutton.js"></script>
<script src="../../_static/design-tabs.js"></script>
<script src="../../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="Software Define Radio Libraries" href="../sdr/index.html" />
<link rel="prev" title="Shell Login" href="login.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../../index.html" class="icon icon-home"> NuttX
</a>
<!-- this version selector is quite ugly, should be probably replaced by something
more modern -->
<div class="version-selector">
<select onchange="javascript:location.href = this.value;">
<option value="../../../latest" selected="selected">latest</option>
<option value="../../../10.0.0" >10.0.0</option>
<option value="../../../10.0.1" >10.0.1</option>
<option value="../../../10.1.0" >10.1.0</option>
<option value="../../../10.2.0" >10.2.0</option>
<option value="../../../10.3.0" >10.3.0</option>
<option value="../../../11.0.0" >11.0.0</option>
<option value="../../../12.0.0" >12.0.0</option>
<option value="../../../12.1.0" >12.1.0</option>
<option value="../../../12.2.0" >12.2.0</option>
<option value="../../../12.2.1" >12.2.1</option>
<option value="../../../12.3.0" >12.3.0</option>
<option value="../../../12.4.0" >12.4.0</option>
<option value="../../../12.5.0" >12.5.0</option>
<option value="../../../12.5.1" >12.5.1</option>
<option value="../../../12.6.0" >12.6.0</option>
<option value="../../../12.7.0" >12.7.0</option>
<option value="../../../12.8.0" >12.8.0</option>
<option value="../../../12.9.0" >12.9.0</option>
<option value="../../../12.10.0" >12.10.0</option>
<option value="../../../12.11.0" >12.11.0</option>
</select>
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Table of Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../index.html">Home</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../introduction/index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../quickstart/index.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contributing/index.html">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../platforms/index.html">Supported Platforms</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../components/index.html">OS Components</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../index.html">Applications</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../audioutils/index.html">Audio Utility libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="../boot/index.html">Bootloader Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../benchmarks/index.html">Benchmark Applications</a></li>
<li class="toctree-l2"><a class="reference internal" href="../canutils/index.html">CAN Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../crypto/index.html">Cryptography Library Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../fsutils/index.html">File System Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../games/index.html">Games</a></li>
<li class="toctree-l2"><a class="reference internal" href="../graphics/index.html">Graphics Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../industry/index.html">Industrial Applications</a></li>
<li class="toctree-l2"><a class="reference internal" href="../inertial/index.html">Inertial Libraries Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../interpreters/index.html">Interpreters</a></li>
<li class="toctree-l2"><a class="reference internal" href="../logging/index.html">Logging Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../lte/index.html">LTE Libraries and NSH Add-Ons</a></li>
<li class="toctree-l2"><a class="reference internal" href="../math/index.html">Math Library Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mlearing/index.html">Machine Learning Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../netutils/index.html">Network Utilities</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">NuttShell (NSH)</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="nsh.html">Overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="commands.html">Commands</a></li>
<li class="toctree-l3"><a class="reference internal" href="config.html">Configuration Settings</a></li>
<li class="toctree-l3"><a class="reference internal" href="customizing.html">The NSH Library and NSH Initialization</a></li>
<li class="toctree-l3"><a class="reference internal" href="customizing.html#nsh-commands">NSH Commands</a></li>
<li class="toctree-l3"><a class="reference internal" href="builtin.html">NSH “Built-In” Applications</a></li>
<li class="toctree-l3"><a class="reference internal" href="installation.html">Customizing NSH Initialization</a></li>
<li class="toctree-l3"><a class="reference internal" href="login.html">Shell Login</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Running Applications from NSH</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../sdr/index.html">Software Define Radio Libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="../system/index.html">System Libraries and NSH Add-Ons</a></li>
<li class="toctree-l2"><a class="reference internal" href="../testing/index.html">Testing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tools/index.html">Host Side Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="../wireless/index.html">Wireless Libraries and NSH Add-Ons</a></li>
<li class="toctree-l2"><a class="reference internal" href="../examples/index.html">Examples</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../implementation/index.html">Implementation Details</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../reference/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../faq/index.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../debugging/index.html">Debugging</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../guides/index.html">Guides</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../logos/index.html">NuttX Logos</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../_tags/tagsindex.html">Tags</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">NuttX</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="../index.html">Applications</a></li>
<li class="breadcrumb-item"><a href="index.html">NuttShell (NSH)</a></li>
<li class="breadcrumb-item active">Running Applications from NSH</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/apache/nuttx/blob/master/Documentation/applications/nsh/running_apps.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="running-applications-from-nsh">
<h1>Running Applications from NSH<a class="headerlink" href="#running-applications-from-nsh" title="Permalink to this heading"></a></h1>
<p>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.</p>
<p>There are currently be three ways to execute applications from NSH:</p>
<ol class="arabic">
<li><p>Executing Builtin Applications</p>
<p><strong>Builtin Applications</strong>
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.</p>
<p>See the NSH documentation for further details.</p>
<p><strong>Example</strong></p>
<p>For example:</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>NuttShell<span class="w"> </span><span class="o">(</span>NSH<span class="o">)</span><span class="w"> </span>NuttX-6.24
nsh&gt;<span class="w"> </span>hello
Hello,<span class="w"> </span>World!!
nsh&gt;
</pre></div>
</div>
</div></blockquote>
<p><strong>Configuration Settings</strong></p>
<p>This functionality depends on these configuration settings:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_BUILTIN=y</span></code> Enables NuttX support for builtin applications, and</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_NSH_BUILTIN_APPS=y</span></code> Enables NSH support for builtin applications</p></li>
</ul>
</div></blockquote>
<p>In additional to other configuration needed by NSH.</p>
</li>
<li><p>Executing Application from a File System</p>
<p><strong>OS Interfaces</strong></p>
<p>NuttX supports running applications that reside on a file system as well.
The standard interfaces used to do this include:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">execv()</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">execl()</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">posix_spawn()</span></code></p></li>
</ul>
</div></blockquote>
<p><strong>Configuration Settings</strong></p>
<p>Execution of applications on a file system is currently supported by Nuttx.
This feature is enabled with:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_LIBC_EXECFUNCS=y</span></code> Enable support for <code class="docutils literal notranslate"><span class="pre">execv()</span></code>, <code class="docutils literal notranslate"><span class="pre">execl()</span></code>,
and <code class="docutils literal notranslate"><span class="pre">posix_spawn()</span></code>, and</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_NSH_FILE_APPS=y</span></code> Enable execution of programs in a file system by NSH.</p></li>
</ul>
</div></blockquote>
<p><strong>Example</strong></p>
<p>When this feature is enabled, you will be able to do the following:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>NuttShell<span class="w"> </span><span class="o">(</span>NSH<span class="o">)</span><span class="w"> </span>NuttX-6.24
nsh&gt;<span class="w"> </span>mount<span class="w"> </span>-t<span class="w"> </span>vfat<span class="w"> </span>/dev/mmcsd0<span class="w"> </span>/mnt/sdcard
nsh&gt;<span class="w"> </span>ls<span class="w"> </span>-l<span class="w"> </span>/mnt/sdcard
/mnt/sdcard:
-rw-r--r--<span class="w"> </span><span class="m">198</span><span class="w"> </span>hello
nsh&gt;<span class="w"> </span>/mnt/sdcard/hello
Hello,<span class="w"> </span>World!!
nsh&gt;
</pre></div>
</div>
<p><strong>The PATH Variable</strong></p>
<p>Notice that the absolute path to the hello program was used. This can be
simplified by setting the following in your configuration:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_BINFMT_EXEPATH=y</span></code> Enable use of the path variable to find executable programs.</p></li>
</ul>
</div></blockquote>
<p><strong>Example</strong></p>
<p>Then, the example becomes:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>NuttShell<span class="w"> </span><span class="o">(</span>NSH<span class="o">)</span><span class="w"> </span>NuttX-6.24
nsh&gt;<span class="w"> </span>mount<span class="w"> </span>-t<span class="w"> </span>vfat<span class="w"> </span>/dev/mmcsd0<span class="w"> </span>/mnt/sdcard
nsh&gt;<span class="w"> </span>ls<span class="w"> </span>-l<span class="w"> </span>/mnt/sdcard
/mnt/sdcard:
<span class="w"> </span>-rw-r--r--<span class="w"> </span><span class="m">198</span><span class="w"> </span>hello
nsh&gt;<span class="w"> </span><span class="nb">set</span><span class="w"> </span>PATH<span class="w"> </span>/mnt/sdcard
nsh&gt;<span class="w"> </span>hello
Hello,<span class="w"> </span>World!!
nsh&gt;
</pre></div>
</div>
<p><strong>Pre-initialized PATH Variables</strong></p>
<p>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:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_PATH_INITIAL=&quot;/mnt/sdcard&quot;</span></code></p></li>
</ul>
</div></blockquote>
<p>This functionality is already in place.</p>
</li>
<li><p>Executing Builtin Applications from a File System</p>
<p><strong>Namespace Management</strong></p>
<p>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?</p>
<p><strong>Proposed Configuration Options</strong></p>
<p>The following configuration options are planned:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_BUILTIN=y</span></code> Will still be needed to enable NuttX support for
builtin applications, and</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_NSH_BUILTIN_APPS=y</span></code> Will still be needed enable to stimulate
programs to register themselves as builtin applications.</p></li>
</ul>
</div></blockquote>
<p>And in addition:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_FS_BINFS=y</span></code> Enable the BINFS file system that is used to access
builtin applications as files,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_LIBC_EXECFUNCS=y</span></code> Enable support for <code class="docutils literal notranslate"><span class="pre">execv()</span></code>, <code class="docutils literal notranslate"><span class="pre">execl()</span></code>, and
<code class="docutils literal notranslate"><span class="pre">posix_spawn()</span></code>,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_NSH_FILE_APPS=y</span></code> Enable execution of programs in a file system by NSH,</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_BINFMT_EXEPATH=y</span></code> Enable the (optional) use of the path variable to
find executable programs, and</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_PATH_INITIAL=&quot;/mnt/sdcard:/bin&quot;</span></code> Optional initial value of the
PATH variable.</p></li>
</ul>
</div></blockquote>
<p><strong>Example</strong></p>
<p>When this feature is enable, will will be able to do this (where myapplication is
the name of some, arbitrary “built-in” application):</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>NuttShell<span class="w"> </span><span class="o">(</span>NSH<span class="o">)</span><span class="w"> </span>NuttX-6.24
nsh&gt;<span class="w"> </span>mount<span class="w"> </span>-t<span class="w"> </span>binfs<span class="w"> </span>/bin
nsh&gt;<span class="w"> </span>ls<span class="w"> </span>-l<span class="w"> </span>/bin
/bin:
<span class="w"> </span>-rw-r--r--<span class="w"> </span><span class="m">0</span><span class="w"> </span>myapplication
nsh&gt;<span class="w"> </span><span class="nb">echo</span><span class="w"> </span><span class="nv">$PATH</span>
/mnt/sdcard:/bin
nsh&gt;<span class="w"> </span>myapplication
...<span class="w"> </span>and<span class="w"> </span>your<span class="w"> </span>FLASH<span class="w"> </span>based<span class="w"> </span>application<span class="w"> </span>runs<span class="w"> </span>...
nsh&gt;
</pre></div>
</div>
<p><strong>Auto-Mounting BINFS</strong></p>
<p>BINFS, like any file system, could be mounted by an startup script
at <code class="docutils literal notranslate"><span class="pre">/etc/init.d/rcS</span></code>.</p>
<p>But since BINFS may be used in many configurations that don’t otherwise
need a startup script, perhaps some configurations would be helpful:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_NSH_AUTOMOUNT_BINFS=y</span></code> Automatically mount the BINFS file
system on startup (<strong>NOT implemented</strong>)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_NSH_BINFS_MOUNTPOINT=&quot;/bin&quot;</span></code> The BINFS mountpoint (NOT implemented).</p></li>
</ul>
</div></blockquote>
<p>Or perhaps a better thing to do would just be to make it easier to add a
startup script?</p>
<p><strong>Next Steps</strong></p>
<p>In the longer term, it would be good to optionally 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 (<strong>NOT implemented</strong>).</p>
</li>
</ol>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="login.html" class="btn btn-neutral float-left" title="Shell Login" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="../sdr/index.html" class="btn btn-neutral float-right" title="Software Define Radio Libraries" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2023, The Apache Software Foundation.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>