Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add warning and note about cabal init and script #10327

Merged
merged 1 commit into from
Sep 24, 2024
Merged

Add warning and note about cabal init and script #10327

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 34 additions & 1 deletion doc/getting-started.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,18 @@ The ``myapp.cabal`` file is a package description file, commonly referred to as
hs-source-dirs: app
default-language: Haskell2010

.. warning::

The version bounds on base, a boot library distributed with GHC
[#boot-packages]_, are tied to the GHC version visible when ``cabal init``
is run. If run with a later version of GHC you might see a difference in the
version bounds.

.. code-block:: diff

- build-depends: base ^>=4.19.0.0
+ build-depends: base ^>=4.20.0.0

It contains metadata (package name and version, author name, license, etc.) and sections
to define package components. Components can be used to split large codebases into smaller,
more managable building blocks.
Expand Down Expand Up @@ -189,7 +201,7 @@ the following file named ``myscript``:
#!/usr/bin/env cabal
{- cabal:
build-depends:
base ^>=4.19.0.0,
base,
haskell-say ^>=1.0.0.0
-}

Expand All @@ -198,6 +210,21 @@ the following file named ``myscript``:
main :: IO ()
main = haskellSay "Hello, Haskell!"

.. note::

Widening or dropping version bound constraints on *packages included with
the compiler* [#boot-packages]_, like ``base``, may allow single-file
scripts to run with a wider range of compiler versions.

.. code-block:: diff

build-depends:
- base ^>=4.19.0.0,
+ base,

The necessary sections of a ``.cabal`` file are placed
directly into the script as a comment.

The necessary sections of a package description that would otherwise be in a
``.cabal`` file are placed directly into the script as a comment.

Expand Down Expand Up @@ -237,3 +264,9 @@ some of the resources on the Haskell website's `documentation page
Cabal on the :doc:`What Cabal does <cabal-context>` page.

.. _Cabal-7070: https://errors.haskell.org/messages/Cabal-7070/

.. [#boot-packages] Packages included with the compiler are also called boot
packages. Each GHC compiler version has accompanying `release notes`_ that
list these included packages.

.. _release notes: https://downloads.haskell.org/ghc/latest/docs/users_guide/release-notes.html
Loading