This is tool for creating completely configured production Haskell projects.
Consider that it's using Stack for
creating and setting up projects.
To start using it make sure you have next tools installed on your machine:
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).
There are several options how to set particular configurations:
- Default configuration file (
~/.summoner.toml). - Explicitly specified configuration file by
--file FILENAMEoption (used instead of default one if specified). - Options that are stated by CLI arguments.
- Interactively inputed answers during work of the
summoncommand (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.
Here is the list of the options that could be configured for your needs:
owner–GitHublogin.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–summoneruses defaultGHC-8.2.2. But additionally you can specify other versions. For each versionx.y.zthestack-x.y.z.yamlwill be created.github–trueif you want to turn onGitHubintegration by default,falseif you don't. If not specified it would be asked during each run of thesummoner.travis–trueif you want to turn onTravisintegration by default,falseif you don't. Ignored ifgithub = false. If not specified it would be asked during each run of thesummoner.appveyor–trueif you want to turn onAppVeyorintegration by default,falseif you don't. Ignored ifgithub = false. If not specified it would be asked during each run of thesummoner.private–trueif you want to create private repositories by default,falseif you don't. Ignored ifgithub = false. If not specified it would be asked during each run of thesummoner.bscript–trueif you want to include build script by default,falseif you don't. If not specified it would be asked during each run of thesummoner.lib–trueif you want to createsrcfolder with dummyLib.hsfile and library target by default,falseif you don't. If not specified it would be asked during each run of thesummoner.exe–trueif you want to createappfolder with dummyMain.hsfile and executable target by default,falseif you don't. If not specified it would be asked during each run of thesummoner.test–trueif you want to createtestfolder with dummySpec.hsfile and test target by default,falseif you don't. If not specified it would be asked during each run of thesummoner.bench–trueif you want to createbenchmarkfolder withMain.hsfile with dummygaugelibrary usage example by default,falseif you don't. If not specified it would be asked during each run of thesummoner.extensions– List of the default extensions to add intodefault-extensionssection in the.cabal.
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 withoutmodulefield).module– Name of the module of the custom prelude you'd like to use in the project (doesn't work withoutpackagefield).
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.
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.
This tool was tested with next settings:
stack version 1.6.1
git version 2.11.0
hub version 2.2.9
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.
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.
./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
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.