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.1, 1.0.2, 1.0.3, 1.0.4, 1.0.5, 1.0.6, 1.1.0, 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 (>=4.9 && <5), bytestring, directory, filepath, generic-deriving, neat-interpolation, optparse-applicative, process, summoner, text, time, tomland (>=0.2.1), universum (>=1.2.0) [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-05-30T16:09:33Z

Modules

[Index]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for summoner-1.0.1

[back to package description]

🔮 Summoner

Build status Windows build status MPL-2.0 license Hackage

This is tool for creating completely configured production Haskell projects. Consider that it's using Stack for creating and setting up 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:

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

  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
Custom prelude options

Should be specified inside [prelude] table.

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.