- SEU: German for software development environment (Software Entwicklungs-Umgebung)
- as-code: to be able to configure, build and program the SEU as source code
The SEU-as-code archetype is a quickstart template for new projects. The archetype is continuously evolved to reflect the latest changes and enhancements.
So you decided to build your next SEU for a new project as code. Excellent choice!
-
Download the latest SEU-as-code Archetype distribution from either Bintray or GitHub.
-
Extract the archive to a custom location and rename the template project directory, e.g.
seubase
. -
Customize the
build.gradle
file. First you need to adjust theext
configuration section and set theseuRoot
directory path and theseuName
accordingly. The adjust thedependencies
configuration section and add thesoftware
orhome
package dependencies you require. For a complete list of packages have a look at the SEU-as-code Package repository. -
At this point you should add your SEU project to a version control system of your choice.
-
Finally, open a console and issue the following command to create the SEU:
gradlew bootstrapSeu
.
For a more detailed description on how to further customize the build file please see the documentation.
The default SEU-as-code project comes with a predefined project layout. In essence, it is nothing more than a Gradle project.
The project contains a build.gradle
file and brings it's own Gradle wrapper. Additionally, there are the following directories:
Directory name | Description |
---|---|
gradle/ | This directory initially contains the Gradle wrapper bootstrap files for the SEU. All downloaded software packages and the GRADLE_USER_HOME directory will also be located in this directory. |
native/ | Contains the native DLLs for Scriptom. Mainly required by the hook scripts for basic Windows interaction. |
repo/ | Flat repository used for custom SEU specific software and home dependencies. Mainly used for additional customization. |
scripts/ | Contains addidional build script fragments that can be included in the main build.script . See the section on Script customization for further details. |
All software artifacts and packages you can install in your SEU are managed as ordinary dependencies. Most of these are located in the Bintray Maven repository. For company internal dependencies it is recommended to use your own company wide repository server, such as Nexus.
To determine where a software package will be installed we use Gradle configurations. Currently, the seauc-base
plugin ships
with three inbuilt configurations:
Configuration | Description |
---|---|
seuac | This is a special configuration used for dependencies that need to be put in the Groovy root classloader, such as Scriptom or JDBC drivers. |
software | The main configuration used for all packages that should be installed into the software directory specified by the SEU layout. |
home | The configuration used to install packages into the user home directory of the SEU. |
You use these configurations when you define your software dependencies on your build.gradle
file:
dependencies {
// dependencies for the Groovy root classloader
seuac 'org.codehaus.groovy.modules.scriptom:scriptom:1.6.0'
seuac 'com.h2database:h2:1.4.188'
// mandatory dependencies for basic SEU setup
home 'de.qaware.seu.as.code:seuac-home:2.3.0'
software 'de.qaware.seu.as.code:seuac-environment:2.3.0:jdk8'
// additional dependencies for a Groovy development environment
software 'org.gradle:gradle:2.14'
software 'org.groovy-lang:groovy:2.4.4'
}
You also have to option to create your own customized software packages and distribute these along with your SEU. Usually
you want your own custom project banner when you start a Console windows, and you might also want to change the default
JDK version. You can take the de.qaware.seu.as.code:seuac-environment:2.3.0
JAR as a starting point for your own package.
Once you have customized this package, give it a different name, create a ZIP file and put it into the repo
directory of
your SEU. Have a look at some of the SEU-as-code Examples.
You should refer to the official Gradle documentation for more information on handling dependencies: Dependency Management Basics
Per default, the following plugins are applied to the SEU template build file: base
, seuac-base
, seuac-svn
, seuac-git
.
Please refer to the individual plugin documentations for a complete list of tasks these plugin provide. To get a list of
the available tasks you can also issue the following command:
gradlew tasks
You can add the --all
command line parameter to see the complete list of all tasks, including non-public utility tasks.
In addition to interacting with your SEU-as-code project using the traditional command line interface, Gradle also offers a graphical user interface you can use:
gradlew --gui
Of course, you can also import the SEU project into your favourite IDE as a Gradle project.
You will probably extend the basic build script with additional functionality required by your project. You may need
to add a Git repository, interact with an application server or database. It is good practice to separate your build
script into small and manageable pieces. For example, with the template project you will get a scripts/svn.gradle
files with a possible SVN repository configuration. You only need to include and apply the extra scripts on your main
build.gradle
file:
apply from: 'scripts/svn.gradle'
To customize your SEU even further you can write your own Gradle task definitions to copy files or do whatever you need your SEU to do. The good thing is that you have the full Groovy power at your hands as well as loads of already inbuilt Gradle tasks and plugins to help you with this. A simple hello task might look like this:
task helloSeu << {
println 'Hello SEU-as-code!'
}
You should refer to the official Gradle documentation for more information on this. Here is a list of interesting and helpful links on the topic:
The idea of SEU-as-code is also about using a proper programming languages for your daily SEU automation instead of writing Bash or Windows shell scripts.
You can use the Nashorn JavaScript engine on the command line for your daily shell scripts. Make sure you have a Java8 SDK dependency declared in your SEU build file:
dependencies {
home 'de.qaware.seu.as.code:seuac-home:2.3.0'
software 'de.qaware.seu.as.code:seuac-environment:2.3.0:jdk8'
software 'net.java:openjdk8:8u40'
}
Put your scripts into a directory that is accessible via your $PATH
environment variable. Then you can use the
shebang (#!) mechanism to call the script directly.
#!/usr/bin/env jjs
var seuAsCode = "SEU-as-code (Nashorn)"
print(seuAsCode)
print("${Date()}")
var name = readLine("What is your name? ")
print("Hello, ${name}!")
Another option is to use Groovy for your daily shell scripts. Make sure you have a Groovy SDK dependency declared in your SEU build file:
dependencies {
home 'de.qaware.seu.as.code:seuac-home:2.1.0'
software 'org.groovy-lang:groovy:2.4.4'
}
Put your scripts into a directory that is accessible via your $PATH
environment variable. Then you can use the
shebang (#!) mechanism to call the script directly.
#!/usr/bin/env groovy
def seuAsCode = "SEU-as-code (Groovy Script)"
println seuAsCode
println "${new Date()}"
def name = System.console().readLine 'What is your name? '
println "Hello, ${name}!"
- Nashorn and Shell Scripting
- Nashorn Syntax Extensions
- CSI: Nashorn - Shell Scripting in JavaScript, WAT?
- Running Groovy on the command line
- invoking scripts using full path broken in cygwin
- Groovy scripts no longer work under Cygwin?
Usually, you will need some sort of credentials to access your SVN or Git repositories or to authenticate against a company wide Nexus repository in order to download your software dependencies.
DO NOT PUT THESE INTO THE GRADLE.PROPERTIES FILE.
On way is to specify these on the command line using the -P
project parameter. Make sure not to use a console that has a history though.
Another option is to put credentials into $USER_HOME/.gradle/gradle.properties
.
In your build.gradle
file you can then access the properties via the project:
repositories {
maven {
url project.nexusUrl
credentials {
username = project.hasProperty('nexusUsername') ? project.nexusUsername : System.getProperty('user.name')
password = project.hasProperty('nexusPassword') ? project.nexusPassword : ''
}
}
}
The recommend way of storing your credentials securely is to use the SEU-as-code Credentials Plugin.
Currently this plugin only works under Windows. In your build.gradle
file you can then access the credentials as follows:
repositories {
maven {
url project.nexusUrl
credentials {
username project.credentials.get('nexusUsername')
password project.credentials.get('nexusPassword')
}
}
}
Sometimes your may need to mount and use Windows or SMB shares. The following Gradle tasks might be helpful. they mount or unmount a given share name:
task mountShare(type: Exec, group: 'Network shares', description: 'Mount the network share') {
commandLine 'cmd', '/c', 'net', 'use', 'X:', '\\\\server\\share', "$password", "/USER:$username", '/persistent:no'
standardInput System.in
}
task unmountShare(type: Exec, group: 'Network shares', description: 'Unmount the network share') {
commandLine 'cmd', '/c', 'net', 'use', 'X:', '/DELETE'
}
To build the archetype archive all you have to do is to issue the following command:
gradlew clean distZip
Is there anything missing? Do you have ideas for new features or improvements? You are highly welcome to contribute your improvements to the SEU-as-code projects. All you have to do is to fork this repository, improve the code and issue a pull request. Make sure you also read the Contribution Guide.
M.-Leander Reimer (@lreimer)
This software is provided under the Apache License, Version 2.0 license.
See the LICENSE
file for details.