blob: bd9f1ea2592cdc351e77993f0cce3669b6927f20 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Newt Tool Guide &mdash; Apache Mynewt latest documentation</title>
<link rel="shortcut icon" href="../_static/mynewt-logo-only-newt32x32.png"/>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/sphinx_theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/bootstrap-3.0.3.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/v2.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/custom.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/restructuredtext.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/overrides.css" type="text/css" />
<link rel="index" title="Index"
href="../genindex.html"/>
<link rel="search" title="Search" href="../search.html"/>
<link rel="top" title="Apache Mynewt latest documentation" href="../index.html"/>
<link rel="next" title="Theory of Operations" href="newt_operation.html"/>
<link rel="prev" title="Sample application" href="../network/mesh/sample.html"/>
<script src="../_static/js/modernizr.min.js"></script>
<script>
(function(i, s, o, g, r, a, m) {
i["GoogleAnalyticsObject"] = r;
(i[r] =
i[r] ||
function() {
(i[r].q = i[r].q || []).push(arguments);
}),
(i[r].l = 1 * new Date());
(a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]);
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m);
})(window, document, "script", "//www.google-analytics.com/analytics.js", "ga");
ga("create", "UA-72162311-1", "auto");
ga("send", "pageview");
</script>
</head>
<body class="not-front page-documentation" role="document" >
<div id="wrapper">
<div class="container">
<div id="banner" class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="../_static/img/logo.png">
</a>
<div class="tagline-cell">
<h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4>
</div>
<div class="news-cell">
<div class="well">
<h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.11.0, Apache NimBLE 1.6.0 </a> released September 7, 2023)
</div>
</div>
</div>
</div>
<header>
<nav id="navbar" class="navbar navbar-inverse" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav navbar-right">
<li>
<a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a>
</li>
<li class="important">
<a href="/quick-start/">Quick Start</a>
</li>
<li>
<a href="/about/">About</a>
</li>
<li>
<a href="/talks/">Talks</a>
</li>
<li class="active">
<a href="/documentation/">Documentation</a>
</li>
<li>
<a href="/download/">Download</a>
</li>
<li>
<a href="/community/">Community</a>
</li>
<li>
<a href="/events/">Events</a>
</li>
</ul>
<!-- Search, Navigation and Repo links -->
<ul class="nav navbar-nav navbar-right">
</ul>
</div>
</div>
</nav>
</header>
<!-- STARTS MAIN CONTENT -->
<div id="main-content">
<div id="breadcrumb">
<div class="container">
<a href="/documentation/">Docs</a> /
Newt Tool Guide
<div class="sourcelink">
<a href="https://github.com/apache/mynewt-newt/edit/master/docs/index.rst" class="icon icon-github"
rel="nofollow"> Edit on GitHub</a>
</div>
</div>
</div>
<!-- STARTS CONTAINER -->
<div class="container">
<!-- STARTS .content -->
<div id="content" class="row">
<!-- STARTS .container-sidebar -->
<div class="container-sidebar col-xs-12 col-sm-3">
<div id="docSidebar" class="sticky-container">
<div role="search" class="sphinx-search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search documentation" class="search-documentation" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<!-- Note: only works when deployed -->
<select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest" selected>
Version: latest
</option>
<option value="/v1_11_0" >
Version: 1.11.0
</option>
<option value="/v1_10_0" >
Version: 1.10.0
</option>
<option value="/v1_9_0" >
Version: 1.9.0
</option>
<option value="/v1_8_0" selected="selected" >
Version: 1.8.0
</option>
<option value="/v1_7_0" >
Version: 1.7.0
</option>
<option value="/v1_6_0" >
Version: 1.6.0
</option>
<option value="/v1_5_0" >
Version: 1.5.0
</option>
<option value="/v1_4_0" >
Version: 1.4.0
</option>
<option value="/v1_3_0/os/introduction" >
Version: 1.3.0
</option>
<option value="/v1_2_0/os/introduction" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" >
Version: 1.0.0
</option>
<option value="/v0_9_0/os/introduction" >
Version: 0.9.0
</option>
</select>
<div class="region region-sidebar">
<div class="docs-menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../get_started/index.html">Setup &amp; Get Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../concepts.html">Concepts</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorials/tutorials.html">Tutorials</a></li>
<li class="toctree-l1"><a class="reference internal" href="../external_links.html">Third-party Resources</a></li>
<li class="toctree-l1"><a class="reference internal" href="../os/os_user_guide.html">OS User Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../network/index.html">BLE User Guide</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Newt Tool Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="newt_operation.html">Theory of Operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="newt_ops.html">Command Structure</a></li>
<li class="toctree-l2"><a class="reference internal" href="install/index.html">Install</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../newtmgr/index.html">Newt Manager Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../mynewt_faq/index.html">Mynewt FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../misc/index.html">Appendix</a></li>
</ul>
</div>
</div>
</div>
<!-- ENDS STICKY CONTAINER -->
</div>
<!-- ENDS .container-sidebar -->
<div class="col-xs-12 col-sm-9">
<div class="alert alert-warning">
<p>
Version 1.8.0 is not the most recent version of the
Apache Mynewt documentation. Click <a href="/latest">here</a> to
read the latest version.
</p>
</div>
<div class="">
<div class="rst-content">
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="newt-tool-guide">
<h1>Newt Tool Guide<a class="headerlink" href="#newt-tool-guide" title="Permalink to this headline"></a></h1>
<div class="toctree-wrapper compound">
</div>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h2>
<p>Newt is a smart build and package management system for embedded
contexts. It is a single tool that accomplishes both the following
goals:</p>
<ul class="simple">
<li><p>source package management</p></li>
<li><p>build, debug and install.</p></li>
</ul>
</div>
<div class="section" id="rationale">
<h2>Rationale<a class="headerlink" href="#rationale" title="Permalink to this headline"></a></h2>
<p>In order for the Mynewt operating system to work well for constrained
environments across the many different types of micro-controller
applications (from doorbells to medical devices to power grids), a
system is needed that lets you select which packages to install and
which packages to build.</p>
<p>The build systems for embedded devices are often fairly complicated and
not well served for this purpose. For example, autoconf is designed for
detecting system compatibility issues but not well suited when it comes
to tasks like:</p>
<ul class="simple">
<li><p>Building for multiple targets</p></li>
<li><p>Deciding what to build in and what not to build in</p></li>
<li><p>Managing dependencies between components</p></li>
</ul>
<p>Fortunately, solutions addressing these very issues can be found in
source package management systems in higher level languages such as
Javascript (Node), Go, PHP and Ruby. We decided to fuse their source
management systems with a make system built for embedded systems and
create Newt.</p>
</div>
<div class="section" id="build-system">
<h2>Build System<a class="headerlink" href="#build-system" title="Permalink to this headline"></a></h2>
<p>A good build system must allow the user to take a few common steps while
developing embedded applications:</p>
<ul class="simple">
<li><p>Generate full flash images</p></li>
<li><p>Download debug images to a target board using a debugger</p></li>
<li><p>Conditionally compile libraries &amp; code based upon build settings</p></li>
</ul>
<p>Newt can read a directory tree, build a dependency tree, and emit the
right build artifacts. An example newt source tree is in
mynewt-blinky/develop:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>tree<span class="w"> </span>-L<span class="w"> </span><span class="m">3</span><span class="w"> </span>.
<span class="go">├── DISCLAIMER</span>
<span class="go">├── LICENSE</span>
<span class="go">├── NOTICE</span>
<span class="go">├── README.md</span>
<span class="go">├── apps</span>
<span class="go">│ └── blinky</span>
<span class="go">│ ├── pkg.yml</span>
<span class="go">│ └── src</span>
<span class="go">├── project.yml</span>
<span class="go">└── targets</span>
<span class="go"> ├── my_blinky_sim</span>
<span class="go"> │ ├── pkg.yml</span>
<span class="go"> │ └── target.yml</span>
<span class="go"> └── unittest</span>
<span class="go"> ├── pkg.yml</span>
<span class="go"> └── target.yml</span>
<span class="go">6 directories, 10 files</span>
</pre></div>
</div>
<p>When Newt sees a directory tree that contains a “project.yml” file, it is smart enough to recognize it as the base directory of a project, and
automatically builds a package tree. It also recognizes two important package directories in the package tree - “apps” and “targets”.
More on these directories in <a class="reference internal" href="newt_operation.html"><span class="doc">Theory of Operations</span></a>.</p>
<p>When Newt builds a target, it recursively resolves all package dependencies, and generates artifacts that are placed in the
bin/targets/&lt;target-name&gt;/app/apps/&lt;app-name&gt; directory, where the bin directory is under the project base directory,
<code class="docutils literal notranslate"><span class="pre">target-name</span></code> is the name of the target, and <code class="docutils literal notranslate"><span class="pre">app-name</span></code> is the name of the application. For our example <code class="docutils literal notranslate"><span class="pre">my_blinky_sim</span></code> is the
name of the target and <code class="docutils literal notranslate"><span class="pre">blinky</span></code> is the name of the application. The <code class="docutils literal notranslate"><span class="pre">blinky.elf</span></code> executable is stored in the
bin/targets/my_blinky_sim/app/apps/blinky directory as shown in the source tree:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>tree<span class="w"> </span>-L<span class="w"> </span><span class="m">6</span><span class="w"> </span>bin/
<span class="go">bin/</span>
<span class="go">└── targets</span>
<span class="go"> ├── my_blinky_sim</span>
<span class="go"> │ ├── app</span>
<span class="go"> │ │ ├── apps</span>
<span class="go"> │ │ │ └── blinky</span>
<span class="go"> │ │ │ ├── apps</span>
<span class="go"> │ │ │ ├── apps_blinky.a</span>
<span class="go"> │ │ │ ├── apps_blinky.a.cmd</span>
<span class="go"> │ │ │ ├── blinky.elf</span>
<span class="go"> │ │ │ ├── blinky.elf.cmd</span>
<span class="go"> │ │ │ ├── blinky.elf.dSYM</span>
<span class="go"> │ │ │ ├── blinky.elf.lst</span>
<span class="go"> │ │ │ └── manifest.json</span>
<span class="go"> │ │ ├── hw</span>
<span class="go"> │ │ │ ├── bsp</span>
<span class="go"> │ │ │ │ └── native</span>
<span class="go"> │ │ │ ├── drivers</span>
<span class="go"> │ │ │ │ └── uart</span>
<span class="go"> │ │ │ ├── hal</span>
<span class="go"> │ │ │ │ ├── hw_hal.a</span>
<span class="go"> │ │ │ │ ├── hw_hal.a.cmd</span>
<span class="go"> │ │ │ │ └── repos</span>
<span class="go">&lt;snip&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="more-operations-using-newt">
<h2>More operations using Newt<a class="headerlink" href="#more-operations-using-newt" title="Permalink to this headline"></a></h2>
<p>Once a target has been built, Newt allows additional operations on the target.</p>
<ul class="simple">
<li><p><strong>load</strong>: Download built target to board</p></li>
<li><p><strong>debug</strong>: Open debugger session to target</p></li>
<li><p><strong>size</strong>: Get size of target components</p></li>
<li><p><strong>create-image</strong>: Add image header to the binary image</p></li>
<li><p><strong>run</strong>: Build, create image, load, and finally open a debug session with the target</p></li>
<li><p><strong>target</strong>: Create, delete, configure, and query a target</p></li>
</ul>
<p>For more details on how Newt works, go to <a class="reference internal" href="newt_operation.html"><span class="doc">Theory of Operations</span></a>.</p>
</div>
<div class="section" id="source-management-and-repositories">
<h2>Source Management and Repositories<a class="headerlink" href="#source-management-and-repositories" title="Permalink to this headline"></a></h2>
<p>The other major element of the Newt tool is the ability to create reusable source distributions from a collection of code.
<strong>A project can be a reusable container of source code.</strong> In other words, projects can be versioned and redistributed, not packages.
A project bundles together packages that are typically needed to work together in a product e.g. RTOS core, filesystem APIs, and networking stack.</p>
<p>A project that has been made redistributable is known as a <strong>repository</strong>.
Repositories can be added to your local project by adding them into your project.yml file. Here is an example of the blinky
project’s yml file which relies on apache-mynewt-core:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>more<span class="w"> </span>project.yml
<span class="go">&lt;snip&gt;</span>
<span class="go">project.repositories:</span>
<span class="go"> - apache-mynewt-core</span>
<span class="go">repository.apache-mynewt-core:</span>
<span class="go"> type: github</span>
<span class="go"> vers: 1-latest</span>
<span class="go"> user: apache</span>
<span class="go"> repo: incubator-mynewt-core</span>
</pre></div>
</div>
<p>When you specify this repository in the blinky’s project file, you can then use the Newt tool to install dependencies:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>newt<span class="w"> </span>install
<span class="go">Downloading repository description for apache-mynewt-core... success!</span>
<span class="go">Downloading repository incubator-mynewt-core (branch: develop) at https://github.com/apache/incubator-mynewt-core.git</span>
<span class="go">Cloning into &#39;/var/folders/7l/7b3w9m4n2mg3sqmgw2q1b9p80000gn/T/newt-repo814721459&#39;...</span>
<span class="go">remote: Counting objects: 17601, done.</span>
<span class="go">remote: Compressing objects: 100% (300/300), done.</span>
<span class="go">remote: Total 17601 (delta 142), reused 0 (delta 0), pack-reused 17284</span>
<span class="go">Receiving objects: 100% (17601/17601), 6.09 MiB \| 3.17 MiB/s, done.</span>
<span class="go">Resolving deltas: 100% (10347/10347), done.</span>
<span class="go">Checking connectivity... done.</span>
<span class="go">Repos successfully installed</span>
</pre></div>
</div>
<p>Newt will install this repository in the &lt;project&gt;/repos directory. In the case of blinky, the directory structure ends up looking like:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>tree<span class="w"> </span>-L<span class="w"> </span><span class="m">2</span>
<span class="go">.</span>
<span class="go">├── DISCLAIMER</span>
<span class="go">├── LICENSE</span>
<span class="go">├── NOTICE</span>
<span class="go">├── README.md</span>
<span class="go">├── apps</span>
<span class="go">│ └── blinky</span>
<span class="go">├── project.state</span>
<span class="go">├── project.yml</span>
<span class="go">├── repos</span>
<span class="go">│ └── apache-mynewt-core</span>
<span class="go">└── targets</span>
<span class="go"> ├── my_blinky_sim</span>
<span class="go"> └── unittest</span>
</pre></div>
</div>
<p>In order to reference the installed repositories in packages, the “&#64;” notation should be specified in the repository
specifier. As an example, the apps/blinky application has the following dependencies in its pkg.yml file. This tells
the build system to look in the base directory of repos/apache-mynewt-core for the <code class="docutils literal notranslate"><span class="pre">kernel/os</span></code>, <code class="docutils literal notranslate"><span class="pre">hw/hal</span></code>, and <code class="docutils literal notranslate"><span class="pre">sys/console/full</span></code> packages.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>more<span class="w"> </span>apps/blinky/pkg.yml
<span class="go">pkg.deps:</span>
<span class="go"> - &quot;@apache-mynewt-core/kernel/os&quot;</span>
<span class="go"> - &quot;@apache-mynewt-core/hw/hal&quot;</span>
<span class="go"> - &quot;@apache-mynewt-core/sys/console/full&quot;</span>
</pre></div>
</div>
<p>Newt has the ability to autocomplete within <code class="docutils literal notranslate"><span class="pre">bash</span></code>. The following
instructions allow MAC users to enable autocomplete within <code class="docutils literal notranslate"><span class="pre">bash</span></code>.</p>
<ol class="arabic simple">
<li><p>Install the autocomplete tools for bash via
<code class="docutils literal notranslate"><span class="pre">brew</span> <span class="pre">install</span> <span class="pre">bash-completion</span></code></p></li>
<li><p>Tell your shell to use newt for autocompletion of newt via
<code class="docutils literal notranslate"><span class="pre">complete</span> <span class="pre">-C</span> <span class="pre">&quot;newt</span> <span class="pre">complete&quot;</span> <span class="pre">newt</span></code>. You can add this to your
.bashrc or other init file to have it automatically set for all bash
shells.</p></li>
</ol>
</div>
<div class="section" id="notes">
<h2>Notes:<a class="headerlink" href="#notes" title="Permalink to this headline"></a></h2>
<ol class="arabic simple">
<li><p>Autocomplete will give you flag hints, but only if you type a ‘-‘.</p></li>
<li><p>Autocomplete will not give you completion hints for the flag
arguments (those optional things after the flag like <code class="docutils literal notranslate"><span class="pre">-l</span> <span class="pre">DEBUG</span></code>)</p></li>
<li><p>Autocomplete uses newt to parse the project to find targets and libs.</p></li>
</ol>
</div>
</div>
</div>
</div>
<div class="rst-footer-buttons row" role="navigation" aria-label="footer navigation">
<a href="newt_operation.html" class="btn btn-neutral float-right" title="Theory of Operations" accesskey="n">Next: Theory of Operations <span class="fa fa-arrow-circle-right"></span></a>
<a href="../network/mesh/sample.html" class="btn btn-neutral" title="Sample application" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous: Sample application</a>
</div>
</div>
</div>
</div>
<!-- ENDS CONTENT SECTION -->
</div>
<!-- ENDS .content -->
</div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="col-xs-12">
<p class="copyright">Apache Mynewt is available under Apache License, version 2.0.</p>
</div>
<div class="col-xs-12">
<div class="logos">
<img src="../_static/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
<small class="footnote">
Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt project logo are either
registered trademarks or trademarks of the Apache Software Foundation in the United States and other countries.
</small>
<a href="">
<img src="../_static/img/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
</div>
</div>
</footer>
</div>
<!-- ENDS #wrapper -->
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'latest',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt',
LINK_SUFFIX: '.html'
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/js/bootstrap-3.0.3.min.js"></script>
<script type="text/javascript" src="../_static/js/affix.js"></script>
<script type="text/javascript" src="../_static/js/main.js"></script>
</body>
</html>