summoner
Tool for creating completely configured production Haskell projects.
https://github.com/kowainik/summoner
Version on this page: | 1.0.5 |
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.0.5@sha256:61db55a6428c9b55dd1584aa86ca8c477b6a5f2ba6741d6ac19e679cad83aa84,3241
๐ฎ Summoner
This is tool for creating completely configured production Haskell projects.
Demo
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:
$ cabal install summoner
or
$ 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:
- Default configuration file (
~/.summoner.toml
). - Explicitly specified configuration file by
--file FILENAME
option (used instead of 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
.bscript
โtrue
if you want to include build script by default,false
if you donโt. 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
.
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 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 [--cabal] [--stack]
[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
--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
-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
Acknowledgments
This project was inspired by Aelve/new-hs,
which is the tool with the same goal but itโs using
cabal
for creating projects.
Changes
Summoner
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
.