Improve user manual section on incremental build. #688
Conversation
This is a rewrite and expansion of the incremental build section of the user manual. It provides proper coverage of this important topic while introducing some of the new features in Gradle 3.0.
| @@ -0,0 +1,816 @@ | |||
| <?xml version="1.0" encoding="UTF-8"?> | |||
There was a problem hiding this comment.
Maybe we could put the original image files (like Photoshop, Graffle etc.) into a separate directory. So far we didn't check in those files but we should definitely keep them version controlled. BTW: Great job on providing images! This was always lacking.
There was a problem hiding this comment.
I saw the .graphml files were included in the directory alongside the PNGs, so assumed that the project files went there.
There was a problem hiding this comment.
OK, let's keep it there for now. At the moment we only have a hand full of images anyway. In the long run I think I'd like to keep them separate.
There was a problem hiding this comment.
I agree, although we're not expecting significant changes to the user manual in the near future.
| </para> | ||
|
|
||
| <para>This example is particularly interesting because it works with collections of source | ||
| files. What happens if only one source file changes? Does the task process all the |
There was a problem hiding this comment.
We should mention at some point if you want to work with source files, we have the great SourceTask at your service that has all the bells and whistles you might need to work with a bunch of sources.
There was a problem hiding this comment.
It's mentioned (and linked) in the advanced incremental build section. I'll think about making it more prominent by moving it to an earlier bit. I'm not sure at this point whether it would act as a distraction or not.
|
I can rebase against |
|
@pledbrook Thanks! I noticed three more things after generating the user guide on my local machine:
|
|
Good catches. I've fixed the links and some typos I noticed. I don't want to change the table because I don't know how to put the starred paragraph after the table while making it look part of the table. So I've gone for the lesser of the two evils. One other thing to bear in mind: I'm waiting on feedback from @lptr about the |
|
PS I think a lot of the user manual is using |
|
@lptr is on vacation and won't be back until Monday. We should make a judgement call whether we can potentially address his comments later. |
|
Well, it depends on whether we want the section to be accurate. This is the relevant comment. |
|
I am a bit confused about @lptr means here exactly. I'd vote for merging and cleaning it up in an internal review on our end. I will try to merge the PR tomorrow if possible. |
|
Internal review: https://code-review.gradle.org/cru/REVIEW-6197 |
|
I finished off the outstanding review items. |
| one input as well. | ||
| </para> | ||
| <para> | ||
| A task with no defined outputs will <emphasis>never</emphasis> be considered up-to-date. |
There was a problem hiding this comment.
A task with no defined outputs will never be considered up-to-date.
This sentence was removed from the manual last year. Is that because it's no longer true? If it is true, I would find it really helpful to keep the sentence in the manual.
My assumption was that a task with inputs but no outputs would run when the inputs change, rather than always run. The fact that this is not the case is surprising (in fact, it seems like Gradle should warn if you define inputs but no outputs) and should still be documented if true...
There was a problem hiding this comment.
It was misleading. For lifecycle tasks, a task can have no inputs, outputs or actions and still report being UP-TO-DATE or not.
We tried to describe the different task outcomes more here.
There was a problem hiding this comment.
I see, but it still seems really unclear to me that the case of "actions, inputs and no outputs" is basically the same as "actions, no inputs, no outputs". My intuition says "if you define inputs and no outputs, then it should re-run whenever the inputs change and not if they don't", but you need to also add outputs.upToDateWhen { true } to make that true. Is there anything anywhere in the page that directly says this?
There was a problem hiding this comment.
I think all tasks have some kind of output (calculate a property, produce some console output, populate a database), but not all outputs are understandable by Gradle. We're limited to outputs that are files right now. So a task with no file outputs means Gradle doesn't have a way to know if the task's work is done.
A rule like "if you define inputs and no outputs, then it should re-run whenever the inputs change and not if they don't" assumes that the output of the task cannot change without a noticeable change in the inputs. This falls down for things like "deploy this application" (which could have inputs and non-file outputs). We're missing a feature that allows you to say some arbitrary serializable thing is the representation of the task's outputs that aren't files.
outputs.upToDateWhen { true } adds to Gradle's up-to-date checking, so this will still always execute the task if there are no other outputs defined. From the Javadoc, task outputs are considered out-of-date if this returns false. It doesn't mean that the task is considered up-to-date if it returns true.
There was a problem hiding this comment.
So the example that led me here is a linter. If the input files haven't changed, I don't want to re-run the linter. (If I really believe there's some sort of non-determinism in my linter, I can use --rerun-tasks, I guess.) I guess this counts as "produce some console output" but I don't know how to express that other than as outputs.upToDateWhen { true }.
There was a problem hiding this comment.
The easiest thing to do is to put your linter's output into a report file and write to the console too (or make that configurable). That's what the built-in Gradle code quality tasks do.
To be clear, outputs.upToDateWhen { true } does not mean your outputs are up-to-date. It only means that the additional check (on top of the check that Gradle already does) considers the task's outputs up-to-date. If the task doesn't have any outputs declared, Gradle considers the task's outputs as unknown/out-of-date.
Please feel free to open a new topic on https://discuss.gradle.org/ if you have more questions.
This is a rewrite and expansion of the incremental build section of the user
manual. It provides proper coverage of this important topic while introducing
some of the new features in Gradle 3.0.