🔮 Summoner

This is tool for creating completely configured production Haskell projects.

Demo

Getting started

Prerequisites

To start using it make sure you have next tools installed on your machine:

• Stack or cabal
• git
• hub

Installation

Installation process can be done with one simple command:

$ cabal install summoner

or

$ stack install summoner --resolver nightly-2018-06-01

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:

1. Default configuration file (~/.summoner.toml).
2. Explicitly specified configuration file by --file FILENAME option (used instead of default one if specified).
3. Options that are stated by CLI arguments.
4. 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 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 it's using cabal for creating projects.