| <!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>Newt Theory of Ops - 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="Newt Theory of Ops"> |
| |
| |
| <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" > |
| Version: 1.0.0 |
| </option> |
| <option value="/v0_9_0/os/introduction" selected="selected" > |
| 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 ><a href="../newt_intro/">Newt Tool Guide</a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| <li class="active"> |
| <a href="./">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=" |
| ../../faq/how_to_edit_docs/ |
| ">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>» <a href="newt/newt_intro/">Newt Tool Guide</a></li> |
| |
| |
| |
| <li>» <a href="os/introduction/">Mynewt Documentation</a></li> |
| |
| |
| |
| <li>» Newt Theory of Ops</li> |
| |
| |
| |
| </ul> |
| </div> |
| </div> |
| |
| |
| |
| |
| <div class="alert alert-warning"> |
| <p> |
| Version 0.9.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-theory-of-operations">Newt Tool - Theory of Operations</h2> |
| <p>Newt has a fairly smart package manager that can read a directory tree, build a dependency tree, and emit the right build artifacts.</p> |
| <h3 id="building-dependencies">Building dependencies</h3> |
| <p>Newt can read a directory tree, build a dependency tree, and emit the right build artifacts. An example newt source tree is in incubator-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 knows that it is in the base directory of a project, and automatically builds a package tree. You can see that there are two essential package directories, "apps" and "targets." </p> |
| <p><br></p> |
| <h4 id="apps-package-directory">"apps" Package Directory</h4> |
| <p><code>apps</code> is where applications are stored, and applications are where the main() function is contained. Along with the <code>targets</code> directory, <code>apps</code> represents the top-level of the build tree, and define the dependencies and features for the rest of the system.</p> |
| <p>The app definition is contained in a <code>pkg.yml</code> file. An example of blinky's <code>pkg.yml</code> file is:</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ more apps/blinky/pkg.yml |
| <snip> |
| pkg.name: apps/blinky |
| pkg.vers: 0.8.0 |
| pkg.description: Basic example application which blinks an LED. |
| pkg.author: "Apache Mynewt <dev@mynewt.incubator.apache.org>" |
| pkg.homepage: "http://mynewt.apache.org/" |
| pkg.repository: |
| pkg.keywords: |
| |
| pkg.deps: |
| - "@apache-mynewt-core/libs/os" |
| - "@apache-mynewt-core/hw/hal" |
| - "@apache-mynewt-core/libs/console/full" |
| </code></pre></div> |
| |
| <p><br></p> |
| <p>This file says that the name of the package is apps/blinky, and it |
| depends on libs/os, hw/hal and libs/console/full packages.</p> |
| <p><strong>NOTE:</strong> @apache-mynewt-core is a repository descriptor, and this will be |
| covered in the "repository" section. </p> |
| <p><br></p> |
| <h4 id="targets-package-directory">"targets" Package Directory</h4> |
| <p><code>targets</code> is where targets are stored, and each target is a collection of parameters that must be passed to Newt in order to generate a reproducible build. Along with the <code>apps</code> directory, <code>targets</code> represents the top of the build tree. Any packages or parameters specified at the target level cascades down to all dependencies.</p> |
| <p>Most targets consist of:</p> |
| <ul> |
| <li>app: The application to build</li> |
| <li>bsp: The board support package to combine with that application</li> |
| <li>build_profile: Either debug or optimized.</li> |
| </ul> |
| <p>The <code>my_blinky_sim</code> target in the example below has the following settings:</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt target show |
| targets/my_blinky_sim |
| app=apps/blinky |
| bsp=@apache-mynewt-core/hw/bsp/native |
| build_profile=debug |
| $ ls my_blinky_sim/ |
| pkg.yml target.yml |
| </code></pre></div> |
| |
| <p>In general, the three basic parameters of a target (<code>app</code>, <code>bsp</code>, and <code>build_profile</code>) are stored in the <code>target.yml</code> file in that target's build directory under <code>targets</code>. You will also see a <code>pkg.yml</code> file in the same directory. Since targets are packages, a <code>pkg.yml</code> is expected. It contains typical package descriptors, dependencies, and additional parameters such as the following:</p> |
| <ul> |
| <li>Cflags: Any additional compiler flags you might want to specify to the build</li> |
| <li>Aflags: Any additional assembler flags you might want to specify to the build</li> |
| <li>Lflags: Any additional linker flags you might want to specify to the build</li> |
| <li>features: Any system level features you want to enable.</li> |
| </ul> |
| <p><br></p> |
| <h3 id="resolving-dependencies">Resolving dependencies</h3> |
| <p>When newt is told to build a project, it will:</p> |
| <ul> |
| <li>find the top-level project.yml file</li> |
| <li>recurse the packages in the package tree, and build a list of all |
| source packages</li> |
| </ul> |
| <p>Newt then looks at the target that the user set, for example, blinky_sim:</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ more targets/my_blinky_sim/ |
| pkg.yml target.yml |
| $ more targets/my_blinky_sim/target.yml |
| ### Target: targets/my_blinky_sim |
| target.app: "apps/blinky" |
| target.bsp: "@apache-mynewt-core/hw/bsp/native" |
| target.build_profile: "debug" |
| </code></pre></div> |
| |
| <p><br></p> |
| <p>The target specifies two major things:</p> |
| <ul> |
| <li>Application (target.app): The application to build</li> |
| <li>Board Support Package (target.bsp): The board support package to build |
| along with that application.</li> |
| </ul> |
| <p>Newt goes and builds the dependency tree specified by all the packages. While building this tree, it does a few other things:</p> |
| <ul> |
| <li>Any package that depends on another package, automatically gets the include directories from the package it includes. Include directories in the |
| newt structure must always be prefixed by the package name. For example, libs/os has the following include tree and its include directory files contains the package name "os" before any header files. This is so in order to avoid any header file conflicts.</li> |
| </ul> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ tree |
| . |
| ├── README.md |
| ├── include |
| │ └── os |
| │ ├── arch |
| │ │ ├── cortex_m0 |
| │ │ │ └── os |
| │ │ │ └── os_arch.h |
| │ │ ├── cortex_m4 |
| │ │ │ └── os |
| │ │ │ └── os_arch.h |
| │ │ └── sim |
| │ │ └── os |
| │ │ └── os_arch.h |
| │ ├── endian.h |
| │ ├── os.h |
| │ ├── os_callout.h |
| │ ├── os_cfg.h |
| │ ├── os_eventq.h |
| │ ├── os_heap.h |
| │ ├── os_malloc.h |
| │ ├── os_mbuf.h |
| │ ├── os_mempool.h |
| │ ├── os_mutex.h |
| │ ├── os_sanity.h |
| │ ├── os_sched.h |
| │ ├── os_sem.h |
| │ ├── os_task.h |
| │ ├── os_test.h |
| │ ├── os_time.h |
| │ └── queue.h |
| ├── pkg.yml |
| └── src |
| ├── arch |
| <snip> |
| </code></pre></div> |
| |
| <p><br></p> |
| <ul> |
| <li> |
| <p>API requirements are validated. Packages can export APIs they |
| implement, (i.e. pkg.api: hw-hal-impl), and other packages can require |
| those APIs (i.e. pkg.req_api: hw-hal-impl).</p> |
| </li> |
| <li> |
| <p>"Features" options are supported. Packages can change what dependencies |
| they have, or what flags they are using based upon what features are enabled in the system. As an example, many packages will add additional software, based on whether the shell package is present. To do this, they can overwrite cflags or deps based upon the shell "feature."</p> |
| </li> |
| </ul> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>pkg.cflags.SHELL: -DSHELL_PRESENT |
| </code></pre></div> |
| |
| <p><br></p> |
| <p>In order to properly resolve all dependencies in the build system, Newt recursively processes the package dependencies until there are no new dependencies or features (because features can add dependencies.) And it builds a big list of all the packages that need to be build.</p> |
| <p>Newt then goes through this package list, and builds every package into |
| an archive file.</p> |
| <p><strong>NOTE:</strong> The Newt tool generates compiler dependencies for all of these packages, and only rebuilds the packages whose dependencies have changed. Changes in package & project dependencies are also taken into account. It is smart, after all!</p> |
| <h3 id="producing-artifacts">Producing artifacts</h3> |
| <p>Once Newt has built all the archive files, it then links the archive files together. The linkerscript to use is specified by the board support package (BSP.)</p> |
| <p>NOTE: One common use of the "features" option above is to overwrite |
| which linkerscript is used, based upon whether or not the BSP is being |
| build for a raw image, bootable image or bootloader itself.</p> |
| <p>The newt tool places all of it's artifacts into the bin/ directory at |
| the top-level of the project, prefixed by the target name being built, |
| for example:</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ tree -L 4 bin/ |
| bin/ |
| └── my_blinky_sim |
| ├── apps |
| │ └── blinky |
| │ ├── blinky.a |
| │ ├── blinky.a.cmd |
| │ ├── blinky.elf |
| │ ├── blinky.elf.cmd |
| │ ├── blinky.elf.dSYM |
| │ ├── blinky.elf.lst |
| │ ├── main.d |
| │ ├── main.o |
| │ └── main.o.cmd |
| ├── hw |
| │ ├── bsp |
| │ │ └── native |
| │ ├── hal |
| │ │ ├── flash_map.d |
| │ │ ├── flash_map.o |
| <snip> |
| </code></pre></div> |
| |
| <p><br></p> |
| <p>As you can see, a number of files are generated:</p> |
| <ul> |
| <li>Archive File</li> |
| <li>*.cmd: The command use to generate the object or archive file</li> |
| <li>*.lst: The list file where symbols are located</li> |
| <li>*.o The object files that get put into the archive file</li> |
| </ul> |
| <h3 id="downloaddebug-support">Download/Debug Support</h3> |
| <p>Once a target has been build, there are a number of helper functions |
| that work on the target. These are:</p> |
| <ul> |
| <li><strong>download</strong> Download built target to board</li> |
| <li><strong>debug</strong> Open debugger session to target</li> |
| <li>size Size of target components</li> |
| <li>create-image Add image header to target binary</li> |
| </ul> |
| <p>Download and debug handles driving GDB and the system debugger. These |
| commands call out to scripts that are defined by the BSP.</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ more repos/apache-mynewt-core/hw/bsp/nrf52pdk/nrf52pdk_debug.sh |
| <snip> |
| # |
| if [ $# -lt 1 ]; then |
| echo "Need binary to download" |
| exit 1 |
| fi |
| |
| FILE_NAME=$2.elf |
| GDB_CMD_FILE=.gdb_cmds |
| |
| echo "Debugging" $FILE_NAME |
| |
| # Monitor mode. Background process gets it's own process group. |
| set -m |
| JLinkGDBServer -device nRF52 -speed 4000 -if SWD -port 3333 -singlerun & |
| set +m |
| |
| echo "target remote localhost:3333" > $GDB_CMD_FILE |
| |
| arm-none-eabi-gdb -x $GDB_CMD_FILE $FILE_NAME |
| |
| rm $GDB_CMD_FILE |
| </code></pre></div> |
| |
| <p>The idea is that every BSP will add support for the debugger environment |
| for that board. That way common tools can be used across various development boards and kits.</p> |
| <p><strong>NOTE:</strong> Both for compiler definitions and debugger scripts, the plan is to |
| create Dockerizable containers of these toolchains. This should make |
| things much easier to support across Mac OS X, Linux and Windows. Newt |
| will know how to call out to Docker to perform these processes.</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> |
