From 6e2ee2ffc6223cfb779b74ddc806e6a012f5667d Mon Sep 17 00:00:00 2001 From: Antonio Bertucci Date: Mon, 14 Nov 2016 11:38:17 +0100 Subject: [PATCH] Update README to reflect current feature set --- README.md | 168 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 88 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index 92df596..4ed1ba9 100644 --- a/README.md +++ b/README.md @@ -32,91 +32,48 @@ buildscript { } } ``` -Then apply the plugin in your buildscript **after the android plugin** via: +Then apply the plugin in your build script via: ```gradle apply plugin: 'com.novoda.build-properties' ``` ## Simple usage -Add a `buildProperties` configuration to your android buildscript listing -all the properties files you intend to reference in your `android` configuration: +Add a `buildProperties` configuration to your build script listing +all the properties files you intend to reference later on: ```gradle buildProperties { secrets { file project.file('secrets.properties') } } - -android { - ... -} ``` where `secrets.properties` is a properties file that can now be referenced -in the buildscript as `buildProperties.secrets`. - -## Features - -#### 1. Store a property value into your `BuildConfig` -In any product flavor configuration (or `defaultConfig`) you can use -`buildConfigProperty` as follows: +in the build script as `buildProperties.secrets`. Entries in such file can be +accessed via the `getAt` operator: ```gradle - defaultConfig { - ... - buildConfigProperty 'API_KEY', buildProperties.secrets['apiKey'] - ... - } +Entry entry = buildProperties.secrets['aProperty'] ``` -#### 2. Store a property value as generated string resource -In any product flavor configuration (or `defaultConfig`) you can use -`resValueProperty` as follows: +The value of an `Entry`` can be retrieved via one of its typed accessors: -```gradle - defaultConfig { - ... - resValueProperty 'api_key', buildProperties.secrets['apiKey'] - ... - } -``` +- `boolean enabled = buildProperties.secrets['x'].boolean` +- `int count = buildProperties.secrets['x'].int` +- `double rate = buildProperties.secrets['x'].double` +- `String label = buildProperties.secrets['x'].string` -#### 3. Load signing configuration from properties -Instead of inline your passwords and other details in your build script -you can fill the signing configuration using a properties file. -```gradle -signingConfigs { - release { - signingConfigProperties buildProperties.releaseSigning - } -} +Is important to note that values are lazily accessed 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: ``` -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. +FAILURE: Build failed with an exception. -## Bonus +* 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) -#### 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: -```gradle -buildConfigField 'String', 'LOL', '\"sometimes the picture take\"' -``` -but now you can instead write: -```gradle -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...'`| +## Features #### Fallback support If a property cannot be found an exception is thrown. It's possible to provide a fallback @@ -128,7 +85,7 @@ value for a given `Entry` via the `or()` operator, defined as: |a `Closure` | `buildProperties.secrets['notThere'].or({ Math.random() })` | |a value | `buildProperties.secrets['notThere'].or('fallback')` | -If the whole fallback chain evaluation fails a `CompositeException` is thrown listing all +If the whole fallback chain evaluation fails then a `CompositeException` is thrown listing all the causes in the chain, eg: ``` @@ -161,30 +118,81 @@ 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. +You can specify a custom error message to provide the user with more information, eg: +```gradle +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 + ''' + } +} +``` + -Given a `BuildProperties` instance one of its entries can be retrieved using the `getAt` operator: +## Android-specific features +When applying the `gradle-build-properties-plugin` to an Android project you get access to and + additional set of poerful features. + +#### 1. Store a property value into your `BuildConfig` +In any product flavor configuration (or `defaultConfig`) you can use +`buildConfigProperty` as follows: ```gradle -Entry entry = buildProperties.secrets['aProperty'] + defaultConfig { + ... + buildConfigProperty 'API_KEY', buildProperties.secrets['apiKey'] + ... + } ``` -The value of an entry can be retrieved via one of the following typed accessors: - -- `entry.getBoolean()`, or `entry.boolean` -- `entry.getInt()`, or `entry.int` -- `entry.getDouble()`, or `entry.double` -- `entry.getString()`, or `entry.string` +#### 2. Store a property value as generated string resource +In any product flavor configuration (or `defaultConfig`) you can use +`resValueProperty` as follows: -If you want to access the raw value (`Object`) you can also use `entry.getValue()`/`entry.value`. -Is important to note that values are lazily accessed 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: +```gradle + defaultConfig { + ... + resValueProperty 'api_key', buildProperties.secrets['apiKey'] + ... + } ``` -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) +#### 3. Load signing configuration from properties +Instead of inline your passwords and other details in your build script +you can fill the signing configuration using a properties file. +```gradle +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: +```gradle +buildConfigField 'String', 'LOL', '\"sometimes the picture take\"' ``` +but now you can instead write: +```gradle +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...'`|