intrepid-plugin

This section describes the types pre-defined by the Holy Gradle.

It is possible to define your own configuration set types, though the ways of doing this are currently not documented. Please look at the source for the interfaces ConfigurationSetType and ConfigurationSet, and the classes which implement them.

This method takes one parameter, the configuration set type for this configuration set. For the pre-defined types, the names of the configurations in the set will be those from the type, with the prefix added at the beginning.

→ You must call this method exactly once.

This method takes one parameter, a string prefix to be added to all names from the type. If this method is not called for a configuration set, the names from its type will be used directly. If you have more than one configuration set of the same or similar types in your build script, you will probably have to use a prefix on all but one of them to avoid configuration name overlaps.

→ Call this method at most once.

Configuration sets themselves have methods which may be useful in your build script.

If this flag is true, Intrepid will call configuration.resolutionStrategy.failOnVersionConflict() for each configuration which is created. This is in contrast to the default Gradle behaviour, which allows conflicts and resolves them according to configurable strategies. To turn off this default behaviour, set the property to false. This behaviour is implemented in this way because there is no Gradle mechanism to revert to allowing resolution of version conflicts after failOnVersionConflict() has been called.

This value can be set in each project in a multi-project build. If it’s not set in a sub-project, that project will use the value from the root project; failing that, it defaults to true.

Source dependencies and packed dependencies are specified as relative paths rather than being immediate subdirectories of the workspace. See Relative paths.

Note that Gradle’s concept of subprojects applies to source dependencies, but not in the way you might expect. Gradle projects can have subprojects, which are subfolders of a source repository containing a build.gradle, selected using include 'path/to/subproject' in the root project’s settings.gradle. A project can discover and operate on its subprojects in its build.gradle, and the build.gradle for a project is (normally) evaluated before the build.gradle of its subprojects. If the settings.gradle includes 'foo' and 'foo/bar' then foo will be a subproject of the root project, and bar will be a subproject of foo. However, any source dependency in any Holy Gradle project is added as a direct subproject of the root project, ignoring where it appears in the folder hierarchy of the root project. This is because the Holy Gradle allows source dependency to exist on disk at a location outside the folder of the project which depends on it; also, it does not require the root project to know about all transitive source dependencies.

The Gradle concept of project/module dependencies does apply to source dependencies, as described under configuration.

By default, intrepid can only fetch source from repositories which do not require authentication. If the project also has the my-credentials-plugin applied, it will use passwords cached in Windows Credential Manager to access Mercurial and Subversion repositories. If cloning, checking out, or exporting a repository for which no password is already cached, the plugin will initialise the cached username and password for that repository based on a value stored under "Intrepid - type" for some string "type".

Before 7.10.0 this type was always the default username and password managed by my-credentials-plugin, "Domain Credentials". Since 7.10.0 you can override the credential used as a basis for the source repository with the plugin-intrepid.html#_credentialBasis property.

using the value stored under "Intrepid - Domain Credentials" (the default username and password managed by my-credentials-plugin).

This method takes one parameter - the URL of the Mercurial repository to clone.

You can optionally specify a particular Mercurial revision after an @ character e.g.

This will result in a clone that has been updated to the specific Mercurial revision.

After the source dependency has been retrieved you may make local modifications or update to a different revision and rerunning fetchAllDependencies will have no effect on your local copy.

→ Call this method at most once.

→ You must call one of hg, git, or svn.

This method takes one parameter - the URL of the Git repository to clone.

You can optionally specify a particular Git revision after an @ character e.g.

This will result in a clone that has been updated to the specific Git revision.

After the source dependency has been retrieved you may make local modifications or update to a different revision and rerunning fetchAllDependencies will have no effect on your local copy.

→ Call this method at most once.

→ You must call one of hg, git, or svn.

This method takes one parameter - the URL of the Subversion repository to checkout from.

You can optionally specify a particular SVN revision after an @ character e.g.

This will result in a checkout of the repository, pinned to a specific version.

After the source dependency has been retrieved you may make local modifications or update to a different revision and rerunning fetchAllDependencies will have no effect on your local copy.

→ Call this method at most once.

→ You must call one of hg, git, or svn.

This is an optional property that defines which "Intrepid - type" credential will be used for the source repository. Using another credential type as a basis means that the user only has to enter their username and password once, even if the same credentials are used for multiple source repositories. The intrepid plugin will read the username and password from the "Intrepid - type" credential in the Windows Credential Manager and cache it for the relevant source control software.

