Google Git
Sign in
apache / mynewt-site / refs/heads/asf-site / . / v1_2_0 / newt / newt_intro / index.html
blob: 046c9998f61a3a69abe00cec9b9a67e9ed361a98 [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">
<!-- This is broken by doc revisioning.
-->
<link rel="shortcut icon" href="../../img/favicon.ico">
<title>toc - Apache Mynewt</title>
<link href="../../css/bootstrap-3.0.3.min.css" rel="stylesheet">
<link rel="stylesheet" href="../../css/highlight.css">
<link href="../../css/base.css" rel="stylesheet">
<link href="../../css/custom.css" rel="stylesheet">
<link href="../../css/v2.css" rel="stylesheet">
<link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
<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="toc">
<div class="container">
<div class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="/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.12.0, Apache NimBLE 1.7.0 </a> released (April 4, 2024)
</div>
</div>
</div>
</div>
<nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" 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
class=""
>
<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
class=""
>
<a href="/about/">About</a>
</li>
<li
class=""
>
<a href="/talks/">Talks</a>
</li>
<li
class="active"
>
<a href="/documentation/">Documentation</a>
</li>
<li
class=""
>
<a href="/download/">Download</a>
</li>
<li
class=""
>
<a href="/community/">Community</a>
</li>
<li
class=""
>
<a href="/events/">Events</a>
</li>
</ul>
</div>
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary">
<div class="top">
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search documentation" />
</div>
</form>
</div>
</div>
<ul class="toc-nav">
<li class="doc-version"><select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest">
Version: master
</option>
<option value="/v1_12_0/" >
Version: 1.12.0
</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/" >
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" selected="selected" >
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></li>
<li ><a href="../../os/introduction/">Mynewt Documentation</a>
<ul>
<li ><a href="../../os/get_started/get_started/">Basic Setup</a>
</li>
<li >
<a href="../../os/get_started/vocabulary/">Concepts</a>
</li>
<li ><a href="../../os/tutorials/tutorials/">Tutorials</a>
</li>
<li ><a href="../../os/os_user_guide/">OS User Guide</a>
</li>
<li><a href="
../../network/ble/ble_intro/
">BLE User Guide</a>
</li>
<li class="active"><a href="./">Newt Tool Guide</a>
<ul>
<li >
<a href="../newt_operation/">Newt Theory of Ops</a>
</li>
<li ><a href="../newt_ops/">Command Guide</a>
</li>
</ul>
</li>
<li ><a href="../../newtmgr/overview/">Newt Manager Guide</a>
</li>
<li >
<a href="../../known_issues/">Known Issues</a>
</li>
</ul>
</li>
<li><a href="
../install/prev_releases/
">Appendix</a>
</li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<div class="doc-header">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="/documentation/">Docs</a></li>
<li>&raquo; Newt Tool Guide</li>
<li>&raquo; <a href="os/introduction/">Mynewt Documentation</a></li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/apache/mynewt-site/blob/master/docs/newt/newt_intro.md"
class="icon icon-github"> Edit on GitHub</a>
</li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 1.2.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>
<h2 id="newt-tool">Newt Tool</h2>
<h3 id="introduction">Introduction</h3>
<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>
<li>source package management </li>
<li>build, debug and install.</li>
</ul>
<h3 id="rationale">Rationale</h3>
<p>In order for the Mynewt operating system to work well for constrained environments across the many different types of microcontroller 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>
<li>Building for multiple targets</li>
<li>Deciding what to build in and what not to build in</li>
<li>Managing dependencies between components</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>
<h3 id="build-system">Build System</h3>
<p>A good build system must allow the user to take a few common steps while developing embedded applications:</p>
<ul>
<li>Generate full flash images</li>
<li>Download debug images to a target board using a debugger</li>
<li>Conditionally compile libraries &amp; code based upon build settings</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="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ tree -L 3
.
├── DISCLAIMER
├── LICENSE
├── NOTICE
├── README.md
<span style="background-color: #ffffcc">├── apps
</span>│ └── blinky
│ ├── pkg.yml
│ └── src
├── project.yml
<span style="background-color: #ffffcc">└── targets
</span> ├── my_blinky_sim
│ ├── pkg.yml
│ └── target.yml
└── unittest
├── pkg.yml
└── target.yml
6 directories, 10 files
</code></pre></div>
<p><br></p>
<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 href="../newt_operation/">Newt Theory of Ops</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>target-name</code> is the name of the target, and <code>app-name</code> is the name of the application. For our example <code>my_blinky_sim</code> is the name of the target and <code>blinky</code> is the name of the application. The <code>blinky.elf</code> executable is stored in the bin/targets/my_blinky_sim/app/apps/blinky directory as shown in the source tree:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>tree -L 6 bin/
bin/
└── targets
├── my_blinky_sim
│   ├── app
│   │   ├── apps
│   │   │   └── blinky
│   │   │   ├── apps
│   │   │   ├── apps_blinky.a
│   │   │   ├── apps_blinky.a.cmd
│   │   │   ├── blinky.elf
│   │   │   ├── blinky.elf.cmd
│   │   │   ├── blinky.elf.dSYM
│   │   │   ├── blinky.elf.lst
│   │   │   └── manifest.json
│   │   ├── hw
│   │   │   ├── bsp
│   │   │   │   └── native
│   │   │   ├── drivers
│   │   │   │   └── uart
│   │   │   ├── hal
│   │   │   │   ├── hw_hal.a
│   │   │   │   ├── hw_hal.a.cmd
│   │   │   │   └── repos
&lt;snip&gt;
</code></pre></div>
<p><br></p>
<h3 id="more-operations-using-newt">More operations using Newt</h3>
<p>Once a target has been built, Newt allows additional operations on the target. </p>
<ul>
<li><strong>load</strong>: Download built target to board</li>
<li><strong>debug</strong>: Open debugger session to target</li>
<li><strong>size</strong>: Get size of target components</li>
<li><strong>create-image</strong>: Add image header to the binary image</li>
<li><strong>run</strong>: Build, create image, load, and finally open a debug session with the target</li>
<li><strong>target</strong>: Create, delete, configure, and query a target</li>
</ul>
<p>For more details on how Newt works, go to <a href="../newt_operation/">Newt - Theory of Operations</a>.</p>
<p><br></p>
<h3 id="source-management-and-repositories">Source Management and Repositories</h3>
<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="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ more project.yml
&lt;snip&gt;
project.repositories:
- apache-mynewt-core
# Use github&#39;s distribution mechanism for core ASF libraries.
# This provides mirroring automatically for us.
#
repository.apache-mynewt-core:
type: github
vers: 1-latest
user: apache
repo: incubator-mynewt-core
</code></pre></div>
<p><br></p>
<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="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt install
Downloading repository description for apache-mynewt-core... success!
Downloading repository incubator-mynewt-core (branch: develop) at
https://github.com/apache/incubator-mynewt-core.git
Cloning into
&#39;/var/folders/7l/7b3w9m4n2mg3sqmgw2q1b9p80000gn/T/newt-repo814721459&#39;...
remote: Counting objects: 17601, done.
remote: Compressing objects: 100% (300/300), done.
remote: Total 17601 (delta 142), reused 0 (delta 0), pack-reused 17284
Receiving objects: 100% (17601/17601), 6.09 MiB | 3.17 MiB/s, done.
Resolving deltas: 100% (10347/10347), done.
Checking connectivity... done.
Repos successfully installed
</code></pre></div>
<p><br></p>
<p>Newt will install this repository in the <project>/repos directory. In the case of blinky, the directory structure ends up looking like:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ tree -L 2
.
├── DISCLAIMER
├── LICENSE
├── NOTICE
├── README.md
├── apps
│ └── blinky
├── project.state
├── project.yml
├── repos
│ └── apache-mynewt-core
└── targets
├── my_blinky_sim
└── unittest
</code></pre></div>
<p><br></p>
<p>In order to reference the installed repositories in packages, the "@" 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>kernel/os</code>, <code>hw/hal</code>, and <code>sys/console/full</code> packages.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ more apps/blinky/pkg.yml
&lt;snip&gt;
pkg.deps:
- &quot;@apache-mynewt-core/kernel/os&quot;
- &quot;@apache-mynewt-core/hw/hal&quot;
- &quot;@apache-mynewt-core/sys/console/full&quot;
</code></pre></div>
<p><br></p>
<p>Newt has the ability to autocomplete within <code>bash</code>. The following instructions allow MAC users to enable autocomplete within <code>bash</code>.</p>
<ol>
<li>Install the autocomplete tools for bash via <code>brew install bash-completion</code></li>
<li>Tell your shell to use newt for autocompletion of newt via <code>complete -C "newt complete" newt</code>. You can add this to your .bashrc or other init file to have it automatically set for all bash shells.</li>
</ol>
<p>Notes:</p>
<ol>
<li>Autocomplete will give you flag hints, but only if you type a '-'. </li>
<li>Autocomplete will not give you completion hints for the flag arguments (those optional things after the flag like <code>-l DEBUG</code>)</li>
<li>Autocomplete uses newt to parse the project to find targets and libs.</li>
</ol>
<div class="row">
<ul class="nav nav-pills" style="margin-bottom: 10px">
<li>
</li>
<li class="pull-right">
</li>
</ul>
</div>
<footer 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">
<a href="https://www.apache.org/">
<img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
</a>
<p>
Copyright © 2015-2021 The Apache Software Foundation.<br>
<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>
</p>
<a href="">
<img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
<a href="https://www.apache.org/licenses/">
<button class="button-footer-asf">
License
</button>
</a>
<a href="https://www.apache.org/foundation/sponsorship.html">
<button class="button-footer-asf">
Sponsorship
</button>
</a>
<a href="https://www.apache.org/foundation/thanks.html">
<button class="button-footer-asf">
Thanks
</button>
</a>
<a href="https://www.apache.org/security/">
<button class="button-footer-asf">
Security
</button>
</a>
<a href="https://apache.org/events/current-event">
<button class="button-footer-asf">
ASF Events
</button>
</a>
</footer>
</div>
</div>
</div>
<script src="../../js/jquery-1.10.2.min.js"></script>
<script src="../../js/bootstrap-3.0.3.min.js"></script>
<script src="../../js/highlight.pack.js"></script>
<script src="../../js/base.js"></script>
<script src="../../js/custom.js"></script>
<script src="search/main.js"></script>
</body>
</html>