Skip to content

Commit 9ab6175

Browse files
committed
Add more information on setting project properties to snapshot builds page
1 parent a4e30c7 commit 9ab6175

1 file changed

Lines changed: 31 additions & 1 deletion

File tree

contributors/composite-builds.md

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,17 +25,47 @@ Importantly, no automatic checkout of branches is done.
2525
This means that if the branches don't match, the build script will complain and fail.
2626
You can adjust this behaviour using the **useCurrentBranch** parameter as explained below.
2727

28-
Keep in mind that this does not include any version checking!
28+
Keep in mind that this does not include any version checking, i.e. the composite build will happily include the version of the dependency that is currently checked out, whether it matches the dependency version or not.
2929
This means that you have to ensure that the version of the dependency being included by the composite build is the correct one.
3030

3131
## Customization
3232
You can customize behaviour of the build script using certain properties.
3333

3434
These can either be set in the `gradle.properties` file in the top level folder of the project (on the same level as `build.gradle`), or be given as a parameter using the `-P` option for Gradle.
35+
For examples of how this works see [the examples section](#examples).
3536

3637
- **useCurrentBranch**: If defined (any value) the branch selection checking will be skipped.
3738
That means the composite build will be enabled no matter the dependency branches that are currently checked out.
3839
This can be useful for when you need a version that is not on `main` but you also do not want to create a new branch.
3940
- **checkoutIfCloned**: If defined (any value), will automatically check out the corresponding
4041
dependency branch (branch with same name) given that the dependency was freshly cloned.
4142
Used by the Travis CI to automatically switch to the right dependency branch for the build.
43+
44+
These properties only affect the project they are set for, not any of its composite build dependencies.
45+
For example, the Predenc library depends on the Craco library which depends on the Math library.
46+
If you enable `useCurrentBranch` only for Predenc, but not for Craco, the following will happen:
47+
Predenc will happily include whatever Craco branch is currently checked out.
48+
Craco, however, will then only include Math if the checked out branch names of Craco and Math match.
49+
50+
More information on Gradle properties can be found in the [official documentation](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties).
51+
52+
### Examples
53+
54+
#### Customizing Settings Via `gradle.properties`
55+
The `gradle.properties` file must be in the same directory as the project's `build.gradle` file.
56+
Enabling `useCurrentBranch` then looks as follows:
57+
```groovy
58+
useCurrentBranch=""
59+
```
60+
We assign an empty string as any value suffices.
61+
62+
#### Customizing Settings Via Gradle's `-P` Parameter
63+
When executing the Gradle wrapper, you can pass it properties via the `-P` parameter.
64+
The property will then affect the project whose wrapper you executed.
65+
The syntax is as follows:
66+
```bash
67+
./gradlew build -PuseCurrentBranch
68+
```
69+
After the `-P` the name of the property follows without spaces.
70+
In this case `useCurrentBranch` does not need a value, but to set a value you would add an equals sign `=` followed by the property's desired value.
71+
For each property a separate `-P` must be used.

0 commit comments

Comments
 (0)