Skip to content
Branch: master
Find file History
lacasseio Merge pull request #9711 from gradle/lacasseio/swift-init-templates
Add Swift application and library build init templates
Latest commit 3233e84 Jun 17, 2019
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
announce Dogfood native test fixtures Jun 15, 2019
antlr Dogfood native test fixtures Jun 15, 2019
api-metadata Change all subprojects to use 'implementation' dependencies May 22, 2019
architecture-test Change all subprojects to use 'implementation' dependencies May 22, 2019
base-services-groovy Dogfood native test fixtures Jun 15, 2019
base-services Merge pull request #9707 from gradle/sg/worker-api/classpath-inferer-2 Jun 15, 2019
bootstrap Simplify launcher project structure Jun 6, 2019
build-cache-http Dogfood native test fixtures Jun 15, 2019
build-cache-packaging Merge pull request #9709 from gradle/wolfs/kitchensink-project Jun 15, 2019
build-cache Dogfood native test fixtures Jun 15, 2019
build-comparison Dogfood native test fixtures Jun 15, 2019
build-init Use `outputContains` in the right context Jun 17, 2019
build-option Change all subprojects to use 'implementation' dependencies May 22, 2019
build-profile Dogfood native test fixtures Jun 15, 2019
build-scan-performance Dogfood native test fixtures Jun 15, 2019
cli Change all subprojects to use 'implementation' dependencies May 22, 2019
code-quality Dogfood native test fixtures Jun 15, 2019
composite-builds Dogfood native test fixtures Jun 15, 2019
core-api Dogfood native test fixtures Jun 15, 2019
core Merge pull request #9709 from gradle/wolfs/kitchensink-project Jun 15, 2019
dependency-management Fix incorrect simplification of intersection of unions Jun 17, 2019
diagnostics Dogfood native test fixtures Jun 15, 2019
distributions-dependencies Make use of the Java Platform plugin for distribution dependencies Dec 21, 2018
distributions Merge pull request #9709 from gradle/wolfs/kitchensink-project Jun 15, 2019
docs Apply suggestions from code review Jun 15, 2019
ear Dogfood native test fixtures Jun 15, 2019
execution Merge pull request #9709 from gradle/wolfs/kitchensink-project Jun 15, 2019
files Merge pull request #9709 from gradle/wolfs/kitchensink-project Jun 15, 2019
ide-native Dogfood native test fixtures Jun 15, 2019
ide-play Dogfood native test fixtures Jun 15, 2019
ide Dogfood native test fixtures Jun 15, 2019
installation-beacon Apply 'java-library' to more subprojects Jun 3, 2019
instant-execution Dogfood native test fixtures Jun 15, 2019
integ-test Dogfood native test fixtures Jun 15, 2019
internal-android-performance-testing Change all subprojects to use 'implementation' dependencies May 22, 2019
internal-integ-testing Fix flaky test Jun 17, 2019
internal-performance-testing Dogfood native test fixtures Jun 15, 2019
internal-testing Do not reacquire project lock when completing a worker-based task Jun 14, 2019
ivy Dogfood native test fixtures Jun 15, 2019
jacoco Dogfood native test fixtures Jun 15, 2019
javascript Dogfood native test fixtures Jun 15, 2019
jvm-services Dogfood native test fixtures Jun 15, 2019
kotlin-compiler-embeddable Change all subprojects to use 'implementation' dependencies May 22, 2019
kotlin-dsl-integ-tests Adjust tests to use 'implementation' instead of 'compile' Jun 6, 2019
kotlin-dsl-plugins Dogfood native test fixtures Jun 15, 2019
kotlin-dsl-provider-plugins Change 'compilOnly' to the more correct 'implementation' Jun 6, 2019
kotlin-dsl-test-fixtures Change all subprojects to use 'implementation' dependencies May 22, 2019
kotlin-dsl-tooling-builders Dogfood native test fixtures Jun 15, 2019
kotlin-dsl-tooling-models Change 'compilOnly' to the more correct 'implementation' Jun 6, 2019
kotlin-dsl Dogfood native test fixtures Jun 15, 2019
language-groovy Dogfood native test fixtures Jun 15, 2019
language-java Merge pull request #9709 from gradle/wolfs/kitchensink-project Jun 15, 2019
language-jvm Dogfood native test fixtures Jun 15, 2019
language-native Dogfood native test fixtures Jun 15, 2019
language-scala Dogfood native test fixtures Jun 15, 2019
launcher Dogfood native test fixtures Jun 15, 2019
logging Dogfood native test fixtures Jun 15, 2019
maven Dogfood native test fixtures Jun 15, 2019
messaging Dogfood native test fixtures Jun 15, 2019
model-core Dogfood native test fixtures Jun 15, 2019
model-groovy Dogfood native test fixtures Jun 15, 2019
native Merge pull request #9709 from gradle/wolfs/kitchensink-project Jun 15, 2019
osgi Dogfood native test fixtures Jun 15, 2019
performance Revert "Rebaseline Gradleception" Jun 15, 2019
persistent-cache Dogfood native test fixtures Jun 15, 2019
pineapple Keep pineapple as a WORKER module Jun 14, 2019
platform-base Dogfood native test fixtures Jun 15, 2019
platform-jvm Dogfood native test fixtures Jun 15, 2019
platform-native Dogfood native test fixtures Jun 15, 2019
platform-play Dogfood native test fixtures Jun 15, 2019
plugin-development Dogfood native test fixtures Jun 15, 2019
plugin-use Dogfood native test fixtures Jun 15, 2019
plugins Dogfood native test fixtures Jun 15, 2019
process-services Dogfood native test fixtures Jun 15, 2019
publish Dogfood native test fixtures Jun 15, 2019
reporting Dogfood native test fixtures Jun 15, 2019
resources-gcs Dogfood native test fixtures Jun 15, 2019
resources-http Dogfood native test fixtures Jun 15, 2019
resources-s3 Dogfood native test fixtures Jun 15, 2019
resources-sftp Dogfood native test fixtures Jun 15, 2019
resources Dogfood native test fixtures Jun 15, 2019
runtime-api-info Change all subprojects to use 'implementation' dependencies May 22, 2019
scala Dogfood native test fixtures Jun 15, 2019
signing Dogfood native test fixtures Jun 15, 2019
smoke-test Dogfood native test fixtures Jun 15, 2019
snapshots Merge pull request #9709 from gradle/wolfs/kitchensink-project Jun 15, 2019
soak Dogfood native test fixtures Jun 15, 2019
test-kit Dogfood native test fixtures Jun 15, 2019
testing-base Merge pull request #9709 from gradle/wolfs/kitchensink-project Jun 15, 2019
testing-junit-platform Change all subprojects to use 'implementation' dependencies May 22, 2019
testing-jvm Dogfood native test fixtures Jun 15, 2019
testing-native Dogfood native test fixtures Jun 15, 2019
tooling-api-builders Simplify launcher project structure Jun 6, 2019
tooling-api Dogfood native test fixtures Jun 15, 2019
tooling-native Dogfood native test fixtures Jun 15, 2019
version-control Dogfood native test fixtures Jun 15, 2019
worker-processes Dogfood native test fixtures Jun 15, 2019
workers Fix flaky test Jun 17, 2019
wrapper Dogfood native test fixtures Jun 15, 2019

