gradle-build-properties-plugin
External properties files support for your build scripts.
Description
Sometimes it's necessary to retrieve some information from a properties file that is not checked in as part of your repo for security reasons (keys, credentials, passwords, etc). Such properties need to end up in your application BuildConfig or in some resource file.
This plugin aims to provide a simple way to:
- define handles to a properties file in your build script (à la
signingConfig) - generate fields in your
BuildConfigwith values from a properties file - generate resources with values from a properties file
- load signing configurations from a properties file
Adding to your project
The plugin is deployed to Bintray's JCenter. Ensure it's correctly defined as a dependency for your build script:
buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'com.novoda:gradle-build-properties-plugin:0.3'
}
}
Then apply the plugin in your build script via:
apply plugin: 'com.novoda.build-properties'Simple usage
Add a buildProperties configuration to your build script listing all the properties files you intend to reference later on:
buildProperties {
secrets {
file project.file('secrets.properties')
}
}
where secrets.properties is a properties file that can now be referenced in the build script as buildProperties.secrets. Entries in such file can be accessed via the getAt operator:
Entry entry = buildProperties.secrets['aProperty']The value of an Entry can be retrieved via one of its typed accessors:
boolean enabled = buildProperties.secrets['x'].booleanint count = buildProperties.secrets['x'].intdouble rate = buildProperties.secrets['x'].doubleString label = buildProperties.secrets['x'].string
It is important to note that values are lazy loaded too (via the internal closure provided in Entry). Trying to access the value of a specific property could generate an exception if the key is missing in the provided properties file, eg:
FAILURE: Build failed with an exception. * What went wrong: A problem occurred configuring project ':app'. > No value defined for property 'notThere' in 'secrets' properties (/Users/toto/novoda/spikes/BuildPropertiesPlugin/sample/properties/secrets.properties) Features
Fallback support
If a property cannot be found an exception is thrown, it's possible to provide a fallback value for a given Entry via the or() operator, defined as:
| Example | |
|---|---|
another Entry | buildProperties.secrets['notThere'].or(buildProperties.secrets['fallback']) |
a Closure | buildProperties.secrets['notThere'].or({
Math.random()
}
) |
| a value | buildProperties.secrets['notThere'].or('fallback') |
If the whole fallback chain evaluation fails then a CompositeException is thrown listing all the causes in the chain, eg:
A problem occurred while evaluating entry: - exception message 1 - exception message 2 - exception message 3 Properties inheritance
It might be useful to have properties files that can recursively include other properties files (specified via an include property). Inherited properties can be overridden by the including set, just redefine the property in the file and its value will be used instead of the one from the included set.
Other built-in Entry sets
It's possible to access a system enviroment variable as Entry via a predefined set of entries, ie:
buildProperties.env['FOO']Such entries are particularly handy when used alongside the Entry.or() operator in order to provide fallback values.
More on loading properties
If the specified file is not found an exception is thrown at build time as soon as one of its properties is evaluated. You can specify a custom error message to provide the user with more information, eg:
buildProperties {
secrets {
file rootProject.file('secrets.properties'), '''
This file should contain the following properties:
- fabricApiKey: API key for Fabric
- googleMapsApiKey: API key for Google Maps
'''
}
}
Android-specific features
When applying the gradle-build-properties-plugin to an Android project you get access to an additional set of powerful features.
1. Store a property value into your BuildConfig
In any product flavor configuration (or defaultConfig) you can use buildConfigProperty as follows:
defaultConfig {
...
buildConfigProperty 'API_KEY', buildProperties.secrets['apiKey']
...
}
2. Store a property value as generated string resource
In any product flavor configuration (or defaultConfig) you can use resValueProperty as follows:
defaultConfig {
...
resValueProperty 'api_key', buildProperties.secrets['apiKey']
...
}
3. Load signing configuration from properties
Instead of inlining your passwords and other details in your build script you can fill the signing configuration using a properties file.
signingConfigs {
release {
signingConfigProperties buildProperties.releaseSigning
}
}
The plugin will automatically retrieve all the needed fields from the properties file. Note: the path of the keystore file is considered relative to the path of the specified properties file.
4. Typed buildConfigField / resValue
The plugin enhances the buildConfigField and resValue facilities to enforce types. To generate a string field in your BuildConfig you used to write:
buildConfigField 'String', 'LOL', '\"sometimes the picture take\"'but now you can instead write:
buildConfigString 'LOL', 'sometimes the picture take'The full list of new typed facilities is as follows:
| Example | |
|---|---|
buildConfigBoolean | buildConfigBoolean 'TEST_BOOLEAN', false |
buildConfigInt | buildConfigInt 'TEST_INT', 42 |
buildConfigLong | buildConfigLong 'TEST_LONG', System.currentTimeMillis() |
buildConfigDouble | buildConfigDouble 'TEST_DOUBLE', Math.PI |
buildConfigString | buildConfigString 'TEST_STRING', 'whateva' |
resValueInt | resValueInt 'debug_test_int', 100 |
resValueBoolean | resValueBoolean 'debug_test_bool', true |
resValueString | resValueString 'debug_test_string', 'dunno bro...' |