Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/boot-clj/boot-new

Generate new projects based on Boot Templates and/or Leiningen Templates!
https://github.com/boot-clj/boot-new

Last synced: about 9 hours ago
JSON representation

Generate new projects based on Boot Templates and/or Leiningen Templates!

Host: GitHub
URL: https://github.com/boot-clj/boot-new
Owner: boot-clj
License: epl-1.0
Created: 2015-12-31T17:14:12.000Z (almost 9 years ago)
Default Branch: master
Last Pushed: 2019-06-27T01:31:39.000Z (over 5 years ago)
Last Synced: 2024-05-27T12:33:59.197Z (6 months ago)
Language: Clojure
Homepage: https://clojars.org/boot/new
Size: 83 KB
Stars: 155
Watchers: 9
Forks: 43
Open Issues: 2
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# boot-new

A Boot task that generates projects from Leiningen templates or Boot templates.

[![Clojars Project](https://img.shields.io/clojars/v/boot/new.svg)](https://clojars.org/boot/new)

## Getting Started

Create a basic application:

boot -d boot/new new -t app -n myapp
cd myapp
boot run

Built-in templates are:

* `app` -- A minimal Hello World! application. Comes with `build`, `run`, `test` tasks. `build` creates a runnable "uberjar" in the `target` folder.
* `default` -- A minimal library. Comes with `build`, `test` tasks. `build` installs a JAR of the project into your local Maven cache so you can use `boot watch build` while you're developing to have the latest version always available to other projects.
* `task` -- An example set of Boot tasks. Provides `*-pass-thru`, `*-post`, `*-pre`, `*-simple` task examples for you to build on, as well as `build`, `test` tasks. `build` works as for `default` above.
* `template` -- A minimal Boot template. Provides `build`, `new`, `test` tasks. `build` works as for `default` above. `new` will create a new project based on the template itself.

## General Usage

You can specify a template and a project name:

boot -d boot/new new -t template-name -n project-name

`boot-new` will look for `template-name/boot-template` (on Clojars and Maven Central). If it doesn't find a Boot Template (see below), it will look for `template-name/lein-template` instead. `boot-new` should be able to run any existing Leiningen template (if you find one that doesn't work, [please tell me about it](https://github.com/boot-clj/boot-new/issues)!). `boot-new` will then generate a new project folder called `project-name` containing files generated from the specified `template-name`.

If the folder `project-name` already exists, `boot-new` will not overwrite it unless you specify the `-f` / `--force` option. You can override the folder name used with the `-o` / `--to-dir` option. By default, `boot-new` will look for the most recent stable release of the specified template. You can tell it to search for snapshots with the `-S` / `--snapshot` option, and you can specify a particular version to use with the `-V` / `--template-version` option. In general, the long-form option follows the naming used by Leiningen's `new` task for familiarity.

You can pass arguments through to the underlying template with the `-a` / `--args` option (Leiningen uses `--` to separate template arguments from other options but Boot already parses options a little differently).

For a full list of options, ask `new` for help:

boot -d boot/new new -h

The intent is that all of the basic options from Leiningen's `new` task are supported, along with Boot-specific versions of the built-in templates (`app`, `default`, `task` -- instead of Leiningen's `plugin`, and `template`).

## Boot Templates

Boot templates are very similar to Leiningen templates but have an artifact name based on `boot-template` instead of `lein-template` and uses `boot` instead of `leiningen` in all the namespace names. In particular the `boot.new.templates` namespace provides functions such as `renderer` and `->files` that are the equivalent of the ones found in `leiningen.new.templates` when writing a Leiningen Template. The built-in templates are Boot templates, that produce Boot projects.

To develop a new template, run `boot -d boot/new new -t template -n my-template`. This will generate a project whose `build.boot` has `(def project 'my-template/boot-template)`, with version `0.1.0-SNAPSHOT`. To test it, you will need to build and install it locally (the generated `build.boot` contains a `build` task for this purpose) and then use it to create a project, using either `--snapshot` or `--template-version` so `boot-new` will know which version to use. By default, it looks for the most recent non-SNAPSHOT release on clojars.org.

### Arguments

Previous sections have revealed that it is possible to pass arguments to templates. For multiple arguments, use one `-a` for each argument. For example:

```
# Inside custom-template folder, relying on that template's boot new task.
boot new -t custom-template -n project-name -a arg1 -a arg2 -a arg3
```

These arguments are accessible in the custom-template function as a second argument.

```clj
(defn custom-template
[name & args]
(println name " has the following arguments: " args))
```

## Boot Generators

Whereas Boot templates will generate an entire new project in a new directory, Boot generators are intended to add / modify code in an existing project. `boot-new` will run a generator with the `-g type` or `-g type=name` options. The `type` specifies the type of generator to use. The `name` is the main argument that is passed to the generator.

A Boot generator can be part of a project or a template. A generator `foo`, has a `boot.generate.foo/generate` function that accepts at least two arguments, `prefix` and the `name` specified in the `-g` / `--generate` option (which will be `nil` if no `name` was specified -- the generator should validate that). `prefix` specifies the directory in which to perform the code generation and defaults to `src`. It can be overridden with the `-p` / `--prefix` option, but a generator is also free to simply ignore it anyway. In addition, any arguments specified by the `-a` / `--args` option are passed as additional arguments to the generator.

There are currently a few built-in generators:
- `file`
- `ns`
- `def`
- `defn`
- `edn`

The `file` generator creates files relative to the prefix. It optionally accepts a body, file extension, and append? argument.
```bash
boot -d boot/new new -g file=foo.bar -a "(ns foo.bar)" -a "clj"
```

The `ns` generator creates a clojure namespace by using the `file` generator and providing a few defaults.
```bash
boot -d boot/new new -g ns=foo.bar
```

This will generate `src/foo/bar.clj` containing `(ns foo.bar)` (and a placeholder docstring). It will not replace an existing file unless you specify `-f` / `--force` (so `ns` generators are safe-by-default.
```bash
boot -d boot/new new -g defn=foo.bar/my-func
```

If `src/foo/bar.clj` does not exist, it will be generated as a namespace first (using the `ns` generator above), then a definition for `my-func` will be appended to that file (with a placeholder docstring and a dummy argument vector of `[args]`). The generator does not check whether that `defn` already exists so it always appends a new `defn`.

Both the `def` and `defn` generators create files using the `ns` generator above.

The `edn` generator uses the `file` generator internally, with a default extension of `"edn"`.
```bash
boot -d boot/new new -g edn=foo.bar -a "(ns foo.bar)"
```

## Roadmap

* Improve the built-in template `template` so that it can be used to seed a new Boot project.

## License

Distributed under the Eclipse Public License version 1.0.