Extend `.cabal` format with "common" definition stanzas

[hvr]

( this is a project task description for the upcoming https://github.com/haskell/cabal/wiki/Hackathon2015 )

One complaint about the .cabal format is that there's avoidable duplication when multiple stanzas requiring to repeat some shared properties are involved (most notably build-depends)

Here's an example how common stanzas could be used:

name: thispkg
version: 1.2.3
cabal-version: >=2.0

-- ...

flag small_base
  description: Choose the new smaller, split-up base package.

-- unnamed global common stanza included implicitly in all library/executable/benchmark/test stanzas
common
  build-depends: base-orphans < 1

-- named common stanza which needs to be explicitly included
common cdef1
  hs-source-dirs: src

  build-depends: text
  if flag(small_base)
    build-depends: base >=2.1 && <5, array, containers, directory
  else
    build-depends: base >= 1.0

library
  include cdef1
  build-depends: parsec
  other-modules:

test-suite tests
  type: exitcode-stdio-1.0
  main-is: test.hs
  include cdef1
  build-depends: thispkg, tasty

benchmark bench1 
  type: exitcode-stdio-1.0
  main-is: bench1.hs
  include cdef1
  build-depends: thispkg, criterion

In the example above a single common section named cdef1 is defined, which is included by all 3 real stanzas. include cdef acts as if the respective common stanza's body was inserted in place of include cdef.

---

Possible extensions

• reserve a few special common stanza ids all, library, test-suites, and benchmark to declare common stanzas that are implicitly included by the respective named real stanza. In the example above we could have used common all instead of common cdef1 and all include cdef1 simply removed.
• allow recursive (but acyclic) includes. I.e. allow common stanzas to include other common stanzas.

/cc @dcoutts

---

@dcoutts suggests to support both,

1. named sections and explicit include at uses sites
2. unnamed global (implicit include into start of all sections) (would subsume Package global build-depends should apply constraints to all components #3404)

Moreover, we'd want this mechanism not only for .cabal files but also for cabal's config files. For non-.cabal files we want to reuse the infrastructure for file-backed include files (include-file ./some-ast-frament.inc).

---

refinement: common stanzas ought to be typed so we can catch mistakes early on during parsing already, see #2832 (comment)

[phadej]

As I can see from proposal, include commands can occur in any position.

Does this imply that they are handled by parser, i.e. not visible in GenericPackageDescription.

From tooling point of view, I'd like to see them in GenericPackageDescription, but as structure of data type doesn't easily support "include anywhere" approach: CondTree would need to be on [Either IncludeField a]. Yet "include at the beginning of the section" would be simpler: ([IncludeField], a):

Shortly, which:

-- current
condExecutables :: [(String, CondTree ConfVar [Dependency] Executable)]
-- anywhere, each block consists of includefields and "the thing"
condExecutables :: [(String, CondTree ConfVar [Dependency] [Either IncludeField Executable])]
-- only on top
condExecutables :: [(String, CondTree ConfVar [Dependency] ([IncludeField], Executable))]

[phadej]

Another comment, include commands will occur in cabal.project field to, meaning to include other file. Maybe we can think this naming thru a bit better. Probably common stanzas would be nice for project files too.

[hvr]

@phadej as to the file-including, there's two ideas on the table, either use non-overloaded include-file to refer to files, or infer include referring to a file by occurence of /s. E.g. include ./foo would refer to a file, whereas include foo would refer to a local named include-stanza. One could have optional file:/common: prefixes for overriding the detection, and allow for additional types (e.g. http:)

Then include file:foo would refer to a file foo rather than a common stanza named foo.

[phadej]

Ok, I agree, let's keep GenericPackageDescription as something rest of Cabal uses. See #3614

[phadej]

Question: should stanzas be declared before used?

If yes, then recursive acyclic stanzas are easy to implement (as stanzas overall)

I have no preference on this.

[23Skidoo]

Question: should stanzas be declared before used?

I'd say yes, it makes sense to nudge users to put common stanzas on top.

[phadej]

Motivated by possible in-parser implementation. There are two ways to parse common stanza: parse them beforehand or not.

• Parsing beforehand is difficult, because you don't know where they are inserted, i.e. which fields are valid.
• Treating them as macro is simpler from implementation pov:
  • when parsing sections, if include foo is encountered, insert stanza's fields and continue.
  • there would be no errors if stanza is not used (yet warning that it's unused)
  • warnings and errors would be reported as many times as it's used.