README.md 4.74 KB
Newer Older
Christian Meyer's avatar
Christian Meyer committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
Gradle build scripts developed in zmt-bremen's department of Theoretical Ecology & Modelling. For more information about Gradle visit https://gradle.org/.

# General
## IDE Support    
To generate .project and .classpath files for developing in the Eclipse IDE enter:
```shell
./gradlew eclipse
```
This will also generate a launch configuration for simulations to run them via GUI.

### Eclipse Support for Gradle
Gradle is supported by Eclipse via Buildship:
https://github.com/eclipse/buildship/

## Versioning
Versioning is done by tagging via git. The current version name is generated from the last git tag. If the current version is not tagged, a short version of the commit hash is added.

## Credentials
You can store your credentials for the dochost server in encrypted form:
```shell
./gradlew addCredentials --key dochostUser --value <username>
./gradlew addCredentials --key dochostPw --value <password>
```
Credentials are stored in `~/.gradle/gradle.encrypted.properties`. This will save you from entering them every time you want to publish or deploy.

For more information about the credentials plugin visit https://github.com/etiennestuder/gradle-credentials-plugin.

28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
## Servers
There are two servers available:

* Public: https://dochost.leibniz-zmt.de/
* Internal: http://dochost.intra.zmt/ (only accessible in ZMT intranet)

Both of them have a Maven Repository within the `maven2/` subdirectory. Libraries are stored there and fetched by Gradle when they are required. See the [publishing entry](#publishing) for more info. The servers are also used for [javadoc](#javadoc) and [distribution deployment](#deployment).

## Properties
There are several custom properties used to control the build process. For more information on how to set properties in gradle, consult https://docs.gradle.org/current/dsl/org.gradle.api.Project.html and https://docs.gradle.org/current/userguide/build_environment.html. Only the most important ones are listed here.

* `simClassName`: The name of the simulation class. Defaults to project name with the first letter upper case. Used in run scripts. The package can be omitted if `sim.engine`.
* `launcherDependency`: The launcher dependency compatible with the project. Defaults to `de.zmt:zmt-launcher:latest.release`.
* `de.zmt.gradle.dochost.deployPublic`: If set `true` [javadoc](#javadoc) and [distributions](#deployment) are put to the public server. Otherwise, the internal one is used. Defaults to `false`.
* `de.zmt.gradle.dochost.publishPublic`: If set `true`, libraries are [published](#publishing) to the public server. Otherwise the internal one is used. Defaults to `true`.
Christian Meyer's avatar
Christian Meyer committed
43 44 45 46 47 48

## Javadoc
Javadoc files of the current project can be build and stored on dochost's `javadoc/` subdirectory:
```
./gradlew deployJavadoc
```
49
Only the recent version is stored and outdated files will be overwritten. The [property](#properties) `de.zmt.gradle.dochost.deployPublic` is used to select the server.
Christian Meyer's avatar
Christian Meyer committed
50 51 52 53 54 55 56

# Simulations
To make your simulation build with the zmt-build add the following to your `build.gradle` file:
```groovy
buildscript {
    repositories {
        maven {
57
            url 'https://dochost.leibniz-zmt.de/maven2/'
Christian Meyer's avatar
Christian Meyer committed
58 59 60 61
        }
    }
    
    dependencies {
62
        classpath 'de.zmt:zmt-build:latest.release'
Christian Meyer's avatar
Christian Meyer committed
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
    }
}
apply plugin: 'de.zmt.simulation'
```

## Distribution
You can build a distribution by running the following in the project root directory:
```shell
./gradlew installDist
```

Build files are then stored in the build subdirectory. The file name of the distribution is generated from the project name and the current version. A CHANGES file will be generated containing all git tags with their messages.

## Deployment
Distributions can be uploaded to the `dist/` subdirectory on 'dochost' server:
```shell
./gradlew deployZip
```
81
The [property](#properties) `de.zmt.gradle.dochost.deployPublic` is used to select the server.
Christian Meyer's avatar
Christian Meyer committed
82

83 84 85 86 87 88 89 90 91 92 93 94 95 96
## Running
The launcher is accessible via the 'run' task. Arguments can be supplied with the 'args' property.
```shell
./gradlew run -Pargs='<args>'
```
Use '--help' as argument to display available options for the launcher.
```shell
./gradlew run -Pargs='--help'
```
To run your simulation in GUI mode, type
```shell
./gradlew run -Pargs='<simulation name> gui'
```

Christian Meyer's avatar
Christian Meyer committed
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
# Libraries
To make your simulation build with the zmt-build add the following to your `build.gradle` file:
```groovy
buildscript {
    repositories {
        maven {
            url "http://dochost.intra.zmt/maven2/"
        }
    }
    
    dependencies {
        classpath 'de.zmt:zmt-build:1+'
    }
}
apply plugin: 'de.zmt.library'
```
## Publishing
Libraries can be published to dochost:
```
./gradlew publish
```
118
After that, they will be accessible by Gradle when required. The [property](#properties) `de.zmt.gradle.dochost.publishPublic` is used to select the server.