summoner

Tool for creating completely configured production Haskell projects.

https://github.com/kowainik/summoner

Version on this page:1.0.3
LTS Haskell 16.31:2.0.1.1
Stackage Nightly 2020-06-29:2.0.1.1
Latest on Hackage:2.0.1.1

See all snapshots summoner appears in

MPL-2.0 licensed by Kowainik
Maintained by [email protected]
This version can be pinned in stack with:summoner-1.0.3@sha256:3d3168195add763613e40038310150b49608805b2f6d732b729e33dee9c3094e,3242

๐Ÿ”ฎ Summoner

Build status Windows build status MPL-2.0 license Hackage Stackage LTS Stackage Nightly

This is tool for creating completely configured production Haskell projects.

Demo

asciicast

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:

$ 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.

Changes

Summoner

1.0.3

  • #92: Remove -fhide-source-paths from generated stack yaml files for GHC < 8.2

1.0.2

  • #87: Fix Travis matrix for not default ghc versions.

1.0.1

  • #85: Remove base-noprelude from dependencies.

1.0.0

  • Important: Rename hs-init to summoner. Transform the script into the package.
  • #54: Rename on and off commands to with and without.
  • #48:
    • Add ability to write configurations file. Remove Targets data type. Use Config instead for default, file and CLI configurations.
  • #60: Use custom prelude universum.
  • #39: Add option to use custom prelude in CLI and in .toml configuration.
  • #38: Add option to add default extensions to .toml config.
  • #62: Make some parts of output not only colorful, but also bold. This makes output prettier.
  • #67: Add Aswer data type to handle yes-no CLI questions.
  • #61: Add CLI --version option.
  • #73: Make custom prelude be table in toml.
  • #74: Print hierarchy tree for the created project.

hs-init

0.0.4

  • Now works on windows systems as well
  • Add powershell install script for Windows

0.0.3

  • #45: Support AppVeyor CI for created projects.

0.0.2

  • Use metavar for on-off commands.
  • Upgrade lts to 10.3, use ghc 8.2.2 as default value.

0.0.1

  • #36: Add option for creating private repositories โ€” -p | --private.