README.md

The docs project produces the user manual, DSL reference, javadoc and release notes (as well as some other minor bits).

The following is some help for working with the docs, all file paths are relative to this directory unless specified otherwise.

Release Notes

The release notes are generated from src/docs/release/notes.md.

Schema

Every h2 tag and h3 will be listed in the generated TOC.

After every h3 all content after the first element (usually a p) will be collapsed/expandable, up until the next h3, or h2.

After every h4 all content will be collapsed/expandable, up until the next h4, h3 or h2.

An h3 may include an incubating marker (i) at the end of its text to indicate that the feature is incubating.

Here's an example:

## h2 New and Noteworthy

### h3 Some feature (i)

This is some incubating feature.

#### h4 Some detail

This detail about the feature is collapsed. The reader can expand it if they are interested.

Generating

Run the viewReleaseNotes task to generate the release notes, and open them in your browser (requires Java 6).

Editing

You can run the editReleaseNotes task to open the raw markdown notes in whatever editor is registered for this file type (requires Java 6).

User Manual

The source for the user manual lives @ src/docs/userguide, and is authored in Asciidoctor.

To generate the user manual and see your changes, run:

./gradlew :docs:userguide

This will generate:

  • A multi-page HTML manual in build/docs/userguide for each chapter. There is a 1-1 mapping from .adoc file to .html file.
  • A single-page HTML manual at build/docs/userguide/userguide_single.html
  • A PDF at build/docs/userguide/userguide.pdf

