Compile avoidance

[sknop]

We have a repository with many reports, each of which is rendered to a PDF document.
There is a buildAll task which will create all reports, but this task does not check if the artefact (i.e. PDF file) already exists.
It would be great if the plugin would check artefacts first before attempting to recreate all PDFs again (since that takes a very long time).

For added credits: the source documents contain 'include' directives for common building blocks of reports. Ideally the check for compile avoidance should check if any of the include files have changed (timestamp) and build documents again that have that dependency.

[ysb33r]

This issue is only considered in the context of 2.0 as it is to complex to fix on the 1.5 (soon to be maintenance) branch.

There are a number of items that will affect rerunning of the task and document generation. It is worth listing them out first:

• sources
• resources
• secondarySources
• task.inputs
• gradle.startParameter.rerunTasks

Consider now this build.gradle snippet where I have utiltised asciidoctorPDF as the OP mentioned for their use-case

asciidoctorPdf {
    sources {
        include 'a.adoc'
        include 'b.adoc'
    }

    resources {
      include 'images/**'
    }

    // The following block is implicit for the PDF plugin, but
    // shown here for context
   secondarySources {
       include '*-theme.y*ml'
   }

   inputs.dir 'some/src/directory'
}

In simplified terms this issue concerns itself with a.adoc and b.adoc which should produce a.pdf and b.pdf. Ignoring the bonus credits of include directives for the moment, then on a re-run if only a.adoc has changed then only a.pdf should be regenerated.

Taking the above build snippet into consideration, there are a number of resources and theme files associated with both documents. It is possible that this is not the case as some images might only be used in one of the documents, but not the other. In a similar fashion there might be multiple theme files, maybe one each for a.adoc and b.adoc. For now we'll classify them in the same problem space as includes and kick that can further down the road.

Thus it means that we now have the following build avoidance algorithm to implement:

• Only rebuild the document that changed.
• If the secondary soruces or resources have changed then rebuild everything.
• If an explicit definition of task inputs exists and it has changdm then rebuild everything.
• If --rerun-tasks has been specfied on the command-line, rebuild everything.

In terms of implementation:

• The Gradle API currently offers little to no support to plugin authors to achieve compile avoidance, so we'll probably need to roll our own solution in order to keep Gradle 4.x compatibility.
• Each task type related to a backend will need to have a method for customising the source doc to output doc(s) mapping as not all backend have a one-to-one mapping.

Bonus items:

• In order to deal with include directives it will require pre-processing of the document using Asciidoctor with a ccustom IncludeProcessor. Due to the architectural model this might turn out more expensive than just regenerating the document. If this is to be implemented it will ned to be an optional feature wich is off by default.
• A similar case can be made for both secondary sources and resources. It might just be easier for a build script author to have multiple asciidoctorX tasks defined.