Be build-tool agnostic

This commit removes the need to specify the [build] section for the
gradle path when compiling from source.

Building Elasticsearch and core plugins from source defaults to
compiling using gradlew.

Since there are two modes of building plugins, one alongside a source
distribution and one against a release Elasticsearch version, and in
the latter compilation is usually done from within the plugin source,
we can't assume what's the build tool e.g. `./gradlew`.

Instead of guessing what build.task should become as build.command for
plugins, just display a warning instead.

Closes #412
Relates #457

docs/command_line_reference.rst

@@ -277,7 +277,7 @@ This activates Java flight recorder and the JIT compiler telemetry devices.
 ``revision``
 ~~~~~~~~~~~~
 
-If you actively develop Elasticsearch and want to benchmark a source build of Elasticsearch (which will Rally create for you), you can specify the git revision of Elasticsearch that you want to benchmark. But note that Rally does only support Gradle as build tool which effectively means that it will only support this for Elasticsearch 5.0 or better. The default value is ``current``.
+If you actively develop Elasticsearch and want to benchmark a source build of Elasticsearch (which Rally will create for you), you can specify the git revision of Elasticsearch that you want to benchmark. But note that Rally uses and expects the Gradle Wrapper in the Elasticsearch repository (``./gradlew``) which effectively means that it will only support this for Elasticsearch 5.0 or better. The default value is ``current``.
 
 You can specify the revision in different formats:
 

docs/configuration.rst

@@ -10,9 +10,7 @@ Simple Configuration
 
 By default, Rally will run a simpler configuration routine and autodetect as much settings as possible or choose defaults for you. If you need more control you can run Rally with ``esrally configure --advanced-config``.
 
-Rally can build Elasticsearch either from sources or use an `official binary distribution <https://www.elastic.co/downloads/elasticsearch>`_. If you have Rally build Elasticsearch from sources, it can only be used to benchmark Elasticsearch 5.0 and above. The reason is that with Elasticsearch 5.0 the build tool was switched from Maven to Gradle. As Rally only supports Gradle, it is limited to Elasticsearch 5.0 and above.
-
-If you want to build Elasticsearch from sources, Gradle needs to be installed prior to running the configuration routine.
+Rally can build Elasticsearch either from sources or use an `official binary distribution <https://www.elastic.co/downloads/elasticsearch>`_. If you have Rally build Elasticsearch from sources, it can only be used to benchmark Elasticsearch 5.0 and above. The reason is that with Elasticsearch 5.0 the build tool switched from Maven to Gradle. As Rally utilizes the Gradle Wrapper, it is limited to Elasticsearch 5.0 and above.
 
 Let's go through an example step by step: First run ``esrally``::
 
@@ -25,63 +23,45 @@ Let's go through an example step by step: First run ``esrally``::
     /_/ |_|\__,_/_/_/\__, /
                     /____/
 
-    Running simple configuration. You can run the advanced configuration with:
+    Running simple configuration. Run the advanced configuration with:
 
       esrally configure --advanced-config
 
     * Autodetecting available third-party software
       git    : [OK]
-      gradle : [OK]
       JDK    : [OK]
 
     * Setting up benchmark data directory in /Users/dm/.rally/benchmarks
+    Enter the JDK 10 root directory (Press Enter to skip):
 
