summoner: Tool for creating completely configured production Haskell projects.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Tool for creating completely configured production Haskell projects. See README.md for details.


[Skip to Readme]

Properties

Versions 1.0.0, 1.0.1, 1.0.2, 1.0.3, 1.0.4, 1.0.5, 1.0.6, 1.1.0, 1.1.0.1, 1.1.0.1, 1.2.0, 1.3.0, 1.3.0.1, 1.4.0.0, 2.0.0.0, 2.0.1.0, 2.0.1.1
Change log CHANGELOG.md
Dependencies aeson, ansi-terminal, base-noprelude (>=4.10 && <5), bytestring, directory, filepath, generic-deriving, gitrev, neat-interpolation (>=0.3.2.2 && <0.4), optparse-applicative, process, relude (>=0.3.0 && <0.4), summoner, text, time, tomland (>=0.4.0 && <0.5) [details]
License MPL-2.0
Copyright 2018 Kowainik
Author Kowainik
Maintainer xrom.xkov@gmail.com
Category CLI, CLI Tool, Development
Home page https://github.com/kowainik/summoner
Bug tracker https://github.com/kowainik/summoner/issues
Source repo head: git clone git@github.com:kowainik/summoner.git
Uploaded by shersh at 2018-09-10T12:45:37Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for summoner-1.1.0.1

[back to package description]

🔮 Summoner

wizard Build status MPL-2.0 license Hackage Stackage LTS Stackage Nightly Hackage-Deps

So many of our dreams at first seem impossible, then they seem improbable, and then, when we summon the will, they soon become inevitable.

Christopher Reeve

Summoner is the tool for creating fully configured production Haskell projects.

Demo

asciicast

Getting started

Prerequisites

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

Installation

The installation process can be done with the one simple command:

$ cabal new-install summoner

or

$ stack install summoner

or directly from GitHub.

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 the required command. To create a project, use summon new command specifying the prefered CLI options, follow the instructions during the interactive process of the project creation, 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 for the new projects:

  1. Default configuration file (~/.summoner.toml).
  2. Explicitly specified configuration file by --file FILENAME option (used instead of the 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
Custom prelude options

Should be specified inside [prelude] table.

Examples

See an example of the configuration for projects of the Kowainik organization.

By default, the summoner looks for the configuration file (.summoner.toml) in home directory.

The other way to specify some particular .toml file is summon new PROJECTNAME --file FILEPATH command.

CLI

Available commands:

Usage:
  summon COMMAND
      Set up your own Haskell project

Available commands:
  new                      Create a new Haskell project
  show                     Show available licenses or ghc versions

Available global options:
  -h, --help               Show this help text
  -v, --version            Show summoner's version

summon new command:

Usage:
  summon new PROJECT_NAME [--cabal] [--stack] [--ignore-config]
             [with [OPTIONS]] [without [OPTIONS]]
             [-f|--file FILENAME]
             [--prelude-package PACKAGE_NAME]
             [--prelude-module MODULE_NAME]

Available options:
  -h, --help               Show this help text
  --ignore-config          Ignore configuration file
  --cabal                  Cabal support for the project
  --stack                  Stack support for the project
  -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
  -l, --library            Library target
  -e, --exec               Executable target
  -t, --test               Tests
  -b, --benchmark          Benchmarks

summon show command:

Usage:
  summon show COMMAND
      Show supported licenses or ghc versions

Available commands:
  ghc                      Show available ghc versions
  license                  Show available licenses
  license [LICENSE_NAME]   Show specific license text

Available options:
  -h, --help               Show this help text

The options to be enabled/disabled can be specified while running the command. If any of the applicable command options wasn't tagged as enabled/disabled, then the question is asked during the work of the tool.

For example,

  summon new my-project with -letgcpw without -b --prelude-package relude --prelude-module Relude

creates the fully functional project which uses custom prelude relude, contains library, executable file, tests 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 new my-project

the tool asks about every particular option, rather you'd like to have it or not in your project.

Features

If you're running the summoner with all options enabled a project with the following hierarchy is 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

Moreover, a repository with one commit at master is added with enabled Travis CI for that.

GHC options

The -Wall option is added to every stanza.

The following warning checks are added by default to executable, tests and benchmark stanzas:

-threaded
-rtsopts
-with-rtsopts=-N

If warnings are not explicitly stated in the configuration file, then the following ghc-options are added to all stanzas.

-Wincomplete-uni-patterns
-Wincomplete-record-updates
-Wcompat
-Widentities
-Wredundant-constraints      (ghc >= 8.0)
-fhide-source-paths          (ghc >= 8.2.2)
-Wmissing-export-lists       (ghc >= 8.4.1)
-Wpartial-fields             (ghc >= 8.4.1)

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 only for creating cabal projects.

Icons made by Nikita Golubev from Flaticon is licensed by CC 3.0 BY.