Artemis | Blog | About & Contact

2018 / 08 / 10 (raw)

Kickstart, a fast and simple project template bootstrapper

Ever had some code base that you regularly use to start a new project?

Until now, you've probably lost some time refactoring everything to fill out the right project name, title etc.

A few tools already exist but either you're lost in feature bloating hell or you're fighting to configure everything in most cases.

The following tool is an early-developement, rust-based, template tool made to be more versatile that its closest python counter-part, cookiecutter.

Also, it perfectly works on Windows, Linux and MacOS without any issue!

A demonstration

Let me demonstrate this tool from a user's point of view.

Say I'm John. I have a need to make several workers for my job queue.

All workers follow the same base structure and only a few bits of code change. Error management is the same, etc.

Without any external tool, the easiest way I could handle that would be to put the template in a Git repository, clone it when needed and change the few fields, like the handler's class name, the configuration file etc.

Still, I'd like to quickly bootstrap all my workers and not have to, by hand, replace each key with the right value.

At the same time, I'm too lazy to set up an entire boostrapping suite or tool, and I'd like to be able to make some very basic project templates that'd work almost out of the box.

My example of worker system uses the following file structure for worker classes:

├── {{name}}.java
└── template.toml

Yes, this tool supports templating in file and folder names!

The {{name}}.java file contains the following very basic template code:

package org.artemix.worker;

class {{name}} extends WorkerBase {
    public void handle(Payload payload) {
        // Some default code

The template.toml contains a few template-specific fields (like its name, description and configuration format version), but also variable declaration for setup prompts.

name = "Worker"
description = "Worker base template"
kickstart_version = 1

prompt="Which class name do you want to give to your worker ?"

Here, with the validation regex, we can attest that we'll get a valid Java class file starting with a capitalized letter.

And that's it!

In a few instants, we created our worker template, and we have a nice base we can later grow if we need any new more complex worker.

Now, how do you create a worker with this template?

The easiest way is by simply running the following command from inside the folder in which you want the files to be created.

$ kickstart /path/to/my/template

This will parse the template.toml inside the given template path and, for each [[variable]] block, will ask the prompt, validate the input, and repeat until it's rightly entered.

Once all prompts have been resolved, it'll copy and parse the files into the current directory.

But I don't want to have all my templates in local, or pass the path every time!

Sure, having everything in local can be bothersome, especially if you're starting a project from a huge project template.

To answer that, in the current version, kickstart supports cloning from a git remote by either HTTP(S), SSH or even git shortcuts!

In that sense, all the following commands are perfectly valid and will clone from a git remote.

$ kickstart
$ kickstart https://git.local/test
# With git shortcuts in the configuration, see
$ kickstart gl:MyUser/MyTemplate

In conclusion

While still young, this tool is already, as-is, really useful and can handle a lot of situations.

Since the goal of this tool is to be as lightweight and basic as possible, you can have a fair guarantee that it won't become an over-complex, feature-bloated, tool.

Not every feature has been showcased in this article, so I can only recommend you to go to the official Github repository, and take a look at the file, which should contains every information you'd need to learn how to use it.

As I publish this article, the official v0.1.7 version have been released, and you can find the relesae on the releases page. If you'd prefer to be on the latest version, you can simply clone the repository, and, while inside it, run cargo builld and have a working version just for you.