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

Add hello world plugin to documentation #6587

Merged
merged 4 commits into from Oct 4, 2018
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
77 changes: 77 additions & 0 deletions src/docs/howto_plugin.md
Expand Up @@ -18,6 +18,83 @@ Pants' `jvm` code registers in
Pants' backend-loader code assumes your plugin has a `register.py` file
there.

Hello world plugin with its own goal
--------------------

The hello world plugin shows how to register your plugin to Pants and define its own `hello-world` goal which contains 2 tasks and
which can be executed by Pants. To achieve that, take a look at the following steps:
- Create a new Pants project so you have pants.ini file in root of your repository

- Create a home directory for your plugins. In this example we will use `plugins/` directory in root of repository,
but the word "plugins" is not special for Pants.

- In the `plugins/` directory, create following filesystem structure:

hello/
__init__.py
register.py
tasks/
__init__.py
your_tasks.py


- `__init__.py` files can be empty - you're just saying to Python that you created modules.

- In `your_tasks.py` place the following content:

from pants.task.task import Task

class HelloTask(Task):
def execute(self):
print("Hello")

class WorldTask(Task):
def execute(self):
print("world!")
[Task](https://github.com/pantsbuild/pants/blob/master/src/python/pants/task/task.py) is a simple base
class for your tasks - you need to implement an `execute` method which will be executed by Pants.

- In `register.py` place the following content:

from pants.goal.goal import Goal
from pants.goal.task_registrar import TaskRegistrar as task
from hello.tasks.your_tasks import HelloTask, WorldTask

def register_goals():
Goal.register(name="hello-world", description="Say hello to your world")
task(name='hello', action=HelloTask).install('hello-world')
task(name='world', action=WorldTask).install('hello-world')

Here you register new Pants goal named `hello-world` and documented with a description,
and then attach 2 tasks to the goal created in previous step.

- In `pants.ini` place the following content:

[GLOBAL]
pants_version: 1.9.0
pythonpath: ["%(buildroot)s/plugins"]
backend_packages: ["hello"]

You need to put your plugins on the `pythonpath` so Pants will know where to find them.
`backend_packages` defines which plugins you want to use in your project.

- You are ready to use your plugin with the `hello-world` goal! First try to find your goal by typing `./pants goals`:

...
hello-world: Say hello to your world
...
- Now you can use your plugin by typing `./pants hello-world`:

...
Executing tasks in goals: hello-world
XX:XX:XX 00:00 [hello-world]
XX:XX:XX 00:00 [hello]Hello

XX:XX:XX 00:00 [world]world!

XX:XX:XX 00:00 [complete]
SUCCESS

Simple Configuration
--------------------

Expand Down