This is part of the Porter project. If you are a new contributor, check out our New Contributor Guide. The Porter Contributing Guide also has lots of information about how to interact with the project.
You need to have porter installed first. Then run
make build install
. This will build and install the plugin into your porter
home directory.
We use mage instead of make. If you don't have mage installed already,
you can install it with go run mage.go EnsureMage
.
Mage targets are not case-sensitive, but in our docs we use camel case to make
it easier to read. You can run either mage Build
or mage build
for
example.
Run mage
without any arguments to see a list of the available targets.
Below are some commonly used targets:
Build
builds the plugin.Install
installs the plugin into ~/.porter/plugins.TestUnit
runs the unit tests.
Porter plugins can be debugged using delve so before attempting to debug install delve. Debugging in porter is initiated by setting the following environment varibles prior to starting porter:
PORTER_RUN_PLUGIN_IN_DEBUGGER
should be set to the name of the plugin to be debugged (e.g.secrets.azure.keyvault
to debug the azure secrets plugin)PORTER_DEBUGGER_PORT
should be set to the port number where the delve API will listen, if not set it defaults to2345
PORTER_PLUGIN_WORKING_DIRECTORY
should be the local path to the source code for the plugin being debugged. (e.g. for the Azure plugin this value would be<PATH>/porter-azure-plugins/cmd/azure
Porter will only attach the debugger to an existing binary in ~/.porter/plugins. It is therefore necessary to build and install the plugin before debugging, use make debug
to do this.
There are 2 different debugging scenarios:
- Run
make debug
- Set the environment variables as described above.
- Set the appropriate configuration in config.toml.
- Run porter with a command that invokes the plugin e.g.
porter install debugtest --tag getporter/plugins-tutorial:v0.1.0 --debug -c plugins-tutorial
- Connect the debugger to the delve API (by default this will be listening at 127.0.0.1:2345), e.g using delve
dlv connect 127.0.0.1:2345
- Run
make debug
- Set the environment variables as described above.
- Set the appropriate configuration in config.toml.
- Run porter under the debugger with a command that invokes the plugin e.g.
dlv exec <path-to-porter> -- install debugtest --tag getporter/plugins-tutorial:v0.1.0 --debug -c plugins-tutorial
. Note that for this to work porter should be compiled so that the debugger can launch the binary successfully, the simplest way to do this is to build with no options. - Using a seperate terminal session connect the debugger to the delve API (by default this will be listening at 127.0.0.1:2345), e.g using delve
dlv connect 127.0.0.1:2345
Visual Studio Code tasks, scripts and launch configurations are included in the .vscode
directory
-
Debug just the plugin.
- Edit the porter command by editing the arguments property in the
RunPorter
task in.vscode/tasks.json
- Set the active launch configuration to
Debug Plugin
- Press F5 to begin debugging.
- Edit the porter command by editing the arguments property in the
-
Debug both porter and the plugin simultaneously.
- Follow the steps outlined above. (VS Code can be used to debug porter rather than using dlv command line.)
- Instead of the final step set the active configuration to
Attach To Plugin
- Press F5 to begin debugging.