You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by GitBox <gi...@apache.org> on 2018/01/10 21:28:29 UTC
[GitHub] vrahane closed pull request #123: move newt tool docs to mynewt-newt repo
vrahane closed pull request #123: move newt tool docs to mynewt-newt repo
URL: https://github.com/apache/mynewt-newt/pull/123
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/command_list/newt_build.rst b/docs/command_list/newt_build.rst
new file mode 100644
index 00000000..af8bef25
--- /dev/null
+++ b/docs/command_list/newt_build.rst
@@ -0,0 +1,42 @@
+newt build
+-----------
+
+Build one or more targets.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt build <target-name> [target_name ...] [flags]
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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. 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.
+
+You can specify a list of target names, separated by a space, to build multiple targets.
+
+Examples
+^^^^^^^^
+
++------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Usage | Explanation |
++====================================+================================================================================================================================================================================================================================================================+
+| ``newt build 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 my_blinky_sim myble`` | Builds the images for the applications defined by the ``my_blinky_sim`` and ``myble`` targets. |
++------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
diff --git a/docs/command_list/newt_clean.rst b/docs/command_list/newt_clean.rst
new file mode 100644
index 00000000..7c2d1f61
--- /dev/null
+++ b/docs/command_list/newt_clean.rst
@@ -0,0 +1,42 @@
+newt clean
+-----------
+
+Delete build artifacts for one or more targets.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt clean <target-name> [target-name...] | all [flags]
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+^^^^^^^^^^^
+
+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
+^^^^^^^^
+
++------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Usage | Explanation |
++====================================+==========================================================================================================================================================================================+
+| ``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. |
++------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
diff --git a/docs/command_list/newt_complete.rst b/docs/command_list/newt_complete.rst
new file mode 100644
index 00000000..205710d4
--- /dev/null
+++ b/docs/command_list/newt_complete.rst
@@ -0,0 +1,35 @@
+newt complete
+--------------
+
+Performs bash autocompletion using tab. It is not intended to be called directly from the command line.
+
+Install bash autocompletion
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ $ brew install bash-completion
+ Updating Homebrew...
+ <snip>
+ Bash completion has been installed to:
+ /usr/local/etc/bash_completion.d
+ ==> Summary
+ ? /usr/local/Cellar/bash-completion/1.3_1: 189 files, 607.8K
+
+Enable autocompletion for newt
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ $ complete -C "newt complete" newt
+
+Usage
+^^^^^
+
+Hit tab and see possible completion options or completed command.
+
+.. code-block:: console
+
+ $ newt target s
+ set show
+ $ newt target show
diff --git a/docs/command_list/newt_create_image.rst b/docs/command_list/newt_create_image.rst
new file mode 100644
index 00000000..0fc7987e
--- /dev/null
+++ b/docs/command_list/newt_create_image.rst
@@ -0,0 +1,57 @@
+newt create-image
+------------------
+
+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:
+^^^^^^
+
+.. code-block:: console
+
+ newt create-image <target-name> <version> [signing-key [key-id]][flags]
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+^^^^^^^^^^^
+
+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 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. It also creates a ``<app-name>.hex`` file for the image in the same directory, and adds the version, build id, image file name, and image hash to the ``manifest.json`` file that the ``newt build`` command created.
+
+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
+^^^^^^^^
+
+================================================== ===========
+Usage Explanation
+================================================== ===========
+``newt create-image myble2 1.0.1.0`` Creates an image for target ``myble2`` and assigns it version
+ ``1.0.1.0``.
+
+ For the following target definition:
+
+ | targets/myble2
+ | app=\@apache-mynewt-core/apps/bletiny
+ | bsp=\@apache-mynewt-core/hw/bsp/nrf52dk
+ | build\_profile=optimized
+ | syscfg=STATS\_NAMES=1
+
+ the 'bin/targets/myble2/app/apps/bletiny/bletiny.img' and
+ 'bin/targets/myble2/app/apps/bletiny/bletiny.hex' files are created,
+ and the manifest in 'bin/targets/myble2/app/apps/bletiny/manifest.json'
+ is updated with the image information.
+
+``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.
+================================================== ===========
diff --git a/docs/command_list/newt_debug.rst b/docs/command_list/newt_debug.rst
new file mode 100644
index 00000000..ce10f1b1
--- /dev/null
+++ b/docs/command_list/newt_debug.rst
@@ -0,0 +1,48 @@
+newt debug
+-----------
+
+Open a debugger session to a target.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt debug <target-name> [flag]
+
+Flags:
+^^^^^^
+
+.. code-block:: console
+
+ --extrajtagcmd string Extra commands to send to JTAG software
+ -n, --noGDB Do not start GDB from command line
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+^^^^^^^^^^^
+
+Opens a debugger session to the image built for the <target-name> target.
+
+Examples
+^^^^^^^^
+
++--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Usage | Explanation |
++==========================+============================================================================================================================================================================================================================================================================================+
+| ``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: targets/myble2 app=\@apache-mynewt-core/apps/bletiny bsp=\@apache-mynewt-core/hw/bsp/nrf52dk build_profile=optimized syscfg=STATS_NAMES=1 |
++--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``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. |
++--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
diff --git a/docs/command_list/newt_help.rst b/docs/command_list/newt_help.rst
new file mode 100644
index 00000000..6a722eb7
--- /dev/null
+++ b/docs/command_list/newt_help.rst
@@ -0,0 +1,68 @@
+newt help
+----------
+
+Display the help text for the newt command line tool:
+
+.. code-block:: console
+
+ 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
+ projects, and then build the necessary artifacts from those projects. For more
+ information on the Mynewt operating system, please visit
+ https://mynewt.apache.org/.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt help [command]
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+
+Available Commands:
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ 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
+ load Load built target to board
+ mfg Manufacturing flash image commands
+ new Create a new project
+ 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
+ test Executes unit tests for one or more packages
+ upgrade Upgrade project dependencies
+ vals Display valid values for the specified element type(s)
+ version Display the Newt version number
+
+Examples
+^^^^^^^^
+
++------------------------+----------------------------------------------------------+
+| Usage | Explanation |
++========================+==========================================================+
+| ``newt help target`` | Displays the help text for the newt ``target`` command |
++------------------------+----------------------------------------------------------+
+| ``newt help`` | Displays the help text for newt tool |
++------------------------+----------------------------------------------------------+
diff --git a/docs/command_list/newt_info.rst b/docs/command_list/newt_info.rst
new file mode 100644
index 00000000..5bc5ab83
--- /dev/null
+++ b/docs/command_list/newt_info.rst
@@ -0,0 +1,29 @@
+newt info
+----------
+
+Show information about the current project.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt info [flags]
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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 repositories in the current project (the local as well as all the external repositories fetched). It also displays the packages in the local repository.
diff --git a/docs/command_list/newt_install.rst b/docs/command_list/newt_install.rst
new file mode 100644
index 00000000..149258fc
--- /dev/null
+++ b/docs/command_list/newt_install.rst
@@ -0,0 +1,38 @@
+newt install
+-------------
+
+Install project dependencies.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt install [flags]
+
+Flags:
+^^^^^^
+
+.. code-block:: console
+
+ -f, --force Force install of the repositories in project, regardless of what exists in repos directory
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+^^^^^^^^^^^
+
+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``.)
diff --git a/docs/command_list/newt_load.rst b/docs/command_list/newt_load.rst
new file mode 100644
index 00000000..f2fd4125
--- /dev/null
+++ b/docs/command_list/newt_load.rst
@@ -0,0 +1,36 @@
+newt load
+----------
+
+Load application image onto the board for a target.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt load <target-name> [flags]
+
+Flags:
+^^^^^^
+
+.. code-block:: console
+
+ --extrajtagcmd string Extra commands to send to JTAG software
+
+Global Flags:
+~~~~~~~~~~~~~
+
+.. code-block:: console
+
+ -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
+^^^^^^^^^^^
+
+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``.
diff --git a/docs/command_list/newt_mfg.rst b/docs/command_list/newt_mfg.rst
new file mode 100644
index 00000000..b45eb693
--- /dev/null
+++ b/docs/command_list/newt_mfg.rst
@@ -0,0 +1,109 @@
+newt mfg
+---------
+
+Commands to create, build, and upload manufacturing image.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt mfg [flags]
+ newt mfg [command]
+
+Available Commands:
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ create Create a manufacturing flash image
+ deploy Build and upload a manufacturing image (build + load)
+ load Load a manufacturing flash image onto a device
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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 the image file, the hex file, and the 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. |
++---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+Examples
+^^^^^^^^
+
+Suppose you have created two targets (one for the bootloader and one for the ``blinky`` app).
+
+.. code-block:: console
+
+ $ newt target show
+ targets/my_blinky_sim
+ app=apps/blinky
+ bsp=@apache-mynewt-core/hw/bsp/native
+ build_profile=debug
+ targets/rb_blinky
+ app=apps/blinky
+ bsp=@apache-mynewt-core/hw/bsp/rb-nano2
+ build_profile=debug
+ targets/rb_boot
+ app=@apache-mynewt-core/apps/boot
+ bsp=@apache-mynewt-core/hw/bsp/rb-nano2
+ build_profile=optimized
+
+Create the directory to hold the mfg packages.
+
+.. code-block:: console
+
+ $ mkdir -p mfgs/rb_blinky_rsa
+
+The ``rb_blinky_rsa`` package needs a pkg.yml file. In addition it is needs a mfg.yml file to specify the two constituent targets. An example of each file is shown below.
+
+.. code-block:: console
+
+ $ more mfgs/rb_blinky_rsa/pkg.yml
+ pkg.name: "mfgs/rb_blinky_rsa"
+ pkg.type: "mfg"
+ pkg.description:
+ pkg.author:
+ pkg.homepage:
+
+.. code-block:: console
+
+ $ more mfgs/rb_blinky_rsa/mfg.yml
+ mfg.bootloader: 'targets/rb_boot'
+ mfg.images:
+ - 'targets/rb_blinky'
+
+Build the bootloader and app images.
+
+.. code-block:: console
+
+ $ newt build rb_boot
+ $ newt create-image rb_blinky 0.0.1
+
+Run the ``newt mfg create`` command to collect all the manufacturing snapshot files.
+
+.. code-block:: console
+
+ $ newt mfg create rb_blinky_rsa
+ Creating a manufacturing image from the following files:
+ <snip>
+ Generated the following files:
+ <snip>
diff --git a/docs/command_list/newt_new.rst b/docs/command_list/newt_new.rst
new file mode 100644
index 00000000..ab094ad1
--- /dev/null
+++ b/docs/command_list/newt_new.rst
@@ -0,0 +1,38 @@
+newt new
+---------
+
+Create a new project from a skeleton. Currently, the default skeleton is the `blinky repository <https://github.com/apache/mynewt-blinky>`__.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt new <project-name> [flags]
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+~~~~~~~~~~~
+
+Creates a new project named ``project-name`` from the default skeleton `blinky repository <https://github.com/apache/mynewt-blinky>`__.
+
+Examples
+^^^^^^^^
+
++---------------------------+-------------------------------------------------------------------------------------------------------------------------+
+| Usage | Explanation |
++===========================+=========================================================================================================================+
+| ``newt new test_project`` | Creates a new project named ``test_project`` using the default skeleton from the ``apache/mynewt-blinky`` repository. |
++---------------------------+-------------------------------------------------------------------------------------------------------------------------+
diff --git a/docs/command_list/newt_pkg.rst b/docs/command_list/newt_pkg.rst
new file mode 100644
index 00000000..a0d13905
--- /dev/null
+++ b/docs/command_list/newt_pkg.rst
@@ -0,0 +1,65 @@
+newt pkg
+---------
+
+Commands for creating and manipulating packages.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt pkg [command] [flags]
+
+Flags:
+^^^^^^
+
+.. code-block:: console
+
+ -t, --type string Type of package to create: app, bsp, lib, sdk, unittest. (default "lib")
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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 ``app``, ``bsp``, ``lib``, ``sdk``, or ``unittest``. The default package type is ``lib``. 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 apps/bletiny apps/new_bletiny`` | Copies the ``apps/bletiny`` package to the ``apps/new_bletiny``. |
++---------------+--------------------------------------------------+-----------------------------------------------------------------------------------------+
+| move | ``newt pkg move 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. |
++---------------+--------------------------------------------------+-----------------------------------------------------------------------------------------+
diff --git a/docs/command_list/newt_resign_image.rst b/docs/command_list/newt_resign_image.rst
new file mode 100644
index 00000000..5c08f894
--- /dev/null
+++ b/docs/command_list/newt_resign_image.rst
@@ -0,0 +1,46 @@
+newt resign-image
+------------------
+
+Sign or re-sign an existing image file.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt resign-image <image-file> [signing-key [key-id]][flags]
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+^^^^^^^^^^^
+
+Changes the signature of an existing image file. To sign an image, specify a .pem file for the ``signing-key`` and an
+optional ``key-id``. ``key-id`` must be a value between 0-255. If a signing key is not specified, the command strips the
+current signature from the image file.
+
+A new image header is created. The rest of the image is byte-for-byte equivalent to the original image.
+
+Warning: The image hash will change if you change the key-id or the type of key used for signing.
+
+Examples
+^^^^^^^^
+
++------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+
+| Usage | Explanation |
++====================================================================================+===============================================================================================+
+| ``newt resign-image bin/targets/myble/app/apps/bletiny/bletiny.img private.pem`` | Signs the ``bin/targets/myble/app/apps/bletiny/bletiny.img`` file with the private.pem key. |
++------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+
+| ``newt resign-image bin/targets/myble/app/apps/bletiny/bletiny.img`` | Strips the current signature from ``bin/targets/myble/app/apps/bletiny/bletiny.img`` file. |
++------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------+
diff --git a/docs/command_list/newt_run.rst b/docs/command_list/newt_run.rst
new file mode 100644
index 00000000..3457e144
--- /dev/null
+++ b/docs/command_list/newt_run.rst
@@ -0,0 +1,53 @@
+newt run
+---------
+
+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 the version number is omitted:
+
+- The create-image step is skipped for a bootloader target.
+- You will be prompted to enter a version number for an application target.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt run <target-name> [<version>][flags]
+
+Flags:
+^^^^^^
+
+.. code-block:: console
+
+ --extrajtagcmd string Extra commands to send to JTAG software
+ -n, --noGDB Do not start GDB from the command line
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+^^^^^^^^^^^
+
+Same as running ``build <target-name>``, ``create-image <target-name> <version>``, ``load <target-name>``, and ``debug <target-name>``.
+
+Examples
+^^^^^^^^
+
++------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Usage | Explanation |
++====================================+======================================================================================================================================================================================================================================================================================================================================================================================+
+| ``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. Note that if there is no bootloader available for a particular board/kit, a signed image creation step is not necessary. |
++------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
diff --git a/docs/command_list/newt_size.rst b/docs/command_list/newt_size.rst
new file mode 100644
index 00000000..79f00162
--- /dev/null
+++ b/docs/command_list/newt_size.rst
@@ -0,0 +1,73 @@
+newt size
+----------
+
+Calculates the size of target components for a target.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt size <target-name> [flags]
+
+Flags:
+^^^^^^
+
+.. code-block:: console
+
+ -F, --flash Print FLASH statistics
+ -R, --ram Print RAM statistics
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+^^^^^^^^
+
++-------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
+| Usage | Explanation |
++===============================+=================================================================================================================================+
+| ``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 blink_rigado``:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+
+ $ newt size blink_rigado
+ FLASH RAM
+ 9 223 *fill*
+ 1052 0 baselibc.a
+ 195 1116 blinky.a
+ 616 452 bmd300eval.a
+ 64 0 cmsis-core.a
+ 124 0 crt0.o
+ 8 0 crti.o
+ 16 0 crtn.o
+ 277 196 full.a
+ 20 8 hal.a
+ 96 1068 libg.a
+ 1452 0 libgcc.a
+ 332 28 nrf52xxx.a
+ 3143 677 os.a
+
+ objsize
+ text data bss dec hex filename
+ 7404 1172 2212 10788 2a24 /Users/<username>/dev/rigado/bin/blink_rigado/apps/blinky/blinky.elf
diff --git a/docs/command_list/newt_sync.rst b/docs/command_list/newt_sync.rst
new file mode 100644
index 00000000..685e05fd
--- /dev/null
+++ b/docs/command_list/newt_sync.rst
@@ -0,0 +1,39 @@
+newt sync
+----------
+
+Synchronize and refresh the contents of the local copy of all the repositories used in the project with the latest
+updates maintained in the remote repositories.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt sync [flags]
+
+Flags:
+^^^^^^
+
+.. code-block:: console
+
+ -f, --force Force overwrite of existing remote repository
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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. Prior to 1.0.0 release, the command deletes and resynchronizes each
+repository. Post 1.0.0, it will abort the synchronization if there are any local changes to any repository. Using the -f
+to force overwrite of existing repository will stash and save the changes while pulling in all the latest changes from the remote repository.
diff --git a/docs/command_list/newt_target.rst b/docs/command_list/newt_target.rst
new file mode 100644
index 00000000..43d31758
--- /dev/null
+++ b/docs/command_list/newt_target.rst
@@ -0,0 +1,184 @@
+newt target
+------------
+
+Commands to create, delete, configure and query targets.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt target [command] [flags]
+
+Available Commands:
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ amend Add, change, or delete values for multi-value target variables
+ config View or populate a target's system configuration settings
+ copy Copy target
+ create Create a target
+ delete Delete target
+ dep View target's dependency graph
+ revdep View target's reverse-dependency graph
+ set Set target configuration variable
+ show View target configuration variables
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+============= ===========
+amend The amend command allows you to add, change, or delete values for multi-value target variables that you
+ have set with the ``newt target set`` command. The format of the amend command is:
+
+ ``newt target amend <target-name> <var-name=var-value> [var-name=var-value...]``
+
+ Specify the ``-d`` flag to delete values.
+
+ The following multi-value variables can be amended: ``aflags``, ``cflags``, ``lflags``, ``syscfg``.
+
+ The ``var-value`` format depends on the ``var-name`` as follows:
+
+ ``aflags``, ``cflags``, ``lflags``:
+ A string of flags, with each flag separated by a space. These variables are saved in the target's ``pkg.yml`` file.
+
+ ``syscfg``:
+ The ``syscfg`` variable allows you to assign values to configuration settings in your target's ``syscfg.yml`` file.
+
+ 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 ``setting-name1``. If ``setting-value1``
+ is not specified, the setting is set to value ``1``. You use a ``:`` to delimit each setting when you amend multiple
+ settings.
+
+ To delete a system configuration setting, you only need to specify the setting name. For example, ``syscfg=setting-name1:setting-name2``
+ deletes configuration settings named ``setting-name1`` and ``setting-name2``.
+
+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``. The config show <target-name> command displays the system
+ configuration setting definitions and values for all the packages that the ``target-name`` target includes.
+ 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.
+
+ The valid ``var-name`` values are: ``app``, ``bsp``, ``loader``, ``build_profile``, ``cflags``,
+ ``lflags``, ``aflags``, ``syscfg``.
+
+ The ``var-value`` format depends on the ``var-name`` as follows:
+
+ ``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``.
+
+ ``build_profile``:
+ ``optimized`` or ``debug``
+
+ ``aflags``, ``cflags``, ``lflags``:
+ A string of flags, with each flag separated by a space. These variables are saved in the target's ``pkg.yml`` file.
+
+ ``syscfg``:
+ The ``syscfg`` variable allows you to assign values to configuration settings in your target's ``syscfg.yml`` file.
+
+ 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 ``setting-name1``.
+ If ``setting-value1`` is not specified, the setting is set to value ``1``. You use a ``:`` to delimit
+ each setting when you set multiple settings.
+
+ You can specify ``var-name=`` or ``var-name=""`` to unset a variable value.
+
+ **Warning**: For multi-value variables, the command overrides all existing values. Use
+ the ``newt target amend`` command to change or add new values for a multi-value variable after you have
+ set the variable value. The multi-value variables are: ``aflags``, ``cflags``, ``lflags``, and ``syscfg``
+
+ 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 |
++===============+=========================================================+=======================================================================================================================================================================================================================================================+
+| amend | ``newt target amend myble`` | Changes (or adds) the ``CONFIG_NEWTMGR`` variable to value 0 in the ``syscfg.yml`` file and adds the -DTEST flag to ``pkg.cflags`` in the ``pkg.yml`` file for the ``myble`` target. Other syscfg setting values and cflags values are not changed. |
+| | ``syscfg=CONFIG_NEWTMGR=0 cflags="-DTEST"`` | |
++---------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| amend | ``newt target amend myble`` | Deletes the ``LOG_LEVEL`` and ``CONFIG_NEWTMGR`` settings from the ``syscfg.yml`` file and the -DTEST flag from ``pkg.cflags`` for the ``myble`` target. Other syscfg setting values and cflags values are not changed. |
+| | ``-d syscfg=LOG_LEVEL:CONFIG_NEWTMGR cflags="-DTEST"`` | |
++---------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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 rb_blinky rb_bletiny`` | Creates the ``rb_bletiny`` target by cloning the ``rb_blinky`` target. |
++---------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| create | ``newt target create 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`` | Use ``bletiny`` as the application to build for the ``myble`` target. |
+| | ``app=@apache-mynewt-core/apps/bletiny`` | |
++---------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| set | ``newt target set myble`` | Set ``pkg.cflags`` variable with ``-DNDEBUG -Werror`` in the ``myble`` target's ``pkg.yml`` file.. |
+| | ``cflags="-DNDEBUG -Werror"`` | |
++---------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| set | ``newt target set myble`` | 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. |
+| | ``syscfg=LOG_NEWTMGR=0:CONFIG_NEWTMGR`` | |
++---------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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. |
++---------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
diff --git a/docs/command_list/newt_test.rst b/docs/command_list/newt_test.rst
new file mode 100644
index 00000000..a971cdaf
--- /dev/null
+++ b/docs/command_list/newt_test.rst
@@ -0,0 +1,51 @@
+newt test
+----------
+
+Execute unit tests for one or more packages.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt test <package-name> [package-names...] | all [flags]
+
+Flags:
+^^^^^^
+
+.. code-block:: console
+
+ -e, --exclude string Comma separated list of packages to exclude
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+^^^^^^^^^^^
+
+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
+^^^^^^^^
+
++---------------------------------------------+-------------------------------------------------------------------------------------+
+| Usage | Explanation |
++=============================================+=====================================================================================+
+| ``newt test @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. |
++---------------------------------------------+-------------------------------------------------------------------------------------+
diff --git a/docs/command_list/newt_upgrade.rst b/docs/command_list/newt_upgrade.rst
new file mode 100644
index 00000000..05fda7e5
--- /dev/null
+++ b/docs/command_list/newt_upgrade.rst
@@ -0,0 +1,36 @@
+newt upgrade
+-------------
+
+Upgrade project dependencies.
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt upgrade [flags]
+
+Flags:
+^^^^^^
+
+.. code-block:: console
+
+ -f, --force Force upgrade of the repositories to latest state in project.yml
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+^^^^^^^^^^^
+
+Upgrades 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.
diff --git a/docs/command_list/newt_vals.rst b/docs/command_list/newt_vals.rst
new file mode 100644
index 00000000..88dff11f
--- /dev/null
+++ b/docs/command_list/newt_vals.rst
@@ -0,0 +1,74 @@
+newt vals
+----------
+
+Display valid values for the specified element type(s).
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt vals <element-type> [element-types...] [flags]
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+^^^^^^^^
+
++-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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``:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This lists all possible values that may be assigned to a target's bsp attribute.
+
+.. code-block:: console
+
+ $ newt vals bsp
+ bsp names:
+ @apache-mynewt-core/hw/bsp/arduino_primo_nrf52
+ @apache-mynewt-core/hw/bsp/bmd300eval
+ @apache-mynewt-core/hw/bsp/ci40
+ @apache-mynewt-core/hw/bsp/frdm-k64f
+ @apache-mynewt-core/hw/bsp/native
+ @apache-mynewt-core/hw/bsp/nrf51-arduino_101
+ @apache-mynewt-core/hw/bsp/nrf51-blenano
+ @apache-mynewt-core/hw/bsp/nrf51dk
+ @apache-mynewt-core/hw/bsp/nrf51dk-16kbram
+ @apache-mynewt-core/hw/bsp/nrf52dk
+ @apache-mynewt-core/hw/bsp/nucleo-f401re
+ @apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard
+ @apache-mynewt-core/hw/bsp/rb-nano2
+ @apache-mynewt-core/hw/bsp/stm32f4discovery
+ $ newt target set sample_target bsp=@apache-mynewt-core/hw/bsp/rb-nano2
+
+Obviously, this output will grow as more board support packages are added for new boards and MCUs.
diff --git a/docs/command_list/newt_version.rst b/docs/command_list/newt_version.rst
new file mode 100644
index 00000000..b6ef0e4c
--- /dev/null
+++ b/docs/command_list/newt_version.rst
@@ -0,0 +1,33 @@
+newt version
+-------------
+
+Display the version of the newt tool you have installed
+
+Usage:
+^^^^^^
+
+.. code-block:: console
+
+ newt version [flags]
+
+Global Flags:
+^^^^^^^^^^^^^
+
+.. code-block:: console
+
+ -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
+
+Examples
+^^^^^^^^
+
++------------------+------------------------------------------------------------+
+| Usage | Explanation |
++==================+============================================================+
+| ``newt version`` | Displays the version of the newt tool you have installed |
++------------------+------------------------------------------------------------+
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 00000000..a979b123
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,223 @@
+Newt Tool Guide
+---------------
+
+.. toctree::
+ :hidden:
+ :titlesonly:
+
+ newt_operation
+ newt_ops
+ install/index
+
+Introduction
+~~~~~~~~~~~~
+
+Newt is a smart build and package management system for embedded
+contexts. It is a single tool that accomplishes both the following
+goals:
+
+- source package management
+- build, debug and install.
+
+Rationale
+~~~~~~~~~
+
+In order for the Mynewt operating system to work well for constrained
+environments across the many different types of micro-controller
+applications (from doorbells to medical devices to power grids), a
+system is needed that lets you select which packages to install and
+which packages to build.
+
+The build systems for embedded devices are often fairly complicated and
+not well served for this purpose. For example, autoconf is designed for
+detecting system compatibility issues but not well suited when it comes
+to tasks like:
+
+- Building for multiple targets
+- Deciding what to build in and what not to build in
+- Managing dependencies between components
+
+Fortunately, solutions addressing these very issues can be found in
+source package management systems in higher level languages such as
+Javascript (Node), Go, PHP and Ruby. We decided to fuse their source
+management systems with a make system built for embedded systems and
+create Newt.
+
+Build System
+~~~~~~~~~~~~
+
+A good build system must allow the user to take a few common steps while
+developing embedded applications:
+
+- Generate full flash images
+- Download debug images to a target board using a debugger
+- Conditionally compile libraries & code based upon build settings
+
+Newt can read a directory tree, build a dependency tree, and emit the
+right build artifacts. An example newt source tree is in
+mynewt-blinky/develop:
+
+.. code-block:: console
+
+ $ tree -L 3 .
+ ??? DISCLAIMER
+ ??? LICENSE
+ ??? NOTICE
+ ??? README.md
+ ??? apps
+ ? ??? blinky
+ ? ??? pkg.yml
+ ? ??? src
+ ??? project.yml
+ ??? targets
+ ??? my_blinky_sim
+ ? ??? pkg.yml
+ ? ??? target.yml
+ ??? unittest
+ ??? pkg.yml
+ ??? target.yml
+
+ 6 directories, 10 files
+
+When Newt sees a directory tree that contains a "project.yml" file, it is smart enough to recognize it as the base directory of a project, and
+automatically builds a package tree. It also recognizes two important package directories in the package tree - "apps" and "targets".
+More on these directories in :doc:`newt_operation`.
+
+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:
+
+.. code-block:: console
+
+ $ 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>
+
+More operations using Newt
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once a target has been built, Newt allows additional operations on the target.
+
+* **load**: Download built target to board
+* **debug**: Open debugger session to 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 :doc:`newt_operation`.
+
+Source Management and Repositories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The other major element of the Newt tool is the ability to create reusable source distributions from a collection of code.
+**A project can be a reusable container of source code.** In other words, projects can be versioned and redistributed, not packages.
+A project bundles together packages that are typically needed to work together in a product e.g. RTOS core, filesystem APIs, and networking stack.
+
+A project that has been made redistributable is known as a **repository**.
+Repositories can be added to your local project by adding them into your project.yml file. Here is an example of the blinky
+project's yml file which relies on apache-mynewt-core:
+
+.. code-block:: console
+
+ $ more project.yml
+ <snip>
+ project.repositories:
+ - apache-mynewt-core
+
+ repository.apache-mynewt-core:
+ type: github
+ vers: 1-latest
+ user: apache
+ repo: incubator-mynewt-core
+
+When you specify this repository in the blinky's project file, you can then use the Newt tool to install dependencies:
+
+.. code-block:: console
+
+ $ newt install
+ Downloading repository description for apache-mynewt-core... success!
+ Downloading repository incubator-mynewt-core (branch: develop) at https://github.com/apache/incubator-mynewt-core.git
+ Cloning into '/var/folders/7l/7b3w9m4n2mg3sqmgw2q1b9p80000gn/T/newt-repo814721459'...
+ remote: Counting objects: 17601, done.
+ remote: Compressing objects: 100% (300/300), done.
+ remote: Total 17601 (delta 142), reused 0 (delta 0), pack-reused 17284
+ Receiving objects: 100% (17601/17601), 6.09 MiB \| 3.17 MiB/s, done.
+ Resolving deltas: 100% (10347/10347), done.
+ Checking connectivity... done.
+ Repos successfully installed
+
+Newt will install this repository in the <project>/repos directory. In the case of blinky, the directory structure ends up looking like:
+
+.. code-block:: console
+
+ $ tree -L 2
+ .
+ ??? DISCLAIMER
+ ??? LICENSE
+ ??? NOTICE
+ ??? README.md
+ ??? apps
+ ? ??? blinky
+ ??? project.state
+ ??? project.yml
+ ??? repos
+ ? ??? apache-mynewt-core
+ ??? targets
+ ??? my_blinky_sim
+ ??? unittest
+
+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.
+
+.. code-block:: console
+
+ $ more apps/blinky/pkg.yml
+ pkg.deps:
+ - "@apache-mynewt-core/kernel/os"
+ - "@apache-mynewt-core/hw/hal"
+ - "@apache-mynewt-core/sys/console/full"
+
+Newt has the ability to autocomplete within ``bash``. The following
+instructions allow MAC users to enable autocomplete within ``bash``.
+
+1. Install the autocomplete tools for bash via
+ ``brew install bash-completion``
+2. Tell your shell to use newt for autocompletion of newt via
+ ``complete -C "newt complete" newt``. You can add this to your
+ .bashrc or other init file to have it automatically set for all bash
+ shells.
+
+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.
diff --git a/docs/install/index.rst b/docs/install/index.rst
new file mode 100644
index 00000000..3acbbc78
--- /dev/null
+++ b/docs/install/index.rst
@@ -0,0 +1,10 @@
+Install
+-----------------
+
+.. toctree::
+ :titlesonly:
+
+ newt_mac
+ newt_linux
+ newt_windows
+ prev_releases
diff --git a/docs/install/newt_linux.rst b/docs/install/newt_linux.rst
new file mode 100644
index 00000000..41b7fa93
--- /dev/null
+++ b/docs/install/newt_linux.rst
@@ -0,0 +1,267 @@
+Installing Newt on Linux
+------------------------
+
+You can install the latest release (1.1.0) of the newt tool from a
+Debian binary package (amd64). You can also download and build the
+latest release version of newt from source.
+
+This page shows you how to:
+
+1. Set up your computer to download Debian binary packages from the
+ runtimeco APT repository.
+ **Note:** The key for signing the repository has changed. If you set
+ up your computer before release 1.1.0, you will need to download and
+ import the public key again.
+
+2. Install the latest release version of newt from a Debian binary
+ package. You can use apt-get to install the package or manually
+ download and install the Debian binary package.
+
+3. Download, build, and install the latest release version of newt from
+ source.
+
+4. Install an earlier version of newt.
+
+If you are installing on an amd64 platform, we recommend that you
+install from the binary package.
+
+**Note:** We have tested the newt tool binary and apt-get install from
+the runtimeco APT repository for Ubuntu version 16. Earlier Ubuntu
+versions (for example: Ubuntu 14) may have incompatibility with the
+repository. You can manually download and install the Debian binary
+package.
+
+**Note:** See :doc:`Setting Up a Go Environment to Contribute to Newt and
+Newtmgr Tools </misc/go_env>` if you want to:
+
+- Use the newt tool with the latest updates from the master branch. The
+ master branch may be unstable and we recommend that you use the
+ latest stable release version.
+- Contribute to the newt tool.
+
+Setting Up Your Computer to use apt-get to Install the Package
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The newt Debian packages are stored in a private APT repository on
+**https://github/runtimeco/debian-mynewt**. To use apt-get, you must set
+up the following on your computer to retrieve packages from the
+repository:
+
+**Note**: You only need to perform this setup once on your computer.
+However, if you previously downloaded and imported the public key for
+the runtimeco APT repository, you will need to perform step 2 again as
+the key has changed.
+
+1. Install the ``apt-transport-https`` package to use HTTPS to retrieve
+ packages.
+2. Download the public key for the runtimeco APT repository and import
+ the key into the apt keychain.
+3. Add the repository for the binary and source packages to the apt
+ source list.
+
+Install the apt-transport-https package:
+
+.. code-block:: console
+
+ $sudo apt-get update
+ $sudo apt-get install apt-transport-https
+
+Download the public key for the runtimeco apt repo (**Note:** There is a
+``-`` after ``apt-key add``):
+
+.. code-block:: console
+
+ wget -qO - https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/mynewt.gpg.key | sudo apt-key add -
+
+Add the repository for the binary and source packages to the
+``mynewt.list`` apt source list file.
+
+.. code-block:: console
+
+ $sudo -s
+ [sudo] password for <user>:
+ root$ cat > /etc/apt/sources.list.d/mynewt.list <<EOF
+ deb https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main
+ EOF
+ root$exit
+
+**Note:** Do not forget to exit the root shell.
+
+Verify the content of the source list file:
+
+.. code-block:: console
+
+ $more /etc/apt/sources.list.d/mynewt.list
+ deb https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main
+
+Update the available packages:
+
+.. code-block:: console
+
+ $sudo apt-get update
+
+**Note:** If you are not using Ubuntu version 16, you may see the
+following errors. We have provided instructions on how to manually
+download and install the binary package.
+
+.. code-block:: console
+
+
+ W: Failed to fetch https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/dists/latest/main/source/Sources Ht
+ tpError404
+
+## Installing the Latest Release of Newt from a Binary Package
+
+You can use either apt-get to install the package, or manually download
+and install the Debian binary package.
+
+#### Method 1: Using apt-get to Upgrade or to Install
+
+Run the following commands to upgrade or install the latest version of
+newt:
+
+.. code-block:: console
+
+
+ $ sudo apt-get update
+ $ sudo apt-get install newt
+
+#### Method 2: Downloading and Installing the Debian Package Manually
+
+Download and install the package manually.
+
+.. code-block:: console
+
+ $wget https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/pool/main/n/newt/newt_1.1.0-1_amd64.deb
+ $sudo dpkg -i newt_1.1.0-1_amd64.deb
+
+See `Checking the Installed Version of Newt <#check>`__ to verify that
+you are using the installed version of newt.
+
+### Installing the Latest Release of Newt from a Source Package
+
+If you are running Linux on a different architecture, you can build and
+install the latest release version of newt from source.
+
+1. You need Go version 1.7.6 or higher to build Newt version 1.0.0.
+Currently, the latest Go version that Ubuntu installs is 1.6. Run
+``go version`` to check if you have Go 1.7.6 installed. You can download
+Go from https://golang.org/dl/.
+
+2. Download and unpack the newt source:
+
+.. code-block:: console
+
+
+ $ wget -P /tmp https://github.com/apache/mynewt-newt/archive/mynewt_1_1_0_tag.tar.gz
+ $ tar -xzf /tmp/mynewt_1_1_0_tag.tar.gz
+
+3. Run the build.sh to build the newt tool.
+
+.. code-block:: console
+
+
+ $ cd mynewt-newt-mynewt_1_1_0_tag
+ $ ./build.sh
+ $ rm /tmp/mynewt_1_1_0_tag.tar.gz
+
+4. You should see the ``newt/newt`` executable. Move the executable to
+a bin directory in your PATH:
+
+- If you previously built newt from the master branch, you can move the
+ binary to your $GOPATH/bin directory.
+
+.. code-block:: console
+
+ $ mv newt/newt $GOPATH/bin
+
+- If you are installing newt for the first time and do not have a Go
+ workspace set up, you can move the binary to /usr/bin or a directory
+ in your PATH:
+
+.. code-block:: console
+
+ $ mv newt/newt /usr/bin
+
+ ### Checking the Installed Version of Newt
+
+1. Check which newt you are using and that the version is the latest
+release version.
+
+.. code-block:: console
+
+ $which newt
+ /usr/bin/newt
+ $newt version
+ Apache Newt version: 1.1.0
+
+2. Get information about newt:
+
+.. code-block:: console
+
+ $newt
+ 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
+ projects, and then build the necessary artifacts from those projects. For more
+ information on the Mynewt operating system, please visit
+ https://mynewt.apache.org/.
+
+ Please use the newt help command, and specify the name of the command you want
+ help for, for help on how to use a specific command
+
+ Usage:
+ newt [flags]
+ newt [command]
+
+ Examples:
+ newt
+ newt help [<command-name>]
+ For help on <command-name>. If not specified, print this message.
+
+ Available Commands:
+ 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
+ load Load built target to board
+ mfg Manufacturing flash image commands
+ new Create a new project
+ pkg Create and manage packages in the current workspace
+ resign-image Re-sign an image.
+ run build/create-image/download/debug <target>
+ size Size of target components
+ sync Synchronize project dependencies
+ target Commands to create, delete, configure, and query targets
+ test Executes unit tests for one or more packages
+ upgrade Upgrade project dependencies
+ vals Display valid values for the specified element type(s)
+ version Display the Newt version number
+
+ 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 [command] --help" for more information about a command.
+
+### Installing Earlier Release Versions of Newt
+
+You can download and install an earlier version of newt.
+
+1. Run ``sudo apt-get remove newt`` command the current installation.
+
+2. Download and install the package. For example, run the following
+commands to install the 1.0.0 version of newt:
+
+.. code-block:: console
+
+
+ $ wget https://raw.githubusercontent.com/runtimeco/binary-releases/master/mynewt-newt-tools_1.0.0/newt_1.0.0-1_amd64.deb
+ $ sudo dpkg -i newt_1.0.0-1_amd64.deb
diff --git a/docs/install/newt_mac.rst b/docs/install/newt_mac.rst
new file mode 100644
index 00000000..353f0b26
--- /dev/null
+++ b/docs/install/newt_mac.rst
@@ -0,0 +1,245 @@
+Installing Newt on Mac OS
+-------------------------
+
+Newt is supported on Mac OS X 64 bit platforms and has been tested on
+Mac OS 10.10 and higher.
+
+This page shows you how to:
+
+- Upgrade to or install the latest release version of newt.
+- Install the latest newt from the master branch (unstable).
+
+See `Installing Previous Releases of Newt <prev_releases>`__ to install an earlier version of newt.
+
+**Note:** If you would like to contribute to the newt tool, see :doc:`Setting Up Go Environment to Contribute
+to Newt and Newtmgr Tools </misc/go_env>`.
+
+Installing Homebrew
+~~~~~~~~~~~~~~~~~~~
+
+If you do not have Homebrew installed, run the following command. You
+will be prompted for your sudo password.
+
+.. code-block:: console
+
+ $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+
+You can also extract (or ``git clone``) Homebrew and install it to
+/usr/local.
+
+Adding the Mynewt Homebrew Tap
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If this is your first time installing newt, add the
+**runtimeco/homebrew-mynewt** tap:
+
+.. code-block:: console
+
+
+ $ brew tap runtimeco/homebrew-mynewt
+ $ brew update
+
+Upgrading to or Installing the Latest Release Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Perform the following to upgrade or install the latest release version
+of newt (1.1.0).
+
+Upgrading to the Latest Release Version of Newt
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you previously installed newt 1.0.0 using brew, run the following
+commands to upgrade to newt 1.1.0:
+
+.. code-block:: console
+
+
+ $ brew update
+ $ brew upgrade mynewt-newt
+
+ #### Installing the Latest Release Version of Newt
+
+Run the following command to install the latest release version (1.1.0)
+of newt:
+
+.. code-block:: console
+
+
+ $ brew update
+ $ brew install mynewt-newt
+ ==> Installing mynewt-newt from runtimeco/mynewt
+ ==> Downloading https://github.com/runtimeco/binary-releases/raw/master/mynewt-newt-tools_1.1.0/mynewt-newt-1.1.0.sierra.bottle.tar.gz
+ ==> Downloading from https://raw.githubusercontent.com/runtimeco/binary-releases/master/mynewt-newt-tools_1.1.0/mynewt-newt-1.1.0.sierra.bottle.tar.gz
+ ######################################################################## 100.0%
+ ==> Pouring mynewt-newt-1.1.0.sierra.bottle.tar.gz
+ ? /usr/local/Cellar/mynewt-newt/1.1.0: 3 files, 10.5MB
+
+ **Notes:** Homebrew bottles for newt 1.1.0 are available for Mac OS
+Sierra, El Captian, and Yosemite. If you are running an earlier version
+of Mac OS, the installation will install the latest version of Go and
+compile newt locally.
+
+ ### Checking the Installed Version
+
+Check that you are using the installed version of newt:
+
+.. code-block:: console
+
+
+ $which newt
+ /usr/local/bin/newt
+ $ls -l /usr/local/bin/newt
+ lrwxr-xr-x 1 user staff 36 Jul 25 19:04 /usr/local/bin/newt -> ../Cellar/mynewt-newt/1.1.0/bin/newt
+ $newt version
+ Apache Newt version: 1.1.0
+
+**Note:** If you previously built newt from source and the output of
+``which newt`` shows
+":math:`GOPATH/bin/newt", you will need to move "`\ GOPATH/bin" after
+"/usr/local/bin" for your PATH in ~/.bash\_profile, and source
+~/.bash\_profile.
+
+ Get information about newt:
+
+.. code-block:: console
+
+
+ $ newt help
+ 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
+ projects, and then build the necessary artifacts from those projects. For more
+ information on the Mynewt operating system, please visit
+ https://mynewt.apache.org/.
+
+ Please use the newt help command, and specify the name of the command you want
+ help for, for help on how to use a specific command
+
+ Usage:
+ newt [flags]
+ newt [command]
+
+ Examples:
+ newt
+ newt help [<command-name>]
+ For help on <command-name>. If not specified, print this message.
+
+ Available Commands:
+ 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
+ load Load built target to board
+ mfg Manufacturing flash image commands
+ new Create a new project
+ pkg Create and manage packages in the current workspace
+ resign-image Re-sign an image.
+ run build/create-image/download/debug <target>
+ size Size of target components
+ sync Synchronize project dependencies
+ target Commands to create, delete, configure, and query targets
+ test Executes unit tests for one or more packages
+ upgrade Upgrade project dependencies
+ vals Display valid values for the specified element type(s)
+ version Display the Newt version number
+
+ 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 [command] --help" for more information about a command.
+
+ ### Installing Earlier Release Versions of Newt
+
+If you want to install newt 1.0, run the following commands:
+
+.. code-block:: console
+
+
+ $ brew update
+ $ brew install mynewt-newt@1.0
+
+**Note:** This is a keg-only installation. newt 1.0 is installed in
+/usr/local/Cellar/mynewt-newt@1.0/1.0.0/bin but not symlinked into
+/usr/local/bin.
+
+If you need this version of newt first in your PATH, run the following
+commands:
+
+.. code-block:: console
+
+
+ $ echo 'export PATH=/usr/local/Cellar/mynewt-newt@1.0/1.0.0/bin:$PATH' >> ~/.bash_profile
+ $ source ~/.bash_profile
+
+ You can also manually symlink into /usr/local/bin as follows:
+
+1. Unlink newt if you have the latest version of newt installed:
+
+ ::
+
+ $ brew unlink mynewt-newt
+
+2. Link mynewt-newt@1.0 into /usr/local/bin:
+
+ ::
+
+ $ brew link -f mynewt-newt@1.0
+
+Installing Newt from the Master Branch
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We recommend that you use the latest release version (1.1.0) of newt. If
+you would like to use the master branch with the latest updates, you can
+install newt from the HEAD of the master branch.
+
+\*\* Notes: \*\*
+
+- The master branch may be unstable.
+- This installation will install the latest version of Go on your
+ computer, if it is not installed, and compile newt locally.
+
+ If you previously installed newt using brew, unlink the current
+version:
+
+.. code-block:: console
+
+ $brew unlink mynewt-newt
+
+ Install the latest unstable version of newt from the master branch:
+
+.. code-block:: console
+
+ $ brew install mynewt-newt --HEAD
+ ==> Installing mynewt-newt from runtimeco/mynewt
+ ==> Cloning https://github.com/apache/mynewt-newt.git
+ Cloning into '/Users/wanda/Library/Caches/Homebrew/mynewt-newt--git'...
+ remote: Counting objects: 624, done.
+ remote: Compressing objects: 100% (502/502), done.
+ remote: Total 624 (delta 156), reused 322 (delta 85), pack-reused 0
+ Receiving objects: 100% (624/624), 1.11 MiB | 0 bytes/s, done.
+ Resolving deltas: 100% (156/156), done.
+ ==> Checking out branch master
+ ==> go install
+ ? /usr/local/Cellar/mynewt-newt/HEAD-5a6266e: 3 files, 10.5MB, built in 5 seconds
+ $newt version
+ Apache Newt version: 1.1.0-dev
+
+ To switch back to the latest stable release version (1.1.0) of newt,
+you can run:
+
+.. code-block:: console
+
+ $brew switch mynewt-newt 1.1.0
+ Cleaning /usr/local/Cellar/mynewt-newt/1.1.0
+ Cleaning /usr/local/Cellar/mynewt-newt/HEAD-5a6266e
+ 1 links created for /usr/local/Cellar/mynewt-newt/1.1.0
+ $newt version
+ Apache Newt version: 1.1.0
diff --git a/docs/install/newt_windows.rst b/docs/install/newt_windows.rst
new file mode 100644
index 00000000..12389ecb
--- /dev/null
+++ b/docs/install/newt_windows.rst
@@ -0,0 +1,251 @@
+Installing Newt on Windows
+--------------------------
+
+You can develop and build Mynewt OS applications for your target boards
+on the Windows platform. This guide shows you how to install the latest
+release version of newt from binary or from source. The tool is written
+in Go (golang).
+
+In Windows, we use MinGW as the development environment to build and run
+Mynewt OS applications for target boards. MinGW runs the bash shell and
+provides a Unix-like environment. This provides a uniform way to build
+Mynewt OS applications. The Mynewt documentation and tutorials use Unix
+commands and you can use the same Unix commands on MinGW to follow the
+tutorials. The documentation will note any commands or behaviors that
+are specific to Windows.
+
+This guide shows you how to perform the following:
+
+1. Install MSYS2/MinGW.
+2. Install Git.
+3. Install latest release of newt (1.2.0) from binary.
+4. Install latest release of newt from source.
+
+See `Installing Previous Releases of
+Newt </newt/install/prev_releases>`__ to install an earlier version of
+newt. You still need to set up your MinGW development environment.
+
+**Note:** If you would like to contribute to the newt tool, see :doc:`Setting
+Up Go Environment to Contribute to Newt and Newtmgr
+Tools </misc/go_env>`.
+
+Installing MSYS2/MinGW
+^^^^^^^^^^^^^^^^^^^^^^
+
+MSYS2/MinGW provides a bash shell and tools
+to build applications that run on Windows. It includes three subsystems:
+
+- MSYS2 toolchain to build POSIX applications that run on Windows.
+- MinGW32 toolchains to build 32 bit native Windows applications.
+- MinGW64 toolchains to build 64 bit native Windows applications.
+
+The subsystems run the bash shell and provide a Unix-like environment.
+You can also run Windows applications from the shell. We will use the
+MinGW subsystem.
+
+**Note:** You can skip this installation step if you already have MinGW
+installed (from an earlier MSYS2/MinGW or Git Bash installation), but
+you must list the **bin** path for your installation in your Windows
+Path. For example: if you installed MSYS2/MinGW in the **C:\\msys64** directory, add
+**C:\\msys64\\usr\\bin** to your
+Windows Path. If you are using Windows 10 WSL, ensure that you use the
+**C:\\msys64\\usr\\bin\\bash.exe** and not the Windows 10 WSL bash.
+
+To install and setup MSYS2 and MinGW:
+
+1. Download and run the `MSYS2 installer <http://www.msys2.org>`__.
+ Select the 64 bit version if you are running on a 64 bit platform.
+ Follow the prompts and check the ``Run MSYS2 now`` checkbox on the
+ ``Installation Complete`` dialog.
+2. In the MSYS2 terminal, run the ``pacman -Syuu`` command. If you get a
+ message to run the update again, close the terminal and run the
+ ``pacman -Syuu`` command in a new terminal.
+
+ To start a new MSYS2 terminal, select the "MSYS2 MSYS" application
+ from the Windows start menu.
+
+3. Add a new user variable named **MSYS2\_PATH\_TYPE** and set the value
+ to **inherit** in your Windows environment. This enables the MSYS2
+ and MinGW bash to inherit your Windows user **Path** values.
+
+ To add the variable, select properties for your computer > Advanced
+ system settings > Environment Variables > New
+
+4. Add the MinGW **bin** path to your Windows Path. For example: if you
+ install MSYS2/MinGW in the **C:\\msys64** directory, add
+ **C:\\msys64\\usr\\bin** to
+ your Windows Path.
+
+ **Note:** If you are using Windows 10 WSL, ensure that you use the
+ **C:\\msys64\\usr\\bin\\bash.exe**
+ and not the Windows 10 WSL bash.
+
+5. Run the ``pacman -Su vim`` command to install the vim editor.
+
+ **Note:** You can also use a Windows editor. You can access your
+ files from the
+ **C:\\\<msys-install-folder\>\\home\\\<username\>** folder,
+ where **msys-install-folder** is the folder you installed MSYS2 in.
+ For example, if you installed MSYS2 in the **msys64** folder, your
+ files are stored in
+ **C:\\msys64\\home\\\<username\>**
+
+You will need to start a MinGW terminal to run the commands specified in
+the Mynewt documentation and tutorials. To start a MinGW terminal,
+select the "MSYS2 Mingw" application from the start Menu (you can use
+either MinGW32 or MinGW64). In Windows, we use the MinGW subsystem to
+build Mynewt tools and applications.
+
+Installing Git for Windows
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Download and install `Git for
+Windows <https://git-for-windows.github.io>`__ if it is not already
+installed.
+
+Installing the Latest Release of the Newt Tool from Binary
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can install the latest release of newt from binary. It has been
+tested on Windows 10 64 bit platform.
+
+1. Start a MinGW terminal.
+
+2. Download the newt binary tar file:
+
+.. code-block:: console
+
+ $ wget -P /tmp https://raw.githubusercontent.com/runtimeco/binary-releases/master/mynewt-newt-tools_1.2.0/newt_1_2_0_windows_amd64.tar.gz
+
+3. Extract the file:
+
+- If you previously built newt from the master branch, you can extract
+ the file into your $GOPATH/bin directory. Note: This overwrites the
+ current newt.exe in the directory and assumes that you are using
+ $GOPATH/bin for your Go applications.
+
+.. code-block:: console
+
+ $ tar -xzf /tmp/newt_1_2_0_windows_amd64.tar.gz -C $GOPATH/bin
+
+- If you are installing newt for the first time and do not have a Go
+ workspace setup, you can extract into /usr/bin directory:
+
+.. code-block:: console
+
+ $ tar -xzf /tmp/newt_1_2_0_windows_amd64.tar.gz -C /usr/bin
+
+4. Verify the installed version of newt. See `Checking the Installed
+Version <#check_newt>`__.
+
+Installing the Latest Release of Newt From Source
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have an older version of Windows or a 32 bit platform, you can
+build and install the latest release version of newt from source.
+
+1. If you do not have Go installed, download and install the latest
+version of `Go <https://golang.org/dl/>`__. Newt requires Go version
+1.7.6 or higher.
+
+2. Start a MinGw terminal.
+
+3. Download and unpack the newt source:
+
+.. code-block:: console
+
+ $ wget -P /tmp https://github.com/apache/mynewt-newt/archive/mynewt_1_2_0_tag.tar.gz
+ $ tar -xzf /tmp/mynewt_1_2_0_tag.tar.gz
+
+4. Run the build.sh to build the newt tool.
+
+.. code-block:: console
+
+ $ cd mynewt-newt-mynewt_1_2_0_tag
+ $ ./build.sh
+ $ rm /tmp/mynewt_1_2_0_tag.tar.gz
+
+5. You should see the ``newt/newt.exe`` executable. Move the executable
+to a bin directory in your PATH:
+
+- If you previously built newt from the master branch, you can move the
+ executable to the $GOPATH/bin directory.
+
+.. code-block:: console
+
+ $ mv newt/newt.exe $GOPATH/bin
+
+- If you are installing newt for the first time and do not have a Go
+ workspace set up, you can move the executable to /usr/bin or a
+ directory in your PATH:
+
+.. code-block:: console
+
+ $ mv newt/newt.exe /usr/bin
+
+Checking the Installed Version
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Check the version of newt:
+
+.. code-block:: console
+
+ $ newt version
+ Apache Newt version: 1.2.0
+
+2. Get information about newt:
+
+.. code-block:: console
+
+ $ newt help
+
+ 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
+ projects, and then build the necessary artifacts from those projects. For more
+ information on the Mynewt operating system, please visit
+ https://mynewt.apache.org/.
+
+ Please use the newt help command, and specify the name of the command you want
+ help for, for help on how to use a specific command
+
+ Usage:
+ newt [flags]
+ newt [command]
+
+ Examples:
+ newt
+ newt help [<command-name>]
+ For help on <command-name>. If not specified, print this message.
+
+ Available Commands:
+ 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
+ load Load built target to board
+ mfg Manufacturing flash image commands
+ new Create a new project
+ pkg Create and manage packages in the current workspace
+ resign-image Re-sign an image.
+ run build/create-image/download/debug <target>
+ size Size of target components
+ sync Synchronize project dependencies
+ target Commands to create, delete, configure, and query targets
+ test Executes unit tests for one or more packages
+ upgrade Upgrade project dependencies
+ vals Display valid values for the specified element type(s)
+ version Display the Newt version number
+
+ 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 [command] --help" for more information about a command.
diff --git a/docs/install/prev_releases.rst b/docs/install/prev_releases.rst
new file mode 100644
index 00000000..b190c3f8
--- /dev/null
+++ b/docs/install/prev_releases.rst
@@ -0,0 +1,89 @@
+Installing Previous Releases of Newt
+------------------------------------
+
+This page shows you how to install previous releases of newt for Mac OS,
+Linux, and Windows.
+
+Mac OS
+~~~~~~
+
+You can install previous releases of newt using ``mynewt-newt@X.Y``
+Homebrew formulas, where X.Y is a version number.
+
+For example, if you want to install newt 1.0, run the following
+commands:
+
+.. code-block:: console
+
+
+ $ brew update
+ $ brew install mynewt-newt@1.0
+
+**Note:** This is a keg-only installation. newt 1.0 is installed in
+/usr/local/Cellar/mynewt-newt@1.0/1.0.0/bin but not symlinked into
+/usr/local/bin.
+
+If you need this version of newt first in your PATH, run the following
+commands:
+
+.. code-block:: console
+
+
+ $ echo 'export PATH=/usr/local/Cellar/mynewt-newt@1.0/1.0.0/bin:$PATH' >> ~/.bash_profile
+ $ source ~/.bash_profile
+
+You can also manually symlink into /usr/local/bin as follows:
+
+1. Unlink newt if you have the latest version of newt installed:
+
+.. code-block:: console
+
+ $ brew unlink mynewt-newt
+
+2. Link mynewt-newt@1.0 into /usr/local/bin:
+
+.. code-block:: console
+
+ $ brew link -f mynewt-newt@1.0
+
+ ### Linux 1. Download the binary:
+
++-----------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+| Version | Download |
++===========+====================================================================================================================================================+
+| 1.0.0 | `newt\_1.0.0-1\_amd64.deb <https://raw.githubusercontent.com/runtimeco/binary-releases/master/mynewt-newt-tools_1.0.0/newt_1.0.0-1_amd64.deb>`__ |
++-----------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+| 1.1.0 | `newt\_1.1.0-1\_amd64.deb <https://raw.githubusercontent.com/runtimeco/binary-releases/master/mynewt-newt-tools_1.1.0/newt_1.1.0-1_amd64.deb>`__ |
++-----------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+
+2. Run the ``sudo apt-get remove newt`` command to remove the the
+current installation.
+
+3. Install the package. For example, run
+``sudo dpkg -i newt_1.0.0-1_amd64.deb`` to install newt 1.0.0
+
+ ### Windows 1. Download the binary:
+
++-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Version | Download |
++===========+================================================================================================================================================================+
+| 1.1.0 | `newt\_1\_1\_0\_windows\_amd64.tar.gz <https://raw.githubusercontent.com/runtimeco/binary-releases/master/mynewt-newt-tools_1.1.0/newt_1.1.0-1_amd64.deb>`__ |
++-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+2. Extract the file:
+
+- If you previously built newt from the master branch, you can extract
+ the file into your $GOPATH/bin directory. Note: This overwrites the
+ current newt.exe in the directory and assumes that you are using
+ $GOPATH/bin for your Go applications.
+
+ ::
+
+ tar -xzf newt_1_1_0_windows_amd64.tar.gz -C $GOPATH/bin
+
+- If you are installing newt for the first time and do not have a Go
+ workspace setup, you can extract into /usr/bin directory:
+
+ ::
+
+ tar -xzf newt_1_1_0_windows_amd64.tar.gz -C /usr/bin
diff --git a/docs/newt_operation.rst b/docs/newt_operation.rst
new file mode 100644
index 00000000..512db983
--- /dev/null
+++ b/docs/newt_operation.rst
@@ -0,0 +1,311 @@
+Theory of Operations
+--------------------
+
+Newt has a fairly smart package manager that can read a directory tree,
+build a dependency tree, and emit the right build artifacts.
+
+Building dependencies
+~~~~~~~~~~~~~~~~~~~~~
+
+Newt can read a directory tree, build a dependency tree, and emit the
+right build artifacts. An example newt source tree is in
+mynewt-blinky/develop:
+
+.. code-block:: console
+
+ $ tree -L 3
+ .
+ ??? LICENSE
+ ??? NOTICE
+ ??? README.md
+ ??? apps
+ ??? ??? blinky
+ ??? ??? pkg.yml
+ ??? ??? src
+ ??? project.yml
+ ??? targets
+ ??? my_blinky_sim
+ ??? ??? pkg.yml
+ ??? ??? target.yml
+ ??? unittest
+ ??? pkg.yml
+ ??? target.yml
+
+ 6 directories, 9 files
+
+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."
+
+"apps" Package Directory
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``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.
+
+.. code-block:: console
+
+ $ ls repos/apache-mynewt-core/apps
+ blecent bleprph blesplit bletiny boot ffs2native slinky spitest test timtest
+ blehci bleprph_oic bletest bleuart fat2native ocf_sample slinky_oic splitty testbench
+
+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:
+
+.. code-block:: console
+
+ $ more apps/blinky/pkg.yml
+ pkg.name: apps/blinky
+ pkg.type: app
+ pkg.description: Basic example application which blinks an LED.
+ pkg.author: "Apache Mynewt <de...@mynewt.apache.org>"
+ pkg.homepage: "http://mynewt.apache.org/"
+ pkg.keywords:
+
+ pkg.deps:
+ - "@apache-mynewt-core/kernel/os"
+ - "@apache-mynewt-core/hw/hal"
+ - "@apache-mynewt-core/sys/console/stub"
+
+This file says that the name of the package is apps/blinky, and it depends on the ``kernel/os``, ``hw/hal`` and ``sys/console/stub`` packages.
+
+**NOTE:** @apache-mynewt-core is a repository descriptor, and this will be
+covered in the "repository" section.
+
+"targets" Package Directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``targets`` 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 ``apps`` directory, ``targets`` represents the top of the build
+tree. Any packages or parameters specified at the target level cascades down to all dependencies.
+
+Most targets consist of:
+
+* app: The application to build
+* bsp: The board support package to combine with that application
+* build_profile: Either debug or optimized.
+
+The ``my_blinky_sim`` target that is included by default has the following settings:
+
+.. code-block:: console
+
+ $ newt target show
+ targets/my_blinky_sim
+ app=apps/blinky
+ bsp=@apache-mynewt-core/hw/bsp/native
+ build_profile=debug
+ $ 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 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'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 :doc:`../os/modules/sysinitconfig/sysinitconfig` for more information on system configuration settings.
+
+Resolving dependencies
+~~~~~~~~~~~~~~~~~~~~~~
+
+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 source packages
+
+Newt then looks at the target that the user set, for example, blinky_sim:
+
+.. code-block:: console
+
+ $ 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"
+
+The target specifies two major things:
+
+* Application (target.app): The application to build
+* Board Support Package (target.bsp): The board support package to build 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, 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.
+
+.. code-block:: console
+
+ $ tree repos/apache-mynewt-core/kernel/os/include/
+ repos/apache-mynewt-core/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
+
+ 12 directories, 25 files
+
+* Validates API requirements. 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).
+
+* 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 in order to access the settings.
+ It also generates a system initialization function to initialize the packages.
+ See :doc:`../os/modules/sysinitconfig/sysinitconfig` 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. 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
+an archive file.
+
+**NOTE:** 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!
+
+Producing artifacts
+~~~~~~~~~~~~~~~~~~~
+
+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.)
+
+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:
+
+.. code-block:: console
+
+ $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>
+
+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
+
+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
+~~~~~~~~~~~~~~~~~~~~~~
+
+Once a target has been built, there are a number of helper functions
+that work on the target. These are:
+
+* **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
+* **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.
+
+.. code-block:: console
+
+ $ more repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_debug.sh
+ <snip>
+ . $CORE_PATH/hw/scripts/jlink.sh
+
+ FILE_NAME=$BIN_BASENAME.elf
+
+ 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
+
+ JLINK_DEV="nRF52"
+
+ jlink_debug
+
+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.
diff --git a/docs/newt_ops.rst b/docs/newt_ops.rst
new file mode 100644
index 00000000..5d723204
--- /dev/null
+++ b/docs/newt_ops.rst
@@ -0,0 +1,69 @@
+Command Structure
+-----------------
+
+.. toctree::
+ :hidden:
+ :titlesonly:
+ :glob:
+
+ command_list/*
+
+Just like verbs are actions in a sentence and adverbs modify 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, *app*, is set to ``@apache-mynewt-core/hw/bsp/nrf52dk``
+
+.. code-block:: console
+
+ 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.
+
+A command may additionally take flags specific to it. For example, the
+``-n`` flag instructs ``newt debug`` not to start GDB from command line.
+
+.. code-block:: console
+
+ newt debug <target-name> -n
+
+In addition to the documentation in :doc:`index`,
+command-line help is available for each command (and subcommand),
+through the ``-h`` or ``--help`` options.
+
+.. code-block:: console
+
+ newt target --help
+ Commands to create, delete, configure, and query targets
+
+ Usage:
+ newt target [flags]
+ newt target [command]
+
+ Available Commands:
+ amend Add, change, or delete values for multi-value target variables
+ config View or populate a target's system configuration
+ copy Copy target
+ create Create a target
+ delete Delete target
+ dep View target's dependency graph
+ revdep View target's reverse-dependency graph
+ set Set target configuration variable
+ show View target configuration variables
+
+ Global Flags:
+ -h, --help Help for newt commands
+ -j, --jobs int Number of concurrent build jobs (default 8)
+ -l, --loglevel string Log level (default "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.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services