From a316d3d5dcfca6dd39e67e0420e4b34ad0705dbd Mon Sep 17 00:00:00 2001 From: Wojciech Pietraszewski Date: Thu, 26 Sep 2024 15:08:14 +0200 Subject: [PATCH] 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 af8bef255..ba2a3c6b1 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 7c2d1f61e..0fd0e6eff 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 9c4c544dc..bd5e94232 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 8bb9af82f..6978c7e1b 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. 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 819a27e0d..fd03b467a 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//`` package (see Examples below), this command collects the manufacturing related files in the newly created ``bin/mfgs/`` 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. | -+---------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. 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//`` package (see Examples below), this command collects the manufacturing related files in the newly created ``bin/mfgs/`` 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 ^^^^^^^^ diff --git a/docs/command_list/newt_new.rst b/docs/command_list/newt_new.rst index ab094ad1c..5c49ecd42 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 3457e1446..099451e0e 100644 --- a/docs/command_list/newt_run.rst +++ b/docs/command_list/newt_run.rst @@ -44,10 +44,13 @@ Same as running ``build ``, ``create-image ` 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 79f001620..b4e2eab44 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 2beece158..818e041b4 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 [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 [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 command displays the system - configuration setting definitions and values for all the packages that the ``target-name`` target includes. - The config init 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 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 command displays the system + configuration setting definitions and values for all the packages that the ``target-name`` target includes. + The config init 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 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 command creates a new target named ``dst-target`` by cloning the + ``src-target`` target. -delete The delete 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 `` - command **before** deleting the target. + create The create 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 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 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 `` + command **before** deleting the target. -revdep The revdep 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 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 [var-name=var-value...] command sets variables (attributes) - for the target. The set command overwrites your current variable values. + revdep The revdep 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 [var-name=var-value...] command sets variables (attributes) + for the 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``: - \@, 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``: + \@, 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 `` - 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 `` + 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 88dff11f1..9a6412865 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``: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^