Skip to content

GitLab

C
Cabal
Commit 97d7101a authored by Herbert Valerio Riedel's avatar Herbert Valerio Riedel 🕺
Browse files
Options

Significantly extend cabal spec history [ci skip] 

and clean up various aspects related to the `cabal-version` field
parent 5110bfff
Hide whitespace changes
Inline Side-by-side
Showing with 220 additions and 45 deletions
Cabal/doc/cabaldomain.py
View file @ 97d7101a
......@@ -8,10 +8,10 @@ data for objects described with directives described here.
Most directives have at least following optional arguments
`:since: 1.23`
`:since: 1.24`
version of Cabal in which feature was added.
`:deprecated: 1.23`
`:deprecated: 1.24`
`:deprecated:`
Feature was deprecatead, and optionally since which version.
......
Cabal/doc/developing-packages.rst
View file @ 97d7101a
......@@ -572,7 +572,7 @@ The HUnit package contains a file ``HUnit.cabal`` containing:
author: Dean Herington
license: BSD3
license-file: LICENSE
cabal-version: >= 1.10
cabal-version: 1.12
build-type: Simple
library
......@@ -656,6 +656,8 @@ is governed by system-dependent parameters, if you specify a little more
(see the section on `system-dependent parameters`_).
A few packages require `more elaborate solutions <more complex packages>`_.
.. _pkg-desc:
Package descriptions
--------------------
......@@ -794,28 +796,25 @@ describe the package as a whole:
package-version = 1*DIGIT *("." 1*DIGIT)
.. pkg-field:: cabal-version: >= x.y
The version of the Cabal specification that this package description
uses. The Cabal specification does slowly evolve, introducing new
features and occasionally changing the meaning of existing features.
By specifying which version of the spec you are using it enables
programs which process the package description to know what syntax
to expect and what each part means.
.. pkg-field:: cabal-version: x.y[.z]
For historical reasons this is always expressed using *>=* version
range syntax. No other kinds of version range make sense, in
particular upper bounds do not make sense. In future this field will
specify just a version number, rather than a version range.
The version of the Cabal specification that this package
description uses. The Cabal specification does slowly evolve (see
also :ref:`spec-history`), introducing new features and
occasionally changing the meaning of existing features. By
specifying which version of the specification you are using it
enables programs which process the package description to know
what syntax to expect and what each part means.
The version number you specify will affect both compatibility and
behaviour. Most tools (including the Cabal library and cabal
behaviour. Most tools (including the Cabal library and the ``cabal``
program) understand a range of versions of the Cabal specification.
Older tools will of course only work with older versions of the
Cabal specification. Most of the time, tools that are too old will
recognise this fact and produce a suitable error message.
Cabal specification that was known at the time. Most of the time,
tools that are too old will recognise this fact and produce a
suitable error message.
As for behaviour, new versions of the Cabal spec can change the
As for behaviour, new versions of the Cabal specification can change the
meaning of existing syntax. This means if you want to take advantage
of the new meaning or behaviour then you must specify the newer
Cabal version. Tools are expected to use the meaning and behaviour
......@@ -829,6 +828,40 @@ describe the package as a whole:
old syntax. Please consult the user's guide of an older Cabal
version for a description of that syntax.
Starting with ``cabal-version: 2.2`` this field is only valid if
fully contained in the very first line of a package description
and ought to adhere to the ABNF_ grammar
.. code-block:: abnf
newstyle-spec-version-decl = "cabal-version" *WS ":" *WS newstyle-spec-version *WS
newstyle-spec-version = NUM "." NUM [ "." NUM ]
NUM = DIGIT0 / DIGITP 1*DIGIT0
DIGIT0 = %x30-39
DIGITP = %x31-39
WS = %20
.. note::
For package descriptions using a format prior to
``cabal-version: 1.12`` the legacy syntax resembling a version
range syntax
.. code-block:: cabal
cabal-version: >= 1.10
needs to be used.
This legacy syntax is supported up until ``cabal-version: >=
2.0`` it is however strongly recommended to avoid using the
legacy syntax. See also :issue:`4899`.
.. pkg-field:: build-type: identifier
:default: ``Custom`` or ``Simple``
......@@ -892,7 +925,11 @@ describe the package as a whole:
type.
.. pkg-field:: license-file: filename
See :pkg-field:`license-files`.
.. pkg-field:: license-files: filename list
:since: 1.20
The name of a file(s) containing the precise copyright license for
this package. The license file(s) will be installed with the
......@@ -1047,6 +1084,7 @@ describe the package as a whole:
a limited form of ``*`` wildcards in file names.
.. pkg-field:: extra-doc-files: filename list
:since: 1.18
A list of additional files to be included in source distributions,
and also copied to the html directory when Haddock documentation is
......@@ -1137,8 +1175,7 @@ The library section should contain the following fields:
Supported only in GHC 8.2 and later. A list of `module signatures <https://downloads.haskell.org/~ghc/master/users-guide/separate_compilation.html#module-signatures>`__ required by this package.
Module signatures are part of the
`Backpack <https://ghc.haskell.org/trac/ghc/wiki/Backpack>`__ extension to
Module signatures are part of the Backpack_ extension to
the Haskell module system.
Packages that do not export any modules and only export required signatures
......@@ -1426,6 +1463,9 @@ build information fields (see the section on `build information`_).
:pkg-field:`hs-source-dirs`. Further, while the name of the file may
vary, the module itself must be named ``Main``.
Starting with ``cabal-version: 1.18`` this field supports
specifying a C, C++, or objC source file as the main entry point.
.. pkg-field:: scope: token
:since: 2.0
......@@ -2268,6 +2308,7 @@ system-dependent values for these fields.
appropriately.
.. pkg-field:: asm-sources: filename list
:since: 2.2
A list of assembly source files to be compiled and linked with the
Haskell files.
......@@ -2292,6 +2333,7 @@ system-dependent values for these fields.
when the package is loaded with GHCi.
.. pkg-field:: extra-bundled-libraries: token list
:since: 2.2
A list of libraries that are supposed to be copied from the build
directory alongside the produced Haskell libraries. Note that you
......@@ -2329,6 +2371,12 @@ system-dependent values for these fields.
command-line arguments with the :pkg-field:`cc-options` and the
:pkg-field:`cxx-options` fields.
.. pkg-field:: asm-options: token list
:since: 2.2
Command-line arguments to be passed to the assembler when compiling
assembler code. See also :pkg-field:`asm-sources`.
.. pkg-field:: ld-options: token list
Command-line arguments to be passed to the linker. Since the
......@@ -2358,6 +2406,7 @@ system-dependent values for these fields.
is ignored on all other platforms.
.. pkg-field:: extra-frameworks-dirs: directory list
:since: 1.24
On Darwin/MacOS X, a list of directories to search for frameworks.
This entry is ignored on all other platforms.
......@@ -2376,7 +2425,7 @@ system-dependent values for these fields.
library
build-depends:
foo >= 1.2.3 && < 1.3
foo ^>= 1.2.3
mixins:
foo
......@@ -2409,9 +2458,7 @@ system-dependent values for these fields.
if the provided renaming clause has whitespace after the opening
parenthesis. This will be fixed in future versions of Cabal.
See issues `#5150 <https://github.com/haskell/cabal/issues/5150>`__,
`#4864 <https://github.com/haskell/cabal/issues/4864>`__, and
`#5293 <https://github.com/haskell/cabal/pull/5293>`__.
See issues :issue:`5150`, :issue:`4864`, and :issue:`5293`.
There can be multiple mixin entries for a given package, in effect creating
multiple copies of the dependency:
......@@ -2441,10 +2488,9 @@ system-dependent values for these fields.
mixins:
sigonly requires (SigOnly.SomeSig as AnotherSigOnly.SomeSig)
See the :pkg-field:`signatures` field for more details.
See the :pkg-field:`library:signatures` field for more details.
Mixin packages are part of the `Backpack
<https://ghc.haskell.org/trac/ghc/wiki/Backpack>`__ extension to the
Mixin packages are part of the Backpack_ extension to the
Haskell module system.
The matching of the module signatures required by a
......@@ -2457,7 +2503,7 @@ system-dependent values for these fields.
.. Warning::
Backpack has the limitation that implementation modules that instantiate
Backpack_ has the limitation that implementation modules that instantiate
signatures required by a :pkg-field:`build-depends` dependency can't
reside in the same component that has the dependency. They must reside
in a different package dependency, or at least in a separate internal
......@@ -2823,7 +2869,7 @@ Starting with Cabal-2.2 it's possible to use common build info stanzas.
ghc-options: -Wall
common test-deps
build-depends: tasty
build-depends: tasty ^>= 0.12.0.1
library
import: deps
......@@ -3112,7 +3158,7 @@ complex build hooks for this poweruser case.
.. pkg-field:: autogen-modules: module list
:since: 2.0
.. TODO: document autogen-modules field
.. todo:: document autogen-modules field
Right now :pkg-field:`executable:main-is` modules are not supported on
:pkg-field:`autogen-modules`.
......
Cabal/doc/file-format-changelog.rst
View file @ 97d7101a
Cabal file format changelog
===========================
.. _spec-history:
Changes in 2.4
--------------
==================================================
Package description format specification history
==================================================
:ref:`pkg-desc` need to specify the version of the
specification they need to be interpreted in via the
:pkg-field:`cabal-version` declaration. The following list describes
changes that occurred in each version of the cabal specification
relative to the respective preceding *published* version.
.. note::
The sequence of specification version numbers is *not*
contiguous because it's synchronised with the version of the
``Cabal`` library. As a consequence, only *even* versions are
considered proper published versions of the specification as *odd*
versions of the ``Cabal`` library denote unreleased development
branches which have no stability guarantee.
``cabal-version: 2.4``
----------------------
* Wildcard matching has been expanded. All previous wildcard
expressions are still valid; some will match strictly more files
......@@ -23,3 +41,112 @@ Changes in 2.4
* License fields use identifiers from SPDX License List version
``3.2 2018-07-10``
``cabal-version: 2.2``
----------------------
* New :pkg-section:`common` stanzas and :pkg-field:`import`
pseudo-field added.
* New :pkg-field:`library:virtual-modules` field added.
* New :pkg-field:`cxx-sources` and :pkg-field:`cxx-options` fields
added for suppporting bundled foreign routines implemented in C++.
* New :pkg-field:`asm-sources` and :pkg-field:`asm-options` fields
added for suppporting bundled foreign routines implemented in
assembler.
* New :pkg-field:`extra-bundled-libraries` field for specifying
additional custom library objects to be installed.
* Extended ``if`` control structure with support for ``elif`` keyword.
* Changed default rules of :pkg-field:`build-type` field to infer
"build-type:" for "Simple"/"Custom" automatically.
* :pkg-field:`license` field syntax changed to require SPDX
expression syntax.
* Allow redundant leading or trailing commas in package fields (which
require commas) such as :pkg-field:`build-depends`.
``cabal-version: 2.0``
----------------------
* New :pkg-field:`library:signatures` and :pkg-field:`mixins` fields
added for supporting Backpack_.
* New :pkg-field:`build-tool-depends` field added for adding
build-time dependencies of executable components.
* New :pkg-field:`custom-setup:autogen-modules` field added for declaring modules
which are generated at build time.
* Support for new PVP_ caret-style version operator (``^>=``) added to
:pkg-field:`build-depends`.
* Add support for new :pkg-section:`foreign-library` stanza.
``cabal-version: 1.24``
----------------------
* New :pkg-section:`custom-setup` stanza and
:pkg-field:`custom-setup:setup-depends` field added for specifying dependencies
of custom ``Setup.hs`` scripts.
* Macros ``VERSION_$pkgname`` and ``MIN_VERSION_$pkgname`` are now
also generated for the current package.
* New :pkg-field:`extra-framework-dirs` field added for specifying
extra locations to find OS X frameworks.
``cabal-version: 1.22``
----------------------
* New :pkg-field:`license` type ``UnspecifiedLicense`` added.
* New :pkg-field:`library:reexported-modules` field.
* Support for ``-none`` version constraint added to
:pkg-field:`build-depends`.
``cabal-version: 1.20``
----------------------
* Add support for new :pkg-field:`license-files` field for declaring
multiple license documents.
``cabal-version: 1.18``
----------------------
* Add support for new :pkg-field:`extra-doc-files` field for
specifying extra file assets referenced by the Haddock
documentation.
* New :pkg-field:`license` type ``AGPL`` added.
* Add support for specifying a C/C++/obj-C source file in
:pkg-field:`executable:main-is` field.
* Add ``getSysconfDir`` operation to ``Paths_`` API.
``cabal-version: 1.16``
----------------------
.. todo::
this needs to be researched; there were only few changes between
1.12 and 1.18;
``cabal-version: 1.12``
----------------------
* Change syntax of :pkg-field:`cabal-version` to support the new recommended
``cabal-version: x.y`` style
.. include:: references.inc
Cabal/doc/nix-local-build.rst
View file @ 97d7101a
......@@ -1318,7 +1318,7 @@ Object code options
--enable-split-sections
--disable-split-sections
:synopsis: Use GHC's split sections feature.
:since: 2.1
:since: 2.2
:default: False
......@@ -1377,7 +1377,7 @@ Object code options
--enable-library-stripping
--disable-library-stripping
:synopsis: Strip installed libraries.
:since: 1.19
:since: 1.20
When installing binary libraries, run the ``strip`` program on the
binary, saving space on the file system. See also
......@@ -1473,7 +1473,7 @@ Dynamic linking options
.. cfg-field:: relocatable:
--relocatable
:synopsis: Build relocatable package.
:since: 1.21
:since: 1.22
:default: False
......@@ -1556,7 +1556,7 @@ Profiling options
--enable-profiling
--disable-profiling
:synopsis: Enable profiling builds.
:since: 1.21
:since: 1.22
:default: False
......@@ -1578,7 +1578,7 @@ Profiling options
.. cfg-field:: profiling-detail: level
--profiling-detail=level
:synopsis: Profiling detail level.
:since: 1.23
:since: 1.24
Some compilers that support profiling, notably GHC, can allocate
costs to different parts of the program and there are different
......@@ -1618,7 +1618,7 @@ Profiling options
.. cfg-field:: library-profiling-detail: level
--library-profiling-detail=level
:synopsis: Libraries profiling detail level.
:since: 1.23
:since: 1.24
Like :cfg-field:`profiling-detail`, but applied only to libraries
......@@ -1643,7 +1643,7 @@ Profiling options
--enable-library-profiling
--disable-library-profiling
:synopsis: Build libraries with profiling enabled.
:since: 1.21
:since: 1.22
:default: False
......@@ -1657,7 +1657,7 @@ Profiling options
--enable-executable-profiling
--disable-executable-profiling
:synopsis: Build executables with profiling enabled.
:since: 1.21
:since: 1.22
:default: False
......@@ -1675,7 +1675,7 @@ Coverage options
--enable-coverage
--disable-coverage
:synopsis: Build with coverage enabled.
:since: 1.21
:since: 1.22
:default: False
......@@ -1689,7 +1689,7 @@ Coverage options
.. cfg-field:: library-coverage: boolean
--enable-library-coverage
--disable-library-coverage
:since: 1.21
:since: 1.22
:deprecated:
:default: False
......
Cabal/doc/references.inc
View file @ 97d7101a
......@@ -22,3 +22,5 @@
.. _cpphs: http://projects.haskell.org/cpphs/
.. _ABNF: https://tools.ietf.org/html/rfc5234
.. _Backpack: https://ghc.haskell.org/trac/ghc/wiki/Backpack
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment