Error in User Guide Chapter 4

The user guide: Chapter 4. Using the Gradle Command-Line

has some serious flaws:

Figure 4.1 and Example 4.1 define a build.gradle file with four tasks:

  1. compile
  2. compileTest
  3. test
  4. dist

In Example 4.8 it suggests:

description = ‘The shared API for the application’

And then shows output with a “dists” task under build. But notice at no point have we declared dists. To me that means I’m suppose to add the description to the existing build.gradle from before to get Example 4.9 output (but dist should be dists).

Example 4.10 now provides a dists, but since we called it dist before it is very confusing.

In general all samples in the user guide are self-contained although this chapter does at times imply that subsequent examples build off each other despite that not being the case.

Example 4.8 is a bit confusing, it’s actually adding the description to the project not a task, so it is in itself a completely valid build script.

it seems pretty clear that the “dists” task referred to in the output of example 4.9 refers to the task that was named “dist” in example 4.1, and also referred to as “dist” in several examples after that.

I’m not sure why you mention example 4.8. I would think that would be fine either standalone, or somehow added to the previously mentioned build.gradle file.

Example 4.10, as the OP mentions, just has a block named “dists”, which doesn’t make sense. If this was instead “task dists”, this would at least be a syntactically valid way to set the properties for a task named “dists”, if we weren’t working, as implied, from an initial build script with a task named “dist”.

Would just renaming this to something more unique make it more clear that this is a completely different build? The ‘compile’ and ‘libs’ task are also not mentioned at all in previous examples so I think the intent there was to convey this is a different build.

Certainly making them completely different would resolve that. That would be a potentially simple fix. However, there is a lot of value in presenting sample output in the doc that the user could easily get on their box, if they made the incremental changes described in the doc. When it’s practical to present an example that uses a “growing” code sample, you get much better learning.

This still doesn’t address the issue in example 4.10, however.