🔮 Summoner
This is tool for creating completely configured production Haskell projects.
Consider that it's using Stack
for
creating and setting up projects.
Demo
[![asciicast](https://asciinema.org/a/Wf8ZOMAZSUFyAJob70pwM6rZ1.png](https://asciinema.org/a/Wf8ZOMAZSUFyAJob70pwM6rZ1)
Getting started
Prerequisites
To start using it make sure you have next tools installed on your machine:
Installation
Installation process can be done with one simple command:
$ stack install summoner
You can turn on the bash auto-completion by running the following command:
$ source <(summon --bash-completion-script `which summon`)
After that you can call summon
with required command line options, follow
the instructions that will appear, and a new project would be created in a subfolder
as well as a repository under your github account (if requested).
Usage
There are several options how to set particular configurations:
- Default configuration file (
~/.summoner.toml
).
- Explicitly specified configuration file by
--file FILENAME
option (used instead of default one if specified).
- Options that are stated by CLI arguments.
- Interactively inputed answers during work of the
summon
command
(for the options that were not specified on previous steps).
So the configuration uses Partial Options Monoid Pattern
.
If none of the mentioned above cases used then the configuration will be built interactively.
Configurations
.toml
files:
Here is the list of the options that could be configured for your needs:
Global keys
owner
– GitHub
login.
fullName
– full name.
email
– e-mail address.
license
– license (possible options: MIT
, BSD2
, BSD3
, GPL-2
, GPL-3
,
LGPL-2.1
, LGPL-3
, AGPL-3
, Apache-2.0
, MPL-2.0
).
ghcVersions
– summoner
uses default GHC-8.2.2
. But additionally you can specify other versions.
For each version x.y.z
the stack-x.y.z.yaml
will be created.
github
– true
if you want to turn on GitHub
integration by default,
false
if you don't. If not specified it would be asked during each run of the summoner
.
travis
– true
if you want to turn on Travis
integration by default,
false
if you don't. Ignored if github = false
.
If not specified it would be asked during each run of the summoner
.
appveyor
– true
if you want to turn on AppVeyor
integration by default,
false
if you don't. Ignored if github = false
.
If not specified it would be asked during each run of the summoner
.
private
– true
if you want to create private repositories by default,
false
if you don't. Ignored if github = false
.
If not specified it would be asked during each run of the summoner
.
bscript
– true
if you want to include build script by default,
false
if you don't. If not specified it would be asked during each run of the summoner
.
lib
– true
if you want to create src
folder with dummy Lib.hs
file and library target by default,
false
if you don't. If not specified it would be asked during each run of the summoner
.
exe
– true
if you want to create app
folder with dummy Main.hs
file and executable target by default,
false
if you don't. If not specified it would be asked during each run of the summoner
.
test
– true
if you want to create test
folder with dummy Spec.hs
file and test target by default,
false
if you don't. If not specified it would be asked during each run of the summoner
.
bench
– true
if you want to create benchmark
folder with Main.hs
file with dummy gauge
library usage example by default,
false
if you don't. If not specified it would be asked during each run of the summoner
.
extensions
– List of the default extensions to add into default-extensions
section in the .cabal
.
Custom prelude options
Should be specified inside [prelude]
table.
package
– Name of the package of the custom prelude you'd like to use in the project (doesn't work without module
field).
module
– Name of the module of the custom prelude you'd like to use in the project (doesn't work without package
field).
Examples
See example of configuration for projects of Kowainik
organization.
By default the summoner
will look for the configuration file (.summoner.toml
) in home directory.
The other way to specify some particular .toml
file is summon PROJECTNAME --file FILEPATH
command.
CLI
See the basic usage syntax below (you can check it out with summon --help
command):
summon PROJECT_NAME [with [OPTIONS]] [without [OPTIONS]]
[-f|--file FILENAME] [--prelude-package PACKAGE_NAME]
[--prelude-module MODULE_NAME]
Available global options:
-h, --help Show this help text
-v, --version Show summoner's version
-f, --file FILENAME Path to the toml file with configurations. If not
specified '~/.summoner.toml' will be used if present
--prelude-package PACKAGE_NAME
Name for the package of the custom prelude to use in
the project
--prelude-module MODULE_NAME
Name for the module of the custom prelude to use in
the project
Available commands:
with Specify options to enable
without Specify options to disable
Available command options:
-h,--help Show this help text
-g, --github Github integration
-p, --private Create private GitHub repository
-c, --travis Travis CI integration
-w, --app-veyor AppVeyor CI integration
-s, --script Build script
-l, --library Library target
-e, --exec Executable target
-t, --test Tests
-b, --benchmark Benchmarks
The options to be enabled/disabled can be specified while running the command.
If any of applicable command options wasn't tagged as enabled/disabled then
the question will be asked during the work of the script.
For example,
summon newProject with -letgcspw without -b --prelude-package universum --prelude-module Universum
will create fully functional project which uses custom prelude universum
, contains
library, executable file, tests, build script
and create private repository on github
integrated with Travis-CI
, AppVeyor-CI
, but benchmarks won't be attached to this one.
But when calling this command
summon newProject
the tool will ask about every particular option, rather you'd like to have it
or not in your project.
Note
This tool was tested with next settings:
stack version 1.6.1
git version 2.11.0
hub version 2.2.9
Features
If you're running the summoner
with all options enabled a project with the following
hierarchy will be created:
project-name
├── app
│  └── Main.hs
├── benchmark
│  └── Main.hs
├── src
│ ├── ProjectName.hs
│  └── Prelude.hs
├── test
│  └── Spec.hs
├── CHANGELOG.md
├── LICENSE
├── project-name.cabal
├── README.md
├── Setup.hs
├── stack.yaml
├── appveyor.yml
├── .git
├── .gitignore
└── .travis.yml
and also repository with one commit at master will be added with enabled Travis-CI
for that.
Build script
The b
script builds the project in a way that is convenient for developers.
It passes the right flags into right places, builds the project with --fast,
tidies up and highlights error messages in GHC output.
Usage
./b build whole project with all targets
./b -c do stack clean
./b -t build and run tests
./b -b build and run benchmarks
./b --nix use nix to build package
Change log
List of changes.
Acknowledgments
This project was inspired by Aelve/new-hs,
which is the tool with the same goal but the difference is that it's using
cabal
for creating projects.