blob: 5da4c394aa6cad1106f6b5bdd9203ce066eeb367 [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.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" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" selected="selected" >
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/get_started/">Basic Setup</a>
</li>
<li >
<a href="../../../get_started/vocabulary/">Concepts</a>
</li>
<li ><a href="../../tutorials/">Tutorials</a>
<ul>
<li ><a href="../../blinky/">Project Blinky</a>
</li>
<li class="active"><a href="./">Work with repositories</a>
<ul>
<li >
<a href="../upgrade_repo/">Upgrade a Repo</a>
</li>
<li >
<a href="../create_repo/">Turn project into a Repo</a>
</li>
<li >
<a href="../private_repo/">Access a private Repo</a>
</li>
</ul>
</li>
<li ><a href="../../project-slinky/">Project Slinky for Remote Comms</a>
</li>
<li >
<a href="../../ibeacon/">BLE iBeacon</a>
</li>
<li >
<a href="../../eddystone/">BLE Eddystone</a>
</li>
<li >
<a href="../../add_newtmgr/">Enable Newt Manager in any app</a>
</li>
<li >
<a href="../../add_shell/">Enable the OS Shell and Console</a>
</li>
<li >
<a href="../../tasks_lesson/">Tasks and Priority Management</a>
</li>
<li >
<a href="../../wi-fi_on_arduino/">Enable Wi-Fi on Arduino MKR1000</a>
</li>
<li >
<a href="../../unit_test/">Write a Test Suite for a Package</a>
</li>
<li >
<a href="../../event_queue/">Events and Event Queues</a>
</li>
<li >
<a href="../../bletiny_project/">BLE app to check stats via console</a>
</li>
<li ><a href="../../bleprph/bleprph-intro/">BLE peripheral project</a>
</li>
<li >
<a href="../../blehci_project/">BLE HCI interface</a>
</li>
<li><a href="
../../air_quality_sensor/
">Air-quality Sensor project</a>
</li>
<li >
<a href="../../nrf52_adc/">Add an Analog Sensor</a>
</li>
</ul>
</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; Work with repositories</li>
<li>&raquo; <a href="os/tutorials/tutorials/">Tutorials</a></li>
<li>&raquo; <a href="os/introduction/">Mynewt Documentation</a></li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 1.0.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="adding-repositories-to-your-project">Adding Repositories to your Project</h2>
<h3 id="what-is-a-repository">What is a Repository</h3>
<p>A repository is a version-ed Mynewt project, which is a collection of Mynewt packages organized in a specific way for redistribution. </p>
<p>What differentiates a repository from a Mynewt project is the presence of a
<code>repository.yml</code> file describing the repository. This will be described
below. For a basic understanding of repositories you may read the <a href="../../../../newt/newt_intro/">Newt Tool Manual</a> and <a href="../create_repo/">How to create repos</a>.</p>
<p><strong>Note:</strong> For the remainder of this document we'll use the term repo as shorthand for a Mynewt repository.</p>
<p>Repos are useful because they are an organized way for the community to share Mynewt packages and projects. In fact, the Mynewt-core is distributed as a repo.</p>
<p><br></p>
<h3 id="why-does-mynewt-need-additional-repos">Why does Mynewt need additional repos?</h3>
<p>Repos add functionality not included in the Mynewt core. New repos might be created for several reasons.</p>
<ul>
<li><strong>Expertise</strong>. Individuals or organizations may have expertise that they want
to share in the form of repos. For example a chip vendor may
create a repo to hold the Mynewt support for their chips.</li>
<li><strong>Non-Core component</strong>. Some components, although very useful to Mynewt users
are not core to all Mynewt users. These are likely candidates to be held in
different repos.</li>
<li><strong>Software licensing</strong>. Some software have licenses that make them incompatible
with the ASF (Apache Software Foundation) license policies. These may be
valuable components to some Mynewt users, but cannot be contained in the <code>apache-Mynewt-core</code>.</li>
</ul>
<p><br></p>
<h3 id="what-repos-are-in-my-project">What Repos are in my Project</h3>
<p>The list of repos used by your project are contained within the
<code>project.yml</code> file. An example can be seen by creating a new project:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ mkdir ~/dev
$ cd ~/dev
$ newt new myproj
$ cd myproj
</code></pre></div>
<p><br></p>
<p>View the <code>project.yml</code> section and you will see a line describing the repos:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>project.repositories:
- apache-Mynewt-core
</code></pre></div>
<p><br> </p>
<p>By default, this newly created project uses a single repo called
<code>apache-Mynewt-core</code>. </p>
<p>If you wish to add additional repos, you would add
additional lines to the <code>project.repositories</code> variable like this.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>project.repositories:
- apache-Mynewt-core
<span style="background-color: #ffffcc"> - another_repo_named_x
</span></code></pre></div>
<p><br></p>
<h3 id="repo-descriptors">Repo Descriptors</h3>
<p>In addition to the repo name, the <code>project.yml</code> file must also contain
a repo descriptor for each repository you include that gives <code>newt</code>
information on obtaining the repo.</p>
<p>In the same <code>myproj</code> above you will see the following repo descriptor.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>repository.apache-Mynewt-core:
type: github
vers: 1-latest
user: apache
repo: incubator-mynewt-core
</code></pre></div>
<p>A repo descriptor starts with <code>repository.&lt;name&gt;.</code>. In this example, the
descriptor specifies the information for the <code>apache-Mynewt-core</code>.</p>
<p><br></p>
<p>The fields within the descriptor have the following definitions:</p>
<ul>
<li>
<p><strong>type</strong> -- The type of code storage the repo uses. The current version
of <code>newt</code> only supports github. Future versions may support generic git or other
code storage mechanisms.</p>
</li>
<li>
<p><strong>vers</strong> -- The version of the repo to use for your project. A source
code repository contains many versions of the source. This field is used to
specify the one to use for this project. See the section on versions below
for a detailed description of the format of this field.</p>
</li>
<li>
<p><strong>user</strong> -- The username for the repo. On github, this is the name
after <code>github.com</code> in the repo path. Consider the repository
<code>https://github.com/apache/incubator-mynewt-core</code>. It has username <code>apache</code>. </p>
</li>
<li>
<p><strong>repo</strong> -- The name of the repo. On github, this is the name after
the username described above. Consider the repository
<code>https://github.com/apache/incubator-mynewt-core</code>. It has path
<code>incubator-mynewt-core</code>. This is a path to the source control
and should not be confused with the name of the repo that you used in the
<code>repository.&lt;name&gt;</code> declaration above. That name is contained elsewhere
within the repo. See Below.</p>
</li>
</ul>
<p><br></p>
<h3 id="adding-existing-repos-to-my-project">Adding Existing Repos to my Project</h3>
<p>To add a new repo to your project, you have to complete two steps.</p>
<ul>
<li>
<p>Edit the <code>project.yml</code> file and add a new repo descriptor. The previous
section includes information on the field required in your repo descriptor.</p>
</li>
<li>
<p>Edit the <code>project/yml</code> file and add a new line to the <code>project.repositories</code>
variable with the name of the repo you are adding. </p>
</li>
</ul>
<p>An example of a <code>project.yml</code> file with two repositories is shown below:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>project.name: &quot;my_project&quot;
project.repositories:
- apache-Mynewt-core
- Mynewt_arduino_zero
# 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
# a special repo to hold hardware specific stuff for arduino zero
repository.Mynewt_arduino_zero:
type: github
vers: 1-latest
user: runtimeco
repo: Mynewt_arduino_zero
</code></pre></div>
<p><br></p>
<h3 id="what-version-of-the-repo-to-use">What Version of the Repo to use</h3>
<p>Mynewt repos are version-ed artifacts. They are stored in source control
systems like github. The repo descriptor in your <code>project.yml</code> file must
specify the version of the repo you will accept into your project.</p>
<p>For now, we are at the beginnings of Mynewt. For testing and evaluation
please use <code>1-latest</code> in the <code>vers</code> field in your repo descriptor.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code> vers:1-latest
</code></pre></div>
<p>See <a href="create_repo">Create a Repo</a> for a description of the versioning system and all the possible ways to specify a version to use.</p>
<p><br></p>
<h3 id="identifying-a-repo">Identifying a Repo</h3>
<p>A repo contains Mynewt packages organized in a specific way and stored in one of the supported code storage methods described above. In other words, it is a Mynewt project with an additional file <code>repository.yml</code> which describes the repo for use by <code>newt</code> (and humans browsing them). It contains a mapping of version numbers to the actual github branches containing the source code.</p>
<p>Note that the <code>repository.yml</code> file lives only in the master branch of the git
repository. <code>Newt</code> will always fetch this file from the master branch and then
use that to determine the actual branch required depending on the version
specified in your <code>project.yml</code> file. Special care should be taken to ensure that this file exists only in the master branch.</p>
<p>Here is the <code>repository.yml</code> file from the apache-Mynewt-core:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>repo.name: apache-mynewt-core
repo.versions:
&quot;0.0.0&quot;: &quot;master&quot;
&quot;0.0.1&quot;: &quot;master&quot;
&quot;0.7.9&quot;: &quot;mynewt_0_8_0_b2_tag&quot;
&quot;0.8.0&quot;: &quot;mynewt_0_8_0_tag&quot;
&quot;0.9.0&quot;: &quot;mynewt_0_9_0_tag&quot;
&quot;0.9.9&quot;: &quot;mynewt_1_0_0_b1_tag&quot;
&quot;0.9.99&quot;: &quot;mynewt_1_0_0_b2_tag&quot;
&quot;0.9.999&quot;: &quot;mynewt_1_0_0_rc1_tag&quot;
&quot;1.0.0&quot;: &quot;mynewt_1_0_0_tag&quot;
&quot;0-latest&quot;: &quot;1.0.0&quot; # 1.0.0
&quot;0-dev&quot;: &quot;0.0.0&quot; # master
&quot;0.8-latest&quot;: &quot;0.8.0&quot;
&quot;0.9-latest&quot;: &quot;0.9.0&quot;
&quot;1.0-latest&quot;: &quot;1.0.0&quot; # 1.0.0
</code></pre></div>
<p><br></p>
<p>It contains the following:</p>
<ul>
<li><strong>repo.name</strong> The external name that is used to include the library in
your <code>project.yml</code> file. This is the name you in include in the <code>project.repositories</code> variable when adding this repository to your project.</li>
<li><strong>repo.versions</strong> A description of what versions to give the user depending
on the settings in their <code>project.yml</code> file. </li>
</ul>
<p><br></p>
<h3 id="repo-version">Repo Version</h3>
<p>The repo version number resolves to an actual git branch depending on the mapping specified in <code>repository.yml</code> for that repo. The version field argument in your <code>project.yml</code> file supports multiple formats for flexibility:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>&lt;major_num&gt;.&lt;minor_num&gt;.&lt;revision_num&gt;
</code></pre></div>
<p>or</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>&lt;major_num&gt;.&lt;minor_num&gt;-&lt;stability string&gt;
</code></pre></div>
<p>or </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>&lt;major_num&gt;-&lt;stability string&gt;
</code></pre></div>
<p><br></p>
<p>The stability string can be one of 3 pre-defined stability values.</p>
<ol>
<li>stable -- A stable release version of the repository</li>
<li>dev -- A development version from the repository</li>
<li>latest -- The latest from the repository</li>
</ol>
<p>In your <code>project.yml</code> file you can specify different combinations of
the version number and stability value. For example:</p>
<ul>
<li><code>1-latest</code> -- The latest version with major number 1</li>
<li><code>1.2-stable</code> -- The latest stable version with major and minor number 1.2</li>
<li><code>1.2-dev</code> -- The development version from 1.2</li>
<li><code>1.1.1</code> -- a specific version 1.1.1</li>
</ul>
<p>You cannot specify a stability string with a fully numbered version, e.g.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>1.2.8-stable
</code></pre></div>
<p><br></p>
<h3 id="repo-versions-available">Repo Versions Available</h3>
<p>A <code>repository.yml</code> file contains information to match a version request
into a git branch to fetch for your project.</p>
<p>It's up to the repository maintainer to map these to branches of the
repository. For example, let's say in a fictitious repository the following are
defined.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>repo.versions:
&quot;0.8.0&quot;: &quot;xxx_branch_0_8_0&quot;
&quot;1.0.0&quot;: &quot;xxx_branch_1_0_0&quot;
&quot;1.0.2&quot;: &quot;xxx_branch_1_0_2&quot;
&quot;1.1.1&quot;: &quot;xxx_branch_1_1_0&quot;
&quot;1.1.2&quot;: &quot;xxx_branch_1_1_2&quot;
&quot;1.2.0&quot;: &quot;xxx_branch_1_2_0&quot;
&quot;1.2.1&quot;: &quot;xxx_branch_1_2_1&quot;
&quot;1.2-dev&quot;: &quot;1.2.1&quot;
&quot;1-dev&quot;: &quot;1.2-dev&quot;
&quot;1.2-stable&quot;: &quot;1.2.0&quot;
&quot;0-latest&quot;: &quot;0.8.0&quot;
&quot;1-latest&quot;: &quot;1-dev&quot;
....
</code></pre></div>
<p>When the <code>project.yml</code> file asks for <code>1.2-stable</code> it is resolved to version
<code>1.2.0</code> (perhaps <code>1.2.1</code> is not stable yet), which in turn resolves to a specific
branch <code>xxx_branch_1_2_0</code>. This is the branch that <code>newt</code> fetches into
your project. </p>
<p><strong>Note:</strong> Make sure a repo version exists in the <code>repository.yml</code> file of a repo you wish to add. Otherwise Newt will not be able to resolve the version and will fail to fetch the repo into your project.</p>
<p><br></p>
<h3 id="how-to-find-out-what-repos-are-available-for-mynewt-components">How to find out what Repos are available for Mynewt components</h3>
<p>Currently, there is no <code>newt</code> command to locate/search Mynewt package
repositories. However, since the <code>newt</code> tool supports only github,
searching github by keyword is a satisfactory option until a search
tool is created.</p>
<p>When searching github, recall that a Mynewt repository must
have a <code>repository.yml</code> file in its root directory. If you don't see
that file, it's not a Mynewt repository and can't be included in your
project via the newt tool. </p>
<p>Once you find a repository, the github URL and <code>repository.yml</code> file
should give you all the information to add it to your <code>project.yml</code> file.</p>
<p><br></p>
<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 (incubating) 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>