summoner-1.1.0: README.md
# 🔮 Summoner
[](http://travis-ci.org/kowainik/summoner)
[](https://github.com/kowainik/summoner/blob/master/LICENSE)
[](https://hackage.haskell.org/package/summoner)
[](http://stackage.org/lts/package/summoner)
[](http://stackage.org/nightly/package/summoner)
[](http://packdeps.haskellers.com/reverse/summoner)
> _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
[](https://asciinema.org/a/198918)
## Getting started
### Prerequisites
To start using it make sure you have the next tools installed on your machine:
* [`Stack`](http://haskellstack.org) or [`cabal`](https://www.haskell.org/cabal/)
* [`git`](https://git-scm.com)
* [`hub`](https://github.com/github/hub)
* [`curl`](https://curl.haxx.se)
### 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`](https://medium.com/@jonathangfischoff/the-partial-options-monoid-pattern-31914a71fc67).
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
* `cabal` – `true` if you want to build you project with `cabal`,
`false` if you don't. If not specified it would be asked during each run of the `summoner`.
* `stack` – `true` if you want to build your project with `stack`,
`false` if you don't. If not specified it would be asked during each run of the `summoner`.
* `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`.
* `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`](https://hackage.haskell.org/package/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`.
* `warnings` – List of the default checks and warnings to add into `ghc-options` section in the `.cabal`.
* `stylish.*` — `stylish.file` to provide the absolute file path to the
`.stylish-haskell.yaml` file to use in the project. `stylish.url` to provide
the link to the `.stylish-haskell.yaml` file to use in the project. In case of
the absense or wrong path/link no `.stylish-haskell.yaml` file is created.
* `contributing.*` — `contributing.file` to provide the absolute file path to the
`CONTRIBUTING.md` file to use in the project. `contributing.url` to provide
the link to the `CONTRIBUTING.md` file to use in the project. In case of
the absense or wrong path/link no `CONTRIBUTING` file is created.
###### 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 an example of [the configuration for projects of the `Kowainik` organization](https://github.com/kowainik/org/blob/master/.summoner.toml).
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](https://github.com)
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](CHANGELOG.md).
## Acknowledgments
This project was inspired by [Aelve/new-hs](https://github.com/aelve/new-hs#readme),
which is the tool with the same goal but it's only for creating cabal projects.
Icons made by [Nikita Golubev](https://www.flaticon.com/authors/nikita-golubev)
from [Flaticon](https://www.flaticon.com/) is licensed by
[CC 3.0 BY](http://creativecommons.org/licenses/by/3.0/).