Note that PNG files in the source are generated from ".graphml" files in the same directory. You can edit these files with tools like yEd and then generate the associated PNG.

If you just need to see a change to one of the userguide sections, try:

./gradlew :docs:userguide -x :docs:userguideSinglePage

Authoring with AsciiDoc

To write a chapter in Asciidoctor format, simply place it in src/docs/userguide called <chapter>.adoc.

You will find these references useful when authoring AsciiDoc:

Using Asciidoctor

To write a chapter in Asciidoctor format, simply place it in src/docs/userguide called <chapter>.adoc.

Code Samples

Samples and output belong under src/samples and are typically included in the user manual. This is a typical example:

Example multi-language sample file listing

This shows Groovy and Kotlin sample projects under "sample-dir" which is defined as "$projectDir/src/samples".

subprojects/docs/src/samples/
└── userguide/initScripts/customLogger/
    ├── customLogger.out
    ├── customLogger.sample.conf
    ├── groovy
    │   ├── build.gradle
    │   ├── init.gradle
    │   └── settings.gradle
    └── kotlin
        ├── build.gradle.kts
        ├── customLogger.init.gradle.kts
        └── settings.gradle.kts

Note here that there are 2 sample projects under userguide/initScripts/customLogger/: one for the Groovy DSL and one for Kotlin DSL. Also note that there is only 1 customLogger.sample.conf file that tells Exemplar how to execute both groovy and kotlin samples, with 1 customLogger.out file proving the output is identical between the two.

Example Asciidoctor multi-language sample declaration

.Customizing what Gradle logs
====
include::sample[dir="userguide/initScripts/customLogger/groovy",files="init.gradle[]"]

include::sample[dir="userguide/initScripts/customLogger/kotlin",files="customLogger.init.gradle.kts[]"]
====

[.multi-language-text.lang-groovy]
----
$ gradle -I init.gradle build
include::{samplesPath}/userguide/initScripts/customLogger/customLogger.out[]
----
[.multi-language-text.lang-kotlin]
----
$ gradle -I customLogger.init.gradle.kts build
include::{samplesPath}/userguide/initScripts/customLogger/customLogger.out[]
----

Let's break down this example to explain:

  • Enclosing ==== around the sample includes groups these samples and collapses them
  • include::sample: invokes the SampleIncludeProcessor asciidoctor extension, with a dir relative to src/samples/, and a list of files separated by ; (only 1 in this example), each with optional tags=... (like Asciidoctor's tags mechanism). We write this once for each DSL dialect. This notes to our front-end code to group these 2 samples and show them with selector tabs.
  • [.multi-language-text.lang-groovy]: Most times the gradle command is identical between Groovy and Kotlin samples, but in this case we need to use [.multi-language-text.lang-*] that our CSS will collapse and switch for the DSL of choice. This is case-sensitive. You can use this construct for any 2 sibling blocks!

It is possible to embed sample sources, commands, and expected output directly in the Asciidoc (or a mixture of embedded and included), but we don't use this for the user manual yet. See the Exemplar documentation if you're interested in this.

Groovy DSL Reference

The DSL reference is authored in Docbook syntax, with sources under src/docs/dsl. Much of the content is extracted from code doc comments.

To build it, run:

./gradlew :docs:dslHtml

The output is available under build/docs/dsl.

Useful docbook tags

See the docbook reference for a list of all available tags.

Custom Tags

<apilink>

This is an inline element which adds a link to the API documentation for a particular class or method.

You can use the <apilink class='org.gradle.api.Project' /> interface to do stuff.

The link will point to the DSL reference for the specified class, if available. Otherwise, it will point to the javadoc for the class.

To link to a method:

<apilink class='org.gradle.api.Project' method="apply(java.util.Map)" />

Javadocs

To build these, run:

./gradlew :docs:javadoc

The output is available within build/docs/javadoc.

Building all the docs

There is a convenience task to build all of the documentation:

./gradlew :docs:docs
You can’t perform that action at this time.