Usage:

This is an optional property that defines which named branch of the repository to use. This is only valid for Mercurial and Git repositories, and the default value is null which equates to retrieving the default branch. This is equivalent to hg clone --branch special — http://path/to/foo foo or git clone --branch special — http://path/to/foo.git foo.

Usage:

This method defines the configuration mapping for the dependency - see the <dependency … conf="…"/> attribute in the example module descriptor above. Mappings are defined from configurations in this module to configurations in the dependency module. This creates a Gradle project dependency between the two projects; see the documentation for DependencyHandler. This dependency means that mappings will be included in the module descriptor when this module is published. The "to" configurations also determine which packaged artifacts from the dependency module will be fetched and unpacked.

More details on extending configurations, and mapping sets of related configurations between modules, can be found in the Configurations section of the link:workflows.html page.

You can pass any number of string parameters to this method, or call the method multiple times.

You can also not call this method, in which case the source will be checked out but its Gradle project configurations will not be linked to the configurations of this module and, when this module is published, it will have no dependency on any module which may be defined in the checked-out repository. This can be useful if, for example,

Here are some examples of string parameters passed to the configuration method and the resulting mappings:

This method creates multiple configuration mappings from this module to a source dependency module, based on the names defined by configuration sets and configuration set types, and any specific mapping rules implemented by the types.

The method takes two main arguments:

If the source is a ConfigurationSet, then the optional "export:" boolean argument can be passed, which affects the mapping of import_* configurations (see Configuration Mapping Rules).

The Holy Gradle does not check that the type for the target is correct. You may be able to get documentation for a dependency, or work out which mapping to use by looking at its package contents or the ivy.xml. From version 7.7.2 the description for each configuration in a configuration set contains a hint about how to use it.

→ Call this method and/or configuration at least once, usually.

Following are some examples of parameters passed to the configurationSet method and the resulting mappings. They assume the following configuration sets in both this module and the target.

This is like a struct which groups together a few different configuration options relating to how the source-code dependency will be referenced (in the Ivy module descriptor XML) when the consumer module is published. The consumer module can be published as depending on the published output of a source-code dependency.

If the publishing configuration is omitted then the source-code dependency will not be mentioned in the module descriptor.

This is an example of a fully-specified publishing element:

This read-only property returns a string "hg" or "svn" depending on whether this project directory is an hg clone or an svn checkout. If it is neither then "n/a" will be returned.

This read-only property returns the url for the source control repository/checkout in the project directory. Null is returned if the project directory is not under source control.

This read-only property returns the revision for the source control repository/checkout in the project directory. Null is returned if the project directory is not under source control.

This method returns a boolean indicating whether the source control repository/checkout in the project directory has any uncommitted modifications. False is returned if the project directory is not under source control.

Source dependencies and packed dependencies are now specified as relative paths rather than always being immediate subdirectories of the workspace. See Relative Paths and Subprojects.

Since 7.12.0, all packed dependencies which share a configuration must appear under the same parent folder, or an exception is thrown. Another simpler way to think of this is that every configuration must have exactly one folder where all its dependencies appear. Multiple configurations can share the same folder, and indeed usually will do when they are part of a configuration set.

Without this restriction, it would be possible for different versions of the same transitive dependency (from different packed dependencies) to target the same folder on disk. With this restriction, that can’t happen, because core Gradle ensures that there can be only one version of any dependency per configuration.

For example, the following declarations are okay, because the relative paths are the same wherever the configurations are the same.

However, the following declarations will fail, because the "build" configuration is part of the main configuration set, so all three dependencies share the "build" configuration, but TestLib is declared to appear under a different parent.

You can specify <version> anywhere within the name of a packed dependency e.g. "my_component-<version> blah". Once the version number has been resolved, the <version> will be replaced with the actual version of the packed dependency that has been retrieved.

The name of the packed dependency affects:

For the example above, the workspace would look like this:

This method configures the coordinates of the dependency. The single parameter must follow the pattern "<groupId>:<artifactId>:<version>" where:

→ Call this method exactly once.

This method works the same as configuration for sourceDependencies. You will normally call this method or configurationSet at least once for a packed dependency, otherwise no packed artifacts will be fetched and unzipped.

