Awesome

Skeletal Project Creation Tool

Quick Links

Introduction

Skeletal is a tool that allows you to create a new project structure for any framework or library for which the tool has a template.

The concept of Skeletal is very similar to Maven archetypes, and what Yeoman does for web applications. Skeletal also includes a subtemplates feature that resembles the behavior of Yeoman's sub-generators, allowing you to generate optional extras (controllers, scaffolding etc.) inside a project.

It consists of a command line application, a Gradle plugin for publishing templates, and a Lazybones Project template for template developers and some other core templates for developers.

Skeletal is a fork of the popular Lazybones project created by Peter Ledbrook. Though unmaintained for some time, Lazybones continued to be used by other projects as a means to generate project layouts from templates and it was distributed on SDKMAN which made it more convenient to install and use. This came to an end with the shutdown of Bintray. in May 2021. Since this is where the application binaries and "built-in" templates lived, SDKMAN stopped distribution as the binaries were no longer available.

We will continue to refer to the templates as Lazybones templates because so many projects have been created from them and that is how they are best known. The template structure has not been changed, except to add a description file, so we see no reason to rebrand what the templates are called.

The big changes from Lazybones are:

The new project name and the application command are both now 'skeletal'.
The user profile directory for configurations and template cache is now $HOME/.skeletal
Bintray repositories are no longer available. Eventually this configuration will be removed.
A new URL based simple repository has been implemented that supports listing and creating projects from it. Publishing to the simple repository is not yet implemented but only require copying the created published manifest file and the template packages to your URL repository.

Existing Lazybones templates should still work if moved to a URL repository as described below.

Documentation

Skeletal application usage and template development guides are located in our project documention pages.

Information on building the application can be found below.

Building

This project is split into three parts:

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 command classes.

The main class plus everything else under src/main is packaged into a skeletal-app-<version>.jar that is included in the distribution zip. The Gradle application plugin generates a skeletal shell script and a skeletal.bat script that then runs the main class with all required dependencies on the classpath.

To build the distribution, from the skeletal project top level directory simply run:

./gradlew distZip

You will find the application packaged in build/distributions/skeletal-<version>.zip

Unpack the zip file contents to anywhere you keep such applications and add the bin subdirectory to your system path to get the skeletal command.
The $HOME/.skeletal profile directory will be created after the first create or config command is ran.

You can build an "installed" build for manual testing locally before production.

./gradlew installDist

You can run it using the path to the application script

skeletal-app/build/install/skeletal/bin/skeletal <command>

Automated Tests

We use Spock for tests (specifications). There are approximatly 300 unit or integration tests currently ran during a build of the distribution.

To run the tests alone

./gradlew check

Gradle reports are found in build/reports/tests. We have recently added Athaydes Spock Reports but we haven't done much with the configuration of those yet. Those reports are found in build/spock-reports

Skeletal Gradle Plugin

The Gradle plugin that was a subproject in Lazybones has been moved into its own Skeletal Gradle Plugin project.

Lazybones Project Templates

Template Versions

You define the version of a template by putting a VERSION file in the root directory of the template that contains just the version number. For example, you specify a version of 1.2.8 for the my-template template by adding the file templates/my-template/VERSION with the contents

1.2.8

Template Description

Skeletal requires a DESCRIPTION file that contains a description for the template.

A project for managing Lazybones project templates.

For core templates in this project, run from the Skeletal project root directory and include the lazybones-templates sub-project:

./gradlew :lazybones-templates:publishTemplate<TemplateName>

You can also publish all the templates in one fell swoop:

./gradlew :lazybones-templates:publishAllTemplates

That's it! The VERSION and DESCRIPTION files will automatically be excluded from the project template archive.

More complete information about template publishing can be found in the project documention pages and the Skeletal Gradle Plugin project.

Creating a Release

Releases are created in the GitHub repo by creating a tag and a Release based on that tag and a Changelog of major changes and uploading build artifacts and source archives.

This is automated by JReleaser using the jreleaser.yml configuration file and the JReleaser CLI.

Pre-Release Checklist

App version is correct in skeletal-app/app.gradle and docs/*.adoc files.
build distribution with ./gradlew distZip
verify all tests passed.

Steps to Create a Release

export JRELEASER_PROJECT_VERSION=version to release
export JRELEASER_OUTPUT_DIRECTORY=skeletal-app/build
jreleaser config
jreleaser full-release --dry-run
check skeletal-app/build/jreleaser/release/CHANGELOG.md for errors
jreleaser full-release

Contributing

Skeletal is written in Apache Groovy, builds with Gradle, and we use Spock for testing.

Contributors are welcome and contributions are appreciated. If you have questions about contributing you can drop a question in the issues or email carl dot marcum at codebuilders dot net.