# Cabal

[![Hackage version](https://img.shields.io/hackage/v/Cabal.svg?label=Hackage)](https://hackage.haskell.org/package/Cabal)
[![Stackage version](https://www.stackage.org/package/Cabal/badge/lts?label=Stackage)](https://www.stackage.org/package/Cabal)
[![Documentation Status](http://readthedocs.org/projects/cabal/badge/?version=latest)](http://cabal.readthedocs.io/en/latest/?badge=latest)
[![IRC chat](https://img.shields.io/badge/chat-via%20libera-brightgreen.svg)](https://web.libera.chat/#hackage)
[![Matrix chat](https://img.shields.io/badge/chat-via%20matrix-brightgreen.svg)](https://matrix.to/#/#hackage:matrix.org)
[![GitLab pipeline status](https://gitlab.haskell.org/haskell/cabal/badges/cabal-head/pipeline.svg?key_text=Release%20CI%20Early%20Warning&key_width=150)](https://gitlab.haskell.org/haskell/cabal/-/commits/cabal-head)

<img src="Cabal-light.png" align="right">

This Cabal Git repository contains the following main packages:

 * [Cabal](Cabal/README.md): the Cabal library package ([license](Cabal/LICENSE))
 * [Cabal-hooks](Cabal-hooks/README.md): the library providing an API for the Cabal `Hooks` build type ([license](Cabal-hooks/LICENSE))
 * [Cabal-syntax](Cabal-syntax/README.md): the `.cabal` file format library ([license](Cabal-syntax/LICENSE))
 * [cabal-install](cabal-install/README.md): the package containing the `cabal` tool ([license](cabal-install/LICENSE))
 * [cabal-install-solver](cabal-install-solver): the package containing the solver component of the `cabal` tool ([license](cabal-install-solver/LICENSE))

The canonical upstream repository is located at
https://github.com/haskell/cabal.

Proposals for the Cabal project
-------------------------------

The [proposals process](proposals.md) is the mechanism which developers can gain
the necessary consensus to make larger changes to the Cabal ecosystem.

* It is light-weight, a PR is opened and discussed on [cabal-proposals](https://github.com/haskell/cabal-proposals/) repo with a fixed discussion period.
* It is developer-led, final decisions are made by developers at the Cabal developers meeting.
* It is flexible, there is no formal voting procedure, decisions are made by [rough consensus](https://datatracker.ietf.org/doc/html/rfc7282).

Ways to get the `cabal-install` binary
--------------------------------

1. _GHCup_ (**preferred**): get GHCup using [the directions on its website](https://www.haskell.org/ghcup/) and run:

    ```
    ghcup install --set cabal latest
    ```

2. _[Download from official website](https://www.haskell.org/cabal/download.html)_:
    the `cabal-install` binary download for your platform should contain the `cabal` executable.

#### Preview Releases

_Getting unreleased versions of `cabal-install`_: gives you a chance to try out yet-unreleased features.
Currently, we only provide binaries for `x86_64` platforms.

1. _GitHub preview release built from the tip of the `master` branch_: [download from GitHub](https://github.com/haskell/cabal/releases/tag/cabal-head) or use this GHCup command to install:

    ```
    ghcup install cabal -u https://github.com/haskell/cabal/releases/download/cabal-head/cabal-head-Linux-x86_64.tar.gz head
    ```

    Replace "Linux" with "Windows" or "macOS" as appropriate.

    The default Linux build is dynamically linked against `zlib`, `gmp` and `glibc`.
    You will need to have appropriate versions of these libraries installed to use it.
    Alternatively a statically linked "Linux-static" binary is also provided.

    You might need to add the following to your `cabal.project` file
    if your build fails because of an out-of-date `Cabal` library:
    ```
    allow-newer:
      *:Cabal,
      *:Cabal-syntax

    source-repository-package
        type: git
        location: https://github.com/haskell/cabal.git
        subdir: Cabal Cabal-syntax
    ```


2. Even more cutting-edge binaries built from pull requests are always available
   from the `Validate` workflow page on GitHub, at the very bottom of the page,
   or from the `build-alpine` workflow for statically linked Linux builds.

Ways to build `cabal-install` for everyday use
--------------------------------------------

1. _With cabal-install_:
    if you have a pre-existing version of `cabal-install`, run:

    ```
    cabal install cabal-install
    ```

    to get the latest version of `cabal-install`. (You may want to `cabal update` first.)

2. _From Git_:
    again with a pre-existing version of `cabal-install`,
    you can install the latest version from the Git repository. Clone the
    Git repository, move to its root, and run:

    ```
    cabal install --project-file=cabal.release.project cabal-install
    ```

3. _Bootstrapping_:
    if you don't have a pre-existing version of `cabal-install`,
    look into the [`bootstrap`](bootstrap) directory.

Learn how to use `cabal` and get support
----------------------------------------

`cabal` comes with a thorough [User Manual](https://cabal.readthedocs.io).
If you are new to `cabal` and want to quickly learn the basics, check
[Getting Started With Haskell and Cabal](https://cabal.readthedocs.io/en/latest/getting-started.html).

Got questions? Ask in [Haskell Matrix](https://matrix.to/#/#haskell:matrix.org)
(online chat) or [Haskell Discourse](https://discourse.haskell.org).

Support window
--------------

Our GHC support window is three years ([reference](https://gitlab.haskell.org/ghc/ghc/-/wikis/GHC%20Status#all-released-ghc-versions))
for both the Cabal library and `cabal-install`.  That is:

* Cabal library must be buildable out-of-the-box against the
  boot libraries shipped with GHC, for any GHC released in the past three
  years from Cabal library release date.
* `cabal-install` should be buildable with `bootstrap/bootstrap.py`
  script, for any GHC released in the past three years from `cabal-install`
  release date.
* `cabal-install` should be able to drive the most recent minor version of
  any GHCs major version released in the past three years from `cabal-install`
  release date.
  In this context, "drive" means `cabal-install` will work with the Cabal
  library (usually but not always the one that came with the ghc version)
  used to build the package.

Self-upgrade to the latest version (i.e. `cabal install cabal-install`)
must work with all versions of `cabal-install` released during the last
three years.

Cabal maintainers try to support GHC versions older than three years
on a minimal-effort basis.

Build for hacking and contributing to cabal
-------------------------------------------

Refer to [CONTRIBUTING.md](CONTRIBUTING.md).

Maintainers
-------------------------------------------

Refer to [MAINTAINERS.md](MAINTAINERS.md).
