1) Updated Newt Intro, Newt Theory of Ops, Newt Command Intro. 2) Updated newt command documentation. 3) Removed newt complete 4) Added newt pkg (also uses copy (instead of ) clone). 5) Added newt sync 6) Removed outdated "feature" from docs.
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/c95710ac Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/c95710ac Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/c95710ac Branch: refs/heads/develop Commit: c95710accf32039bea1943646a893bc5e76c805d Parents: 7a428ec Author: cwanda <[email protected]> Authored: Mon Feb 27 00:36:14 2017 -0800 Committer: cwanda <[email protected]> Committed: Mon Feb 27 21:35:03 2017 -0800 ---------------------------------------------------------------------- docs/newt/command_list/newt_build.md | 34 +++-- docs/newt/command_list/newt_clean.md | 33 ++--- docs/newt/command_list/newt_create_image.md | 29 ++-- docs/newt/command_list/newt_debug.md | 25 ++-- docs/newt/command_list/newt_help.md | 48 +++---- docs/newt/command_list/newt_info.md | 17 +-- docs/newt/command_list/newt_install.md | 21 +-- docs/newt/command_list/newt_load.md | 24 ++-- docs/newt/command_list/newt_mfg.md | 24 ++-- docs/newt/command_list/newt_new.md | 25 ++-- docs/newt/command_list/newt_pkg.md | 43 ++++++ docs/newt/command_list/newt_run.md | 29 ++-- docs/newt/command_list/newt_size.md | 23 ++-- docs/newt/command_list/newt_sync.md | 24 ++++ docs/newt/command_list/newt_target.md | 67 ++++----- docs/newt/command_list/newt_test.md | 32 ++--- docs/newt/command_list/newt_upgrade.md | 25 ++-- docs/newt/command_list/newt_vals.md | 47 +++---- docs/newt/command_list/newt_version.md | 21 ++- docs/newt/newt_intro.md | 66 +++++---- docs/newt/newt_operation.md | 164 +++++++++++++---------- docs/newt/newt_ops.md | 14 +- mkdocs.yml | 3 +- 23 files changed, 454 insertions(+), 384 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_build.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_build.md b/docs/newt/command_list/newt_build.md index c785074..b11a19d 100644 --- a/docs/newt/command_list/newt_build.md +++ b/docs/newt/command_list/newt_build.md @@ -1,36 +1,32 @@ ## <font color="#F2853F" style="font-size:24pt">newt build </font> -Compiles, links, and builds one or more apps. +Build one or more targets. #### Usage: ```no-highlight - newt build [flags] input1 -``` - -where `input1` is the name of the target to build. - -#### Flags: - -```no-highlight - -h, --help=false: help for target + newt build <target-name> [target_name ...] [flags] ``` #### Global Flags: - ```no-highlight - -l, --loglevel="WARN": Log level, defaults to WARN. - -o, --outfile string Filename to tee log output to - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` +#### Description +Compiles, links, and builds an ELF binary for the target named <target-name>. It builds an ELF file for the application specified by the `app` variable for the `target-name` target. The image can be loaded and run on the hardware specified by the `bsp` variable for the target. The command creates the 'bin/' directory under the project's base directory (that the `newt new` command created) and stores the executable in the 'bin/targets/<target-name>/app/apps/<app-name>' directory. + +You can specify a list of target names, separated by a space, to build multiple targets. #### Examples Sub-command | Usage | Explanation -------------| -----------------------|----------------- -build | newt build <br> `input1` | Builds the source code into an image that can be loaded on the hardware (`bsp`) associated with the target named `input1` to run the application enabled by the `app` setting associated with that target. It creates 'bin/' directory and 'bin/<input1>/apps/<app>' subdirectory inside the base directory for the app, compiles and generates binaries and executables, and places them in that subdirectory. - | newt build <br> my_blinky_sim | For example, if `app` was set to `apps/blinky` for the target "my_blinky_sim", you will find the generated .elf, .a, and .lst files in bin/my_blinky_sim/apps/blinky directory created under the base directory for the app created using `newt new` at the start of the project. -build | newt build my_blinky_sim myble | builds the apps defined for both the targets "my_blinky_sim" and "myble". + | newt build <br> my_blinky_sim | Builds an executable for the `my_blinky_sim` target. For example, if the `my_blinky_sim` target has `app` set to `apps/blinky`, you will find the generated .elf, .a, and .lst files in the 'bin/targets/my_blinky_sim/app/apps/blinky' directory. + | newt build <br> my_blinky_sim myble | Builds the images for the applications defined by the `my_blinky_sim` and `myble` targets. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_clean.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_clean.md b/docs/newt/command_list/newt_clean.md index a79c216..632b184 100644 --- a/docs/newt/command_list/newt_clean.md +++ b/docs/newt/command_list/newt_clean.md @@ -1,37 +1,32 @@ ## <font color="#F2853F" style="font-size:24pt">newt clean </font> -Deletes application build artifacts for a specified target +Delete build artifacts for one or more targets. #### Usage: ```no-highlight - newt clean [flags] input1 -``` - -#### Flags: - -```no-highlight - -h, --help=false: help for target + newt clean <target-name> [target-name...] | all [flags] ``` #### Global Flags: - ```no-highlight - -l, --loglevel="WARN": Log level, defaults to WARN. - -o, --outfile string Filename to tee log output to - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands + ``` #### Description -Sub-command | Explanation --------------| ------------------------ -clean | Deletes all the build artifacts generated for target specified by `input1`. It does not delete the target definition. - +Deletes all the build artifacts generated for the `target-name` target. It does not delete the target definition. You can specify a list of targets, separated by a space, to delete the artifacts for multiple targets, or specify `all` to delete the artifacts for all targets. #### Examples Sub-command | Usage | Explanation -------------| -----------------------|----------------- -clean | newt clean myble2 | Removes all the files generated while building the target `myble2` and placed in the `bin/myble2` directory created during the build process. + | newt clean myble | Deletes the 'bin/targets/myble' directory where all the build artifacts generated from the `myble` target build are stored. + | newt clean my_blinky_sim myble | Deletes the 'bin/targets/my_blinky_sim' and the 'bin/targets/myble' directories where all the artifacts generated from the `my_blinky_sim` and `myble` target builds are stored. + | newt clean all | Removes the artifacts for all target builds. Deletes the top level 'bin' directory. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_create_image.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_create_image.md b/docs/newt/command_list/newt_create_image.md index d659a46..f4f3658 100644 --- a/docs/newt/command_list/newt_create_image.md +++ b/docs/newt/command_list/newt_create_image.md @@ -1,35 +1,32 @@ ## <font color="#F2853F" style="font-size:24pt">newt create-image </font> -Creates a signed image by adding image header to created binary file for specified target. Version number in the header is set to be <version> +Create and sign an image by adding an image header to the binary file created for a target. Version number in the header is set to <version>. To sign an image provide a .pem file for the signing-key and an optional key-id. #### Usage: ```no-highlight - newt create-image <target-name> <version> [flags] -``` - -#### Flags: -```no-highlight - -h, --help=false: help for target + newt create-image <target-name> <version> [signing-key [key-id]][flags] ``` #### Global Flags: ```no-highlight - -l, --loglevel="WARN": Log level, defaults to WARN. - -o, --outfile string Filename to tee log output to - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` #### Description -Sub-command | Explanation --------------| ------------------------ -create-image | Signs and adds image header to the created binary file for target named `<target-name>` and given the version specified as `<version>`. The application image generated is `<app-name>.img` where the app-name is the same as the app specified in the target definition. The generated application image can be found in `/bin/<target-name>/apps/<app-name>/`. <br> <br> A build manifest file `manifest.json` is also generated in the same directory. This build manifest contains information such as build time, version, image name, a hash to identify the image, packages actually used to create the build, and the target for which the image is built. +Adds an image header to the created binary file for the `target-name` target. The image version is set to `version`. It creates a `<app-name>.img` file for the image, where `app-name` is the value specified in the target `app` variable, and stores the file in the '/bin/targets/<target-name>/app/apps/<app-name>/' directory. A `manifest.json` build manifest file is also generated in the same directory. This build manifest contains information such as build time, version, image name, a hash to identify the image, packages actually used to create the build, and the target for which the image is built. +To sign an image, provide a .pem file for the `signing-key` and an optional `key-id`. `key-id` must be a value between 0-255. #### Examples Sub-command | Usage | Explanation -------------| -----------------------|----------------- -create-image | newt create-image myble2 1.0.1.0 | Creates a signed image for target `myble2` and assigns it the version `1.0.1.0`. <br> <br> If the target is as follows: <br> targets/myble2 <br> app=@apache-mynewt-core/apps/bletiny <br> bsp=@apache-mynewt-core/hw/bsp/nrf52pdk <br> build_profile=optimized <br> cflags=-DSTATS_NAME_ENABLE <br> <br> then, the created image is `bin/myble2/apps/bletiny/bletiny.img` and the manifest is `bin/myble2/apps/bletiny/manifest.json` + | newt create-image myble2 1.0.1.0 | Creates an image for target `myble2` and assigns it version `1.0.1.0`. <br> <br> For the following target definition: <br> targets/myble2 <br> app=@apache-mynewt-core/apps/bletiny <br> bsp=@apache-mynewt-core/hw/bsp/nrf52pdk <br> build_profile=optimized <br> cflags=-DSTATS_NAME_ENABLE <br> <br> the created image is 'bin/targets/myble2/app/apps/bletiny/bletiny.img' and the manifest is 'bin/targets/myble2/app/apps/bletiny/manifest.json' + | newt create-image myble2 1.0.1.0 private.pem | Creates an image for target `myble2` and assigns it the version `1.0.1.0`. Signs the image using private key specified by the private.pem file. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_debug.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_debug.md b/docs/newt/command_list/newt_debug.md index 25725ee..b433307 100644 --- a/docs/newt/command_list/newt_debug.md +++ b/docs/newt/command_list/newt_debug.md @@ -1,35 +1,36 @@ ## <font color="#F2853F" style="font-size:24pt">newt debug </font> -Opens debugger session for specified target. +Open a debugger session to a target. #### Usage: ```no-highlight newt debug <target-name> [flag] ``` - #### Flags: ```no-highlight - -h, --help=false: help for target + --extrajtagcmd string Extra commands to send to JTAG software + -n, --noGDB Do not start GDB from command line ``` #### Global Flags: ```no-highlight - -l, --loglevel="WARN": Log level, defaults to WARN. - -o, --outfile string Filename to tee log output to - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` #### Description -Sub-command | Explanation --------------| ------------------------ -debug | Opens the appropriate debugging session for the image built for the named target. +Opens a debugger session to the image built for the <target-name> target. #### Examples Sub-command | Usage | Explanation -------------| -----------------------|----------------- -debug | newt debug myble2 | Opens J-Link connection and starts a GNU gdb session to debug bin/myble2/apps/bletiny/bletiny.elf when the target is as follows: <br> <br> targets/myble2 <br> app=@apache-mynewt-core/apps/bletiny <br> bsp=@apache-mynewt-core/hw/bsp/nrf52pdk <br> build_profile=optimized <br> cflags=-DSTATS_NAME_ENABLE \ No newline at end of file + | newt debug myble2 | Opens a J-Link connection and starts a GNU gdb session to debug bin/targets/myble2/app/apps/bletiny/bletiny.elf when the target is as follows: <br> <br> targets/myble2 <br> app=@apache-mynewt-core/apps/bletiny <br> bsp=@apache-mynewt-core/hw/bsp/nrf52pdk <br> build_profile=optimized <br> cflags=-DSTATS_NAME_ENABLE + | newt debug myble2 -n | Opens a J-Link connection bin/targets/myble2/app/apps/bletiny/bletiny.elf but do not start GDB on the command line. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_help.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_help.md b/docs/newt/command_list/newt_help.md index 1fbfc27..7db5675 100644 --- a/docs/newt/command_list/newt_help.md +++ b/docs/newt/command_list/newt_help.md @@ -1,9 +1,8 @@ ## <font color="#F2853F" style="font-size:24pt">newt help </font> -Displays the help text for the newt command line tool: +Display the help text for the newt command line tool: ```no-highlight - Newt allows you to create your own embedded application based on the Mynewt operating system. Newt provides both build and package management in a single tool, which allows you to compose an embedded application, and set of @@ -14,45 +13,48 @@ https://mynewt.apache.org/. #### Usage: ```no-highlight - newt help [input1] + newt help [command] ``` -#### Flags: +#### Global Flags: ```no-highlight - - -h, --help=false: help for newt + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") -o, --outfile string Filename to tee output to - -l, --loglevel="WARN": Log level, defaults to WARN. - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` #### Available Commands: - ```no-highlight - version Display the Newt version number. + build Build one or more targets + clean Delete build artifacts for one or more targets + create-image Add image header to target binary + debug Open debugger session to target + info Show project info install Install project dependencies - upgrade Upgrade project dependencies + load Load built target to board + mfg Manufacturing flash image commands new Create a new project - info Show project info + pkg Create and manage packages in the current workspace + run build/create-image/download/debug <target> + size Size of target components + sync Synchronize project dependencies target Command for manipulating targets - build Builds one or more targets. - clean Deletes build artifacts for one or more targets. test Executes unit tests for one or more packages - load Load built target to board - debug Open debugger session to target - size Size of target components - create-image Add image header to target binary - run build/create-image/download/debug <target> + upgrade Upgrade project dependencies + vals Display valid values for the specified element type(s) + version Display the Newt version number ``` #### Examples Sub-command | Usage | Explanation -------------| -----------------------|----------------- -help | newt help target | Displays the help text for the newt command 'target' -help | newt help | Displays the help text for newt tool + | newt help target | Displays the help text for the newt `target` command + | newt help | Displays the help text for newt tool http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_info.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_info.md b/docs/newt/command_list/newt_info.md index 3f1a066..3e2c209 100644 --- a/docs/newt/command_list/newt_info.md +++ b/docs/newt/command_list/newt_info.md @@ -1,6 +1,6 @@ ## <font color="#F2853F" style="font-size:24pt">newt info </font> -Shows information about the current project. +Show information about the current project. #### Usage: @@ -11,15 +11,16 @@ Shows information about the current project. #### Global Flags: ```no-highlight - -l, --loglevel="WARN": Log level, defaults to WARN. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") -o, --outfile string Filename to tee output to - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` + #### Description -Sub-command | Explanation --------------| ------------------------ -info | Displays the repositories in the current project (the local as well as all the external repositories fetched). Also displays the packages in the local repository. +Displays the repositories in the current project (the local as well as all the external repositories fetched). It also displays the packages in the local repository. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_install.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_install.md b/docs/newt/command_list/newt_install.md index 623d17e..9a56ad0 100644 --- a/docs/newt/command_list/newt_install.md +++ b/docs/newt/command_list/newt_install.md @@ -1,6 +1,6 @@ ## <font color="#F2853F" style="font-size:24pt">newt install </font> -Install project dependencies. +Install project dependencies. #### Usage: ```no-highlight @@ -9,21 +9,22 @@ Install project dependencies. #### Flags: ```no-highlight - -f, --force Force install of the repositories in project, regardless of what exists in repos directory + -f, --force Force install of the repositories in project, regardless of what exists in repos directory ``` #### Global Flags: ```no-highlight - -h, --help=false: help for newt + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") -o, --outfile string Filename to tee output to - -l, --loglevel="WARN": Log level, defaults to WARN. - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` #### Description -Sub-command | Explanation --------------| ------------------------ -install | Downloads description of all the repositories specified in the project.yml file of the current project directory. Installs all the correct versions of all the packages dictated by the project dependencies. <br> <br> Always run the command from within the project directory (i.e. remember to `cd` into the app directory after creating a new app using `newt new`) before running `newt install`. +This command downloads the description for all the repositories specified in the `project.yml` file for the current project, and installs the correct versions of all the packages specified by the project dependencies. + +You must run this command from within the current project directory. (Remember to `cd` into this project directory after you use `newt new` to create this project before you run `newt install`.) http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_load.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_load.md b/docs/newt/command_list/newt_load.md index e7fb2b9..ad77ca4 100644 --- a/docs/newt/command_list/newt_load.md +++ b/docs/newt/command_list/newt_load.md @@ -1,6 +1,6 @@ ## <font color="#F2853F" style="font-size:24pt">newt load </font> -Load app image to specified target. +Load application image onto the board for a target. #### Usage: @@ -8,20 +8,24 @@ Load app image to specified target. newt load <target-name> [flags] ``` + #### Flags: + ```no-highlight - -h, --help=false: help for target + --extrajtagcmd string Extra commands to send to JTAG software + ``` -#### Global Flags: + +### Global Flags: ```no-highlight - -l, --loglevel="WARN": Log level, defaults to WARN. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") -o, --outfile string Filename to tee output to - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` #### Description -Sub-command | Explanation --------------| ------------------------ -load | Uses download scripts to automatically load, onto the connected board, the image built for the app defined in the target specified by <target-name>. <br> <br> If the wrong board is connected, or the target definition is wrong (i.e. the wrong values are given for bsp or app), the command will fail with error messages such as `Can not connect to J-Link via USB` or `Unspecified error -1`. \ No newline at end of file +Uses download scripts to automatically load, onto the connected board, the image built for the app defined by the `target-name` target If the wrong board is connected or the target definition is incorrect (i.e. the wrong values are given for bsp or app), the command will fail with error messages such as `Can not connect to J-Link via USB` or `Unspecified error -1`. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_mfg.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_mfg.md b/docs/newt/command_list/newt_mfg.md index 7e6fe7d..4847fa0 100644 --- a/docs/newt/command_list/newt_mfg.md +++ b/docs/newt/command_list/newt_mfg.md @@ -1,6 +1,6 @@ ## <font color="#F2853F" style="font-size:24pt">newt mfg </font> -Provides commands to create, build, and upload manufacturing image. +Commands to create, build, and upload manufacturing image. #### Usage: @@ -12,30 +12,26 @@ Provides commands to create, build, and upload manufacturing image. ```no-highlight create Create a manufacturing flash image - deploy Builds and uploads a manufacturing image (build + load) + deploy Build and upload a manufacturing image (build + load) load Load a manufacturing flash image onto a device ``` -#### Flags: - -```no-highlight - -h, --help=false: help for mfg -``` - #### Global Flags: ```no-highlight - -l, --loglevel="WARN": Log level, defaults to WARN. - -o, --outfile string Filename to tee log output to - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` #### Description Sub-command | Explanation -------------| ------------------------ -create | A manufacturing image specifies 1) a boot loader target, and 2) one or more image targets. Assuming the manufacturing entity has been created and defined in the `mfgs/<mfg image name>/` package(see Examples below), this command collects the manufacturing related files in the newly created `bin/mfgs/<mfg image name>` directory. The collection includes manifests with the image build time, version, manufacturing package build time, image ID (or hash) etc. It is essentially a snapshot of the image data and metadata uploaded to the device flash at manufacturing time. Note that the command expects the targets and images to have already been built using `newt build` and `newt create-image` commands. +create | A manufacturing image specifies 1) a boot loader target, and 2) one or more image targets. Assuming the manufacturing entity has been created and defined in the `mfgs/<mfg image name>/` package (see Examples below), this command collects the manufacturing related files in the newly created `bin/mfgs/<mfg image name>` directory. The collection includes manifests with the image build time, version, manufacturing package build time, image ID (or hash) etc. It is essentially a snapshot of the image data and metadata uploaded to the device flash at manufacturing time. Note that the command expects the targets and images to have already been built using `newt build` and `newt create-image` commands. deploy | A combination of build and load commands to put together and upload manufacturing image on to the device. load | Loads the manufacturing package onto to the flash of the connected device. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_new.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_new.md b/docs/newt/command_list/newt_new.md index 511cbd3..638e9ca 100644 --- a/docs/newt/command_list/newt_new.md +++ b/docs/newt/command_list/newt_new.md @@ -1,31 +1,30 @@ ## <font color="#F2853F" style="font-size:24pt">newt new </font> -Create a new application, specified by <app-name>, from a given skeleton. Currently, the default skeleton is the [blinky repository](https://git-wip-us.apache.org/repos/asf/incubator-mynewt-blinky.git) in Apache Mynewt (or [https://github.com/apache/incubator-mynewt-blinky](https://github.com/apache/incubator-mynewt-blinky) on its github mirror.) +Create a new project from a skeleton. Currently, the default skeleton is the [blinky repository](https://git-wip-us.apache.org/repos/asf/incubator-mynewt-blinky.git) in Apache Mynewt (or [https://github.com/apache/incubator-mynewt-blinky](https://github.com/apache/incubator-mynewt-blinky) on its github mirror.) #### Usage: ```no-highlight - newt new [flags] <app-name> + newt new <project-name> [flags] ``` -#### Flags: -```no-highlight - -h, --help=false: help for new -``` #### Global Flags: ```no-highlight - -h, --help=false: help for newt + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") -o, --outfile string Filename to tee output to - -l, --loglevel="WARN": Log level, defaults to WARN. - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` +### Description +Creates a new project named `project-name` from the default skeleton [blinky repository](https://git-wip-us.apache.org/repos/asf/incubator-mynewt-blinky.git) in Apache Mynewt (or [https://github.com/apache/incubator-mynewt-blinky](https://github.com/apache/incubator-mynewt-blinky) on its github mirror.) + #### Examples Sub-command | Usage | Explanation -------------| -----------------------|----------------- -newt new | newt new test_project | Creates a new app named "test_project " using the default skeleton from the `apache/incubator-mynewt-blinky` repo. - + | newt new test_project | Creates a new project named `test_project` using the default skeleton from the `apache/incubator-mynewt-blinky` repository. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_pkg.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_pkg.md b/docs/newt/command_list/newt_pkg.md new file mode 100644 index 0000000..83c992d --- /dev/null +++ b/docs/newt/command_list/newt_pkg.md @@ -0,0 +1,43 @@ +## <font color="#F2853F" style="font-size:24pt">newt pkg </font> + +Commands for creating and manipulating packages. + +#### Usage: +```no-highlight + newt pkg [command] [flags] +``` +#### Flags: +```no-highlight + -t, --type string Type of package to create: pkg, bsp, sdk. (default "pkg") +``` +#### Global Flags: +```no-highlight + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands +``` +#### Description + +The pkg command provides subcommands to create and manage packages. The subcommands take one or two `package-name` arguments. + +Sub-command | Explanation +------------------------| ------------------------ +copy | The copy <src-pkg> <dst-pkg> command creates the new `dst-pkg` package by cloning the `src-pkg` package. +move | The move <old-pkg> <new-pkg> command moves the `old-pkg` package to the `new-pkg` package. +new | The new <new-pkg> command creates a new package named `new-pkg`, from a template, in the current directory. You can create a package of type `pkg`, `bsp`, or `sdk`. The default package type is `pkg`. You use the -t flag to specify a different package type. +remove | The remove <my-pkg> command deletes the `my-pkg` package. + +#### Examples + +Sub-command | Usage | Explanation +-------------| -----------------------|----------------- +copy | newt pkg copy <br>apps/bletiny apps/new_bletiny | Copies the `apps/bletiny` package to the `apps/new_bletiny`. +move | newt pkg move <br>apps/slinky apps/new_slinky | Moves the `apps/slinky` package to the `apps/new_slinky` package. +new | newt pkg new apps/new_slinky | Creates a package named `apps/new_slinky` of type `pkg` in the current directory. +new | newt pkg new hw/bsp/myboard -t bsp| Creates a package named `hw/bsp/myboard` of type `bsp` in the current directory. +remove | newt pkg remove hw/bsp/myboard | Removes the `hw/bsp/myboard` package. + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_run.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_run.md b/docs/newt/command_list/newt_run.md index 269c244..1b78b3e 100644 --- a/docs/newt/command_list/newt_run.md +++ b/docs/newt/command_list/newt_run.md @@ -1,8 +1,8 @@ ## <font color="#F2853F" style="font-size:24pt">newt run </font> -A single command to do four steps - build a target, create-image, load image on a board, and start a debug session with the image on board. +A single command to do four steps - build a target, create-image, load image on a board, and start a debug session with the image on the board. -**Note**: If version number is omitted, create-image step is skipped +**Note**: If the version number is omitted, the create-image step is skipped. #### Usage: @@ -12,28 +12,27 @@ A single command to do four steps - build a target, create-image, load image on #### Flags: ```no-highlight - -h, --help=false: help for target + --extrajtagcmd string Extra commands to send to JTAG software + -n, --noGDB Do not start GDB from the command line ``` #### Global Flags: ```no-highlight - -l, --loglevel="WARN": Log level, defaults to WARN. - -o, --outfile string Filename to tee log output to - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` #### Description - -Sub-command | Explanation --------------| ------------------------ -run | Same as running `build <target>`, `create-image <target> <version>`, `load <target>`, and `debug <target>`. - +Same as running `build <target-name>`, `create-image <target-name> <version>`, `load <target-name>`, and `debug <target-name>`. #### Examples Sub-command | Usage | Explanation -------------| -----------------------|----------------- -run | newt run blink_rigado | First compiles and builds executable for running the app defined in the target `blink_rigado` on the board defined in the same target, then loads image onto the board, and finally opens an active GNU gdb debugging session to run the image. -run | newt run ble_rigado 0.1.0.0 | First compiles and builds executable for running the app defined in the target `ble_rigado` on the board defined in the same target, then signs and creates image with version number 0.1.0.0, loads the image onto the board, and finally opens an active GNU gdb debugging session to run the image. <br> <br> Note that if there is no bootloader available for a particular board/kit, a signed image creation step is not necessary. \ No newline at end of file + | newt run blink_rigado | Compiles and builds the image for the `app` and the `bsp` defined for target `blink_rigado`, loads the image onto the board, and opens an active GNU gdb debugging session to run the image. + | newt run ble_rigado 0.1.0.0 | Compiles and builds the image for the `app` and the `bsp` defined for target `ble_rigado`, signs and creates the image with version number 0.1.0.0, loads the image onto the board, and opens an active GNU gdb debugging session to run the image. <br> <br> Note that if there is no bootloader available for a particular board/kit, a signed image creation step is not necessary. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_size.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_size.md b/docs/newt/command_list/newt_size.md index b345f4b..4804654 100644 --- a/docs/newt/command_list/newt_size.md +++ b/docs/newt/command_list/newt_size.md @@ -1,6 +1,6 @@ ## <font color="#F2853F" style="font-size:24pt">newt size </font> -Calculate the size of target components specified by <target-name> +Calculates the size of target components for a target. #### Usage: @@ -10,26 +10,31 @@ Calculate the size of target components specified by <target-name> #### Flags: ```no-highlight - -h, --help=false: help for target + -F, --flash Print FLASH statistics + -R, --ram Print RAM statistics ``` #### Global Flags: ```no-highlight - -l, --loglevel="WARN": Log level, defaults to WARN. - -o, --outfile string Filename to tee log output to - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` +#### Description +Displays the RAM and FLASH size of each component for the `target-name` target. #### Examples Sub-command | Usage | Explanation -------------| -----------------------|----------------- -size | newt size blink_rigado | Inspects and lists the RAM and Flash memory use by each component (object files and libraries) of the target. + | newt size blink_rigado | Inspects and lists the RAM and Flash memory that each component (object files and libraries) for the `blink_rigado` target. -#### Example output for `newt size boot_olimex`: +#### Example output for `newt size blink_rigado`: ```no-highlight http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_sync.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_sync.md b/docs/newt/command_list/newt_sync.md new file mode 100644 index 0000000..abf8c9b --- /dev/null +++ b/docs/newt/command_list/newt_sync.md @@ -0,0 +1,24 @@ +## <font color="#F2853F" style="font-size:24pt">newt sync </font> + +Synchronize project dependencies. + +#### Usage: + +```no-highlight + newt version [flags] +``` +#### Flags: +```no-highlight + -f, --force Force overwrite of existing remote repository +#### Global Flags: +```no-highlight + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands +``` +#### Description +Synchronize project dependencies and repositories. Use -f to force overwrite of existing repository. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_target.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_target.md b/docs/newt/command_list/newt_target.md index 82130cb..4233905 100644 --- a/docs/newt/command_list/newt_target.md +++ b/docs/newt/command_list/newt_target.md @@ -1,15 +1,15 @@ ## <font color="#F2853F" style="font-size:24pt">newt target </font> -Provides commands to create, build, delete, and query targets. +Commands to create, delete, configure and query targets. #### Usage: ```no-highlight - newt target [command] input1 [input2] + newt target [command] [flags] ``` #### Available Commands: ```no-highlight - config View target system configuration + config View or populate a target's system configuration settings copy Copy target create Create a target delete Delete target @@ -19,45 +19,46 @@ Provides commands to create, build, delete, and query targets. show View target configuration variables ``` -#### Flags: - -```no-highlight - -h, --help=false: help for target -``` - #### Global Flags: - ```no-highlight - -l, --loglevel="WARN": Log level, defaults to WARN. - -o, --outfile string Filename to tee log output to - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` + #### Description +The target command provides subcommands to create, build, delete, and query targets. The subcommands take one or two `target-name` arguments. Sub-command | Explanation -------------| ------------------------ -config | Displays the specified target's system configuration. The configuration for any package is listed in its `syscfg.yml` file. A target build consists of several packages. The command lists the settings for the config variables from all the included packages. If the default values have not been changed then the default values will be seen. -copy | Set variables (attributes) of the target named via `input1`. Currently the list of possible attributes (variables) are:`app`, `bsp`, `build_profile`, `cflags`, `lflags`. For a simulated target, e.g. for software testing purposes, `bsp` is set to `@apache-mynewt-core/hw/bsp/native`. -create | Creates an empty target definition by the name of `input1`. -delete | Deletes only the description for the target. Does not delete the target directory with associated binaries. If you want to clean out the binaries, list files, and executables use`newt clean <target-name>` **before** deleting the target! -dep | Creates dependency tree for packages in the code for a target. Display shows each package followed by the list of libraries or packages that it depends on. -revdep | Creates the reverse dependency tree for packages in the code for a target. Display shows each package followed by the list of libraries or packages that depend on it. -set | Set variables (attributes) of the target named via `input1`. Currently the list of possible attributes (variables) are:`app`, `bsp`, `build_profile`, `features`, `cflags`, `lflags`. For a simulated target, e.g. for software testing purposes, `bsp` is set to `@apache-mynewt-core/hw/bsp/native`. - | To display all the existing values for a target variable (attribute), you can issue a `newt vals <variable-name>` command. For example, `newt vals app` displays the valid values available for the variable `app` for any target. - | Currently, the only two values available for `build_profile` are `optimized` and `debug`. -show | Shows what variables (attributes) are set on the specified target `input1`. If no `input1` is specified then show the configuration for all the targets defined so far. - +config | The config command allows you to view or populate a target's system configuration settings. A target's system configuration settings include the settings of all the packages it includes. The settings for a package are listed in the package's `syscfg.yml` file. The `config` command has two subcommands: `show` and `init`. <br><br> The config show <target-name> command displays the system configuration setting definitions and values for all the packages that the `target-name` target includes. <br><br>The config init <target-name> command populates the target's `syscfg.yml` file with the system configuration values for all the packages that the `target-name` target includes. +copy | The copy <src-target> <dst-target> command creates a new target named `dst-target` by cloning the `src-target` target. +create | The create <target-name> command creates an empty target named `target-name`. It creates the `targets/target-name` directory and the skeleton `pkg.yml` and `target.yml` files in the directory. +delete | The delete <target-name> command deletes the description for the `target-name` target. It deletes the 'targets/target-name' directory. It does not delete the 'bin/targets/target-name' directory where the build artifacts are stored. If you want to delete the build artifacts, run the `newt clean <target-name>` command **before** deleting the target. +dep | The dep <target-name> command displays a dependency tree for the packages that the `target-name` target includes. It shows each package followed by the list of libraries or packages that it depends on. +revdep | The revdep <target-name> command displays the reverse dependency tree for the packages that the `target-name` target includes. It shows each package followed by the list of libraries or packages that depend on it. +set | The set <target-name> <var-name=var-value> [var-name=var-value...] command sets variables (attributes) for the <target-name> target. The set command overwrites your current variable values. <br><br>The valid `var-name` values are: `app`, `bsp`, `loader`, `build_profile`, `cflags`, `lflags`, `aflags`, `syscfg`. <br><br>The `var-value` format depends on the `var-name` as follows: <ul><li>`app`, `bsp`, `loader`: @<source-path>, where `source-path` is the directory containing the application or bsp source. These variables are stored in the target's target.yml file. For a simulated target, e.g. for software testing purposes, set `bsp` to `@apache-mynewt-core/hw/bsp/native`.</li> <li>`build_profile`: `optimized` or `debug`</li><li>`cflags`, `aflags`, `lflags`: A string of flags, with each flag separated by a space. These variables are saved in the target's `pkg.yml` file. </li><li>`syscfg`: The `syscfg` variable allows you to assign values to configuration settings in your target's `syscfg.yml` file. <br>The format is `syscfg=setting-name1=setting-value1[:setting-name2=setting-value2...]`, where `setting-name1` is a configuration setting name and `setting-value1` is the value to assign to `settingname1`. If `settingvalue1` is not specified, the setting is set to value `1`. You use a `:` to delimit each setting when you set multiple settings. <br>**Warning**: All existing setting values in the `syscfg.yml` file are deleted. Only new settings that are specified in the command are saved in the `syscfg.yml` file.</li></ul> You can specify `var-name=` or `var-name=""` to unset a variable value.<br><br>To display all the existing values for a target variable (attribute), you can run the `newt vals <variable-name>` command. For example, `newt vals app` displays the valid values available for the variable `app` for any target. +show | The show [target-name] command shows the values of the variables (attributes) for the `target-name` target. When `target-name` is not specified, the command shows the variables for all the targets that are defined for your project. #### Examples Sub-command | Usage | Explanation --------------| -----------------------|----------------- -config | newt target config rb_blinky | Shows all the system configuration settings for all the packages in the target named `rb_blinky`. -copy | newt target copy rb_blinky rb_bletiny | Clones the target settings in `rb_blinky` to the destination target `rb_bletiny` -create | newt target create target1 | Creates an empty target by the name `target1` -show | newt target show myble | Shows all variable settings for the target named "myble" i.e. what app, bsp, build_profile, features, cflags are set to. Note that all variables are not required to be set in order to successfully define a target. -show | newt target show | Shows all variable settings for all the targets defined. -set | newt target set myble app=@apache-mynewt-core/apps/bletiny | Assign `bletiny` to be the application to be included in the build for the target named `myble`. +--------------| -----------------------|----------------- +config show | newt target config show rb_blinky | Shows the system configuration settings for all the packages that the `rb_blinky` target includes. +config init | newt target config init my_blinky | Creates and populates the `my_blinky` target's `syscfg.yml` file with the system configuration setting values from all the packages that the `my_blinky` target includes. +copy | newt target copy <br>rb_blinky rb_bletiny | Creates the `rb_bletiny` target by cloning the `rb_blinky` target. +create | newt target create <br>my_new_target | Creates the `my_newt_target` target. It creates the `targets/my_new_target` directory and creates the skeleton `pkg.yml` and `target.yml` files in the directory. +delete | newt target delete rb_bletiny | Deletes the `rb_bletiny` target. It deletes the `targets/rb_bletiny` directory. +dep | newt target dep myble | Displays the dependency tree of all the package dependencies for the `myble` target. It lists each package followed by a list of packages it depends on. +revdep | newt target revdep myble | Displays the reverse dependency tree of all the package dependencies for the `myble` target. It lists each package followed by a list of packages that depend on it. +set | newt target set myble <br>app=@apache-mynewt-core/apps/bletiny | Use `bletiny` as the application to build for the `myble` target. +set | newt target set myble <br>cflags="-DNDEBUG -Werror" | Set `pkg.cflags` variable with `-DNDEBUG -Werror` in the `myble` target's `pkg.yml` file.. +set | newt target set myble syscfg=LOG_NEWTMGR=0:CONFIG_NEWTMGR | Sets the `syscfg.vals` variable in the `myble` target's `syscfg.yml` file with the setting values: LOG_NEWTMGR: 0 and CONFIG_NEWTMGR: 1. CONFIG_NEWTMGR is set to 1 because a value is not specified. +set | newt target set myble cflags= | Unsets the `pkg.cflags` variable in the `myble` target's `pkg.yml` file. +show | newt target show myble | Shows all variable settings for the `myble` target, i.e. the values that app, bsp, build_profile, cflags, aflags, ldflags, syscfg variables are set to. Note that not all variables have to be set for a target. +show | newt target show | Shows all the variable settings for all the targets defined for the project. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_test.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_test.md b/docs/newt/command_list/newt_test.md index 8a33968..27afdba 100644 --- a/docs/newt/command_list/newt_test.md +++ b/docs/newt/command_list/newt_test.md @@ -1,41 +1,41 @@ ## <font color="#F2853F" style="font-size:24pt">newt test </font> -Executes unit tests for one or more packages +Execute unit tests for one or more packages. #### Usage: ```no-highlight - newt test [flags] input1 [input2] ... + newt test <package-name> [package-names...] | all [flags] ``` #### Flags: ```no-highlight - -h, --help=false: help for target + -e, --exclude string Comma separated list of packages to exclude + ``` #### Global Flags: ```no-highlight - -l, --loglevel="WARN": Log level, defaults to WARN. - -o, --outfile string Filename to tee log output to - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` #### Description - -Sub-command | Explanation --------------| ------------------------ -test | Test a pkg named `input1`. You may specify multiple packages separated by space in the same command. - +Executes unit tests for one or more packages. You specify a list of packages, separated by space, to test multiple packages in the same command, or specify `all` to test all packages. When you use the `all` option, you may use the `-e` flag followed by a comma separated list of packages to exclude from the test. #### Examples Sub-command | Usage | Explanation -------------| -----------------------|----------------- -test | newt test targets/myble2 | Tests the pkg named 'targets/myble2' - | newt test @apache-mynewt-core/libs/os | Tests the libs/os pkg in the repo named apache-mynewt-core - | newt test libs/os libs/json | Tests the `libs/os` and `libs/json packages` in the current repo. Should indicate at the end of the output: <br> `Passed tests: [libs/os libs/json]` <br> `All tests passed` + | newt test <br>@apache-mynewt-core/kernel/os | Tests the `kernel/os` package in the `apache-mynewt-core` repository. + | newt test kernel/os encoding/json | Tests the `kernel/os` and `encoding/json` packages in the current repository. + | newt test all | Tests all packages. + | newt test all -e net/oic,encoding/json | Tests all packages except for the `net/oic` and the `encoding/json` packages. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_upgrade.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_upgrade.md b/docs/newt/command_list/newt_upgrade.md index 6c07692..0e9f731 100644 --- a/docs/newt/command_list/newt_upgrade.md +++ b/docs/newt/command_list/newt_upgrade.md @@ -1,26 +1,25 @@ ## <font color="#F2853F" style="font-size:24pt">newt upgrade </font> -Upgrade project dependencies +Upgrade project dependencies. #### Usage: ```no-highlight - newt pkg [command][flag] input1 input2 + newt upgrade [flags] ``` #### Flags: ```no-highlight -f, --force Force upgrade of the repositories to latest state in project.yml - +``` #### Global Flags: - - -l, --loglevel="WARN": Log level, defaults to WARN. - -o, --outfile string Filename to tee log output to - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. +```no-highlight + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` #### Description - -Sub-command | Explanation --------------| ------------------------ -upgrade | If you have changed the project.yml description for the project, you need to run this command to update all the package dependencies. \ No newline at end of file +Upagrades your project and package dependencies. If you have changed the project.yml description for the project, you need to run this command to update all the package dependencies. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_vals.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_vals.md b/docs/newt/command_list/newt_vals.md index 381b1f7..7931cd7 100644 --- a/docs/newt/command_list/newt_vals.md +++ b/docs/newt/command_list/newt_vals.md @@ -1,16 +1,6 @@ ## <font color="#F2853F" style="font-size:24pt">newt vals </font> -Displays valid values for the specified element type(s). Appropriate values must be chosen and assigned to one or more elements when defining a package or target. Element types currently available are the following: - -* api -* app -* bsp -* build_profile -* compiler -* feature -* lib -* sdk -* target +Display valid values for the specified element type(s). #### Usage: @@ -18,27 +8,34 @@ Displays valid values for the specified element type(s). Appropriate values must ```no-highlight newt vals <element-type> [element-types...] [flags] ``` - -#### Flags: -```no-highlight - -h, --help=false: help for target -``` - #### Global Flags: ```no-highlight - -l, --loglevel="WARN": Log level, defaults to WARN. - -o, --outfile string Filename to tee log output to - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands ``` +#### Description + +Displays valid values for the specified element type(s). You must set valid values for one or more elements when you define a package or a target. Valid element types are: +* api +* app +* bsp +* build_profile +* compiler +* lib +* sdk +* target #### Examples - Sub-command | Usage | Explanation --------------| -----------------------|----------------- -vals | newt vals api | Shows the possible values for APIs a package may specify as required. For example, the `pkg.yml` for `adc` specifies that it requires the api named `ADC_HW_IMPL`, one of the values listed by the command. + Sub-command | Usage | Explanation +-------------| --------------------|----------------- + | newt vals api | Shows the possible values for APIs a package may specify as required. For example, the `pkg.yml` for `adc` specifies that it requires the api named `ADC_HW_IMPL`, one of the values listed by the command. #### Example output for `newt vals bsp`: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/command_list/newt_version.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_version.md b/docs/newt/command_list/newt_version.md index 956d96e..f28ac42 100644 --- a/docs/newt/command_list/newt_version.md +++ b/docs/newt/command_list/newt_version.md @@ -1,6 +1,6 @@ ## <font color="#F2853F" style="font-size:24pt">newt version </font> -Allows you to query the version of newt installed in your application space. +Display the version of the newt tool you have installed #### Usage: @@ -8,24 +8,21 @@ Allows you to query the version of newt installed in your application space. newt version [flags] ``` -#### Flags: -```no-highlight - -h, --help=false: help for version -``` - #### Global Flags: ```no-highlight - -l, --loglevel string Log level, defaults to WARN. (default "WARN") + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") -o, --outfile string Filename to tee output to - -q, --quiet Be quiet; only display error output. - -s, --silent Be silent; don't output anything. - -v, --verbose Enable verbose output when executing commands. -``` + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands +``` #### Examples Sub-command | Usage | Explanation -------------| -----------------------|----------------- -version | newt version | Displays the version of newt tool installed + | newt version | Displays the version of the newt tool you have installed http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/newt_intro.md ---------------------------------------------------------------------- diff --git a/docs/newt/newt_intro.md b/docs/newt/newt_intro.md index a43e126..1b0cf6b 100644 --- a/docs/newt/newt_intro.md +++ b/docs/newt/newt_intro.md @@ -60,34 +60,34 @@ When Newt sees a directory tree that contains a "project.yml" file, it is smart automatically builds a package tree. It also recognizes two important package directories in the package tree - "apps" and "targets". More on these directories in [Newt Theory of Ops](newt_operation.md). -When Newt is told to build a project, it recursively resolves all package dependencies and generates artifacts that are placed in the bin/ directory at the top-level of the project. The artifact directory is prefixed by the target name being built - `my_blinky_sim` for example: +When Newt builds a target, it recursively resolves all package dependencies, and generates artifacts that are placed in the bin/targets/<target-name>/app/apps/<app-name> directory, where the bin directory is under the project base directory, `target-name` is the name of the target, and `app-name` is the name of the application. For our example `my_blinky_sim` is the name of the target and `blinky` is the name of the application. The `blinky.elf` executable is stored in the bin/targets/my_blinky_sim/app/apps/blinky directory as shown in the source tree: ``` -$ tree bin -bin -âââ my_blinky_sim - âââ apps - â  âââ blinky - â  âââ blinky.a - â  âââ blinky.a.cmd - â  âââ blinky.elf - â  âââ blinky.elf.cmd - â  âââ blinky.elf.dSYM - â  â  âââ Contents - â  â  âââ Info.plist - â  â  âââ Resources - â  â  âââ DWARF - â  â  âââ blinky.elf - â  âââ blinky.elf.lst - â  âââ main.d - â  âââ main.o - â  âââ main.o.cmd - âââ hw - â  âââ bsp - â  â  âââ native - â  â  âââ hal_bsp.d - â  â  âââ hal_bsp.o - â  â  âââ hal_bsp.o.cmd +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 + <snip> ``` @@ -102,6 +102,7 @@ Once a target has been built, Newt allows additional operations on the target. * **size**: Get size of target components * **create-image**: Add image header to the binary image * **run**: Build, create image, load, and finally open a debug session with the target +* **target**: Create, delete, configure, and query a target For more details on how Newt works, go to [Newt - Theory of Operations](newt_operation.md). @@ -174,15 +175,15 @@ $ tree -L 2 <br> -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 `libs/os`, `hw/hal`, and `libs/console/full` packages. +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 `kernel/os`, `hw/hal`, and `sys/console/full` packages. ``` $ more apps/blinky/pkg.yml <snip> pkg.deps: - - "@apache-mynewt-core/libs/os" + - "@apache-mynewt-core/kernel/os" - "@apache-mynewt-core/hw/hal" - - "@apache-mynewt-core/libs/console/full" + - "@apache-mynewt-core/sys/console/full" ``` <br> @@ -200,10 +201,3 @@ Notes: 1. Autocomplete will give you flag hints, but only if you type a '-'. 2. Autocomplete will not give you completion hints for the flag arguments (those optional things after the flag like `-l DEBUG`) 3. Autocomplete uses newt to parse the project to find targets and libs. - - - - - - - http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/newt_operation.md ---------------------------------------------------------------------- diff --git a/docs/newt/newt_operation.md b/docs/newt/newt_operation.md index 936344a..51e74ff 100644 --- a/docs/newt/newt_operation.md +++ b/docs/newt/newt_operation.md @@ -41,12 +41,13 @@ When newt sees a directory tree that contains a "project.yml" file it knows that ``` @~/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 +blecent blesplit boot sensors_test splitty +blehci bletest fat2native slinky test +bleprph bletiny ffs2native slinky_oic testbench +bleprph_oic bleuart ocf_sample spitest timtest ``` -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. +Along with the `targets` directory, `apps` represents the top-level of the build tree for the particular project, and define the dependencies 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: @@ -68,8 +69,7 @@ pkg.deps: <br> -This file says that the name of the package is apps/blinky, and it -depends on kernel/os, hw/hal and sys/console/full packages. +This file says that the name of the package is apps/blinky, and it depends on the `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. @@ -100,20 +100,23 @@ 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 +* **target show**: Displays the variable values for either a specific target or all targets defined for the project +* **target set**: Sets values for target variables -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: +In general, the three basic parameters of a target (`app`, `bsp`, and `build_profile`) are stored in the target's `target.yml` file in the targets/<target-name> directory, where `target-name` is the name of the target. 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 +You can also override the values of the system configuration settings that are defined by the packages that your target includes. You override the values in your target's `syscfg.yml` file (stored in the targets/<target-name> directory). You can use the `newt target config show` command to see the configuration settings and values for your target, and use the `newt target set` command to set the `syscfg` variable and override the configuration setting values. You can also use an editor to create your target's `syscfg.yml` file and add the setting values to the file. See [System Configuration And Initialization](/os/modules/sysinitconfig/sysinitconfig.md) for more information on system configuration settings. + <br> ### Resolving dependencies -When newt is told to build a project, it will: +When newt builds a project, it will: * find the top-level project.yml file * recurse the packages in the package tree, and build a list of all @@ -142,45 +145,50 @@ along with that application. Newt builds the dependency tree specified by all the packages. While building this tree, it does a few other things: - Sets up the include paths for each package. 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. +newt structure must always be prefixed by the package name. For example, kernel/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. ``` -$ 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 +$tree kernel/os/include +kernel/os/include +âââ os âââ arch + â  âââ cortex_m0 + â  â  âââ os + â  â  âââ os_arch.h + â  âââ cortex_m4 + â  â  âââ os + â  â  âââ os_arch.h + â  âââ mips + â  â  âââ os + â  â  âââ os_arch.h + â  âââ sim + â  â  âââ os + â  â  âââ os_arch.h + â  âââ sim-mips + â  âââ os + â  âââ os_arch.h + âââ endian.h + âââ os.h + âââ os_callout.h + âââ os_cfg.h + âââ os_cputime.h + âââ os_dev.h + âââ os_eventq.h + âââ os_fault.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 + <snip> ``` @@ -192,12 +200,12 @@ implement, (i.e. pkg.api: hw-hal-impl), and other packages can require those APIs (i.e. pkg.req_api: hw-hal-impl). - Reads and validates the configuration setting definitions and values from the package `syscfg.yml` files. -It generates a `syscfg.h` header file that packages include in the source files inorder to access the settings. +It generates a `syscfg.h` header file that packages include in the source files in order to access the settings. It also generates a system initialization function to initialize the packages. See [System Configuration And Initialization](/os/modules/sysinitconfig/sysinitconfig.md) for more information. -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. +In order to properly resolve all dependencies in the build system, newt recursively processes the package dependencies until there are no new dependencies. And it builds a big list of all the packages that need to be build. Newt then goes through this package list, and builds every package into @@ -209,35 +217,41 @@ an archive file. 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.) -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. - -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: +The newt tool creates a bin directory under the base project directory, and places a target's build artifacts into the bin/targets/<target-name>/app/apps/<app-name> directory, where `target-name` is the name of the target and `app-name` is the name of the application. As an example, the `blinky.elf` executable for the `blinky` application defined by the `my_blinky_sim` target is stored in the bin/targets/my_blinky_sim/app/apps/blinky directory as shown in the following source tree: ``` -$ 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 +$tree -L 9 bin/ bin/ +âââ targets + âââ my_blinky_sim + â  âââ app + â  â  âââ apps + â  â  â  âââ blinky + â  â  â  âââ apps + â  â  â  â  âââ blinky + â  â  â  â  âââ src + â  â  â  â  âââ main.d + â  â  â  â  âââ main.o + â  â  â  â  âââ main.o.cmd + â  â  â  âââ apps_blinky.a + â  â  â  âââ apps_blinky.a.cmd + â  â  â  âââ blinky.elf + â  â  â  âââ blinky.elf.cmd + â  â  â  âââ blinky.elf.dSYM + â  â  â  â  âââ Contents + â  â  â  â  âââ Info.plist + â  â  â  â  âââ Resources + â  â  â  â  âââ DWARF + â  â  â  âââ blinky.elf.lst + â  â  â  âââ manifest.json + â  â  âââ hw + â  â  â  âââ bsp + â  â  â  â  âââ native + â  â  â  â  âââ hw_bsp_native.a + â  â  â  â  âââ hw_bsp_native.a.cmd + â  â  â  â  âââ repos + â  â  â  â  âââ apache-mynewt-core + â  â  â  â  âââ hw + <snip> ``` @@ -248,7 +262,8 @@ As you can see, a number of files are generated: - Archive File - *.cmd: The command use to generate the object or archive file - *.lst: The list file where symbols are located -- *.o The object files that get put into the archive file + +Note: The *.o object files that get put into the archive file are stored in the bin/targets/my_blinky_sim/app/apps/blinky/apps/blinky/src directory. ### Download/Debug Support @@ -260,6 +275,7 @@ that work on the target. These are: * **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 +* **target** Create, delete, configure, and query a target `load` and `debug` handles driving GDB and the system debugger. These commands call out to scripts that are defined by the BSP. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/docs/newt/newt_ops.md ---------------------------------------------------------------------- diff --git a/docs/newt/newt_ops.md b/docs/newt/newt_ops.md index 113968f..4b46c96 100644 --- a/docs/newt/newt_ops.md +++ b/docs/newt/newt_ops.md @@ -1,11 +1,11 @@ ## Command Structure -Just like verbs are actions in a sentence and adverdbs modifiy verbs, so in *newt* tool, commands are actions and flags modify actions. A command can have subcommands, too. Arguments to commands and subcommands, with appropriate flags, will dictate the execution and result of a command. +Just like verbs are actions in a sentence and adverbs modifiy verbs, so in the *newt* tool, commands are actions and flags modify actions. A command can have subcommands. Arguments to commands and subcommands, with appropriate flags, dictate the execution and result of a command. -For instance, in the example below, the *newt* command has the subcommand `target set` in which the argument 'my_target1' is the target whose attribute, *arch*, is set to 'cortex_md.' +For instance, in the example below, the *newt* command has the subcommand `target set` in which the argument 'my_target1' is the target whose attribute, *app*, is set to '@apache-mynewt-core/hw/bsp/nrf52dk' ```no-highlight - newt target set my_target1 arch=cortex_m4 + newt target set my_target1 app=@apache-mynewt-core/hw/bsp/nrf52dk ``` Global flags work uniformly across *newt* commands. Consider the flag `-v, --verbose,` It works both for command and subcommands, to generate verbose output. Likewise, the help flag `-h` or `--help,` to print helpful messsages. @@ -19,14 +19,14 @@ In addition to the [Newt Tool Manual](newt_intro.md) in docs, command-line help ```no-highlight newt target --help - Command for manipulating targets + Commands to create, delete, configure, and query targets Usage: newt target [flags] newt target [command] Available Commands: - config View target system configuration + config View or populate a target's system configuration copy Copy target create Create a target delete Delete target @@ -36,12 +36,14 @@ In addition to the [Newt Tool Manual](newt_intro.md) in docs, command-line help 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 "WARN") -o, --outfile string Filename to tee output to -q, --quiet Be quiet; only display error output -s, --silent Be silent; don't output anything -v, --verbose Enable verbose output when executing commands - + Use "newt target [command] --help" for more information about a command. ``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c95710ac/mkdocs.yml ---------------------------------------------------------------------- diff --git a/mkdocs.yml b/mkdocs.yml index cb27b88..87a7cfd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -487,7 +487,6 @@ pages: - toc: 'newt/newt_ops.md' - 'newt build': 'newt/command_list/newt_build.md' - 'newt clean': 'newt/command_list/newt_clean.md' - - 'newt complete': 'newt/command_list/newt_complete.md' - 'newt create-image': 'newt/command_list/newt_create_image.md' - 'newt debug': 'newt/command_list/newt_debug.md' - 'newt help': 'newt/command_list/newt_help.md' @@ -496,8 +495,10 @@ pages: - 'newt load': 'newt/command_list/newt_load.md' - 'newt mfg': 'newt/command_list/newt_mfg.md' - 'newt new': 'newt/command_list/newt_new.md' + - 'newt pkg': 'newt/command_list/newt_pkg.md' - 'newt run': 'newt/command_list/newt_run.md' - 'newt size': 'newt/command_list/newt_size.md' + - 'newt sync': 'newt/command_list/newt_sync.md' - 'newt target': 'newt/command_list/newt_target.md' - 'newt test': 'newt/command_list/newt_test.md' - 'newt upgrade': 'newt/command_list/newt_upgrade.md'