-As you can see above, Rally autodetects if git, Gradle and a JDK are installed. If you don't have Gradle, that's no problem, you are just not able to build Elasticsearch from sources. Let's assume you don't have Gradle installed::
-
-    dm@io:~ $ esrally
-
-        ____        ____
-       / __ \____ _/ / /_  __
-      / /_/ / __ `/ / / / / /
-     / _, _/ /_/ / / / /_/ /
-    /_/ |_|\__,_/_/_/\__, /
-                    /____/
-
-    Running simple configuration. You can run the advanced configuration with:
-
-      esrally configure --advanced-config
-
-    * Autodetecting available third-party software
-      git    : [OK]
-      gradle : [MISSING]
-      JDK 8  : [OK]
+As you can see above, Rally autodetects if git and a JDK are installed. It also searches for a JDK 10; if you don't have it, that's no problem, you are just not able to build Elasticsearch from sources. Let's assume you press Enter and don't specify a path for JDK 10::
 
     ********************************************************************************
-    You don't have the required software to benchmark Elasticsearch source builds.
+    You don't have a valid JDK 10 installation and cannot benchmark source builds.
 
     You can still benchmark binary distributions with e.g.:
 
-      esrally --distribution-version=5.0.0
+      esrally --distribution-version=6.0.0
     ********************************************************************************
 
 As you can see, Rally tells you that you cannot build Elasticsearch from sources but you can still benchmark official binary distributions.
 
-It's also possible that Rally cannot automatically find your JDK 8 or JDK 10 home directory. In that case, it will ask you later in the configuration process. If you do not provide a JDK home directory, Rally cannot start Elasticsearch on this machine but you can still use it as a load generator to :doc:`benchmark remote clusters </recipes>`.
+It's also possible that Rally cannot automatically your JDK home directory. In that case, it will ask you later in the configuration process. If you do not provide a JDK home directory, Rally cannot start Elasticsearch on this machine but you can still use it as a load generator to :doc:`benchmark remote clusters </recipes>`.
 
-After running the initial detection, Rally will try to autodetect your Elasticsearch project directory (either in the current directory or in ``../elasticsearch``) or will choose a default directory::
+If you specify a valid path for JDK 10, Rally will try to autodetect your Elasticsearch project directory (either in the current directory or in ``../elasticsearch``) or will choose a default directory::
 
     * Setting up benchmark data directory in /Users/dm/.rally/benchmarks
     * Setting up benchmark source directory in /Users/dm/.rally/benchmarks/src/elasticsearch
 
-If Rally has not found Gradle in the first step, it will not ask you for a source directory and just go on.
+If a valid path for JDK 10 was not found (or entered), it will not ask you for a source directory and just go on.
 
 Now Rally is done::
 
     Configuration successfully written to /Users/dm/.rally/rally.ini. Happy benchmarking!
 
-    To benchmark Elasticsearch with the default benchmark, run:
+    To benchmark Elasticsearch 6.0.0 with the default benchmark, run:
 
-      esrally
+      esrally --distribution-version=6.0.0
 
     More info about Rally:
 
@@ -121,7 +101,7 @@ Configuration Options
 Rally will ask you a few more things in the advanced setup:
 
 * **Benchmark data directory**: Rally stores all benchmark related data in this directory which can take up to several tens of GB. If you want to use a dedicated partition, you can specify a different data directory here.
-* **Elasticsearch project directory**: This is the directory where the Elasticsearch sources are located. If you don't actively develop on Elasticsearch you can just leave the default but if you want to benchmark local changes you should point Rally to your project directory. Note that Rally will run builds with Gradle in this directory (it runs ``gradle clean`` and ``gradle :distribution:tar:assemble``).
+* **Elasticsearch project directory**: This is the directory where the Elasticsearch sources are located. If you don't actively develop on Elasticsearch you can just leave the default but if you want to benchmark local changes you should point Rally to your project directory. Note that Rally will run builds with the Gradle Wrapper in this directory (it runs ``./gradlew clean`` and ``./gradlew :distribution:tar:assemble``).
 * **JDK root directory**: Rally will only ask this if it could not autodetect the JDK home by itself. Just enter the root directory of the JDK you want to use. By default, Rally will choose Java 8 if available and fallback to Java 10.
 * **Metrics store type**: You can choose between ``in-memory`` which requires no additional setup or ``elasticsearch`` which requires that you start a dedicated Elasticsearch instance to store metrics but gives you much more flexibility to analyse results.
 * **Metrics store settings** (only for metrics store type ``elasticsearch``): Provide the connection details to the Elasticsearch metrics store. This should be an instance that you use just for Rally but it can be a rather small one. A single node cluster with default setting should do it. When using self-signed certificates on the Elasticsearch metrics store, certificate verification can be turned off by setting the ``datastore.ssl.verification_mode`` setting to ``none``. Alternatively you can enter the path to the certificate authority's signing certificate in ``datastore.ssl.certificate_authorities``. Both settings are optional.

docs/developing.rst

@@ -10,7 +10,6 @@ Please ensure that the following packages are installed before installing Rally
 * ``pip3`` available on the path (verify with ``pip3 --version``)
 * JDK 8 or 9
 * git 1.9 or better
-* Gradle 3.3 or better
 
 Please check the :doc:`installation guide </install>` for detailed installation instructions for these packages.
 
@@ -76,4 +75,4 @@ How to contribute code
 
 First of all, please read the `contributors guide <https://github.com/elastic/rally/blob/master/CONTRIBUTING.md>`_.
 
-We strive to be PEP-8 compliant but don't follow it to the letter.
+We strive to be PEP-8 compliant but don't follow it to the letter.

docs/elasticsearch_plugins.rst

@@ -96,16 +96,19 @@ To make this work, you need to manually edit Rally's configuration file in ``~/.
 
     plugin.my-plugin.remote.repo.url = [email protected]:example-org/my-plugin.git
     plugin.my-plugin.src.subdir = elasticsearch-extra/my-plugin
