Skip to content
Permalink
Browse files

scripts: make west build -h fit on a screen

The west build --help output no longer fits in a single page.  Move
details and examples into the documentation, so the -h output doesn't
require scrolling around.

Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
  • Loading branch information...
mbolivar authored and nashif committed May 4, 2019
1 parent 3a486a8 commit 83a5fd8d4ca360c86162229d5751a4caf9afa523
Showing with 36 additions and 60 deletions.
  1. +25 −8 doc/guides/west/build-flash-debug.rst
  2. +8 −49 scripts/west_commands/build.py
  3. +3 −3 scripts/west_commands/build_helpers.py
@@ -27,16 +27,31 @@ directly delegate to West.
Building: ``west build``
************************

.. tip:: Run ``west build -h`` for additional help.
.. tip:: Run ``west build -h`` for a quick overview.

The ``build`` command helps you build Zephyr applications from source. You can
use :ref:`west config <west-config-cmd>` to configure its behavior.

This command attempts to "do what you mean" when run from a Zephyr application
source or build directory:

- When you run ``west build`` in an existing build directory, the board, source
directory, etc. are obtained from the CMake cache, and that build directory
is re-compiled.

- The same is true if a Zephyr build directory named :file:`build` exists in
your current working directory.

- Otherwise, the source directory defaults to the current working directory, so
running ``west build`` from a Zephyr application's source directory compiles
it.

Basics
======

The easiest way to use it is to go to an application's root directory (i.e. the
folder containing its :file:`CMakeLists.txt`) and then run::
The easiest way to use ``west build`` is to go to an application's root
directory (i.e. the folder containing the application's :file:`CMakeLists.txt`)
and then run::

west build -b <BOARD>

@@ -52,12 +67,13 @@ exactly the same name you would supply to CMake if you were to invoke it with:
A build directory named :file:`build` will be created, and the application will
be compiled there after ``west build`` runs CMake to create a build system in
that directory. If you run ``west build`` with an existing build directory, the
application is incrementally re-compiled without re-running CMake.
application is incrementally re-compiled without re-running CMake (you can
force CMake to run again with ``--cmake``).

You don't need to give ``-b`` if you've already got an existing build
directory; ``west build`` can figure out the board from the CMake cache. For
new builds, the :envvar:`BOARD` environment variable and ``build.board``
configuration option can also be used to set the board.
You don't need to use the ``--board`` option if you've already got an existing
build directory; ``west build`` can figure out the board from the CMake cache.
For new builds, the ``--board`` option, :envvar:`BOARD` environment variable,
or ``build.board`` configuration option are checked (in that order).

To configure ``west build`` to build for the ``reel_board`` by default::

@@ -109,6 +125,7 @@ To let west decide for you if a pristine build is needed, use ``-p auto``::
You can run ``west config build.pristine auto`` to make this setting
permanent.


.. _west-building-generator:

To add additional arguments to the CMake invocation performed by ``west
@@ -25,43 +25,8 @@
BUILD_DESCRIPTION = '''\
Convenience wrapper for building Zephyr applications.
This command attempts to do what you mean when run from a Zephyr
application source or a pre-existing build directory:
- When the build directory ('./build' by default, see below) exists and is
already a Zephyr build directory, the source directory is obtained from the
CMake cache, and that build directory is re-compiled.
- Otherwise, the source directory defaults to the current working
directory, so running "west build" from a Zephyr application's
source directory compiles it.
The source and build directories can be explicitly set with the
--source-dir and --build-dir options. The build directory defaults to
'build' if it is not auto-detected. The build directory is always
created if it does not exist.
The board to build for is taken from the CACHED_BOARD CMake cache
variable, --board option, BOARD environment variable, or build.board
configuration option, in decreasing order of precedence.
This command runs CMake to generate a build system if one is not
present in the build directory, then builds the application.
Subsequent builds try to avoid re-running CMake; you can force it
to run by setting --cmake.
To pass additional options to CMake, give them as extra arguments
after a '--'. For example, this sets an overlay config file:
west build [...] -- -DOVERLAY_CONFIG=some.conf
(Doing this forces a CMake run.)
positional arguments:
source_dir Explicitly set the source directory. If not given and
rebuilding an existing Zephyr build directory, this is
taken from the CMake cache. Otherwise, the current
directory is assumed.
source_dir Use this path as the source directory
cmake_opt Extra options to pass to CMake; implies -c
'''

@@ -121,29 +86,23 @@ def do_add_parser(self, parser_adder):
parser.add_argument('-s', '--source-dir', help=argparse.SUPPRESS)
parser.add_argument('-d', '--build-dir',
help=BUILD_DIR_DESCRIPTION +
"The directory is created if it doesn't exist.")
" Always created if it doesn't exist.")
parser.add_argument('-t', '--target',
help='''Override the build system target (e.g.
'clean', 'pristine', etc.)''')
help='''Build system target to run''')
parser.add_argument('-p', '--pristine', choices=['auto', 'always',
'never'], action=AlwaysIfMissing, nargs='?',
help='''Control whether the build folder is made
pristine before building if a build system is
present in the build dir. --pristine is the same as
--pristine=always. If set to auto, the build folder
will be made pristine only if required based on the
existing build system and the options provided.
This allows for reusing a build folder even if it
contains build files for a different board or
application.''')
pristine before running CMake. --pristine is the
same as --pristine=always. If 'auto', it will
be made pristine only if needed.''')
parser.add_argument('-c', '--cmake', action='store_true',
help='Force CMake to run')
parser.add_argument('--cmake-only', action='store_true',
help="Just run CMake; don't build. Implies -c.")
parser.add_argument('-n', '--just-print', '--dry-run', '--recon',
dest='dry_run', action='store_true',
help='''Just print the build commands which would
have run, without actually running them.''')
help='''Just print the build commands; don't run
them''')
parser.add_argument('-o', '--build-opt', default=[], action='append',
help='''Options to pass to the build tool.
May be given more than once to append multiple
@@ -21,9 +21,9 @@
'''Name of the default CMake generator.'''

BUILD_DIR_DESCRIPTION = '''\
Explicitly sets the build directory. If not given and the current
directory is a Zephyr build directory, it will be used; otherwise,
"{}" is assumed.'''.format(DEFAULT_BUILD_DIR)
Build directory. If missing and run in a Zephyr build directory, it is
used; otherwise, it's "{}".'''.format(
DEFAULT_BUILD_DIR)


def find_build_dir(dir):

0 comments on commit 83a5fd8

Please sign in to comment.
You can’t perform that action at this time.