SEU-as-code Archetype

• 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.

Quickstart

So you decided to build your next SEU for a new project as code. Excellent choice!

1. Download the latest SEU-as-code Archetype distribution from either Bintray or GitHub.

2. Extract the archive to a custom location and rename the template project directory, e.g. seubase.

3. Customize the build.gradle file. First you need to adjust the ext configuration section and set the seuRoot directory path and the seuName accordingly. The adjust the dependencies configuration section and add the software or home package dependencies you require. For a complete list of packages have a look at the SEU-as-code Package repository.

4. At this point you should add your SEU project to a version control system of your choice.

5. 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.

Developing with SEU-as-code

Project Layout

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.

Dependency Customization

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

Build Tasks

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.

Graphical User Interface

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.

Script Customization

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'

Task Customization

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:

• Build Script Basics
• Writing Custom Task Classes
• Gradle Build Language Reference
• Gradle User Guide

Shell Scripting with SEU-as-code

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.

Basic Shell Scripting with Nashorn

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}!")

Basic Shell Scripting with Groovy

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}!"

Further reading

• 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?

Best Practises and Recipies

Do not put credentials into gradle.properties

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')
        }
    }
}

Using Windows network drives

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'
}

Building

To build the archetype archive all you have to do is to issue the following command:

	gradlew clean distZip

Contributing

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.

Maintainer

M.-Leander Reimer (@lreimer)

License

This software is provided under the Apache License, Version 2.0 license.

See the LICENSE file for details.