This is an automated email from the ASF dual-hosted git repository.
janc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/mynewt-newt.git
The following commit(s) were added to refs/heads/master by this push:
new dab17236 docs: Fix the layout in multiple .rst files for the PDF output
dab17236 is described below
commit dab172365665cdf9481454db7f61519dd6b6443d
Author: Wojciech Pietraszewski <[email protected]>
AuthorDate: Thu Sep 26 15:08:14 2024 +0200
docs: Fix the layout in multiple .rst files for the PDF output
Fixes formatting issues in the `command list` section.
---
docs/command_list/newt_build.rst | 17 ++-
docs/command_list/newt_clean.rst | 21 +--
docs/command_list/newt_create_image.rst | 47 +++----
docs/command_list/newt_debug.rst | 17 ++-
docs/command_list/newt_mfg.rst | 21 +--
docs/command_list/newt_new.rst | 13 +-
docs/command_list/newt_run.rst | 17 ++-
docs/command_list/newt_size.rst | 13 +-
docs/command_list/newt_target.rst | 223 ++++++++++++++++----------------
docs/command_list/newt_vals.rst | 13 +-
10 files changed, 218 insertions(+), 184 deletions(-)
diff --git a/docs/command_list/newt_build.rst b/docs/command_list/newt_build.rst
index af8bef25..ba2a3c6b 100644
--- a/docs/command_list/newt_build.rst
+++ b/docs/command_list/newt_build.rst
@@ -33,10 +33,13 @@ You can specify a list of target names, separated by a
space, to build multiple
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.
|
-+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+.. tabularcolumns:: |l|p{10cm}|
+.. table::
+
+
+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | 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
index 7c2d1f61..0fd0e6ef 100644
--- a/docs/command_list/newt_clean.rst
+++ b/docs/command_list/newt_clean.rst
@@ -31,12 +31,15 @@ Deletes all the build artifacts generated for the
``target-name`` target. It doe
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.
|
-+------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+.. tabularcolumns:: |l|p{10cm}|
+.. table::
+
+
+------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | 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_create_image.rst
b/docs/command_list/newt_create_image.rst
index 9c4c544d..bd5e9423 100644
--- a/docs/command_list/newt_create_image.rst
+++ b/docs/command_list/newt_create_image.rst
@@ -33,25 +33,28 @@ To sign an image, provide a .pem file for the
``signing-key`` and an optional ``
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/btshell
- |
bsp=\@apache-mynewt-core/hw/bsp/nrf52dk
- | build\_profile=optimized
- | syscfg=STATS\_NAMES=1
-
- the
'bin/targets/myble2/app/apps/btshell/btshell.img' and
-
'bin/targets/myble2/app/apps/btshell/btshell.hex' files are created,
- and the manifest in
'bin/targets/myble2/app/apps/btshell/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.
-==================================================
=================================================================================
+.. tabularcolumns:: |l|p{7.2cm}|
+.. table::
+
+ ==================================================
=================================================================================
+ 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/btshell
+ |
bsp=\@apache-mynewt-core/hw/bsp/nrf52dk
+ |
build\_profile=optimized
+ | syscfg=STATS\_NAMES=1
+
+ the
'bin/targets/myble2/app/apps/btshell/btshell.img' and
+
'bin/targets/myble2/app/apps/btshell/btshell.hex' files are created,
+ and the manifest in
'bin/targets/myble2/app/apps/btshell/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
index 8bb9af82..6978c7e1 100644
--- a/docs/command_list/newt_debug.rst
+++ b/docs/command_list/newt_debug.rst
@@ -39,10 +39,13 @@ 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/btshell/btshell.elf when the
target is as follows: targets/myble2 app=\@apache-mynewt-core/apps/btshell
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/btshell/btshell.elf but do not start GDB on the
command line.
|
-+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+.. tabularcolumns:: |l|p{12cm}|
+.. table::
+
+
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | Usage | Explanation
|
+
+==========================+============================================================================================================================================================================================================================================================================================+
+ | ``newt debug myble2`` | Opens a J-Link connection and starts a GNU gdb
session to debug bin/targets/myble2/app/apps/btshell/btshell.elf when the
target is as follows: targets/myble2 app=\@apache-mynewt-core/apps/btshell
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/btshell/btshell.elf but do not start GDB on the
command line.
|
+
+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
diff --git a/docs/command_list/newt_mfg.rst b/docs/command_list/newt_mfg.rst
index 819a27e0..fd03b467 100644
--- a/docs/command_list/newt_mfg.rst
+++ b/docs/command_list/newt_mfg.rst
@@ -36,15 +36,18 @@ Global Flags:
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 [...]
-+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
-| 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.
[...]
-+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+.. tabularcolumns:: |l|p{13cm}|
+.. table::
+
+
+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+ | 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 t [...]
+
+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+ | 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
^^^^^^^^
diff --git a/docs/command_list/newt_new.rst b/docs/command_list/newt_new.rst
index ab094ad1..5c49ecd4 100644
--- a/docs/command_list/newt_new.rst
+++ b/docs/command_list/newt_new.rst
@@ -31,8 +31,11 @@ Creates a new project named ``project-name`` from the
default skeleton `blinky r
Examples
^^^^^^^^
-+---------------------------+-------------------------------------------------------------------------------------------------------------------------+
-| Usage | Explanation
|
-+===========================+=========================================================================================================================+
-| ``newt new test_project`` | Creates a new project named ``test_project``
using the default skeleton from the ``apache/mynewt-blinky`` repository. |
-+---------------------------+-------------------------------------------------------------------------------------------------------------------------+
+.. tabularcolumns:: |l|p{11.5cm}|
+.. table::
+
+
+---------------------------+-------------------------------------------------------------------------------------------------------------------------+
+ | 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_run.rst b/docs/command_list/newt_run.rst
index 3457e144..099451e0 100644
--- a/docs/command_list/newt_run.rst
+++ b/docs/command_list/newt_run.rst
@@ -44,10 +44,13 @@ Same as running ``build <target-name>``, ``create-image
<target-name> <version>`
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. |
-+------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+.. tabularcolumns:: |l|p{10.5cm}|
+.. table::
+
+
+------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | 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
index 79f00162..b4e2eab4 100644
--- a/docs/command_list/newt_size.rst
+++ b/docs/command_list/newt_size.rst
@@ -39,11 +39,14 @@ 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. |
-+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
+.. tabularcolumns:: |l|p{11.5cm}|
+.. table::
+
+
+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
+ | 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``:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/command_list/newt_target.rst
b/docs/command_list/newt_target.rst
index 2beece15..818e041b 100644
--- a/docs/command_list/newt_target.rst
+++ b/docs/command_list/newt_target.rst
@@ -43,143 +43,150 @@ 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:
+.. tabularcolumns:: |l|p{13.8cm}|
+.. table::
+ :class: longtable
- ``newt target amend <target-name> <var-name=var-value>
[var-name=var-value...]``
+ =============
=========================================================================================================================
+ 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:
- Specify the ``-d`` flag to delete values.
+ ``newt target amend <target-name> <var-name=var-value>
[var-name=var-value...]``
- The following multi-value variables can be amended:
``aflags``, ``cflags``, ``lflags``, ``syscfg``.
+ Specify the ``-d`` flag to delete values.
- The ``var-value`` format depends on the ``var-name`` as
follows:
+ The following multi-value variables can be amended:
``aflags``, ``cflags``, ``lflags``, ``syscfg``.
- ``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.
+ The ``var-value`` format depends on the ``var-name`` as
follows:
- ``syscfg``:
- The ``syscfg`` variable allows you to assign values to
configuration settings in your target's ``syscfg.yml`` file.
+ ``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.
- 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.
+ ``syscfg``:
+ The ``syscfg`` variable allows you to assign values to
configuration settings in your target's ``syscfg.yml`` file. The format is:
- 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``.
+
``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.
-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.
+ 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``.
-copy The copy <src-target> <dst-target> command creates a new
target named ``dst-target`` by cloning the
- ``src-target`` target.
+ 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.
-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.
+ copy The copy <src-target> <dst-target> command creates a new
target named ``dst-target`` by cloning the
+ ``src-target`` target.
-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.
+ 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.
-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.
+ 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.
-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.
+ 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.
-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.
+ 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.
- The valid ``var-name`` values are: ``app``, ``bsp``,
``loader``, ``build_profile``, ``cflags``,
- ``lflags``, ``aflags``, ``syscfg``.
+ 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 ``var-value`` format depends on the ``var-name`` as
follows:
+ The valid ``var-name`` values are: ``app``, ``bsp``,
``loader``, ``build_profile``, ``cflags``,
+ ``lflags``, ``aflags``, ``syscfg``.
- ``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``.
+ The ``var-value`` format depends on the ``var-name`` as
follows:
- ``build_profile``:
- ``optimized`` or ``debug``
+ ``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``.
- ``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.
+ ``build_profile``:
+ ``optimized`` or ``debug``
- ``syscfg``:
- The ``syscfg`` variable allows you to assign values to
configuration settings in your target's ``syscfg.yml`` file.
+ ``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.
- 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.
+ ``syscfg``:
+ The ``syscfg`` variable allows you to assign values to
configuration settings in your target's ``syscfg.yml`` file. The format is:
- You can specify ``var-name=`` or ``var-name=""`` to unset a
variable value.
+
``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.
- **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``
+ You can specify ``var-name=`` or ``var-name=""`` to unset a
variable value.
- 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.
+ **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``
-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.
+ 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_btshell`` |
Creates the ``rb_btshell`` 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_btshell`` |
Deletes the ``rb_btshell`` target. It deletes the ``targets/rb_btshell``
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 ``btshell`` as the application to build for the ``myble`` target.
|
-| | ``app=@apache-mynewt-core/apps/btshell`` |
|
-+---------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| 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.
|
-+---------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+.. tabularcolumns:: |l|p{6.5cm}|p{7cm}|
+.. table::
+
+
+---------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | 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_btshell`` |
Creates the ``rb_btshell`` 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_btshell`` |
Deletes the ``rb_btshell`` target. It deletes the ``targets/rb_btshell``
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 ``btshell`` as the application to build for the ``myble`` target.
|
+ | | ``app=@apache-mynewt-core/apps/btshell`` |
|
+
+---------------+---------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | 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_vals.rst b/docs/command_list/newt_vals.rst
index 88dff11f..9a641286 100644
--- a/docs/command_list/newt_vals.rst
+++ b/docs/command_list/newt_vals.rst
@@ -40,11 +40,14 @@ Displays valid values for the specified element type(s).
You must set valid valu
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. |
-+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+.. tabularcolumns:: |l|p{13cm}|
+.. table::
+
+
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | 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``:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
