buildscript {
repositories { jcenter() } // <1>
dependencies { classpath 'io.werval:io.werval.gradle:0.7.5' } // <2>
}
apply plugin: 'io.werval.application' // <3>In this section you’ll find guides for frequent and practical development use cases from IDE support to deployment.
./build.gradle
buildscript {
repositories { jcenter() } // <1>
dependencies { classpath 'io.werval:io.werval.gradle:0.7.5' } // <2>
}
apply plugin: 'io.werval.application' // <3>Add JCenter repository
Add Werval Gradle Plugin to build classpath
Apply the Werval Gradle plugin
Use Werval dependencies of the same version as the Werval Gradle plugin:
dependencies {
compile werval.api
compile werval.module('json')
runtime werval.nettyServer
testCompile werval.test
}gradle distZip
|
Tip
|
If you need RPM or DEB packaging, use the gradle-ospackage-plugin. |
The Werval Gradle plugin:
declare a devshell task that depend on the classes task.
declare a devshell_rebuild task that depend on the classes task too.
When running the devshell task it will run classes and other dependents tasks and then the Werval DevShell, embedded. The application is now running in development mode.
Once a source code change is detected, the first request received by the application summon a gradle daemon to run the devshell_rebuild task on the application project.
You add dependent tasks to the devshell and devshell_rebuild that way;
devshell.dependsOn gulp_bower, gulp_dev
devshell_rebuild.dependsOn gulp_devThis example is from an application that use bower and gulp for client javascript build, thanks to the gradle-gulp-plugin.
Configuring theses tasks in your build allow you to fine tune the work needed to get your app in dev mode and what should be done when the source has changed.
The devshell task has an extraWatch property that allow one to add files or directories to watch for changes in dev mode:
devshell.extraWatch += "path/to/dir"
devshell.extraWatch += [ "path/to/elsewhere", "and/anywhere" ]Thanks to Gradle’s incredible incremental build behaviour, handling complex build scenarios is both confy and productive.
You can enrich the application classpath in development mode by adding dependencies to the devshell configuration:
dependencies {
devshell 'group:id:version'
}You can also enrich the application classpath in development mode by adding files to the dev source-set, that is in src/dev/java and src/dev/resources.
Typical usage is to use development specific configuration. Putting it in the dev source-set prevent it to be in the application distribution.
This is achieved in two steps,
add a developement.conf file in src/dev/resources with at least include "application.conf" in it ;
use development.conf as application configuration in development mode:
devshell.configResource 'development.conf'You can now add content to development.conf to define configuration properties that will be used in development mode only.
devshell {
// Only one of theses three can be set
configResource = "application-dev.conf"
configFile = file( "path/to/file.conf" )
configUrl = new URL( "http://url.to/file.conf" )
}
start {
// Only one of theses three can be set
configResource = "application-dev.conf"
configFile = file( "path/to/file.conf" )
configUrl = new URL( "http://url.to/file.conf" )
}
// Sample custom start task
task customStart( type: io.werval.gradle.StartTask )
{
configResource = "application-custom.conf"
}The werval:devshell goal depends on the compile phase by default.
Rebuilds trigger the compile phase by default too.
In other words, the project is compiled before running the development mode and at each rebuild triggered by a source code change.
The werval:devshell goal has an extraWatch property that allow one to add files or directories to watch for changes in dev mode:
./pom.xml
<build>
<plugins>
<plugin>
<groupId>io.werval</groupId>
<artifactId>io.werval.maven</artifactId>
<version>{werval_version}</version>
<configuration>
<extraWatch>
<param>path/to/dir</param>
<param>another/path/to/file.ext</param>
</extraWatch>
</configuration>
</plugin>
</plugins>
</build>./pom.xml
<build>
<plugins>
<plugin>
<groupId>io.werval</groupId>
<artifactId>io.werval.maven</artifactId>
<version>{werval_version}</version>
<configuration>
<!-- Only one of theses three can be set -->
<configResource>application-dev.conf</configResource>
<configFile>path/to/file.conf</configFile>
<configUrl>http://url.to/file.conf</configUrl>
</configuration>
</plugin>
</plugins>
</build>Using Maven plugin <executions/> you can override config location for both the werval:devshell and werval:start goals.
./pom.xml
<build>
<plugins>
<plugin>
<groupId>io.werval</groupId>
<artifactId>io.werval.maven</artifactId>
<version>{werval_version}</version>
<configuration>
<extraClassPath>
<param>custom/dir</param>
<param>custom-file.jar</param>
</extraClassPath>
</configuration>
</plugin>
</plugins>
</build>Using Maven plugin <executions/> you can enrich the application classpath for both the werval:devshell and werval:start goals.
|
Tip
|
If you need RPM or DEB packaging, use the rpm-maven-plugin and jdeb-maven-plugin |
Werval is build system agnostic. As long as your IDE support the one you choose you’re good to go. Depending on the language you write your applications you’ll want to choose the IDE that best suit your needs. Two types of files needs special attention here: the routes and the configuration. No IDE will give you syntax highlighting nor autocompletion in theses.
Below are some quick pointers to get started with the three main Java IDEs.
Netbeans comes with Maven support out of the box. For Gradle support you need to install the appropriate Netbeans plugin. The latest release can be downloaded from the Netbeans Plugins Portal and is also available via the Update Center (Tools/Plugins: Look for "Gradle Support").
|
Tip
|
Dependencies Sources and Javadocs
The easiest way to get dependencies sources and javadocs in your Netbeans IDE is to apply the IDEA plugin to your project:
build.gradle
and run This will download all project’s dependencies source and javadoc and thus make them available in Netbeans. |
IDEA comes with both Maven and Gradle support out of the box. You can also use the IDEA plugin for Gradle to generate the IDEA metadata.
Eclipse comes with no Maven nor Gradle support out of the box. For Maven support you need to install the appropriate Eclipse plugin. For Gradle support you need to install the appropriate Eclipse plugin. You can also use the Eclipse plugin for Gradle to generate the Eclipse metadata.
Module build is easy when using Gradle as a dedicated plugin is available.
apply plugin: 'io.werval.module'You can also start from the werval-skel-module skeleton that comes with a complete sample Plugin including unit tests.
Declare Plugins in your build:
moduleDescriptor.plugin 'name', impl: 'fqcn.of.YourPlugin'You can declare several of them.
Documentation must be put in src/doc in Asciidoc format. At least the index.adoc file must be present. You can add other files and resources (images…).
When your module is present in an application classpath, its documentation will be automatically listed at /@doc/modules/index.html and integrated at /@doc/modules/your-module-id in development mode.
Deploy a Werval Application on Heroku is rather simple: launching the main class with a correct classpath is enough. Application classpath building is a good job for a build system with dependency management like Gradle or Maven.
Deploying on Heroku means building an executable version of the application and writing a Procfile file relaying the Heroku environment variables to our application. If you are not familiar with Heroku, see the Java and Procfile documentation.
Werval Applications configuration properties can easily be set from the command line, you can use this mechanism in your Procfile. However, if you feel the need, nothing stops you to gather System Properties directly from your Application’s code.
Now that we saw the basics we’ll walk through two practical cases. The first one using Gradle, the second one using Maven. In theses two samples, we pass the HTTP server listening port to the application. Heroku set the port to use in the POST environment variable.
Given that your application is named app, put the following in a file named Procfile at the root of your project:
web: ./build/install/app/bin/app.sh -Dwerval.http.address=0.0.0.0 -Dwerval.http.port=$PORTHeroku Gradle support will invoke the stage task provided by the io.werval.application plugin. This task deploy the application distribution filetree in build/install/app. The Procfile will then run your application.
You can use the stage task to test locally:
user@host $ gradle stage
# [Removed output]
BUILD SUCCESSFUL
user@host $ ./build/install/app/bin/app|
Important
|
This guide is intended for developers who want to build applications against the development version of Werval or want to contribute code or documentation. |
You need to install:
The Java 8 JDK
GraphViz, optional
Before going any further, ensure that the following commands show proper versions:
java -versionShould output something like:
java version "1.8.0" (1)
Java(TM) SE Runtime Environment (build 1.8.0-bXXX)
Java HotSpot(TM) 64-Bit Server VM (build 25.0-bXX, mixed mode)This is Java 8
gradle --versionShould output something like:
------------------------------------------------------------
Gradle 2.1 (1)
------------------------------------------------------------
Build time: 2014-09-08 10:40:39 UTC
Build number: none
Revision: e6cf70745ac11fa943e19294d19a2c527a669a53
Groovy: 2.3.6
Ant: Apache Ant(TM) version 1.9.3 compiled on December 23 2013
JVM: 1.8.0_11 (Oracle Corporation 25.11-b03) (2)This is Gradle 2.1
Using Java 8
mvn --versionShould output something like:
Apache Maven 3.2.1 (1)
Maven home: /path/to/your/maven/installation
Java version: 1.8.0, vendor: Oracle Corporation (2)
Java home: /path/to/your/java/installation (3)This is Maven 3.2.x
Using Java 8
From the right JAVA_HOME
We recommend to create a local directory to put all Werval clones.
mkdir -p ~/src/werval-related (1)
cd ~/src/werval-related (2)Create a werval-related directory
Move into the werval-related directory
git clone git@github.com:werval/werval.gitgit clone git@github.com:werval/werval-website.gitgit clone git@github.com:werval/werval-sample-beerdb.gitGradle and Maven both need some global local configuration before going any further.
The core Werval build create a repository/ sub-directory where artifacts are deployed. We need to set this directory globally so that you can build other projects (samples, skeletons, etc..) with the whole codebase on the develop branch, or any other branch, tag etc…
For Gradle,
// Werval Local Repository
wervalLocalRepository=file:///home/you/src/werval-related/werval/repositoryFor Maven,
<settings>
<profiles>
<profile>
<id>wervalDevelopment</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<repositories>
<repository>
<id>wervalLocalRepository</id>
<url>file:///home/you/src/werval-related/werval/repository</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>wervalLocalRepository</id>
<url>file:///home/you/src/werval-related/werval/repository</url>
</pluginRepository>
</pluginRepositories>
</profile>
</profiles>
</settings>We’re now done with the setup, time to build!
|
Tip
|
If you need to use the wervalLocalRepository in another gradle project, simply throw thie following line in its build.gradle: |
The Werval SDK lies in the werval repository, previously cloned into ~/src/werval/related/werval.
This very git repository contains several independent projects.
io.werval Werval Core
io.werval.modules Modules
io.werval.gradle Gradle Plugin
io.werval.maven Maven Plugin
io.werval.dist Werval DistributionsFor convenience, four shell scripts are provided:
clean.sh Clean the repository of built artifacts
build.sh Quick build without tests
check.sh Full build with all tests
dist.sh Create distributions archives, without testsPlease note that if you want to get UML diagrams generated in Javadocs you’ll need to have GraphViz installed. The build will pass without though. But with less fun.
When working on the Werval source code, it is recommended to run all tests first, giving you confidence that the whole thing work on your computer. You can do that easily by running the check.sh build script.
Werval do not have much dependencies but the build system and the tests do. As a consequence, a vast amount of code is downloaded the first time you run a build. Theses downloads are cached in ~/.gradle/caches.
Werval artifacts produced by the build are installed in the local Werval repository (~/src/werval-related/werval/repository) for use by other projects.
By default version number 0 is used, you can override this with -Dversion=WHATEVER.
If you encounter any problem, please fill an issue with the output of the build process.
The whole Werval documentation is built using Gradle alongside the codebase.
The complete documentation toolchain involve more than Gradle itself, it is use as an orchestrator of Asciidoctor for Asciidoc support, Freemarker for templating and finally, JBake to bake the static websites
Documentation of a given Werval version includes core documentation plus dynamic documentation for officially supported modules.
The documentation build is organized to allow documentation:
to be hosted in development mode, including the documentation of modules found in your application classpath ;
to be packaged as downloadable archives including documentation for all officialy supported modules ;
and to be included in the Werval website, versionned, for all Werval releases.
Both core and dynamic documentation are written using Asciidoc and can contain other static assets such as images and the like.
Core documentation
Core documentation includes a getting started guide, the other guides, the manual and the API javadoc. Its sources are in the io.werval.doc project.
The io.werval.doc build generates the core documentation using JBake. The resulting files are included in the JAR at io/werval/doc/html.
|
Note
|
io.werval.doc contains the JBake project that is used later to build the Werval Documentation |
All documentation source is assembled in a ZIP artifact published with the doc classifier:
io.werval:io.werval.doc:{werval_version}:doc@zipIt contains the complete JBake project.
Dynamic documentation
Each Werval module can have its own documentation included thanks to dynamic documentation. This is not called modules documentation on purpose, dynamic documentation way better convey what is going on under the hood. Moreover, this mechanism is applied to officially supported modules only.
|
Tip
|
Community modules are documented as explained in the module writing guide. |
Dynamic documentations are registered by adding the following lines to a reference.conf files in the module’s classpath root:
werval.devshell.dyndoc.your-module-id {
name = "Your shiny module's name"
base_path = io/werval/modules/your-module-id/doc
}Static documentation is then be generated at base_path in the module’s classpath.
All documentation source is assembled in a ZIP artifact published with the doc classifier.
Example for the SMTP Module:
io.werval:io.werval.modules.smtp:{werval_version}:doc@zipThe build system of io.werval.modules do all that automatically as soon as it can find the src/doc directory in a module’s project.
Development shell
The io.werval.doc project host the DocumentationPlugin that gets automatically registered in development mode and setup routes to serve documentation at /@doc.
The DocumentationPlugin serve core and dynamic documentations directly from the classpath. It generates a dynamic page with links to all registered dynamic documentations found in the application classpath. Dynamic documentation and its index are passed through SiteMesh to decorate them with the documentation website layout.
There’s no easy way to get live reload of changes made in io.werval.doc.
The jbake Gradle task generates the development mode documentation static part in the build/jbake directory. You can open the static website from there and run gradle jbake to see changes applied.
Or, to see the result in-situ, with dynamic documentation served, you can:
use any application that depends on the Werval development version ;
gradle install the io.werval.doc project ;
gradle devshell your application ;
refresh /@doc.
Documentations archives
The io.werval.dist project that create distributions, does the job of assembling documentation archives.
It depends on io.werval:io.werval.doc::doc@zip and all the doc classified ZIP artifacts from officially supported modules to generate the documentation website. Dynamic documentation index is generated as an Asciidoc file.
Aggregated documentation JBake project is then processed. The result is assembled in a ZIP archive published with the doc classifier for easy download and offline browsing.
io.werval:io.werval.dist:{werval_version}:doc@zip
Website
The Werval website provide general information about Werval and its community and embedd documentation sites for all past, current and develop versions documentations mini-sites.
Notable things included in the website are out of the Werval releases lifecycle, like Skeletons and Samples. Thus, this is built in a separate project, in a separate git repository named werval-website.
The Werval website is generated using JBake again.
The project depends on documentation archives of the past releases, current stable release and development version. All documentation websites are extracted and used as JBake assets under /doc.
The project use the Gradle Werval plugin allowing you to get live reload on changes made in the JBake project (gradle devshell).
A deployWebsite task allow to deploy the website with a single command line, it is for internal use only though.
As the documentation is stored alongside the code, the contribution workflow is the same as for code contributions.
The documents can use code snippets which will extract code from the project. This is preferred way to include source code in the documentation, since any refactoring will be reflected in the documentation.
Try to put one sentence on each line. Lines without empty lines between them still belongs to the same paragraph. This makes it easy to move content around and produce easier to review patches.
As {} are used for Asciidoc attributes, everything inside will be treated as an attribute. What you have to do is to escape the opening brace: \{. If you don’t, the braces and the text inside them will be removed without any warning being issued!
Here are the Werval specific attributes that are set while rendering the documentation:
|
The version of Werval that is being built |