README.md

   1 # Cabal
   2
   3 [![Hackage version](https://img.shields.io/hackage/v/Cabal.svg?label=Hackage)](https://hackage.haskell.org/package/Cabal)
   4 [![Stackage version](https://www.stackage.org/package/Cabal/badge/lts?label=Stackage)](https://www.stackage.org/package/Cabal)
   5 [![Documentation Status](http://readthedocs.org/projects/cabal/badge/?version=latest)](http://cabal.readthedocs.io/en/latest/?badge=latest)
   6 [![IRC chat](https://img.shields.io/badge/chat-via%20libera-brightgreen.svg)](https://web.libera.chat/#hackage)
   7 [![Matrix chat](https://img.shields.io/badge/chat-via%20matrix-brightgreen.svg)](https://matrix.to/#/#hackage:matrix.org)
   8 [![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)
   9
  10 <img src="https://www.haskell.org/cabal/images/Cabal-light.png" align="right">
  11
  12 This Cabal Git repository contains the following main packages:
  13
  14  * [Cabal](Cabal/README.md): the Cabal library package ([license](Cabal/LICENSE))
  15  * [Cabal-syntax](Cabal-syntax/README.md): the `.cabal` file format library ([license](Cabal-syntax/LICENSE))
  16  * [cabal-install](cabal-install/README.md): the package containing the `cabal` tool ([license](cabal-install/LICENSE))
  17  * [cabal-install-solver](cabal-install-solver): the package containing the solver component of the `cabal` tool ([license](cabal-install-solver/LICENSE))
  18
  19 The canonical upstream repository is located at
  20 https://github.com/haskell/cabal.
  21
  22 Ways to get the `cabal-install` binary
  23 --------------------------------
  24
  25 1. _GHCup_ (**preferred**): get GHCup using [the directions on its website](https://www.haskell.org/ghcup/) and run:
  26
  27     ```
  28     ghcup install --set cabal latest
  29     ```
  30
  31 2. _[Download from official website](https://www.haskell.org/cabal/download.html)_:
  32     the `cabal-install` binary download for your platform should contain the `cabal` executable.
  33
  34 #### Preview Releases
  35
  36 _Getting unreleased versions of `cabal-install`_: gives you a chance to try out yet-unreleased features.
  37 Currently, we only provide binaries for `x86_64` platforms.
  38
  39 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:
  40
  41     ```
  42     ghcup install cabal -u https://github.com/haskell/cabal/releases/download/cabal-head/cabal-head-Linux-x86_64.tar.gz head
  43     ```
  44
  45     Replace "Linux" with "Windows" or "macOS" as appropriate.
  46
  47     The default Linux build is dynamically linked against `zlib`, `gmp` and `glibc`.
  48     You will need to have appropriate versions of these libraries installed to use it.
  49     Alternatively a statically linked "Linux-static" binary is also provided.
  50
  51     You might need to add the following to your `cabal.project` file
  52     if your build fails because of an out-of-date `Cabal` library:
  53     ```
  54     allow-newer:
  55       *:Cabal,
  56       *:Cabal-syntax
  57
  58     source-repository-package
  59         type: git
  60         location: https://github.com/haskell/cabal.git
  61         subdir: Cabal Cabal-syntax
  62     ```
  63
  64
  65 2. Even more cutting-edge binaries built from pull requests are always available
  66    from the `Validate` worklow page on GitHub, at the very bottom of the page,
  67    or from the `build-alpine` workflow for statically linked Linux builds.
  68
  69 Ways to build `cabal-install` for everyday use
  70 --------------------------------------------
  71
  72 1. _With cabal-install_:
  73     if you have a pre-existing version of `cabal-install`, run:
  74
  75     ```
  76     cabal install cabal-install
  77     ```
  78
  79     to get the latest version of `cabal-install`. (You may want to `cabal update` first.)
  80
  81 2. _From Git_:
  82     again with a pre-existing version of `cabal-install`,
  83     you can install the latest version from the Git repository. Clone the
  84     Git repository, move to its root, and run:
  85
  86     ```
  87     cabal install --project-file=cabal.project.release cabal-install
  88     ```
  89
  90 3. _Bootstrapping_:
  91     if you don't have a pre-existing version of `cabal-install`,
  92     look into the [`bootstrap`](bootstrap) directory.
  93
  94 Learn how to use `cabal` and get support
  95 ----------------------------------------
  96
  97 `cabal` comes with a thorough [User Manual](https://cabal.readthedocs.io).
  98 If you are new to `cabal` and want to quickly learn the basics, check
  99 [Getting Started With Haskell and Cabal](https://cabal.readthedocs.io/en/latest/getting-started.html).
 100
 101 Got questions? Ask in [Haskell Matrix](https://matrix.to/#/#haskell:matrix.org)
 102 (online chat) or [Haskell Discourse](https://discourse.haskell.org).
 103
 104 Build for hacking and contributing to cabal
 105 -------------------------------------------
 106
 107 Refer to [CONTRIBUTING.md](CONTRIBUTING.md).