pw_package#

Pigweed AI summary: The package module in Pigweed provides a way to install additional tools not covered by pw_env_setup. This is useful for dependencies that are large, have multiple versions, have license issues, or require installation beyond extraction. The pw package command has subcommands for listing, installing, checking status, and removing packages. Middleware-only packages are not recommended for use in downstream projects, but can be installed with the --force flag. To add a new package, create a class that subclasses Package from pw_package/package

The package module provides a mechanism to install additional tools used by Pigweed. Most Pigweed dependencies should be installed using pw_env_setup. Examples of reasons packages should be managed using this module instead are listed below.

  • The dependency is extremely large and not commonly used.

  • The dependency has a number of compatible versions and we want to allow downstream projects to pick a version rather than being forced to use ours.

  • The dependency has license issues that make it complicated for Google to include it directly as a submodule or distribute it as a CIPD package.

  • The dependency needs to be “installed” into the system in some manner beyond just extraction and thus isn’t a good match for distribution with CIPD.

Usage#

Pigweed AI summary: The package module can be accessed through the "pw package" command, which has several subcommands including listing all installed and available packages, installing a package, checking the status of a package, and removing a package. By default, "pw package" operates on the directory referenced by PW_PACKAGE_ROOT. Pigweed includes middleware-only packages that should not be used by projects using Pigweed, but can be installed with the use of "--force" on the command line or "force=True" in Python code

The package module can be accessed through the pw package command. This has several subcommands.

pw package list

Lists all the packages installed followed by all the packages available.

pw package install <package-name>

Installs <package-name>. Exactly how this works is package-dependent, and packages can decide to do nothing because the package is current, do an incremental update, or delete the current version and install anew. Use --force to remove the package before installing.

pw package status <package-name>

Indicates whether <package-name> is installed.

pw package remove <package-name>

Removes <package-name>.

By default pw package operates on the directory referenced by PW_PACKAGE_ROOT.

Middleware-Only Packages#

Pigweed AI summary: Pigweed has several middleware-only packages that clone git repositories, but they should not be used by projects using Pigweed. These packages are used by Pigweed to avoid using submodules, which can result in multiple copies of a repository in the source tree of downstream projects. Instead, projects using Pigweed should use submodules, which are supported by more mature tooling like git. However, if necessary, these packages can be installed using the "--force" command line option or "force=True"

Pigweed itself includes a number of packages that simply clone git repositories. In general, these should not be used by projects using Pigweed. Pigweed uses these packages to avoid using submodules so downstream projects don’t have multiple copies of a given repository in their source tree. Projects using Pigweed should use submodules instead of packages because submodules are supported by much more mature tooling: git. To install these packages anyway, use --force on the command line or force=True in Python code.

Configuring#

Pigweed AI summary: This document provides instructions for configuring and adding a new package to the package manager in Python 3. To add a new package, create a class that subclasses "Package" from "pw_package/package_manager.py" and register it with the package manager. There is also a helper class for retrieving specific revisions of Git repositories in "pw_package/git_repo.py". To set up the package manager for a new project, create a file and add it to the "PW_PLUGINS" file. Options for code

Compatibility#

Pigweed AI summary: Python 3 is mentioned in the Compatibility section.

Python 3

Adding a New Package#

Pigweed AI summary: This section explains how to add a new package by creating a class that subclasses "Package" from "pw_package/package_manager.py". The class should implement the installation of a specific package and have methods for installing, removing, and checking the status of the package. There is also a helper class for retrieving specific revisions of Git repositories. Finally, the new class should be registered with the package manager using "pw_package.package_manager.register(PackageClass)".

To add a new package create a class that subclasses Package from pw_package/package_manager.py.

class Package:
    """Package to be installed.

    Subclass this to implement installation of a specific package.
    """
    def __init__(self, name):
        self._name = name

    @property
    def name(self):
        return self._name

    def install(self, path: pathlib.Path) -> None:
        """Install the package at path.

        Install the package in path. Cannot assume this directory is empty—it
        may need to be deleted or updated.
        """

    def remove(self, path: pathlib.Path) -> None:
        """Remove the package from path.

        Removes the directory containing the package. For most packages this
        should be sufficient to remove the package, and subclasses should not
        need to override this package.
        """
        if os.path.exists(path):
            shutil.rmtree(path)

    def status(self, path: pathlib.Path) -> bool:
        """Returns if package is installed at path and current.

        This method will be skipped if the directory does not exist.
        """

There’s also a helper class for retrieving specific revisions of Git repositories in pw_package/git_repo.py.

Then call pw_package.package_manager.register(PackageClass) to register the class with the package manager.

Setting up a Project#

Pigweed AI summary: This paragraph explains how to set up the package manager for a new project by creating a file and adding it to the PW_PLUGINS file. It provides a sample code for the file and mentions the need to import certain modules despite them appearing unused.

To set up the package manager for a new project create a file like below and add it to the PW_PLUGINS file (see pw_cli for details). This file is based off of pw_package/pigweed_packages.py.

from pw_package import package_manager
# These modules register themselves so must be imported despite appearing
# unused.
from pw_package.packages import nanopb

def main(argv=None) -> int:
    return package_manager.run(**vars(package_manager.parse_args(argv)))

Options#

Pigweed AI summary: The "Options" section explains that code formatting options can be specified in the "pigweed.json" file, with the current limitation of only one option. The available option is "allow_middleware_only_packages", which allows middleware-only packages to be installed. The section includes a code block showing how to specify this option in the "pigweed.json" file.

Options for code formatting can be specified in the pigweed.json file (see also SEED-0101). This is currently limited to one option.

  • allow_middleware_only_packages: Allow middleware-only packages to be installed. See Middleware-Only Packages for more.

{
  "pw": {
    "pw_package": {
      "allow_middleware_only_packages": true
    }
  }
}