.. _spec-history: ================================================== 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: 3.0`` ---------------------- * Added the :pkg-field:`extra-dynamic-library-flavours` field to specify non-trivial variants of dynamic flavours. It is :pkg-field:`extra-library-flavours` but for shared libraries. Mainly useful for GHC's RTS library. * Free text fields (e.g. :pkg-field:`description`) preserve empty lines and indentation. In other words, you don't need to add dots for blank lines. * License fields use identifiers from SPDX License List version ``3.6 2019-07-10`` * Remove deprecated ``hs-source-dir``, :pkg-field:`extensions` and :pkg-field:`build-tools` fields. * Common stanzas are now allowed also in the beginnning of conditional sections. In other words, the following is valid :: library import deps if flag(foo) import foo-deps * Allow redundant leading or trailing commas in package fields with optional commas, such as :pkg-field:`exposed-modules` * Require fields with optional commas to consistently omit or place commas between elements. * Changed the behavior of :pkg-field:`extra-bundled-libraries` field. The naming convention of dynamic library files (e.g. generated by a custom build script) has changed. For library names prefixed with "C", the dynamic library file name(s) must be of the form `lib.*` instead of the old `libC-ghc.` * New set-notation syntax for ``==`` and ``^>=`` operators, see :pkg-field:`build-depends` field documentation for examples. * Allow more whitespace in :pkg-field:`mixins` field * Wildcards are disallowed in :pkg-field:`pkgconfig-depends`, Yet the pkgconfig format is relaxed to accept e.g. versions like ``1.1.0h``. * New :pkg-field:`autogen-includes` for specifying :pkg-field:`install-includes` which are autogenerated (e.g. by a ``configure`` script). * New :pkg-field:`asm-sources` and :pkg-field:`asm-options` fields added for suppporting bundled foreign routines implemented in assembler. * New :pkg-field:`cmm-sources` and :pkg-field:`cmm-options` fields added for suppporting bundled foreign primops implemented in C--. ``cabal-version: 2.4`` ---------------------- * Wildcard matching has been expanded. All previous wildcard expressions are still valid; some will match strictly more files than before. Specifically: * Double-star (``**``) wildcards are now accepted for recursive matching immediately before the final slash; they must be followed by a filename wildcard (e.g., ``foo/**/*.html`` is valid; ``foo/**/bar/*.html`` and ``foo/**/**/*.html``, ``foo/**/bar.html`` are all invalid). As ``**`` was an error in globs before, this does not affect any existing ``.cabal`` files that previously worked. * Wildcards now match when the pattern's extensions form a suffix of the candidate file's extension, rather than requiring strict equality (e.g., previously ``*.html`` did not match ``foo.en.html``, but now it does). * 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:`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 (using SPDX license list version ``3.0 2017-12-28``). * 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. * Add support for :ref:`internal library stanzas `. * New CPP Macro ``CURRENT_PACKAGE_VERSION``. ``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. * CPP Macros ``VERSION_$pkgname`` and ``MIN_VERSION_$pkgname`` are now also generated for the current package. * New CPP Macros ``CURRENT_COMPONENT_ID`` and ``CURRENT_PACKAGE_KEY``. * New :pkg-field:`extra-framework-dirs` field added for specifying extra locations to find OS X frameworks. ``cabal-version: 1.22`` ----------------------- * New :pkg-field:`library:reexported-modules` field. * Support for ``-none`` version constraint added to :pkg-field:`build-depends`. * New :pkg-field:`license` type ``ISC`` added. ``cabal-version: 1.20`` ----------------------- * Add support for new :pkg-field:`license-files` field for declaring multiple license documents. * New CPP Macro ``MIN_TOOL_VERSION_$buildtool``. * New :pkg-field:`license` types ``BSD2`` and ``MPL-2.0`` added. ``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`` and ``AGPL-3`` 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