From 5d280b36a6e7822fca32abf093e95e5a76603bc4 Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Fri, 29 Mar 2024 17:07:11 -0500 Subject: [PATCH 01/18] Add plugin documentation page Signed-off-by: Bryce Gattis --- docs/source/index.rst | 1 + docs/source/plugins.rst | 66 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 docs/source/plugins.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 676021b0f..405d33718 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -31,6 +31,7 @@ Welcome to rez's documentation! managing_packages caching pip + plugins .. toctree:: :maxdepth: 2 diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst new file mode 100644 index 000000000..dc1b12f7e --- /dev/null +++ b/docs/source/plugins.rst @@ -0,0 +1,66 @@ +======= +Plugins +======= + +Plugins are extensions of rez that extend rez functionality. + +Plugins are currently bundled in the main rez repo, but will be split out +to their own repos in the future. + +The plugins that exist are currently located at :gh-rez:`src/rezplugins`. + +Existing plugins +================ + +- :gh-rez:`src/rezplugins/build_process` +- :gh-rez:`src/rezplugins/build_system` +- :gh-rez:`src/rezplugins/command` +- :gh-rez:`src/rezplugins/build_process/package_repository` +- :gh-rez:`src/rezplugins/build_process/release_hook` +- :gh-rez:`src/rezplugins/build_process/release_vcs` +- :gh-rez:`src/rezplugins/build_process/shell` + +Developing your own plugin +========================== + +Rez plugins require a specific folder structure as follows: + +.. code-block:: text + + /plugin_name + /__init__.py (adds plugin path to rez) + /rezconfig.py (defines configuration settings for your plugin) + /plugin_file1.py (your plugin file) + /plugin_file2.py (your plugin file) + etc. + +To make your plugin available to rez, you can install them directly under +``src/rezplugins`` (that's called a namespace package) or you can add +the path to :envvar:`REZ_PLUGIN_PATH`. + +Plugin types +------------ + +There are two different plugin types in Rez. + +- Plugin +- Extension + +Extensions differ from standard plugins in that they add a new command to rez's +CLI. + +Required file contents +---------------------- +``__init__.py`` + +.. code-block:: python + + from rez.plugin_managers import extend_path + __path__ = extend_path(__path__, __name__) + +``your_plugin_file.py`` + +.. code-block:: python + + def register_plugin(): + return YourPluginClass \ No newline at end of file From 32b773fd24682d075254d6c8865da236d0bdb3cd Mon Sep 17 00:00:00 2001 From: BryceGattis <36783788+BryceGattis@users.noreply.github.com> Date: Fri, 29 Mar 2024 17:39:49 -0500 Subject: [PATCH 02/18] Update docs/source/plugins.rst Co-authored-by: Jean-Christophe Morin <38703886+JeanChristopheMorinPerso@users.noreply.github.com> Signed-off-by: BryceGattis <36783788+BryceGattis@users.noreply.github.com> --- docs/source/plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index dc1b12f7e..7e3f6d32d 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -7,7 +7,7 @@ Plugins are extensions of rez that extend rez functionality. Plugins are currently bundled in the main rez repo, but will be split out to their own repos in the future. -The plugins that exist are currently located at :gh-rez:`src/rezplugins`. +The built-in plugins are located at :gh-rez:`src/rezplugins`. Existing plugins ================ From 0c474ed51e2b2172524b7525c148b5a6e0a1e83f Mon Sep 17 00:00:00 2001 From: BryceGattis <36783788+BryceGattis@users.noreply.github.com> Date: Fri, 29 Mar 2024 17:40:06 -0500 Subject: [PATCH 03/18] Update docs/source/plugins.rst Co-authored-by: Jean-Christophe Morin <38703886+JeanChristopheMorinPerso@users.noreply.github.com> Signed-off-by: BryceGattis <36783788+BryceGattis@users.noreply.github.com> --- docs/source/plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 7e3f6d32d..7c4e0e53c 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -2,7 +2,7 @@ Plugins ======= -Plugins are extensions of rez that extend rez functionality. +Rez is designed around the concept of plugins. Plugins can be used to extend rez's functionalities without modifying any of rez's source code. Plugins are currently bundled in the main rez repo, but will be split out to their own repos in the future. From 234389ff1a5398df04c9dc2dbca884255e1a3231 Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Sat, 6 Apr 2024 17:02:53 -0500 Subject: [PATCH 04/18] Add captions Signed-off-by: Bryce Gattis --- docs/source/plugins.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 7c4e0e53c..d3f99217c 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -51,16 +51,16 @@ CLI. Required file contents ---------------------- -``__init__.py`` - .. code-block:: python + :caption: __init__.py from rez.plugin_managers import extend_path __path__ = extend_path(__path__, __name__) -``your_plugin_file.py`` + .. code-block:: python + :caption: your_plugin_file.py def register_plugin(): return YourPluginClass \ No newline at end of file From b6c80608c21aee320e5462a6d2c595992e7f054f Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Sat, 6 Apr 2024 17:04:54 -0500 Subject: [PATCH 05/18] Change plugin to plugin type Signed-off-by: Bryce Gattis --- docs/source/plugins.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index d3f99217c..451567fbf 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -9,8 +9,8 @@ to their own repos in the future. The built-in plugins are located at :gh-rez:`src/rezplugins`. -Existing plugins -================ +Existing plugin types +===================== - :gh-rez:`src/rezplugins/build_process` - :gh-rez:`src/rezplugins/build_system` @@ -27,7 +27,7 @@ Rez plugins require a specific folder structure as follows: .. code-block:: text - /plugin_name + /plugin_type /__init__.py (adds plugin path to rez) /rezconfig.py (defines configuration settings for your plugin) /plugin_file1.py (your plugin file) From 095bdb3d928a7ea2456db4eaa42510a088c91267 Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Sat, 6 Apr 2024 17:18:48 -0500 Subject: [PATCH 06/18] Start fixing up extensions section, and add section about how to query loaded plugins Signed-off-by: Bryce Gattis --- docs/source/plugins.rst | 42 ++++++++++++++++++++++++++++++++++------- 1 file changed, 35 insertions(+), 7 deletions(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 451567fbf..5b210f4ea 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -9,6 +9,38 @@ to their own repos in the future. The built-in plugins are located at :gh-rez:`src/rezplugins`. +Loaded plugins +============== + +Currently loaded plugins can be queried by running ``rez -i`` + +.. code-block:: console + + $ rez -i + + Rez 2.113.0 + + PLUGIN TYPE NAME DESCRIPTION STATUS + ----------- ---- ----------- ------ + build process local Builds packages on local host loaded + build process remote Builds packages on remote hosts loaded + build system cmake CMake-based build system loaded + build system custom Package-defined build command loaded + build system make Make-based build system loaded + package repository filesystem Filesystem-based package repository loaded + package repository memory In-memory package repository loaded + release hook amqp Publishes a message to the broker. loaded + release hook command Executes pre- and post-release shell commands loaded + release hook emailer Sends a post-release email loaded + release vcs git Git version control loaded + release vcs hg Mercurial version control loaded + release vcs stub Stub version control system, for testing purposes loaded + release vcs svn FAILED: No module named 'pysvn' + shell cmd Windows Command Prompt (DOS) shell. loaded + shell gitbash Git Bash (for Windows) shell loaded + shell powershell Windows PowerShell 5 loaded + shell pwsh PowerShell Core 6+ loaded + Existing plugin types ===================== @@ -38,16 +70,12 @@ To make your plugin available to rez, you can install them directly under ``src/rezplugins`` (that's called a namespace package) or you can add the path to :envvar:`REZ_PLUGIN_PATH`. -Plugin types +Extending rez ------------ -There are two different plugin types in Rez. - -- Plugin -- Extension +Optionally, plugins can provide new ``rez`` commands. -Extensions differ from standard plugins in that they add a new command to rez's -CLI. +# TODO: How do you provide new rez commands. Required file contents ---------------------- From 95f6fce0152b6423bdad1d7ceff94004b55205f1 Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Sat, 6 Apr 2024 17:47:10 -0500 Subject: [PATCH 07/18] Fix GitHub links, add new registering subcommands section. Signed-off-by: Bryce Gattis --- docs/source/plugins.rst | 62 ++++++++++++++++++++++++++++++----------- 1 file changed, 46 insertions(+), 16 deletions(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 5b210f4ea..2f5202be0 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -47,10 +47,10 @@ Existing plugin types - :gh-rez:`src/rezplugins/build_process` - :gh-rez:`src/rezplugins/build_system` - :gh-rez:`src/rezplugins/command` -- :gh-rez:`src/rezplugins/build_process/package_repository` -- :gh-rez:`src/rezplugins/build_process/release_hook` -- :gh-rez:`src/rezplugins/build_process/release_vcs` -- :gh-rez:`src/rezplugins/build_process/shell` +- :gh-rez:`src/rezplugins/package_repository` +- :gh-rez:`src/rezplugins/release_hook` +- :gh-rez:`src/rezplugins/release_vcs` +- :gh-rez:`src/rezplugins/shell` Developing your own plugin ========================== @@ -70,25 +70,55 @@ To make your plugin available to rez, you can install them directly under ``src/rezplugins`` (that's called a namespace package) or you can add the path to :envvar:`REZ_PLUGIN_PATH`. -Extending rez ------------- +Registering subcommands +----------------------- -Optionally, plugins can provide new ``rez`` commands. +Optionally, plugins can provide new ``rez`` subcommands. -# TODO: How do you provide new rez commands. +To register a plugin and expose a new subcommand, the plugin module: + +- MUST have a module-level docstring (used as the command help) +- MUST provide a `setup_parser()` function +- MUST provide a `command()` function +- MUST provide a `register_plugin()` function +- SHOULD have a module-level attribute `command_behavior` + +For example, a plugin named 'foo' and this is the ``foo.py``: -Required file contents ----------------------- .. code-block:: python - :caption: __init__.py + :caption: your_plugin_file.py - from rez.plugin_managers import extend_path - __path__ = extend_path(__path__, __name__) + '''The docstring for command help, this is required. + ''' + from rez.command import Command + + command_behavior = { + "hidden": False, # optional: bool + "arg_mode": None, # optional: None, "passthrough", "grouped" + } + + def setup_parser(parser, completions=False): + parser.add_argument("--hello", ...) + def command(opts, parser=None, extra_arg_groups=None): + if opts.hello: + print("world") + class CommandFoo(Command): + schema_dict = {} + @classmethod + def name(cls): + return "foo" + def register_plugin(): + return CommandFoo + +Other required file contents +---------------------------- .. code-block:: python - :caption: your_plugin_file.py + :caption: __init__.py + + from rez.plugin_managers import extend_path + __path__ = extend_path(__path__, __name__) + - def register_plugin(): - return YourPluginClass \ No newline at end of file From 5877eb08985077a07278a2a57837891171f1d96d Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Sat, 6 Apr 2024 17:47:47 -0500 Subject: [PATCH 08/18] Change caption on file for clarity Signed-off-by: Bryce Gattis --- docs/source/plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 2f5202be0..632ff5a44 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -86,7 +86,7 @@ To register a plugin and expose a new subcommand, the plugin module: For example, a plugin named 'foo' and this is the ``foo.py``: .. code-block:: python - :caption: your_plugin_file.py + :caption: foo.py '''The docstring for command help, this is required. ''' From ae8d55d7c6797e1344a54c82a5e1fde352916c12 Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Sat, 6 Apr 2024 18:13:27 -0500 Subject: [PATCH 09/18] Add TODO for configuring plugins section Signed-off-by: Bryce Gattis --- docs/source/plugins.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 632ff5a44..424051541 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -41,6 +41,12 @@ Currently loaded plugins can be queried by running ``rez -i`` shell powershell Windows PowerShell 5 loaded shell pwsh PowerShell Core 6+ loaded + +Configuring plugins +=================== + +# TODO: Write this part. + Existing plugin types ===================== From 52b86b9857042920d0bb1122bda22d6036b78069 Mon Sep 17 00:00:00 2001 From: BryceGattis <36783788+BryceGattis@users.noreply.github.com> Date: Tue, 9 Apr 2024 08:03:00 -0500 Subject: [PATCH 10/18] Update docs/source/plugins.rst Co-authored-by: Jean-Christophe Morin <38703886+JeanChristopheMorinPerso@users.noreply.github.com> Signed-off-by: BryceGattis <36783788+BryceGattis@users.noreply.github.com> --- docs/source/plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 424051541..2e626bd9c 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -12,7 +12,7 @@ The built-in plugins are located at :gh-rez:`src/rezplugins`. Loaded plugins ============== -Currently loaded plugins can be queried by running ``rez -i`` +Currently loaded plugins can be queried by running :option:`rez -i` .. code-block:: console From 14739ab35ccc00ebbbe463d878816616580e1057 Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Tue, 9 Apr 2024 08:04:28 -0500 Subject: [PATCH 11/18] Wording change Signed-off-by: Bryce Gattis --- docs/source/plugins.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 2e626bd9c..25be631b1 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -9,10 +9,10 @@ to their own repos in the future. The built-in plugins are located at :gh-rez:`src/rezplugins`. -Loaded plugins +List installed plugins ============== -Currently loaded plugins can be queried by running :option:`rez -i` +Currently installed plugins can be queried by running :option:`rez -i` .. code-block:: console From b7041a6c7c72316019f360262039b4cd85b8803f Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Tue, 9 Apr 2024 08:04:52 -0500 Subject: [PATCH 12/18] Fix header Signed-off-by: Bryce Gattis --- docs/source/plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 25be631b1..1f2ca1bc7 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -10,7 +10,7 @@ to their own repos in the future. The built-in plugins are located at :gh-rez:`src/rezplugins`. List installed plugins -============== +====================== Currently installed plugins can be queried by running :option:`rez -i` From de2a051f033bacb1b188331af01e16a657cc090c Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Tue, 9 Apr 2024 08:11:01 -0500 Subject: [PATCH 13/18] Add configuring plugins section Signed-off-by: Bryce Gattis --- docs/source/plugins.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 1f2ca1bc7..ad12a9477 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -45,7 +45,14 @@ Currently installed plugins can be queried by running :option:`rez -i` Configuring plugins =================== -# TODO: Write this part. +Plugins can be configured by adding a ``plugins`` key to your ``rezconfig.py`` +like this: + +.. code-block:: python + + plugins = { + "filesystem": {} + } Existing plugin types ===================== From b5b61f97fbfe59481f3a11bf9a93af7fdbb36bdf Mon Sep 17 00:00:00 2001 From: BryceGattis <36783788+BryceGattis@users.noreply.github.com> Date: Tue, 9 Apr 2024 21:44:25 -0500 Subject: [PATCH 14/18] Update docs/source/plugins.rst Co-authored-by: Jean-Christophe Morin <38703886+JeanChristopheMorinPerso@users.noreply.github.com> Signed-off-by: BryceGattis <36783788+BryceGattis@users.noreply.github.com> --- docs/source/plugins.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index ad12a9477..020670a70 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -57,13 +57,13 @@ like this: Existing plugin types ===================== -- :gh-rez:`src/rezplugins/build_process` -- :gh-rez:`src/rezplugins/build_system` -- :gh-rez:`src/rezplugins/command` -- :gh-rez:`src/rezplugins/package_repository` -- :gh-rez:`src/rezplugins/release_hook` -- :gh-rez:`src/rezplugins/release_vcs` -- :gh-rez:`src/rezplugins/shell` +- :gh-rez:`build_process ` +- :gh-rez:`build_system ` +- :gh-rez:`command ` +- :gh-rez:`package_repository ` +- :gh-rez:`release_hook ` +- :gh-rez:`release_vcs ` +- :gh-rez:`shell ` Developing your own plugin ========================== From 6bfabb3678caffbbd1c02ef6d619be198e889e68 Mon Sep 17 00:00:00 2001 From: BryceGattis <36783788+BryceGattis@users.noreply.github.com> Date: Tue, 9 Apr 2024 21:46:46 -0500 Subject: [PATCH 15/18] Update docs/source/plugins.rst Co-authored-by: Jean-Christophe Morin <38703886+JeanChristopheMorinPerso@users.noreply.github.com> Signed-off-by: BryceGattis <36783788+BryceGattis@users.noreply.github.com> --- docs/source/plugins.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 020670a70..c0d769314 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -101,8 +101,7 @@ For example, a plugin named 'foo' and this is the ``foo.py``: .. code-block:: python :caption: foo.py - '''The docstring for command help, this is required. - ''' + """The docstring for command help, this is required.""" from rez.command import Command command_behavior = { From 2d3b60ccd95bb574afff882482de84c1493078ed Mon Sep 17 00:00:00 2001 From: BryceGattis <36783788+BryceGattis@users.noreply.github.com> Date: Tue, 9 Apr 2024 21:48:40 -0500 Subject: [PATCH 16/18] Update docs/source/plugins.rst Co-authored-by: Jean-Christophe Morin <38703886+JeanChristopheMorinPerso@users.noreply.github.com> Signed-off-by: BryceGattis <36783788+BryceGattis@users.noreply.github.com> --- docs/source/plugins.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index c0d769314..0b9e4b89c 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -4,10 +4,7 @@ Plugins Rez is designed around the concept of plugins. Plugins can be used to extend rez's functionalities without modifying any of rez's source code. -Plugins are currently bundled in the main rez repo, but will be split out -to their own repos in the future. - -The built-in plugins are located at :gh-rez:`src/rezplugins`. +Rez comes with built-in plugins that are located at :gh-rez:`src/rezplugins`. New plugins are encouraged to be developed out-of-tree (outside rez). List installed plugins ====================== From 6454f2288b0f034e50020d1f5d4f836ae682835b Mon Sep 17 00:00:00 2001 From: BryceGattis <36783788+BryceGattis@users.noreply.github.com> Date: Tue, 9 Apr 2024 21:51:56 -0500 Subject: [PATCH 17/18] Update docs/source/plugins.rst Co-authored-by: Jean-Christophe Morin <38703886+JeanChristopheMorinPerso@users.noreply.github.com> Signed-off-by: BryceGattis <36783788+BryceGattis@users.noreply.github.com> --- docs/source/plugins.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 0b9e4b89c..97175ddf4 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -122,8 +122,6 @@ For example, a plugin named 'foo' and this is the ``foo.py``: def register_plugin(): return CommandFoo -Other required file contents ----------------------------- .. code-block:: python :caption: __init__.py From a3d0de71efbbc995ec4c57ee117d75f13d417d8a Mon Sep 17 00:00:00 2001 From: Bryce Gattis Date: Tue, 9 Apr 2024 22:02:37 -0500 Subject: [PATCH 18/18] Specify where files go and add info on schema_dict Signed-off-by: Bryce Gattis --- docs/source/plugins.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 97175ddf4..da68cf226 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -93,7 +93,8 @@ To register a plugin and expose a new subcommand, the plugin module: - MUST provide a `register_plugin()` function - SHOULD have a module-level attribute `command_behavior` -For example, a plugin named 'foo' and this is the ``foo.py``: +For example, a plugin named 'foo' and this is the ``foo.py`` in the plugin type +root directory: .. code-block:: python :caption: foo.py @@ -114,7 +115,12 @@ For example, a plugin named 'foo' and this is the ``foo.py``: print("world") class CommandFoo(Command): - schema_dict = {} + # This is where you declare the settings the plugin accepts. + schema_dict = { + "str_option": str, + "int_option": int, + ... + } @classmethod def name(cls): return "foo" @@ -122,6 +128,9 @@ For example, a plugin named 'foo' and this is the ``foo.py``: def register_plugin(): return CommandFoo +All new plugin types must define an ``__init__.py`` in their root directory +so that the plugin manager will find them. + .. code-block:: python :caption: __init__.py