→ Call this method and/or configurationSet at least once, usually.

This method works the same as configurationSet for sourceDependencies. You will normally call this method or configuration at least once for a packed dependency, otherwise no packed artifacts will be fetched and unzipped.

→ Call this method and/or configuration at least once, usually.

This property defines whether the dependency should be unpacked to the central cache for unpacked dependencies, or unpacked directly to the workspace.

→ Default value: true

Calling this method on a packed dependency causes the rebuildLinks and deleteLinks task to ignore it. This allows you to create your own folder or link in the appropriate location, to replace a packed dependency with, for example, a locally-built version.

It is expected that developers will normally only use this method temporarily in their local check-out, and not commit it to shared version-controlled source. If this method is called on a packed dependency, then attempting to publish the containing project will throw an exception, because Gradle cannot know the real version of the dependency.

Note that, before Holy Gradle 7.8.0, this method was called noCreateSymlinkToCache.

This property determines whether the unpacked dependency directory (and all subdirectories and files) should be set to read-only. This can help to prevent the unpacked dependency files being unintentionally modified.

Note: this will only be done if applyUpToDateChecks is false.

→ Default value: true

This property determine whether fetchAllDependencies should perform full up-to-date checks to compare the dependency zip files with the target directory. This will take much longer to execute, but avoids any possibility that the unpacked dependencies have been modified.

→ Default value: false

The default location for the unpacked dependency cache is <Gradle User Home dir>/unpackCache. You can change the location of your Gradle User Home directory. If you want more specific control then that can be achieved with the following piece of DSL.

If this value is set in the root project, it will affect all sub-projects unless they override it.

Since this specifies a machine-specific location you should probably avoid including the path in a build script that will be shared with other developers. You may wish to use a user.gradle file or gradle.properties file to configure the path.

If you set this to point to a network share, the Holy Gradle will use a symlink. If your user account has local Administrator rights, then this requires the Gradle process to run with Administrator privileges on Windows 8 and above. Putting your cache on a share is not recommended, for performance reasons.

Older versions of the Holy Gradle allowed published modules to specify the relative location where each transitive packed dependency should appear. This design caused various problems, as follows.

In practice, all uses had a relative path of "../module_name", so this is now the default. Since 7.12.0 the previous behaviour has been removed. Attempting to use the following DSL will now cause an exception.

There are several limitations restrictions in using source overrides.

The direct and transitive dependencies of a source override may differ from those of the binary package it is replacing. In that case, the Holy Gradle will make sure that dependency versions are consistent between the root project and the override source — just as Gradle checks consistency for binary dependencies. This check also applies if there are multiple dependencies with source overrides, or if the override source project itself contains source overrides.

To do this check, the sourceOverride requires a valid Ivy file with the list of immediate dependencies at <sourceOverride>/build/publications/ivy/ivy.xml and an XML file at <sourceOverride>/all-dependencies.xml containing a full list of immediate and transitive dependencies for the project in the format created by the summariseAllDependencies task, as follows.

To make sure these files are up-to-date, when trying to resolve dependencies the plugin will try several methods in turn until one succeeds, as follows.

# If the sourceOverride declares an plugin-intrepid.html#_ivyFileGenerator closure, call that to generate the two files and return the paths to them. # If the batch file <sourceOverride>/generateSourceOverrideDetails.bat exists, run that to generate the two files. # Run "<sourceOverride>/gw.bat -PrecordAbsolutePaths generateIvyModuleDescriptor summariseAllDependencies".

This method specifies the coordinates of the dependency to override. It should follow the same pattern as the packedDependency definition. Transitive dependencies of this and any source dependencies will also be overridden but transitive dependencies of a source override will not. This will be reported as a version conflict at dependency resolution time. If you need to override the transitive dependencies of a source override, then you must use sourceOverrides in that source override project as well.

This method defines a path, either absolute or relative to the root project, where the override source is located.

This method defines a closure to run to generate the dependency files for this source override. It should return a list of two File objects, one for the direct dependency Ivy file and the other for the transitive dependency XML file. The SourceOverrideHandler is passed into the closure giving access to (among other things) the project object.

This is useful in cases where the source does not use a compatible version of the Holy Gradle, or is not a Holy Gradle project, or not a Gradle project at all. It is also useful if want to override some dependencies which are built as part of a multi-project build; the following example will generate the dependency files for a sub-project of "framework".

