blob: 576e6c3309ac704e0b210026612a07635a756579 [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>Concepts - 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="Concepts">
<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.11.0, Apache NimBLE 1.6.0 </a> released (September 7, 2023)
</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_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" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" selected="selected" >
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="../../introduction/">Mynewt Documentation</a>
<ul>
<li ><a href="../get_started/">Basic Setup</a>
</li>
<li class="active">
<a href="./">Concepts</a>
</li>
<li ><a href="../../tutorials/tutorials/">Tutorials</a>
</li>
<li ><a href="../../os_user_guide/">OS User Guide</a>
</li>
<li><a href="
../../../network/ble/ble_intro/
">BLE User Guide</a>
</li>
<li ><a href="../../../newt/newt_intro/">Newt Tool Guide</a>
</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="
../../../faq/go_env/
">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; <a href="os/introduction/">Mynewt Documentation</a></li>
<li>&raquo; Concepts</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/apache/mynewt-site/blob/master/docs/os/get_started/vocabulary.md"
class="icon icon-github"> Edit on GitHub</a>
</li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 1.1.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="concepts">Concepts</h2>
<p>This page is meant to introduce you to some of the concepts inherent to
the Apache Mynewt Operating System, and <em>Newt</em> the tool that stitches a
project built on Apache Mynewt together.</p>
<h3 id="project">Project</h3>
<p>The project is the base directory of your embedded software tree. It is a
workspace that contains a logical collection of source code, for one or
more of your applications. A project consists of the following items:</p>
<ul>
<li>Project Definition: defines project level dependencies, and parameters
(located in <code>project.yml</code>)</li>
<li>Packages</li>
</ul>
<p><a href="#package">Packages</a> are described in detail in the section below. </p>
<p>Here is an example project definition file from the default Apache Mynewt
project: </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ more project.yml
&lt;snip&gt;
project.name: &quot;my_project&quot;
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: mynewt-core
$
</code></pre></div>
<p>A couple of things to note in the project definition:</p>
<ul>
<li>
<p><code>project.repositories</code>: Defines the remote repositories that this project
relies upon.</p>
</li>
<li>
<p><code>repository.apache-mynewt-core</code>: Defines the repository information for
the <code>apache-mynewt-core</code> repository.</p>
</li>
<li>
<p><code>vers=1-latest</code>: Defines the repository version. This string will use the
latest stable version in the 'Master' github branch. To use the latest version in the
master branch, just change it to <code>vers=0-dev</code>. Note that this branch might not be stable. </p>
</li>
</ul>
<p>Repositories are versioned collections of packages. </p>
<p>Projects can rely on remote repositories for functionality, and the newt tool
will resolve those remote repositories, and download the correct version into
your local source tree. Newly fetched repositories are put in the <code>repos</code>
directory of your project, and can be referenced throughout the system by using
the <code>@</code> specifier. </p>
<p>By default, the <code>@apache-mynewt-core</code> repository is included in every
project. Apache Mynewt Core contains all the base functionality of the Apache
Mynewt Operating System, including the Real Time Kernel, Bluetooth Networking
Stack, Flash File System, Console, Shell and Bootloader.</p>
<p><em>NOTE:</em> Any project can be converted into a repository by providing it with a
<code>repository.yml</code> file and putting it up onto Github. More information
about repositories can be found in the Newt documentation.</p>
<h3 id="package">Package</h3>
<p>A package is a collection items that form a fundamental unit in the Mynewt
Operating System. Packages can be:</p>
<ul>
<li>Applications</li>
<li>Libraries</li>
<li>Compiler definitions</li>
<li>Targets</li>
</ul>
<p>A package is identified by having a <code>pkg.yml</code> file in it's base
directory. Here is a sample <code>pkg.yml</code> file for the blinky applicaton:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ more pkg.yml
&lt;snip&gt;
pkg.name: apps/blinky
pkg.type: app
pkg.description: Basic example application which blinks an LED.
pkg.author: &quot;Apache Mynewt &lt;dev@mynewt.apache.org&gt;&quot;
pkg.homepage: &quot;http://mynewt.apache.org/&quot;
pkg.keywords:
pkg.deps:
- &quot;@apache-mynewt-core/libs/os&quot;
- &quot;@apache-mynewt-core/hw/hal&quot;
- &quot;@apache-mynewt-core/libs/console/full&quot;
</code></pre></div>
<p>Packages have a few features worth noting:</p>
<ul>
<li>Dependencies: Packages can rely upon other packages, and when they do
they will inherit their functionality (header files, library definitions, etc.)</li>
<li>APIs: Packages can export named APIs, and they can require that certain
APIs be present, in order to compile.</li>
</ul>
<p>Everything that newt knows about within a project's directory is a package. This
makes it very clean and easy to write re-usable components, which can describe their
Dependencies and APIs to the rest of the system.</p>
<h3 id="target">Target</h3>
<p>A target in Apache Mynewt is very similar to a target in <em>make</em>. It is the collection
of parameters that must be passed to Newt in order to generate a reproducible build. A
target represents the top of the build tree, and any packages or parameters specified at
the target level, cascade down to all dependencies.</p>
<p>Targets are also packages, and are stored in the <code>targets/</code> directory at the base
of your project. Most targets consist of: </p>
<ul>
<li><code>app</code>: The application to build.</li>
<li><code>bsp</code>: The board support package to combine with that application</li>
<li><code>build_profile</code>: Either <code>debug</code> or <code>optimized</code>. </li>
</ul>
<p>Targets can also have additional items specified, including: </p>
<ul>
<li><code>aflags</code>: Any additional assembler flags you might want to specify to the build.</li>
<li><code>cflags</code>: Any additional compiler flags you might want to specify to the build.</li>
<li><code>lflags</code>: Any additional linker flags you might want to specify to the build.</li>
</ul>
<p>In order to create and manipulate targets, the <em>newt</em> tool offers a set of helper commands,
you can find more information about these by issuing:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt target
```no-highlight
newt target
Usage:
newt target [flags]
newt target [command]
Available Commands:
config View or populate a target&#39;s system configuration
copy Copy target
create Create a target
delete Delete target
dep View target&#39;s dependency graph
revdep View target&#39;s reverse-dependency graph
set Set target configuration variable
show View target configuration variables
Global Flags:
-h, --help Help for newt commands
-j, --jobs int Number of concurrent build jobs (default 8)
-l, --loglevel string Log level (default &quot;WARN&quot;)
-o, --outfile string Filename to tee output to
-q, --quiet Be quiet; only display error output
-s, --silent Be silent; don&#39;t output anything
-v, --verbose Enable verbose output when executing commands
Use &quot;newt target [command] --help&quot; for more information about a command.
$
</code></pre></div>
<h3 id="configuration">Configuration</h3>
<p>Additional help topics:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt target config show &lt;target-name&gt;
...
* PACKAGE: sys/stats
* Setting: STATS_CLI
* Description: Expose the &quot;stat&quot; shell command.
* Value: 0
* Setting: STATS_NAMES
* Description: Include and report the textual name of each statistic.
* Value: 0
* Setting: STATS_NEWTMGR
* Description: Expose the &quot;stat&quot; newtmgr command.
* Value: 0
...
$
</code></pre></div>
<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>