Home Docs Examples Source code Issues

Documentation

Table of contents

  1. Basic setup
  2. Configuration
    1. Configs
    2. Configuration files templates
    3. Environment
    4. Output directory
  3. Tasks
    1. processConfigs
    2. cleanConfigs

Basic setup

This plugin is published to Gradle plugin portal. To apply it to project add the following to your build.gradle

plugins {
  id 'info.gconfig' version '1.0.1'
}

Configuration

After plugin is applied a new DSL element gconfig will be created with 4 configurable options inside:

Name Type Default Overridable by project properties? Description
configs FileCollection files('configs') Yes List of properties files
templates File file('templates') No Directory with configuration templates
environment string - Yes Name of the environment that will be used for picking actual settings
outputDir File file('configs') inside project.buildDir No Directory where ready-to-use configs will be placed
  1. configs
    • Type: FileCollection
    • Description: List of properties files
    • Default: files('configs')
    • Overridable by project properties?: Yes
  2. templates
    • Type: File
    • Description: Directory with configuration templates
    • Default: file('templates')
    • Overridable by project properties?: No
  3. environment
    • Type: string
    • Description: Name of the environment that will be used for picking actual settings
    • Default: -
    • Overridable by project properties?: Yes
  4. outputDir
    • Type: File
    • Description: Directory where ready-to-use configs will be placed
    • Default: file('configs') inside project.buildDir
    • Overridable by project properties?: No

Configs

List of properties files with settings. Default value is single file named as configs. Usage:

plugins {
  id 'info.gconfig' version '1.0.1'
}

gconfig {
  configs = files('dbConfig', 'appConfig')
}
Warning

You can override settings found in config files by passing Gradle project properties with gc.prop. prefix. Read the details below

Usually, it is done in two ways:

  1. Via gradle.properties file located in project directory or .gradle directory inside user's home directory. See example of gradle.properties:

    gc.prop.DB_HOST=localhost
    gc.prop.DB_USER=admin
  2. Via command line properties. See example of command line properties usage:

    gradle processConfigs -Pgc.prop.DB_HOST=localhost

Configuration files templates

Directory with configuration templates. Default value is single directory named as templates. Usage:

plugins {
  id 'info.gconfig' version '1.0.1'
}

gconfig {
  configTemplates = file('templatesDirectory')
}
Warning

During execution of processConfigs task plugin will open each file in templates directory and look for tokens like %{TOKEN} where TOKEN - name of settings which were found in config files

Directories are acceptable inside templates directory. Plugin will go recursively to pick everything

Environment

If defined, plugin will look for files named the same way as config files but with suffix .%environment_name% at the end and load settings from them. For example, if your build.gradle looks like this:

plugins {
  id 'info.gconfig' version '1.0.1'
}

gconfig {
  configs = files('dbconfig')
  environment = 'local'
}

Then plugin, beside dbconfig, will look for dbconfig.local and load settings from it. Settings, which will be found in dbconfig.local will take precedence over settings from dbconfig.

Warning

environment can be overridden via project properties with gc.env prefix. Read the details below

Usually, it is done in two ways:

  1. Via gradle.properties file located in project directory or user's home directory. See example of gradle.properties:

    gc.env=staging
  2. Via command line properties. See example of command line properties usage:

    gradle processConfigs -Pgc.env=staging

Output directory

Directory where ready-to-use configs will be stored. Default value - single directory named as configs inside project.buildDir. Usage:

plugins {
  id 'info.gconfig' version '1.0.1'
}

gconfig {
  outputDir = file('someCustomOutputDir')
}

Tasks

Plugin creates 2 tasks: processConfigs and cleanConfigs. You can run them with info logging level for additional details:

gradle processConfigs -i

processConfigs

Transforms config templates to ready-to-use templates. Algorithm is very simple:

  1. Collect all settings from configs and environment.
  2. Go through all files inside templates.
  3. Check each file for %{TOKEN} where TOKEN is the name of setting.
  4. Replace all tokens in file with actual settings and put results in outputDir.

cleanConfigs

Removes outputDir with all content inside.