custom template - maxbalan/gradle-custom-init GitHub Wiki

Introduction

This template will build a a custom template project. As this is not a predefined template by this plugin, you will have to make sure your template is set in predefined way as described in section bellow How-To-Build-My-Own-Template.

How to build my own template

As this is not a predefined plugin template make sure you arrange the template structure as described here.

Your template will have to have 2 directories called script and template
- tempalte - in this directory put all you project files that you want to be created when calling this custom build command. All the files in this directory can have any markdowns which during the build operation will be replaced with the values provided in CustomInit.properties, which is explained a bit farther in this paragraph. The markdowns have to comply with the groovy template-engine.
- script - here you should add a file called CustomInit.properties, in this files you can specify any argument that should be replaced in the files under template directory, replacement will takes place as described in template-engine so make sure all defined markdowns comply with groovy-template-engine otherwise it won't be replaced during the build operation

NOTE: though the groovy template engine is cool, it is unstable when it encounters similar syntax to the one it is expecting e.g.(bash script). For now it is suggested to have your templates simple. A fix might be provided later.

As a summary of the things mentioned above lets have an example in order to better understand how the things works:

Lets assume we have the following structure for the project

      * foo
          * script
              - CustomInit.properties
          * template
              - build.gradle
              - readme.txt

and the files contains the following data:

  build.gradle

      version '${projectVersion}'
      
      <% plugin.each { println "apply plugin: '$it'" } %>
      
      sourceCompatibility = ${compatibility}
      
      repositories {
          jcenter()
      }

  readme.txt

      This is a readme file for project: ${projectName}

based on the 2 files above then the CustomInit.properties will contain the following information

      projectVersion=1.0.0
      plugin=[idea,java,groovy]
      compatibility=1.8
      projectName=test_mark_down

so based on the information above after the build we will have the following files:

  build.gradle

      version '1.0.0'
      
      apply plugin: `idea`
      apply plugin: `java`
      apply plugin: `groovy`
      
      sourceCompatibility = 1.8
      
      repositories {
          jcenter()
      }

  readme.txt

      This is a readme file for project: test_mark_down

as you can see all the information above was replaced with the value described in the CustomInit.properies file. Though it's worth mentioning that in case of an array value, like in case of plugin=[idea,java,groovy] all the values should be separated by a comma inside square brackets.

How to serve my template

Now that we know how to build our own template in terms of directory structure and markdowns we can discuss about how the template is read by the plugin, for now only the following ways are possible to serve you custom template to the plugin:

GitHub

Serve template from GitHub

Serving your template from github is quit simple, all you have to do is to provide the github repository and make sure that the user you running the plugin have all the rights to access that repo in case it is private one. Though there is a demo on how to do it and the topic is covered in more details on custom-template-demo page, here is how to set it

    gradle custom-init --project-type custom --custom-template https://github.com/maxbalan/custom-template-demo.git

Though it is not advantageous to create a repository for each template you might want to build, its most probably you are gonna nest them all in a single repository. It is still possible to specify which one you want to build e.g.:

Lets assume you have a nested template repository as follow

    * foo
        * init
            * java
                * template
                * script
            * groovy
                * template
                * script

having the above structure in your repository lets assume you want to deploy java project, then the command is as follow

    gradle custom-init --project-type custom \
                       --custom-template https://github.com/maxbalan/custom-template-demo.git \
                       --custom-template-target "foo/init/java"

as a result of the command above a java project will be created in the directory where the command was ran.

How to build

In order to build the custom project make sure you've read and are using of the methods described in the How-To-Use page. It does not matter which approach you choose bash script or plugin directly you will have to specify the same parameters:

Required arguments:
- --project-type - set it to custom
```
    --project-type custom
```
Optional arguments:
- --project-target - set target directory where the project will be created. Default will be set or the directory where the script is being called from e.g.:
```
    --project-target "/foo/boo/project_dir"
```
- **--custom-template - set this method as described in any of the possible methods listed under How-To-Serve-My-Template
```
      --custom-tempalte "you_template_location"
```
- custom-template-target - set this argument in case when you provided a nested directory structure for --custom-template argument. For more details see build method used under How-To-Serve-My-Template
- --group - set your own group parameter value. Default --project-target directory name will be used
```
     --group "foo.project"
```

A minimal configuration to build it will look like this:

for bash script:

      sh ExecuteCustomInit.sh --project-type custom --project-target "foo/my_project" --custom-template "your_template"

for direct plugin call

    gradle --project-type custom --project-target "foo/my_project" --custom-template "your_template"