summoner
Tool for creating completely configured production Haskell projects.
https://github.com/kowainik/summoner
Version on this page: | 1.1.0.1 |
LTS Haskell 16.31: | 2.0.1.1 |
Stackage Nightly 2020-06-29: | 2.0.1.1 |
Latest on Hackage: | 2.0.1.1 |
summoner-1.1.0.1@sha256:e4e2d7c4257fc64e8da8918d6a59ad698aa6da19118ac82ae769719f8e943c91,4529
Module documentation for 1.1.0.1
๐ฎ 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
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:
- Default configuration file (
~/.summoner.toml
). - Explicitly specified configuration file by
--file FILENAME
option (used instead of the default one if specified). - Options that are stated by CLI arguments.
- 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
cabal
โtrue
if you want to build you project withcabal
,false
if you donโt. If not specified it would be asked during each run of thesummoner
.stack
โtrue
if you want to build your project withstack
,false
if you donโt. If not specified it would be asked during each run of thesummoner
.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 defaultGHC-8.2.2
. But additionally you can specify other versions. For each versionx.y.z
thestack-x.y.z.yaml
will be created.github
โtrue
if you want to turn onGitHub
integration by default,false
if you donโt. If not specified it would be asked during each run of thesummoner
.travis
โtrue
if you want to turn onTravis
integration by default,false
if you donโt. Ignored ifgithub = false
. If not specified it would be asked during each run of thesummoner
.appveyor
โtrue
if you want to turn onAppVeyor
integration by default,false
if you donโt. Ignored ifgithub = false
. If not specified it would be asked during each run of thesummoner
.private
โtrue
if you want to create private repositories by default,false
if you donโt. Ignored ifgithub = false
. If not specified it would be asked during each run of thesummoner
.lib
โtrue
if you want to createsrc
folder with dummyLib.hs
file and library target by default,false
if you donโt. If not specified it would be asked during each run of thesummoner
.exe
โtrue
if you want to createapp
folder with dummyMain.hs
file and executable target by default,false
if you donโt. If not specified it would be asked during each run of thesummoner
.test
โtrue
if you want to createtest
folder with dummySpec.hs
file and test target by default,false
if you donโt. If not specified it would be asked during each run of thesummoner
.bench
โtrue
if you want to createbenchmark
folder withMain.hs
file withgauge
library usage example by default,false
if you donโt. If not specified it would be asked during each run of thesummoner
.extensions
โ List of the default extensions to add intodefault-extensions
section in the.cabal
.warnings
โ List of the default checks and warnings to add intoghc-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 theCONTRIBUTING.md
file to use in the project.contributing.url
to provide the link to theCONTRIBUTING.md
file to use in the project. In case of the absense or wrong path/link noCONTRIBUTING
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 withoutmodule
field).module
โ Name of the module of the custom prelude youโd like to use in the project (doesnโt work withoutpackage
field).
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
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.
Changes
Summoner
1.1.0.1
- Bump up
relude
version to0.3.0
. - #146:
Migrate to
base-noprelude
.
1.1.0
- #128:
Important: Replace
summon
withsummon new
command. To create a project now the following command should be used:summon new my-project
- #82: Add stackage badges.
- #109: Fix travis cache directories.
- #117: Step into created project properly
- #110: Print executing command.
- #91: Add warning fields for ghc.
- #90: Add TOML test.
- #120: Bump up dependencies.
- #58:
Make
Licence
type safer. - #124: Print directories bold.
- #130:
Show git revision version under
--version
command. - #63:
Add
show ghc
,show license
andshow license <LICENSE_NAME>
commands. - #122: Remove github link from CHANGELOG when github is not chosen.
- #35:
Add config option to add
.stylish-haskell.yaml
to your project (via URL or file path). - Bump up
tomland
version to0.4.0
. - #138:
Remove traces of GitHub from
.cabal
file when GitHub integration is disabled. - #31:
Add config option to add
CONTRIBUTING.md
to your project (via URL or file path). - #27:
Remove
b
script.
1.0.6
- Use
relude
instead ofuniversum
. - #105:
Add
--ignore-config
option.
1.0.5
- #100:
Bump up to
ghc-8.4.3
. Add support forGhc843
in code and make it default. - Make CI badges in README be shown depending on the chosen options.
- #99:
UseTravis-specific env variable
TRAVIS_BUILD_DIR
in created travis file. - #97: Add cabal to created travis file.
- #96:
Add option to choose
cabal
,stack
or both.
1.0.4
- Bump up
tomland
to version0.3
.
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
tosummoner
. Transform the script into the package. - #54:
Rename
on
andoff
commands towith
andwithout
. - #48:
- Add ability to write configurations file. Remove
Targets
data type. UseConfig
instead for default, file and CLI configurations.
- Add ability to write configurations file. Remove
- #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
to10.3
, useghc 8.2.2
as default value.
0.0.1
- #36:
Add option for creating private repositories โ
-p | --private
.