🔮 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 a tool for scaffolding fully configured batteries-included production-level Haskell projects.

Do you want to create a library that is to be uploaded to Hackage/Stackage, that builds with both Cabal and Stack and supports the latest three major GHC versions? Or are you building a production application which uses a custom prelude and has CI with GitHub Actions or Travis Linux and AppVeyors Windows checks? Maybe do you want to play with your idea in a single module without introducing the whole complexity of the Haskell projects? Summoner can help you do all that with minimal effort from you - it can even upload the project to GitHub if you wish!

By the way, Summoner operates as either CLI or TUI application, so you can choose what you are more comfortable with and install only the required one.

Structure

• Demo
  • TUI demo
  • CLI demo
  • Examples
• Features
• Get started
  • Prerequisites
  • Installation
    • Summon-TUI
      • TUI: download binary
      • TUI: Homebrew
      • TUI: Ubuntu
      • TUI: from Hackage
      • TUI: from source
    • Summon-CLI
      • CLI: download binary
      • CLI: Homebrew
      • CLI: Ubuntu
      • CLI: from Hackage
      • CLI: from source
  • Setup
• Usage
  • Command-line arguments
  • File configuration
  • TUI
  • CLI
• FAQ
• For Developers
  • Build
  • Test
  • Run
• Acknowledgments

Demo

[Back to the Table of Contents] ↑

TUI demo

[Back to the Table of Contents] ↑

CLI demo

[Back to the Table of Contents] ↑

Examples

[Back to the Table of Contents] ↑

You can also see complete examples in the following folder:

• summon-cli/examples/: Examples of scaffolded projects

The directory contains the following examples:

• cabal-minimal: Minimal Haskell project with the Cabal-only support, default settings and all of the integrations disabled.
• cabal-full: Cabal-only project with all integrations enabled.
• stack-full: Stack-only project with all integrations enabled.
• full-batteries: All batteries-included project which supports both build tools and shows every Summoner feature.

Features

[Back to the Table of Contents] ↑

Summoner is a tool that combines predefined configurations, command-line arguments and a chosen interface.

To fully understand the power in your hands with the help of Summoner, please read this section.

Below you can see highlighted features in different categories.

Project

[Back to the Table of Contents] ↑

Features related to the structure and content of the generated projects.

• Support for Cabal and Stack build tools.

• Ability to pick stanzas (library, executable, test-suite, benchmark).

• Usage of common stanza to reduce .cabal file's boilerplate.

• Option to include an alternative prelude, if desired. The project would then use the mixins technique.

• Whole Hackage-upload checklist support (exhaustive .cabal file, PVP versioning, GHC options, conventional meta files).

• Support for multiple GHC versions, with thoughtful reflection on project meta, base versions (e.g. base >= 4.9 && < 4.13), etc.

• Ability to create runnable Haskell scripts.

• Different license support: MIT, BSD-2-Clause, BSD-3-Clause, GPL-2.0, GPL-3.0, LGPL-2.1, LGPL-3.0, AGPL-3.0, Apache-2.0, MPL-2.0, ISC, None (without file).

• Creation of the CHANGELOG.md file with PVP versioning policy.

• Ability to include any custom files (including .stylish-haskell.yaml, CONTRIBUTING.md, CODEOWNERS, FUNDING.yml etc.).

• Usage of the ghc-options field with sensible defaults.

  If ghc-options are not explicitly stated in the configuration file, then the following list of GHC flags is added to all stanzas:

  -Wall
  -Wcompat
  -Widentities
  -Wincomplete-uni-patterns
  -Wincomplete-record-updates
  -Wredundant-constraints
  -Wnoncanonical-monad-instances
  -fhide-source-paths              (GHC ⩾ 8.2)
  -Wmissing-export-lists           (GHC ⩾ 8.4)
  -Wpartial-fields                 (GHC ⩾ 8.4)
  -Wmissing-deriving-strategies    (GHC ⩾ 8.8)
  -fwrite-ide-info                 (GHC ⩾ 8.8)
  -hiedir=.hie                     (GHC ⩾ 8.8)
  -Wunused-packages                (GHC ⩾ 8.10)
  -Wincomplete-record-selectors    (GHC ⩾ 9.10)
  -Wdeprecated-type-abstractions   (GHC ⩾ 9.10)
  -Wdata-kinds-tc                  (GHC ⩾ 9.10)
  -Wdefaulted-exception-context    (GHC ⩾ 9.10)
  -Wview-pattern-signatures        (GHC ⩾ 9.12)
  

  Besides, the following GHC options are added to the executable, tests and benchmark stanzas:

  -threaded
  -rtsopts
  -with-rtsopts=-N
  

GitHub

[Back to the Table of Contents] ↑

• Initialisation of the git repository inside the project folder.
• Initial commit creation.
• Uploading the repository to GitHub.
• Exhaustive .gitignore file.
• Formation of the README file with Hackage, Stackage and CI badges.
• Linking to the GitHub repository in the .cabal file.
• Ability to include your custom GitHub meta files: CONTRIBUTING.md, CODEOWNERS, .github/pull_request_template.md, etc.
• Guessing user credentials from the local .gitconfig file.

CI

[Back to the Table of Contents] ↑

• Generation of the .travis.yml file that runs build and tests on CI under Linux using Dead simple Haskell Travis Settings for Cabal and Stack.
• Generation of the appveyor.yaml file which runs build and tests on CI under Windows.
• Generation of the .github/workflows/ci.yml file that runs build and tests on GitHub Actions CI under Linux using Cabal.
• Configuration matrix on CI to build with multiple GHC versions and various build tools.
• -Werror is enabled on CI not to miss any warnings.
• Run HLint checks on CI.

Others

[Back to the Table of Contents] ↑

• Carefully collected Haskell project best practices gathered in your projects' scaffold.
• Generate beginner-friendly default configuration using the summon config command.
• Ability to create a project in the offline mode.
• Ability to check GHC-specific versions of the corresponding base library and Stackage snapshot resolver via summon show ghc command.

Project structure example

[Back to the Table of Contents] ↑

This is an example of the project hierarchy you can get if you are running Summoner's new command with all options enabled:

project-name/
├── app/
│   └── Main.hs
├── benchmark/
│   └── Main.hs
├── src/
│   ├── ProjectName.hs
│   └── Prelude.hs
├── test/
│   └── Spec.hs
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── project-name.cabal
├── README.md
├── Setup.hs
├── stack.yaml
├── stack-8.6.5.yaml
├── appveyor.yml
├── .git
├── .gitignore
├── .stylish-haskell.yaml
└── .travis.yml

Get started

[Back to the Table of Contents] ↑

Prerequisites

[Back to the Table of Contents] ↑

To start using Summoner make sure that you have the following tools installed on your machine:

• git ⩾ 2.28 – to initialize the GitHub repo.
• gh – to upload the project to GitHub.
• curl – to download licenses.

We also have minimal version requirements for build tools:

• Cabal ⩾ 3.0
• Stack ⩾ 2.1.3

However, it is always recommended to use the newest versions of build tools.

Installation

[Back to the Table of Contents] ↑

Summon contains two executables:

• summon: scaffold projects using interactive CLI mode.
• summon-tui: scaffold projects using TUI.

Below you can find the description of h