Skip to content

Commit

Permalink
Add pants_plugin and contrib_plugin targets.
Browse files Browse the repository at this point in the history
These targets support easy adoption of pants own plugin entry_points to
allow for one less step when installing pants plugins.

The existing plugins are converted to use these targets and the contrib
README is updated to reflect the new best-practice boilerplate.

Testing Done:
Tested that the re-vamped plugin install tests that use the new
entry_points worked via: `./build-support/bin/release.sh -n`

CI went green here:
  https://travis-ci.org/pantsbuild/pants/builds/75535801

Bugs closed: 1967, 1968

Reviewed at https://rbcommons.com/s/twitter/r/2615/
  • Loading branch information
jsirois committed Aug 14, 2015
1 parent 3c22a3c commit 67eaef6
Show file tree
Hide file tree
Showing 12 changed files with 177 additions and 83 deletions.
11 changes: 3 additions & 8 deletions build-support/bin/release.sh
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,9 @@ PKG_PANTS_BACKEND_ANDROID=(
function pkg_pants_backend_android_install_test() {
PIP_ARGS="$@"
pip install ${PIP_ARGS} pantsbuild.pants.backend.android==$(local_version) && \
python -c "from pants.backend.android import *"
execute_packaged_pants_with_internal_backends \
--plugins="['pantsbuild.pants.backend.android']" \
goals | grep "apk" &> /dev/null
}

# Once an individual (new) package is declared above, insert it into the array below)
Expand All @@ -83,12 +85,6 @@ function run_local_pants() {
# and it'll fail. To solve that problem, we load the internal backend package
# dependencies into the pantsbuild.pants venv.
function execute_packaged_pants_with_internal_backends() {
local extra_backend_packages
if [[ "$1" =~ "extra_backend_packages=" ]]; then
extra_backend_packages=${1#*=}
shift
fi

local extra_bootstrap_buildfiles
if [[ "$1" =~ "extra_bootstrap_buildfiles" ]]; then
extra_bootstrap_buildfiles=${1#*=}
Expand All @@ -104,7 +100,6 @@ function execute_packaged_pants_with_internal_backends() {
'internal_backend.repositories', \
'internal_backend.sitegen', \
'internal_backend.utilities', \
${extra_backend_packages}
]" \
--goals-bootstrap-buildfiles="[ \
'${ROOT}/BUILD', \
Expand Down
2 changes: 1 addition & 1 deletion build-support/virtualenv
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#!/usr/bin/env bash
# Wrapper for self-bootstrapping virtualenv
set -e
VIRTUALENV_VERSION=12.1.1
VIRTUALENV_VERSION=13.1.0
VIRTUALENV_PACKAGE_LOCATION=${VIRTUALENV_PACKAGE_LOCATION:-https://pypi.python.org/packages/source/v/virtualenv}

REPO_ROOT=$(cd $(dirname "${BASH_SOURCE[0]}") && cd "$(git rev-parse --show-toplevel)" && pwd)
Expand Down
38 changes: 24 additions & 14 deletions contrib/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,9 @@ Contrib plugins should generally follow 3 basic setup steps:
src/python/pants/contrib/example/...
tests/python/pants_test/contrib/example/...
```
The only hard requirement though is the `register.py` entry point file in the main src dir -
in this example: `contrib/example/src/python/pants/contrib/example/register.py`.

Source roots for this layout would be added to contrib/example/BUILD:
```
source_root('src/python', page, python_library, resources)
Expand Down Expand Up @@ -67,32 +70,39 @@ Contrib plugins should generally follow 3 basic setup steps:
]
```

3. When you're ready for your plugin to be distributed, add a `provides` `contrib_setup_py`
descriptor to your main plugin BUILD target and register the plugin with the release script.
The `provides` descriptor just requires a name and description for your plugin suitable for
[pypi](https://pypi.python.org/pypi):
3. When you're ready for your plugin to be distributed, convert your main `python_library` plugin
target to a `contrib_plugin` target and register the plugin with the release script.

The `contrib_plugin` target assumes 1 source of `register.py`; so, the sources argument should be
removed. It still accepts dependencies and other python target arguments with some special
additions to help define the plugin distribution. You'll need to supply a `distribution_name`
and a `description` of the plugin suitable for [pypi](https://pypi.python.org/pypi) as well as
parameters indicating which plugin entry points your plugin implements:
```python
python_library(
name='plugin',
sources=['register.py'],
provides=contrib_setup_py(
name='pantsbuild.pants.contrib.example',
description='An example pants contrib plugin.'
)
contrib_plugin(
name='plugin',
distribution_name='pantsbuild.pants.contrib.example',
description='An example pants contrib plugin.'
build_file_aliases=True,
register_goals=True,
)
```
In this example, the plugin implements the `build_file_aliases` and `register_goals` entry point
methods, but a plugin may additionally implement the `global_subsystems` entry point method, in
which case it's `contrib_plugin` target would have a `global_subsystems=True,` entry as well.

To register with the release script, add an entry to `contrib/release_packages.sh`:
```bash
PKG_EXAMPLE=(
"pantsbuild.pants.example"
"pantsbuild.pants.contrib.example"
"//contrib/example/src/python/pants/contrib/example:plugin"
"pkg_example_install_test"
)
function pkg_example_install_test() {
PIP_ARGS="$@"
pip install ${PIP_ARGS} pantsbuild.pants.example==$(local_version) && \
pip install ${PIP_ARGS} pantsbuild.pants.contrib.example==$(local_version) && \
execute_packaged_pants_with_internal_backends \
"extra_backend_packages='pants.contrib.example'" \
--plugins="['pantsbuild.pants.contrib.example']" \
goals | grep "example-goal" &> /dev/null
}

Expand Down
11 changes: 5 additions & 6 deletions contrib/cpp/src/python/pants/contrib/cpp/BUILD
Original file line number Diff line number Diff line change
@@ -1,18 +1,17 @@
# Copyright 2015 Pants project contributors (see CONTRIBUTORS.md).
# Licensed under the Apache License, Version 2.0 (see LICENSE).

python_library(
contrib_plugin(
name='plugin',
sources=['register.py'],
dependencies=[
'contrib/cpp/src/python/pants/contrib/cpp/targets:targets',
'contrib/cpp/src/python/pants/contrib/cpp/tasks:tasks',
'contrib/cpp/src/python/pants/contrib/cpp/toolchain:toolchain',
'src/python/pants/base:build_file_aliases',
'src/python/pants/goal:task_registrar',
],
provides=contrib_setup_py(
name='pantsbuild.pants.contrib.cpp',
description='C++ pants plugin.',
),
distribution_name='pantsbuild.pants.contrib.cpp',
description='C++ pants plugin.',
build_file_aliases=True,
register_goals=True,
)
11 changes: 5 additions & 6 deletions contrib/go/src/python/pants/contrib/go/BUILD
Original file line number Diff line number Diff line change
@@ -1,17 +1,16 @@
# Copyright 2015 Pants project contributors (see CONTRIBUTORS.md).
# Licensed under the Apache License, Version 2.0 (see LICENSE).

python_library(
contrib_plugin(
name='plugin',
sources=['register.py'],
dependencies=[
'contrib/go/src/python/pants/contrib/go/targets',
'contrib/go/src/python/pants/contrib/go/tasks',
'src/python/pants/base:build_file_aliases',
'src/python/pants/goal:task_registrar',
],
provides=contrib_setup_py(
name='pantsbuild.pants.contrib.go',
description='Go language support for pants.',
)
distribution_name='pantsbuild.pants.contrib.go',
description='Go language support for pants.',
build_file_aliases=True,
register_goals=True,
)
11 changes: 7 additions & 4 deletions contrib/release_packages.sh
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,11 @@ PKG_SCROOGE=(
function pkg_scrooge_install_test() {
PIP_ARGS="$@"
pip install ${PIP_ARGS} pantsbuild.pants.contrib.scrooge==$(local_version) && \
execute_packaged_pants_with_internal_backends "extra_backend_packages='pants.contrib.scrooge'" \
execute_packaged_pants_with_internal_backends \
--plugins="['pantsbuild.pants.contrib.scrooge']" \
--explain gen | grep "scrooge" &> /dev/null && \
execute_packaged_pants_with_internal_backends "extra_backend_packages='pants.contrib.scrooge'" \
execute_packaged_pants_with_internal_backends \
--plugins="['pantsbuild.pants.contrib.scrooge']" \
goals | grep "thrift-linter" &> /dev/null
}

Expand All @@ -47,7 +49,8 @@ PKG_SPINDLE=(
function pkg_spindle_install_test() {
PIP_ARGS="$@"
pip install ${PIP_ARGS} pantsbuild.pants.contrib.spindle==$(local_version) && \
execute_packaged_pants_with_internal_backends "extra_backend_packages='pants.contrib.spindle'" \
execute_packaged_pants_with_internal_backends \
--plugins="['pantsbuild.pants.contrib.spindle']" \
--explain gen | grep "spindle" &> /dev/null
}

Expand All @@ -60,8 +63,8 @@ function pkg_go_install_test() {
PIP_ARGS="$@"
pip install ${PIP_ARGS} pantsbuild.pants.contrib.go==$(local_version) && \
execute_packaged_pants_with_internal_backends \
"extra_backend_packages='pants.contrib.go'" \
"extra_bootstrap_buildfiles='${ROOT}/contrib/go/BUILD'" \
--plugins="['pantsbuild.pants.contrib.go']" \
compile.go contrib/go/examples::
}

Expand Down
16 changes: 7 additions & 9 deletions contrib/scrooge/src/python/pants/contrib/scrooge/BUILD
Original file line number Diff line number Diff line change
@@ -1,18 +1,16 @@
# Copyright 2015 Pants project contributors (see CONTRIBUTORS.md).
# Licensed under the Apache License, Version 2.0 (see LICENSE).

python_library(
contrib_plugin(
name='plugin',
sources=['register.py'],
dependencies=[
'contrib/scrooge/src/python/pants/contrib/scrooge/tasks',
'src/python/pants/goal:task_registrar',
],
provides=contrib_setup_py(
name='pantsbuild.pants.contrib.scrooge',
description='Scrooge thrift generator pants plugins.',
additional_classifiers=[
'Topic :: Software Development :: Code Generators'
]
)
distribution_name='pantsbuild.pants.contrib.scrooge',
description='Scrooge thrift generator pants plugins.',
additional_classifiers=[
'Topic :: Software Development :: Code Generators'
],
register_goals=True,
)
17 changes: 8 additions & 9 deletions contrib/spindle/src/python/pants/contrib/spindle/BUILD
Original file line number Diff line number Diff line change
@@ -1,20 +1,19 @@
# Copyright 2015 Pants project contributors (see CONTRIBUTORS.md).
# Licensed under the Apache License, Version 2.0 (see LICENSE).

python_library(
contrib_plugin(
name='plugin',
sources=['register.py'],
dependencies=[
'contrib/spindle/src/python/pants/contrib/spindle/targets',
'contrib/spindle/src/python/pants/contrib/spindle/tasks',
'src/python/pants/base:build_file_aliases',
'src/python/pants/goal:task_registrar',
],
provides=contrib_setup_py(
name='pantsbuild.pants.contrib.spindle',
description='Spindle thrift -> scala generator pants plugins.',
additional_classifiers=[
'Topic :: Software Development :: Code Generators'
]
)
distribution_name='pantsbuild.pants.contrib.spindle',
description='Spindle thrift -> scala generator pants plugins.',
additional_classifiers=[
'Topic :: Software Development :: Code Generators'
],
build_file_aliases=True,
register_goals=True,
)
2 changes: 2 additions & 0 deletions pants-plugins/src/python/internal_backend/utilities/BUILD
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,11 @@ python_library(
sources=['register.py'],
dependencies=[
'3rdparty/python/twitter/commons:twitter.common.collections',
'src/python/pants/backend/python/targets:python',
'src/python/pants/backend/python:python_artifact',
'src/python/pants/base:build_environment',
'src/python/pants/base:build_file_aliases',
'src/python/pants/base:exceptions',
]
)

Loading

0 comments on commit 67eaef6

Please sign in to comment.