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