Lazybones Project Creation Tool
Lazybones was born out of frustration that Ratpack does not and will not have a command line tool that will bootstrap a project. It’s a good decision for Ratpack, but I’m lazy and want tools to do the boring stuff for me.
The tool is very simple: it allows you to create a new project structure for any framework or library for which the tool has a template. You can even contribute templates by sending pull requests to this GitHub project or publishing the packages to the relevant Bintray repository (more info available below).
The concept of Lazybones is very similar to Maven archetypes, and what Yeoman does for web applications. Lazybones also includes a subtemplates feature that resembles the behaviour of Yeoman’s sub-generators, allowing you to generate optional extras (controllers, scaffolding etc.) inside a project.
Developers
Contributors
Running it
Grab lazybones from sdkman (formerly gvm):
sdk install lazybones
or alternatively, grab the distribution from Bintray,
unpack it to a local directory, and then add its ‘bin’ directory to your PATH
environment variable.
Finding out what templates are available
To see what templates you can install, run
lazybones list
This will list all aliases and remote templates. If you want to see what templates you have cached locally, run
lazybones list --cached
In fact, --cached
is implied if Lazybones can’t connect to the internet.
You can also find out more about a template through the info
command:
lazybones info <template name>
This will print a description of the template and what versions are available for it. If you’re offline, this will simply display an error message.
Configuration
Lazybones will run out of the box without any extra configuration, but the tool does allow you to override the default behaviour via a fixed set of configuration options. These options can be provided in a number of ways following a set order of precedence:
System properties of the form
lazybones.*
, which can be passed into the app via eitherJAVA_OPTS
orLAZYBONES_OPTS
environment variables. For example:env JAVA_OPTS="-Dlazybones.config.file=/path/to/my-custom-default-config.groovy" lazybones ...
Highest precedence, i.e. it overrides all other sources of setting data.
User configuration file in
$USER_HOME/.lazybones/config.groovy
. This is parsed using Groovy’sConfigSlurper
, so if you’re familiar with that syntax you’ll be right at home. Otherwise, just see the examples below.(Since 0.8) A JSON configuration file in
$USER_HOME/.lazybones/managed-config.groovy
that is used by theconfig
commands. You can edit it this as well.A Groovy-based default configuration file that is provided by the application itself, but you can specify an alternative file via the
lazybones.config.file
system property.
Lazybones also provides a convenient mechanism for setting and removing options
via the command line: the config
command.
Custom repositories
Lazybones will by default download the templates from a specific Bintray
repository. If you want to host template packages in a different repository
you can add it to Lazybone’s search path via the bintrayRepositories
setting:
bintrayRepositories = [
"kyleboon/lazybones",
"pledbrook/lazybones-templates"
]
If a template exists in more than one repository, it will be downloaded from the first repository in the list that it appears in.
Package aliases
If you regularly use a template at a specific URL rather than from Bintray, then you will want to alias that URL to a name. That’s where template mappings (or aliases) come in. The aliases are defined as normal settings of the form
templates.mappings.<alias> = <url>
In a Groovy configuration file, you can define multiple aliases in a block:
templates {
mappings {
test = "http://dl.dropboxusercontent.com/u/29802534/custom-ratpack.zip"
after = "file:///var/tmp/afterburnerfx-2.0.0.zip"
}
}
Alternatively, add them from the command line like this:
lazybones config set templates.mappings.after file:///var/tmp/afterburnerfx-2.0.0.zip
The aliases will always be available to you until you remove them from the persisted configuration.
Setting a proxy (and other system properties) (Since 0.8.1)
Many people have to work behind a proxy, but Lazybones didn’t make it easy to
configure one. In fact the only way to do it was to add the relevant system
properties to a JAVA_OPTS
environment variable. From 0.8.1, you now have another
option.
Lazybones has stolen the idea of having a special form of configuration option for
system properties from Gradle. So if you define a property with a systemProp.
prefix, it will be added as a system property internally. So to configure an HTTP
proxy, you only need to add the following to your Lazybones configuration:
systemProp {
http {
proxyHost = "localhost"
proxyPort = 8181
}
https {
proxyHost = "localhost"
proxyPort = 8181
}
}
To avoid potential configuration issues, use the same proxy settings for HTTP and HTTPS if possible.
If your proxy requires authentication, you will need to add a couple of extra properties:
systemProp {
http {
proxyUser = "johndoe"
proxyPassword = "mypassword"
}
}
As with the host and port, there are https
variants of the username and passwordi
as well.
General options
These are miscellaneous options that can be overridden on the command line:
// <-- This starts a line comment
// Set logging level - overridden by command line args
options.logLevel = "SEVERE"
The logging level can either be overridden using the same logLevel
setting:
lazybones --logLevel SEVERE info ratpack
or via --verbose
, --quiet
, and --info
options:
lazybones --verbose info ratpack
The logging level can be one of:
- OFF
- SEVERE
- WARNING
- INFO
- FINE
- FINEST
- ALL
Building it
This project is split into two parts:
- The lazybones command line tool; and
- The project templates.
The command line tool
The command line tool is created via Gradle’s application plugin. The main
class is uk.co.cacoethes.lazybones.LazyBonesMain
, which currently implements
all the sub-commands (create, list, etc.) as concrete methods.
The main class plus everything else under src/main is packaged into a lazybones
JAR that is included in the distribution zip. The application Gradle plugin
generates a lazybones
script that then runs the main class with all required
dependencies on the classpath.
To build the distribution, simply run
./gradlew distZip
The project templates
The project templates are simply directory structures with whatever files in them that you want. Ultimately, the template project directories will be zipped up and stored on Bintray. From there, lazybones downloads the zips on demand and caches them in a local user directory (currently ~/.lazybones/templates).
If you want empty directories to form part of the project template, then simply add an empty .retain file to each one. When the template archive is created, any .retain files are filtered out (but the containing directories are included).
To package up a template, simply run
./gradlew packageTemplate<TemplateName>
The name of the project template comes from the containing directory, which is assumed to be lowercase hyphenated. The template name is the equivalent camel case form. So the template directory structure in src/templates/my-template results in a template called ‘MyTemplate’, which can be packaged with
./gradlew packageTemplateMyTemplate
The project template archive will be created in the build directory with the
name ‘-template-
You can also package all the templates in one fell swoop:
./gradlew packageAllTemplates
Once a template is packaged up, you can publish it to a generic (non-Maven) Bintray repository by running
./gradlew publishTemplate<TemplateName>
This will initially fail, because the build does not know where to publish to. That’s quickly fixed by adding a gradle.properties file in the root of this project that contains at least these properties:
repo.username=your_bintray_username
repo.apiKey=your_bintray_apikey
You can then publish new versions of templates whenever you want. Note that you cannot republish with this mechanism, so remember to increment the version if you need to.
Finally, you can publish the whole shebang (unusual) with
./gradlew publishAllTemplates
If you don’t want to publish your template you can install it locally using the installTemplate rule.
./gradlew installTemplate<TemplateName>
This will install the template to ~/.lazybones/templates so that you can use it without moving it to bintray first.
And that’s it for the project templates.