Demonstrate generated source files

[lacasseio]

To complement globing and cherry-picking, we can generate sources:

def generatorTask = tasks.register('generateSources', Sync) {
    from(zipTree('sources.zip')) {
        into('sources') { include '**/*.c' }
        into('includes') { include '**/*.h' }
    }
    destinationDir = layout.buildDirectory.dir('generated/main').get().asFile
}

application {
    cSources.setFrom(generatorTask.map { "${destinationDir}/sources" })
    privateHeaders.setFrom(generatorTask.map { "${destinationDir}/includes" })
}

It's important to note there are several ways to implement a generator. This particular generator is one way to extract files from a zip file. However, you could use zipTree directly as inputs to cSources and privateHeaders. This is a demonstration. Usually the Sync task would be replaced by a custom task implementation.

[lacasseio]

I think to properly demonstrate the generated sources, we should implement a proper generator task. We would need to find a common use case that requires generated code (i.e. config headers or a mock-up protobuf compile task). Regardless of the choice, the focus is on the cSources and privateHeaders configuration. the generator task implementation is an implementation detail and we should most likely put the code in a collapsable block (which is collapsed by default) to avoid too much noise in the sample.

[Ladalz]

Is generator a common knowledge if not we also need to add to the FYI "what is a generator for sources and when to use them" and have a link to it at the start of the sample/demonstration to clarify necessity before getting into sample that might be overexplained for newer/most users

[lacasseio]

Good point, the generator is the abstract process to generate the sources. I think we can have a quick mention when we gloss over the generator task implementation. Most users generally refer to generated sources which stand by themselves for some process leading to additional sources. It could be a good idea to include it in our terminology chapter which is inspired by Gradle terminology for dependency management. I'm unsure if we should have a focused terminology chapter but for now, we can bunch them all in the same chapter and split them later when it makes sense.

[lacasseio]

In other build systems, they use similar terminology. For example, in CMake, they have a section in the tutorial about generated files and Meson has a section about generating sources. When reading their documentation, we have to be careful because the term generator has a different meaning in some contexts.

In general, generated sources is the result the user wants and generating sources (or generator) is the process to arrive at the result. There are multiple ways to get the same result which is why we should focus more on the result and less on the process. The result is more in the control of Nokee while the process is more in the control of Gradle.