pw_module#

Stable

The pw_module module contains tools for managing Pigweed modules. For information on the structure of a Pigweed module, refer to Platform.

Commands#

pw module check#

The pw module check command exists to ensure that your module conforms to the Pigweed module norms.

For example, at time of writing pw module check pw_module is not passing its own lint:

$ ./pw module check pw_module

 ▒█████▄   █▓  ▄███▒  ▒█    ▒█ ░▓████▒ ░▓████▒ ▒▓████▄
  ▒█░  █░ ░█▒ ██▒ ▀█▒ ▒█░ █ ▒█  ▒█   ▀  ▒█   ▀  ▒█  ▀█▌
  ▒█▄▄▄█░ ░█▒ █▓░ ▄▄░ ▒█░ █ ▒█  ▒███    ▒███    ░█   █▌
  ▒█▀     ░█░ ▓█   █▓ ░█░ █ ▒█  ▒█   ▄  ▒█   ▄  ░█  ▄█▌
  ▒█      ░█░ ░▓███▀   ▒█▓▀▓█░ ░▓████▒ ░▓████▒ ▒▓████▀

20191205 17:05:19 INF Checking module: pw_module
20191205 17:05:19 ERR PWCK004: Missing ReST documentation; need at least e.g. "docs.rst"
20191205 17:05:19 ERR FAIL: Found errors when checking module pw_module

pw module create#

The pw module create command generates all the required boilerplate for a new Pigweed project module, including source files, tests, documentation, and build files for GN, Bazel, and CMake.

Usage#

pw module create [OPTIONS] MODULE_NAME

Options

  • --build-systems: A comma-separated list of build systems the module should support (e.g., gn,bazel). Options are gn, bazel, and cmake. Defaults can be configured as described in Configuration.

  • --languages: A comma-separated list of languages the module will use. Supported languages are cc and py.

  • --owners: (Upstream only) A comma-separated list of emails of the people who will own and maintain the new module. This list must contain at least two entries, and at least one user must be a top-level OWNER.

Naming Conventions

Module names must conform to a specific format:

  • They must start with a prefix of at least two letters (e.g., pw).

  • The prefix must be followed by an underscore and the rest of the name.

  • The rest of the name consists of groups of alphanumeric characters separated by single underscores.

  • Upstream Pigweed modules must use the pw prefix.

  • In C++ code, the prefix and the rest of the name define a nested namespace for the module. For example, pw_module_name results in the namespace pw::module_name.

Upstream Integration

In upstream Pigweed, pw module create also registers the module in PIGWEED_MODULES and the docs build, and scaffolds //<module>/module.toml. The new module.toml file has no documentation category yet, so the docs build fails until you add one and run the sync tool, as described in Module categorization.

Downstream Support

When run in a downstream project, pw module create creates the module directory and files but skips the upstream integration steps.

Configuration#

You can configure the default build systems and languages for pw module commands in your pigweed.json file:

If omitted, these default to all supported build systems and languages.

{
  "pw": {
    "pw_module": {
      "default_build_systems": ["gn", "bazel"],
      "default_languages": ["cc"]
    }
  }
}