Project configuration vs. project evaluation

In section 58.6.1 at https://docs.gradle.org/current/userguide/build_lifecycle.html project evaluation is mentioned. However, to me that page makes not clear how that relates to project configuration. Are these synonyms? Or is evaluation a part of configuration? If so, what other (sub-)phases does the configuration phase have? Could we maybe have a diagram similar to the one at http://stackoverflow.com/questions/24638691/when-gradles-hooks-are-added-in-build-lifecycle in the userguide?

2 Likes

These terms are used a bit interchangeably. Typically we use “configuration” in the context of the configuration phase which is Gradle evaluating all your build scripts, plugins, etc just before beginning execution. We say that a project is evaluated when the configuration for that project has been evaluated. Some of these lines also are a bit unclear, as code in an afterEvaluate { } block is considered configuration and therefore still evaluated as part of the configuration phase.

Indeed very confusing. You literally say “configuration phase is when Gradle is evaluating”, but why is it not called “evaluation phase” then? Could you please improve the docs in this respect, for example by not using the verb “configure” at all, but only “evaluate”, and make clear that the “configuration phase” consists of evaluating (not configuring) all projects?

1 Like

I use those two words because they are appropriate in the context. “Configuration” is a noun, “evaluate” is a verb. We say configuration to mean the build scripts and evaluate to mean the execution of those scripts. You could argue that “configuring” and “evaluating” are the same thing however we are unlikely to change these terms a) because afterEvaluate is part of the API and changing it would be a breaking change and b) the notion of “configuration” phase is ubiquitous in the Gradle community.

That’s why I was asking to at least explain in the docs the relation between these. If you cannot fix the issue, at least document it.

We can certainly make this distinction clearer in the documentation. Is the main issue being that it is not clear that projects are “evaluated” during the configuration phase?

Sort of. IMO it could be clearer that the configuration phase is made up of exactly and only evaluating all projects taking part in the build, i.e. that evaluation is part of the configuration phase (and not a separate phase) and that nothing else than evaluating projects is done in the configuration phase (i.e. no other work than evaluating is going on).

Thanks for the feedback, Sebastian. We are actually doing some rework of the user guide right now. I’ll look at incorporating these comments as part of that effort.

Not sure if the docs were updated but this issue still exists and is still confusing. One suggestion is to mention Evaluation when defining Configuration in the Build Phases section.
Something like:

This phase is also known as “Evaluation”.