Modern project template/scaffolding for `cabal init`

[m-renaud]

Overview

Provide a modern project template/scaffolding when running cabal init.

Target Release: cabal-install 3.0

A number of features (internal libraries, cabal.project files, etc.) have been added over the past several releases but most of them are hidden in the docs (I only found them because I took some time to read through all the Cabal user docs). We should showcase these features and provide a better scaffolding by default when initializing a package.

There are a few options for when to use this new template:

• For the LibraryAndExecutable package type.
• For a new PackageScaffolding package type.

New Template

Assume packageName: myapp.

Directory structure:

./myapp.cabal
./cabal.project
./app/Main.hs
./src/Lib.hs
./test/LibTest.hs
./benchmark/Main.hs

myapp.cabal

cabal-version: 2.4
name: myapp
version: 0.1.0.0
synopsis: My application synopsis.
description: My application description.
license: BSD-3-Clause
license-file: LICENSE
build-type: Simple

common common-deps
  default-language: Haskell2010
  build-depends:
    base ^>=4.12,
  ghc-options:
    -Wall
    -Wincomplete-uni-patterns
    -Wincomplete-record-updates
    -Wcompat
    -Widentities
    -Wredundant-constraints
    -fhide-source-paths
    -Wmissing-export-lists
    -Wpartial-fields

library my-internal-lib
  import: common-deps
  hs-source-dirs: src
  exposed-modules:
    Lib
--  build-depends:
--    deps, here,

executable myapp
  import: common-deps
  hs-source-dirs: app
  main-is: Main.hs
  ghc-options:
    -threaded
    -rtsopts
    -with-rtsopts=-N
  build-depends:
    my-internal-lib,

test-suite my-internal-lib-test
  import: common-deps
  type: exitcode-stdio-1.0
  hs-source-dirs: test
  main-is: LibTest.hs
  build-depends:
    my-internal-lib,


benchmark my-internal-lib-benchmark
  import: common-deps
  type: exitcode-stdio-1.0
  hs-source-dirs: benchmark
  main-is: Main.hs
  build-depends:
    my-internal-lib,

cabal.project

-- packages: ./*.cabal
-- with-compiler: ghc-8.6.2

Related Issues

#5005 - Cabal init project command?
#5696 - Beginner friendly cabal-install CLI

[hvr]

One nitpick: I cringe at myproject.cabal because .cabal files are package descriptions, whereas if you want to describe a project, there's the cabal.project to describe your project configuration (which may consist of one or more packages). It makes it very confusing if people refer to .cabal files as projects... ;-)

[m-renaud]

@hvr Very valid nitpick, I've updated the "package" name to be myapp instead :)

Any objections overall?

[phadej]

can't it be simply mypackage ?

[phadej]

this is easy to bikeshed issue, I simply cannot resist, sorry for that:

I assume that the goal is "show a lot of things cabal can do" ?

• tests (and benchmarks) should be demoed too. E.g. using internal library
• common stanzas

[m-renaud]

@phadej Updated the proposed template quite a bit, PTAL.

Also, we could use this new template for the SimplePackage (probably needs a better name ;P) type is selected on cabal init (see #5707). This would provide a nice scaffolding which showcases a lot of the nice new cabal features.

[m-renaud]

Let the bikeshedding begin!

[m-renaud]

What are folks thoughts on setting up the benchmark suite from the start using gauge? From what I can tell there isn't a "competing" benchmark library, unless you consider criterion which is written by the same author and for most cases it looks like gauge is just as good and has a much smaller dependency footprint.

[phadej]

gauge is forked from criterion (therefore same author, maintainers are different); people have strong opinions about these. FWIW criterion has a lot more material about it, starting with http://www.serpentine.com/criterion/tutorial.html

[m-renaud]

same author, maintainers are different ... people have strong opinions about these

Hmm, I don't want to step on anyone's toes or play "favorites", I just want there to be a good starting place for folks when they create a new project. My reason for leaning towards gauge was the incredibly small dependency set.

FWIW criterion has a lot more material about it

Currently true, yes. Although I'm pretty sure that changing import Criterion to import Gauge and following that tutorial will give you almost identical results, so I think in practice the set of material about them may not be that different.

[hvr]

@m-renaud I'm not sure we should even be providing too featureful templates in cabal which promote specific packages (and if we did, I'd strongly be against promoting gauge over the established criterion framework). I'd rather prefer to keep cabal init "lean" in the sense of KISS, and leave more advanced templating/scaffolding to tools such as summoner to allow faster dev cycles and reduce feature creep in cabal proper; and also external tools/projects can handle the controversial issues (tasty vs hspec vs test-framework vs ... / criterion vs gauge vs Bench) by maintaining a templates repository -- something which I'd rather not want to burden cabal development with.

[m-renaud]

@hvr

I'm not sure we should even be providing too featureful templates in cabal which promote specific packages

Agreed, I've removed all references to specific packages above, the main function can just have something like putStrLn "TODO: Write benchmarks" and same for tests, I DO think there is benefit to automatically generating a benchmark and test-suite stanza for the library though.

and leave more advanced templating/scaffolding to tools such as summoner

I'm +1 on this too, it would be nice if you could use Stack templates from summoner. It looks like someone opened an issue against summoner to support common stanzas, I'll open a few more issues there when I get a chance.