You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/12/21 01:07:45 UTC
[2/2] incubator-mynewt-site git commit: updated newt_operation.md doc
to reflect recent changes
updated newt_operation.md doc to reflect recent changes
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/8436efc0
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/8436efc0
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/8436efc0
Branch: refs/heads/master
Commit: 8436efc0de05827efa4d9b37aa502c2da3a60394
Parents: b5ea890
Author: aditihilbert <ad...@runtime.io>
Authored: Mon Dec 19 17:06:59 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Mon Dec 19 22:29:54 2016 -0800
----------------------------------------------------------------------
docs/newt/newt_operation.md | 84 +++++++++++++++++++---------------------
1 file changed, 39 insertions(+), 45 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/8436efc0/docs/newt/newt_operation.md
----------------------------------------------------------------------
diff --git a/docs/newt/newt_operation.md b/docs/newt/newt_operation.md
index 2f23310..82a3b15 100644
--- a/docs/newt/newt_operation.md
+++ b/docs/newt/newt_operation.md
@@ -37,31 +37,39 @@ When Newt sees a directory tree that contains a "project.yml" file it knows that
#### "apps" Package Directory
-`apps` is where applications are stored, and applications are where the main() function is contained. Along with the `targets` directory, `apps` represents the top-level of the build tree, and define the dependencies and features for the rest of the system.
+`apps` is where applications are stored, and applications are where the main() function is contained. The base project directory comes with one simple app called `blinky` in the `apps` directory. The core repository `@apache-mynewt-core` comes with many additional sample apps in its `apps` directory. At the time of this writing, there are several example BLE apps, the boot app, slinky app for using newt manager protocol, and more in that directory.
-The app definition is contained in a `pkg.yml` file. An example of blinky's `pkg.yml` file is:
+```
+@~/dev/myproj$ ls repos/apache-mynewt-core/apps/
+blecent bleprph_oic bleuart ffs2native slinky_oic test
+blehci bletest boot ocf_sample spitest timtest
+bleprph bletiny fat2native slinky splitty
+```
+
+Along with the `targets` directory, `apps` represents the top-level of the build tree for the particular project, and define the dependencies and features for the rest of the system. Mynewt users and developers can add their own apps to the project's `apps` directory.
+
+The app definition is contained in a `pkg.yml` file. For example, blinky's `pkg.yml` file is:
```
$ more apps/blinky/pkg.yml
<snip>
pkg.name: apps/blinky
-pkg.vers: 0.8.0
+pkg.type: app
pkg.description: Basic example application which blinks an LED.
pkg.author: "Apache Mynewt <de...@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"
+ - "@apache-mynewt-core/kernel/os"
+ - "@apache-mynewt-core/hw/hal"
+ - "@apache-mynewt-core/sys/console/full"
```
<br>
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.
+depends on kernel/os, hw/hal and sys/console/full packages.
**NOTE:** @apache-mynewt-core is a repository descriptor, and this will be
covered in the "repository" section.
@@ -78,7 +86,7 @@ Most targets consist of:
* bsp: The board support package to combine with that application
* build_profile: Either debug or optimized.
-The `my_blinky_sim` target in the example below has the following settings:
+The `my_blinky_sim` target that is included by default has the following settings:
```
$ newt target show
@@ -86,16 +94,19 @@ targets/my_blinky_sim
app=apps/blinky
bsp=@apache-mynewt-core/hw/bsp/native
build_profile=debug
-$ ls my_blinky_sim/
+$ ls targets/my_blinky_sim/
pkg.yml target.yml
```
+There are helper functions to aid the developer specify parameters for a target.
+
+* **vals**: Displays all valid values for the specified parameter type (e.g. bsp for a target)
+* **target show**: Displays the build artifacts for specified or all targets
In general, the three basic parameters of a target (`app`, `bsp`, and `build_profile`) are stored in the `target.yml` file in that target's build directory under `targets`. You will also see a `pkg.yml` file in the same directory. Since targets are packages, a `pkg.yml` is expected. It contains typical package descriptors, dependencies, and additional parameters such as the following:
* Cflags: Any additional compiler flags you might want to specify to the build
* Aflags: Any additional assembler flags you might want to specify to the build
* Lflags: Any additional linker flags you might want to specify to the build
-* features: Any system level features you want to enable.
<br>
@@ -180,14 +191,6 @@ $ tree
implement, (i.e. pkg.api: hw-hal-impl), and other packages can require
those APIs (i.e. pkg.req_api: hw-hal-impl).
-- "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."
-
-```
-pkg.cflags.SHELL: -DSHELL_PRESENT
-```
-
-<br>
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.
@@ -246,45 +249,36 @@ As you can see, a number of files are generated:
Once a target has been build, there are a number of helper functions
that work on the target. These are:
-* **download** Download built target to board
+* **load** Download built target to board
* **debug** Open debugger session to target
-* size Size of target components
-* create-image Add image header to target binary
+* **size** Size of target components
+* **create-image** Add image header to target binary
+* **run** The equivalent of build, create-image, load, and debug on specified target
-Download and debug handles driving GDB and the system debugger. These
+`load` and `debug` handles driving GDB and the system debugger. These
commands call out to scripts that are defined by the BSP.
```
-$ more repos/apache-mynewt-core/hw/bsp/nrf52pdk/nrf52pdk_debug.sh
+$ more repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_debug.sh
<snip>
-#
-if [ $# -lt 1 ]; then
- echo "Need binary to download"
- exit 1
-fi
+. $CORE_PATH/hw/scripts/jlink.sh
-FILE_NAME=$2.elf
-GDB_CMD_FILE=.gdb_cmds
+FILE_NAME=$BIN_BASENAME.elf
-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
+if [ $# -gt 2 ]; then
+ SPLIT_ELF_NAME=$3.elf
+ # TODO -- this magic number 0x42000 is the location of the second image
+ # slot. we should either get this from a flash map file or somehow learn
+ # this from the image itself
+ EXTRA_GDB_CMDS="add-symbol-file $SPLIT_ELF_NAME 0x8000 -readnow"
+fi
-echo "target remote localhost:3333" > $GDB_CMD_FILE
+JLINK_DEV="nRF52"
-arm-none-eabi-gdb -x $GDB_CMD_FILE $FILE_NAME
+jlink_debug
-rm $GDB_CMD_FILE
```
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.
-**NOTE:** 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.
-