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