pw_watch CLI reference#

Pigweed AI summary: The pw_watch CLI reference provides information on how to use the embedded development file system watcher. The CLI has various options for specifying build directories, targets, and commands, as well as options for build execution, log files, display output, and watch settings. Users can specify patterns to watch for recompilation, ignore patterns, and directories to exclude during pw watch. Additionally, the CLI allows users to start a webserver for documentation and use a fullscreen interface.

usage: pw watch [-h] [-C directory [target ...]]
                [--build-system-command directory command]
                [--run-command RUN_COMMAND] [-j JOBS] [-k] [--parallel]
                [--parallel-workers PARALLEL_WORKERS] [--logfile LOGFILE]
                [--separate-logfiles] [--debug-logging] [--banners]
                [--no-banners] [--colors] [--no-colors] [--patterns PATTERNS]
                [--ignore-patterns IGNORE_PATTERNS_STRING]
                [--exclude-list EXCLUDE_LIST [EXCLUDE_LIST ...]]
                [--no-restart] [--serve-docs]
                [--serve-docs-port SERVE_DOCS_PORT]
                [--serve-docs-path SERVE_DOCS_PATH] [-f]
                [target [target ...]]

Build Directory and Command Options#

Pigweed AI summary: This section discusses the build directory and command options for a software development tool. Users can specify a build directory and targets to build using the "-C" option, and the default directory is "out". The "target" option allows users to specify default build targets. The "--build-system-command" option sets the build system command to "ninja" by default. The "--run-command" option allows users to run additional commands before any "-C" arguments. All of these options have default values of

-C, --build-directory

Specify a build directory and optionally targets to build. pw watch -C out target1 target2 is equivalent to ‘ninja -C out taret1 target2’. The ‘out’ directory will be used if no others are provided.

Default: []

target

Default build targets. For example if the build directory is ‘out’ then, ‘ninja -C out taret1 target2’ will be run. To specify one or more directories, use the -C / --build-directory option.

Default: []

--build-system-command

Build system command for . Default: ninja

Default: []

--run-command

Additional commands to run. These are run before any -C arguments and may be repeated. For example: –run-command ‘bazel build //pw_cli/…’ –run-command ‘bazel test //pw_cli/…’ -C out python.lint python.test

Default: []

Build Execution Options#

Pigweed AI summary: This section discusses the build execution options available for the ninja, bazel, and make build systems. Users can specify the number of cores to use for each build system with the "-j" option, keep building past the first failure with the "-k" option, and run all builds in parallel with the "--parallel" option. Additionally, users can set the number of builds that may run at the same time with the "--parallel-workers" option, with a default value of 0 meaning all builds

-j, --jobs

Specify the number of cores to use for each build system. This is passed to ninja, bazel and make as “-j”

-k, --keep-going

Keep building past the first failure. This is equivalent to running “ninja -k 0” or “bazel build -k”.

--parallel

Run all builds in parallel.

--parallel-workers

How many builds may run at the same time when –parallel is enabled. Default: 0 meaning run all in parallel.

Default: 0

Log File Options#

Pigweed AI summary: This paragraph describes the different options available for logging in a global build output log file. The first option is to use the "--logfile" option to create a single log file for all builds. The second option is to use the "--separate-logfiles" option to create separate log files for each build directory. The third option is to use the "--debug-logging" option to enable debug logging for the Python build execution tool.

--logfile

Global build output log file.

--separate-logfiles

Create separate log files per build directory.

--debug-logging

Enable Python build execution tool debug logging.

Display Output Options#

Pigweed AI summary: This section describes the display output options for a program. The options include showing or hiding pass/fail banners and forcing or not forcing color output from the program.

--banners

Show pass/fail banners.

--no-banners

Hide pass/fail banners.

--colors

Force color output from ninja.

--no-colors

Don’t force ninja to use color output.

Watch Options#

Pigweed AI summary: This section describes various options for watching and compiling files in a project. The options include specifying patterns to trigger recompilation, ignoring certain patterns, excluding directories, disabling automatic restarts, and starting a webserver for documentation. The default values for these options are also provided.

--patterns

Comma delimited list of globs to watch to trigger recompile.

Default: “.bloaty,.c,*.cc,*.css,*.cpp,*.cmake,CMakeLists.txt,*.dts,*.dtsi,*.gn,*.gni,*.go,*.h,*.hpp,*.html,*.js,*.ld,*.md,*.options,*.proto,*.py,*.rs,*.rst,*.s,*.S,*.toml,*.ts”

--ignore-patterns

Comma delimited list of globs to ignore events from.

--exclude-list

Directories to ignore during pw watch. This option may be repeated. Directories are passed as separate arguments.

Default: []

--no-restart

Do not restart ongoing builds if files change.

--serve-docs

Start a webserver for docs on localhost. The port for this webserver can be set with the –serve-docs-port option. Defaults to http://127.0.0.1:8000

--serve-docs-port

Set the port for the docs webserver. Default: 8000.

Default: 8000

--serve-docs-path

Set the path for the docs to serve. Default: docs/gen/docs in the build directory.

Default: docs/gen/docs

-f, --fullscreen

Use a fullscreen interface.