This article gives an overview over open source build tools created by smartics. It shows how we use them to automate our build process, reducing manual steps as much as possible.
It will also give hints on how to use these tools in corporation projects to handle versioned sites of in-house projects.
Why automate?
Before we delve into the details of automation, I want to give you the reasons why we are putting much effort in writing build tools.
Save Resources
As a tiny company we are constantly low on one particular resource: time. Therefore we push automation as far as possible.
Repeatability
Having only very limited resources we have to do releases in a small amount of time. Often late in the night, where releases have to be a no-brain-involved task.
Easy to Use
Since we do not want to have something in our way, launching our tools should be as easy as possible.
Traceablility
If something went wrong, we have to access information that helps us to pin down the root cause of the problem. This allows us to fix it and get better with time.
Reuse
We want to enable other companies, which includes our customers, to use our tools to be more efficient in their effort to produce high quality software.
We also hope to get into a discussion with our users to improve our tools for the benefit of everyone.
Project Creation
Continuous Integration
On the first check-in of a new project, we want our integration server to build the project continuously. Therefore we create a job on our Hudson server by launching
chj
on the project’s configuration. This uses the Alias Maven Plugin and launches Maven to use our POM to create that job on the server, using the Hudson Maven Plugin. chj is an alias for create hudson job.
Issue Tracking
To further traceability we want to assign new features, change requests, improvements, and bugs to the versions of our products to fix them. This allows to generate release reports automatically, which we will later show. Therefore we have to create a product on our Bugzilla issues server by running
bi
This will again launch Maven, using the Bugzilla Maven Plugin, to create the Bugzilla product upon information found in the POM. bi is an alias for bugzilla initialize project.
If you ask yourself, how in the world should I remember all these shortcuts (aka aliases)?
Simply type
h
into your console and you get the follwing result:
--- mvn t = mvn -T 4 clean test [args] p = mvn -T 4 clean package [args] i = mvn -T 4 clean install [args] s = mvn -T 4 initialize site [args] sd = mvn -T 4 clean deploy site-deploy [args] l = mvn initialize license:format [args] --- jboss asd = mvn jboss-as:deploy [args] asr = mvn jboss-as:redeploy [args] asu = mvn jboss-as:undeploy [args] iasd = mvn clean install jboss-as:deploy [args] iasr = mvn clean install jboss-as:redeploy [args] --- project-sync b = mvn bugzilla:sync [args] bi = mvn bugzilla:init [args] chj = mvn hudson:createJobs [args] dhj = mvn hudson:deleteJobs [args] --- project-analysis a = mvn dependency:analyze [args] dpu = mvn versions:display-plugin-updates [args] ddu = mvn versions:display-dependency-updates [args] --- project-release r = mvn -T 4 release:prepare release:perform [args] rpr = mvn -T 4 release:prepare [args] rpe = mvn -T 4 release:perform [args] rr = mvn release:rollback [args] rc = mvn release:clean [args] --- java j5 = set JAVA_HOME="JAVA_HOME_5";; set PATH=JAVA_HOME_5\bin;PATH j6 = set JAVA_HOME="JAVA_HOME_6";; set PATH=JAVA_HOME_6\bin;PATH j7 = set JAVA_HOME="JAVA_HOME_7";; set PATH=JAVA_HOME_7\bin;PATH --- ALIAS EXTENSIONS ...aq (... and quit!): taq paq iaq saq sdaq laq raq rpraq rpeaq rraq rcaq --- help h = This help. For additional information please refer to: https://www.smartics.eu/de.smartics.config/config-smartics-alias/1.1.0/alias-report.html
Clicking on the given link will direct you to a HTML version of the report.
Project Release
Releasing
The act of releasing a software version is already automated by the Maven Release Plugin. This command can be launched via the integration server, which is – for reproducible builds – highly recommended. Alternatively it can be launched from any developer machine using the alias-maven-plugin by typing
r
After the release we often want to update the product information in the Bugzilla server. Typing
b
will add the new released version and milestones for the project.
Static Project Site
Using the Maven Site Plugin we create project sites with Maven that provide essential documentation on a specific version of a product. The site will be automatically pushed to our sites server using the Maven groupId, artifactId, and version.
This creates some long and ugly URLs, not easily to remember by a standard human brain. For smartics-commons, a small library for Java that contains utilities we often use in our projects, the URL for version 0.5.2 is
http://www.smartics.eu/de.smartics.util/smartics-commons/0.5.2
What would be nicer is this:
http://www.smartics.eu/smartics-commons/0.5.2
And even, if we want to refer to the latest version of the project
http://www.smartics.eu/smartics-commons
While a particular version is actually deployed to the location mentioned first, our smartics Softlink Tool, running on our server as a background process, will automatically generate the missing links.
Metadata
The following metadata about our products is automatically released as part of the generated project sites.
Release Reports
Adding release notes manually is cumbersome and sometimes error-prone. It is easy to forget some details. Therefore we add issues to our Bugzilla server and extract release reports for our projects automatically with the help of our Issues Maven Plugin.
Build Metadata
To help our users and ourselves to check how a version has been built, we add a build report using our Buildmetadata Maven Plugin.
Project Metadata
For all project metadata we do not want to attach to the main artifact, our Projectmetadata Maven Plugin will create an attached artifact. This artifact is stored side-by-side with the main, sources, and javadoc artifact.
Test Stories
Our testdoc-tools allow to add metadata to tests. With this metadata, reports can be generated that allow to read tests like stories about the software. There is also a plugin for Eclipse that helps navigating between code and its test cases.
Library Reports
The following reports of projects, using the mentioned smartics libraries, are automatically released in the generated project site. Keeping codes or constants documentation in sync with its code is difficult. Therefore we use the libraries to let the build machine controls this issue for us.
Exception Codes Report
smartics Exceptions is a library for Java that helps handling exception codes. Central are exception codes that identify error conditions. A report on these codes is generated by the exceptioncodes-maven-plugin.
Properties Report
We are currently developing a library that makes handling configurations with Java easier. The project is called smartics Properties. Part of this project is the Properties Maven Plugin that generates reports about properties, using the metadata and Javadoc comments provided in the code.
Recommendations for Projects
If you are using Hudson or Bugzilla you may consider to use the Hudson Maven Plugin or the Bugzilla Maven Plugin to create the project’s representation on the servers. Creating a product or updating the version information on the Bugzilla server as well as creating or deleting a Hudson job may always be effortless.
If you already use Maven sites and their reports as part of your project documentation, creating easy to remember links automatically with the smartics Softlink Tool may be an easy-to-install option.
Creating release reports with the Issues Maven Plugin depends on your requirements. It is easy to include, but over time, as more and more issues will be analyzed on each release, the creation of the report may get time consuming. If your issues server already manages those reports, you may safely skip this plugin.
Metadata for your projects may proof invaluable, but for some they are just an additional burden with its benefits never be used. If it happens that SNAPSHOT versions get passed around within your team – or even worse – between different teams, you may welcome metadata within the archive to track the artifact to its sources in your SVN version control system. So the Buildmetadata Maven Plugin may be a tool to use. Before you employ the Projectmetadata Maven Plugin, check if you have use cases for the data preserved. Otherwise you build process will only be slowed down without any gain.
The same is true for using the testdoc-tools. Although the Eclipse plugin will help in navigation despite the reports are of no use for your team.
Using the libraries in your project is a question on another level. Due to the nature of exception design in Java, the smartics Exceptions library will leak transitively into your API. This may or may not be a problem, but it should be discussed.
smartics Properties is a relatively new project where you are on the bleeding edge. We are currently working on tighter integration into the JBoss application server and this might make it easier for some teams to integrate this tool. We will inform our users about changes on the project’s website.
Conclusion
As Mike Clark puts it:
Automation will give you back something you don’t have enough of: time.- Mike Clark
This article introduced the smartics tool set in the context of increasing productivity. We use these tools to create our open source software and also help our clients to add more automation to their in-house projects.
That is not that every project needs to use all of them. It depends on the qualities required by the project. But many of them may make the developer’s life easier, without being costly or heavily invasive. Saving time on everyday tasks helps teams to put time and mind at problems worth the effort.