Note that the SourceOverrideHandler is private to the Holy Gradle so you cannot actually reference that type in your build script. However, since Groovy is a dynamic language, you can still call methods from SourceOverrideHandler on that object.

The next example just returns static files; for example, these might be created by hand.

If you override a module which comes from a multi-project build, and that module depends on other modules in that multi-project build, you may want to override several modules from one build. To do that, you can use a pattern like the following.

→ Calling this method is optional.

This method takes one or more parameters. Each parameter defines a location in the retrieved source-code dependency folder. The name of the resulting link will always correspond to the last component of the path argument.

→ Call this method any number of times with any number of arguments.

This property defines the configuration that the package belongs to. For example look at the conf attribute below:

You do not have to explicitly set the configuration if the name of the package already matches the name of the configuration.

→ Default value: package name

This method defines file-path patterns to include in the package, subject to those files not being excluded by the exclude patterns.

You can pass any number of string parameters to this method, or call the method multiple times.

→ Call this method at least once.

This method defines file-path patterns to exclude from the package. This will take priority over any include patterns.

Some patterns will be excluded by default: .gradle, packages/ivy.xml, packages/*.zip

You can pass any number of string parameters to this method, or call the method multiple times.

→ Call this method any number of times.

These methods allow you to change the path to files that you include in a package. By default the packaging process behaves as if both from and to had been set to ".".

In the example above the files docs/output/aaa/a.txt and docs/output/bbb/b.txt will be included in the docs package, but their path will be api/aaa/a.txt and api/bbb/b.txt.

You can use multiple from/to combinations in the same package e.g.

→ Call from any number of times. Call to at most once in each context.

This method allows you to dynamically create a text file to be included in the package. e.g.

This extension allows you to dynamically create a build script to be included in the package. There is support for taking the sourceDependencies already defined and converting them to pinned source dependencies or to packedDependencies. This facilitates the creation of source and binary meta-packages for releases.

This method defines the group name for the published artifacts. It will determine part of the URL to the artifacts once they are published, and also determines what goes in the info->organisation attribute in the module descriptor above. The group is often based on the name of the organisation, and helps to disambiguate modules with the same name from different organisations.

Calling this method has the same effect as setting the group property on the Project.

→ Call this method exactly once.

This method defines the version number for the published artifacts. This will determine part of the URL to the artifacts once they are published, and also determines what goes in the info->revision attribute in the module descriptor above.

There are two variant of this method: one taking a single string parameter, and another taking a closure which should return a string value.

Calling this method has the same effect as setting the version property on the Project.

→ Call one of nextVersionNumber, nextVersionNumberAutoIncrementFile and nextVersionNumberEnvironmentVariable

This method has the same effect as nextVersionNumber with a few important differences:

→ Call one of nextVersionNumber, nextVersionNumberAutoIncrementFile and nextVersionNumberEnvironmentVariable

This method has the same effect as nextVersionNumber except that the single string parameter defines the name of an environment variable which contains the version number. This may be useful if, for example, your autobuild already has a notion of version number and is invoking the publish task.

→ Call one of nextVersionNumber, nextVersionNumberAutoIncrementFile and nextVersionNumberEnvironmentVariable

This method has the same type as the repositories method on the Project. However, only publishing to Ivy repositories is supported. This is because Ivy supports publishing multiple artifacts, which is not currently supported by the Maven publishing functionality provided by Gradle.

→ Minimal usage:

If your repository supports anonymous publishing (which is not recommended) then you could omit the credentials section. Note that it is recommended that you use the my-credentials-plugin rather than hard-coding credentials.

This task also fetches transitive dependencies. For example, assume a module’s build script declares a packed dependency on foo:

and the module descriptor for foo declares a transitive dependency on bar as follows:

and the module descriptor for bar declares artifacts as follows:

In this example the top-level module is dependent on the configurations runtime_x64_Debug and runtime_x64_Runtime of foo, which are then dependent on the same named configurations of bar. Although bar defines four artifacts, only bar-runtime_x64_Debug and bar-runtime_x64_Release belong to the configurations of interest, so these will be fetched. Finally, since both of these artifacts have the file-extension "zip" (see the artifact->ext attribute in the module descriptor for bar) the intrepid plugin assumes that they should be unpacked to your unpacked cache, and creates a link from your workspace.