Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.md plugins section #286

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -413,8 +413,7 @@ Details on the merge command can be found in the docs page [here](./docs/basic_u

## Plugins

Surfactant supports using plugins to add additional features. For users, installing and enabling a plugin usually just involves
doing a `pipx inject surfactant` when using pipx or `pip install` of the plugin if manually managing virtual environments.
Surfactant supports using plugins to add additional features. Users can install plugins with `surfactant plugin install` and disable or enable them with `surfactant plugin disable` and `surfactant plugin enable` respectively. `surfactant plugin install` detects the active virtual environment and runs the appropriate command i.e. `pipx` or `pip`. Alternatively, users can manually manage their environments with `pipx inject surfactant` when using pipx or `pip install`.

Detailed information on configuration options for the plugin system and how to develop new plugins can be found [here](./docs/plugins.md).

Expand Down
5 changes: 3 additions & 2 deletions docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ In order to create a plugin, you will need to write your implementation for one

### Step 2. Write pyproject.toml File

Once you have written your plugin, you will need to write a pyproject.toml file. Include any relevant project metadata/dependencies for your plugin, as well as an entry-point specification (example below) to make the plugin discoverable by surfactant. Once you write your .toml file, you can `pip install .` your plugin.
Once you have written your plugin, you will need to write a pyproject.toml file. Include any relevant project metadata/dependencies for your plugin, as well as an entry-point specification (example below) to make the plugin discoverable by surfactant. Once you write your .toml file, you can `surfactant plugin install <plugin name>` to install your plugin. Alternatively, you can `pip install .` your plugin.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should say . or <path to plugin's folder> instead -- at this stage, they probably haven't uploaded their package to PyPI yet.


More information on entry points can be found [here](https://setuptools.pypa.io/en/latest/userguide/entry_point.html#entry-points-syntax)

#### Example
Expand All @@ -46,6 +47,6 @@ def write_sbom(sbom: SBOM, outfile) -> None:
[project.entry-points."surfactant"]
sampleplugin = "sampleplugin"
```
From the same folder as your sampleplugin files, run `pip install .` to install your plugin and surfactant will automatically load and use the plugin.
Run `surfactant plugin install sampleplugin` to install the plugin. Surfactant will automatically load and use the plugin. Alternatively, from the same folder as your sampleplugin files, run `pip install .`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since surfactant plugin install is calling pip, this should probably just say to run surfactant plugin install . (or the path to the folder on their local filesystem that the plugin is located in) so that pip doesn't try to find a package on PyPI that either doesn't exist yet (or a completely different package someone else created that happens to have the same name).

We could mention uploading their plugin to PyPI for easier sharing and to enable installation using the PyPI package name for the plugin.


Another example can be found in the [plugins/checksec.py](https://github.com/LLNL/Surfactant/tree/main/plugins/checksec.py) folder. There you can see the [pyproject.toml](https://github.com/LLNL/Surfactant/tree/main/plugins/checksec.py/pyproject.toml) file with the `[project.entry-points."surfactant"]` entry. In the [surfactantplugin_checksec.py](https://github.com/LLNL/Surfactant/tree/main/plugins/checksec.py/surfactantplugin_checksec.py) file, you can identify the hooked functions with the `@surfactant.plugin.hookimpl` hook.
Loading