-    plugin.my-plugin.build.task = :my-plugin:plugin:assemble
+    plugin.my-plugin.build.command = ./gradlew :my-plugin:plugin:assemble
     plugin.my-plugin.build.artifact.subdir = plugin/build/distributions
 
 Let's discuss these properties one by one:
 
 * ``plugin.my-plugin.remote.repo.url`` (optional): This is needed to let Rally checkout the source code of the plugin. If this is a private repo, credentials need to be setup properly. If the source code is already locally available you may not need to define this property. The remote's name is assumed to be "origin" and this is not configurable. Also, only git is supported as revision control system.
 * ``plugin.my-plugin.src.subdir`` (mandatory): This is the directory to which the plugin will be checked out relative to ``src.root.dir``. In order to allow to build the plugin alongside Elasticsearch, the plugin needs to reside in a subdirectory of ``elasticsearch-extra`` (see also the `Elasticsearch testing documentation <https://github.com/elastic/elasticsearch/blob/master/TESTING.asciidoc#building-with-extra-plugins>`_.
-* ``plugin.my-plugin.build.task`` (mandatory): The Gradle task to run in order to build the plugin artifact. Note that this command is run from the Elasticsearch source directory as Rally assumes that you want to build your plugin alongside Elasticsearch (otherwise, see the next section).
+* ``plugin.my-plugin.build.command`` (mandatory): The full build command to run in order to build the plugin artifact. Note that this command is run from the Elasticsearch source directory as Rally assumes that you want to build your plugin alongside Elasticsearch (otherwise, see the next section).
 * ``plugin.my-plugin.build.artifact.subdir`` (mandatory): This is the subdirectory relative to ``plugin.my-plugin.src.subdir`` in which the final plugin artifact is located.
 
+.. warning::
+    ``plugin.my-plugin.build.command`` has replaced ``plugin.my-plugin.build.task`` in earlier Rally versions. It now requires the **full** build command.
+
 In order to run a benchmark with ``my-plugin``, you'd invoke Rally as follows: ``esrally --revision="elasticsearch:some-elasticsearch-revision,my-plugin:some-plugin-revision" --elasticsearch-plugins="my-plugin"`` where you need to replace ``some-elasticsearch-revision`` and ``some-plugin-revision`` with the appropriate :ref:`git revisions <clr_revision>`. Adjust other command line parameters (like track or car) accordingly. In order for this to work, you need to ensure that:
 
 * All prerequisites for source builds are installed.
@@ -122,16 +125,19 @@ To make this work, you need to manually edit Rally's configuration file in ``~/.
 
     plugin.my-plugin.remote.repo.url = [email protected]:example-org/my-plugin.git
     plugin.my-plugin.src.dir = /path/to/your/plugin/sources
-    plugin.my-plugin.build.task = :my-plugin:plugin:assemble
+    plugin.my-plugin.build.command = /usr/local/bin/gradle :my-plugin:plugin:assemble
     plugin.my-plugin.build.artifact.subdir = build/distributions
 
 Let's discuss these properties one by one:
 
 * ``plugin.my-plugin.remote.repo.url`` (optional): This is needed to let Rally checkout the source code of the plugin. If this is a private repo, credentials need to be setup properly. If the source code is already locally available you may not need to define this property. The remote's name is assumed to be "origin" and this is not configurable. Also, only git is supported as revision control system.
 * ``plugin.my-plugin.src.dir`` (mandatory): This is the absolute directory to which the source code will be checked out.
-* ``plugin.my-plugin.build.task`` (mandatory): The Gradle task to run in order to build the plugin artifact. This command is run from the plugin project's root directory.
+* ``plugin.my-plugin.build.command`` (mandatory): The full build command to run in order to build the plugin artifact. This command is run from the plugin project's root directory.
 * ``plugin.my-plugin.build.artifact.subdir`` (mandatory): This is the subdirectory relative to ``plugin.my-plugin.src.dir`` in which the final plugin artifact is located.
 
+.. warning::
+    ``plugin.my-plugin.build.command`` has replaced ``plugin.my-plugin.build.task`` in earlier Rally versions. It now requires the **full** build command.
+
 In order to run a benchmark with ``my-plugin``, you'd invoke Rally as follows: ``esrally --distribution-version="elasticsearch-version" --revision="my-plugin:some-plugin-revision" --elasticsearch-plugins="my-plugin"`` where you need to replace ``elasticsearch-version`` with the correct release (e.g. 6.0.0) and ``some-plugin-revision`` with the appropriate :ref:`git revisions <clr_revision>`. Adjust other command line parameters (like track or car) accordingly. In order for this to work, you need to ensure that:
 
 * All prerequisites for source builds are installed.
@@ -238,4 +244,3 @@ For this to work you need ensure two things:
 
 1. The plugin needs to be available for the version that you want to benchmark (5.5.0 in the example above).
 2. Rally will choose the most appropriate branch in the team repository before starting the benchmark. In practice, this will most likely be branch "5" for this example. Therefore you need to ensure that your plugin configuration is also available on that branch. See the `README in the team repository <https://github.com/elastic/rally-teams#versioning-scheme>`_ to learn how the versioning scheme works.
-

docs/faq.rst

@@ -4,12 +4,12 @@ Frequently Asked Questions (FAQ)
 A benchmark aborts with ``Couldn't find a tar.gz distribution``. What's the problem?
 ------------------------------------------------------------------------------------
 
-This error occurs when Rally cannot build an Elasticsearch distribution from source code. The most likely cause is that there is some problem in the build setup.
+This error occurs when Rally cannot build an Elasticsearch distribution from source code. The most likely cause is that there is some problem building the Elasticsearch distribution.
 
 To see what's the problem, try building Elasticsearch yourself. First, find out where the source code is located (run ``grep src ~/.rally/rally.ini``). Then change to the directory (``src.root.dir`` + ``elasticsearch.src.subdir`` which is usually ``~/.rally/benchmarks/src/elasticsearch``) and run the following commands::
 
-    gradle clean
-    gradle :distribution:tar:assemble
+    ./gradlew clean
+    ./gradlew :distribution:tar:assemble
 
 By that you are mimicking what Rally does. Fix any errors that show up here and then retry.
 
@@ -74,4 +74,3 @@ Do I need an Internet connection?
 You do NOT need Internet access on any node of your Elasticsearch cluster but the machine where you start Rally needs an Internet connection to download track data sets and Elasticsearch distributions. After it has downloaded all data, an Internet connection is not required anymore and you can specify ``--offline``. If Rally detects no active Internet connection, it will automatically enable offline mode and warn you.
 
 We have a dedicated documentation page for :doc:`running Rally offline </offline>` which should cover all necessary details.
-

docs/migrate.rst

@@ -4,6 +4,31 @@ Migration Guide
 Migrating to Rally 0.10.0
 -------------------------
 
+Removal of auto-detection and dependency on Gradle
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We have removed the auto-detection and dependency on Gradle, required until now to build from source, in favor of the `Gradle Wrapper <https://docs.gradle.org/current/userguide/gradle_wrapper.html>`_ which is present in the `Elasticsearch repository <https://github.com/elastic/elasticsearch>`_ for all branches >= 5.0.0.
+
+Use full build command in plugin configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With Rally 0.10.0 we have removed the property :code:`build.task` for plugin definitions, in the :code:`source` section of the Rally configuration file.
+Instead, a new property :code:`build.command` has been introduced where the **full build command** needs to be supplied.
+
+The earlier syntax, to build a hypothetical plugin called :code:`my-plugin` `alongside Elasticsearch <elasticsearch_plugins.html#plugins-built-alongside-elasticsearch>`_, required::
+
+    plugin.my-plugin.build.task = :my-plugin:plugin:assemble
+
+This needs to be changed to the full command::
+
+    plugin.my-plugin.build.command = ./gradlew :my-plugin:plugin:assemble
+
+Note that if you are configuring `Plugins based on a released Elasticsearch version <elasticsearch_plugins.html#plugins-based-on-a-released-elasticsearch-version>`_ the command specified in :code:`build.command` will be executed from the plugins root directory. It's likely this directory won't have the Gradle Wrapper so you'll need to specify the full path to a Gradle command e.g.::
+
+    plugin.my-plugin.build.command = /usr/local/bin/gradle :my-plugin:plugin:assemble
+
+Please refer to `Building plugins from sources <elasticsearch_plugins.html#building-plugins-from-sources>`_ for more information.
+
 Removal of operation type ``index``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -220,4 +245,4 @@ With Rally 0.9.0, the signatures need to be changed to::
     class CustomParamSource:
         def __init__(self, track, params, **kwargs):
 
-Rally will issue a warning along the lines of ``Parameter source 'custom_param_source' is using deprecated method signature`` if your track is affected. If you need access to the ``indices`` list, you can call ``track.indices`` to retrieve it from the track.
+Rally will issue a warning along the lines of ``Parameter source 'custom_param_source' is using deprecated method signature`` if your track is affected. If you need access to the ``indices`` list, you can call ``track.indices`` to retrieve it from the track.