third_party/pigweed/repo/pw_package/docs.rst

   1 .. _module-pw_package:
   2
   3 ==========
   4 pw_package
   5 ==========
   6 The package module provides a mechanism to install additional tools used by
   7 Pigweed. Most Pigweed dependencies should be installed using
   8 :ref:`module-pw_env_setup`. Examples of reasons packages should be managed using
   9 this module instead are listed below.
  10
  11 * The dependency is extremely large and not commonly used.
  12 * The dependency has a number of compatible versions and we want to allow
  13   downstream projects to pick a version rather than being forced to use ours.
  14 * The dependency has license issues that make it complicated for Google to
  15   include it directly as a submodule or distribute it as a CIPD package.
  16 * The dependency needs to be "installed" into the system in some manner beyond
  17   just extraction and thus isn't a good match for distribution with CIPD.
  18
  19 -----
  20 Usage
  21 -----
  22 The package module can be accessed through the ``pw package`` command. This
  23 has several subcommands.
  24
  25 ``pw package list``
  26   Lists all the packages installed followed by all the packages available.
  27
  28 ``pw package install <package-name>``
  29   Installs ``<package-name>``. Exactly how this works is package-dependent,
  30   and packages can decide to do nothing because the package is current, do an
  31   incremental update, or delete the current version and install anew. Use
  32   ``--force`` to remove the package before installing.
  33
  34 ``pw package status <package-name>``
  35   Indicates whether ``<packagxe-name>`` is installed.
  36
  37 ``pw package remove <package-name>``
  38   Removes ``<package-name>``.
  39
  40 -----------
  41 Configuring
  42 -----------
  43
  44 Compatibility
  45 ~~~~~~~~~~~~~
  46 Python 3
  47
  48 Adding a New Package
  49 ~~~~~~~~~~~~~~~~~~~~
  50 To add a new package create a class that subclasses ``Package`` from
  51 ``pw_package/package_manager.py``.
  52
  53 .. code-block:: python
  54
  55   class Package:
  56       """Package to be installed.
  57
  58       Subclass this to implement installation of a specific package.
  59       """
  60       def __init__(self, name):
  61           self._name = name
  62
  63       @property
  64       def name(self):
  65           return self._name
  66
  67       def install(self, path: pathlib.Path) -> None:
  68           """Install the package at path.
  69
  70           Install the package in path. Cannot assume this directory is empty—it
  71           may need to be deleted or updated.
  72           """
  73
  74       def remove(self, path: pathlib.Path) -> None:
  75           """Remove the package from path.
  76
  77           Removes the directory containing the package. For most packages this
  78           should be sufficient to remove the package, and subclasses should not
  79           need to override this package.
  80           """
  81           if os.path.exists(path):
  82               shutil.rmtree(path)
  83
  84       def status(self, path: pathlib.Path) -> bool:
  85           """Returns if package is installed at path and current.
  86
  87           This method will be skipped if the directory does not exist.
  88           """
  89
  90 There's also a helper class for retrieving specific revisions of Git
  91 repositories in ``pw_package/git_repo.py``.
  92
  93 Then call ``pw_package.package_manager.register(PackageClass)`` to register
  94 the class with the package manager.
  95
  96 Setting up a Project
  97 ~~~~~~~~~~~~~~~~~~~~
  98 To set up the package manager for a new project create a file like below and
  99 add it to the ``PW_PLUGINS`` file (see :ref:`module-pw_cli` for details). This
 100 file is based off of ``pw_package/pigweed_packages.py``.
 101
 102 .. code-block:: python
 103
 104   from pw_package import package_manager
 105   # These modules register themselves so must be imported despite appearing
 106   # unused.
 107   from pw_package.packages import nanopb
 108
 109   def main(argv=None) -> int:
 110       return package_manager.run(**vars(package_manager.parse_args(argv)))