forked from haskell/cabal-website
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
157 lines (130 loc) · 7.05 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link href="nominolo.css" type="text/css" rel="stylesheet">
<link href="./images/Cabal-tiny.png" rel="icon">
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
<title>The Haskell Cabal | Overview</title>
</head>
<body>
<h1 class="mainheader">The Haskell Cabal <span class="subheading">| Overview</span></h1>
<span style="font-style: italic">Cabal: Common Architecture for Building Applications and Libraries</span>
<h2>Introduction</h2>
<p>Cabal is a system for building and packaging Haskell libraries and programs.
It defines a common interface for package authors and distributors to
easily build their applications in a portable way. Cabal is part of a larger
infrastructure for distributing, organizing, and cataloging Haskell libraries
and programs.
</p>
<p>The term <span style="font-style: italic">cabal</span> can refer to
either: <span style="font-style: italic">cabal-the-spec</span> (.cabal
files), <span style="font-style: italic">cabal-the-library</span> (code
that understands .cabal files), or <span style="font-style:
italic">cabal-the-tool</span>
(the <span class="inline-code">cabal-install</span> package which provides
the <span class="inline-code">cabal</span> executable); usually folks are
referring to cabal-the-tool when they say cabal.
</p>
<h2><a href="#install-upgrade">Install/Upgrade <span class="inline-code">cabal</span></a></h2>
<p>
The recommended method to install the <span class="inline-code">cabal</span> executable
is to use <a href="https://www.haskell.org/ghcup/">ghcup</a>, which can manage multiple
versions of <span class="inline-code">cabal</span> on Linux, Mac and Windows.
Alternatively, you can install <span class="inline-code">cabal</span> using your
distribution's package manager (if you are using Linux or Mac), or download the source
or prebuilt binary from the <a href="download.html">Download</a> page.
</p>
<p>
If you have installed <span class="inline-code">cabal</span> using <a href="https://www.haskell.org/ghcup/">ghcup</a>,
then you can also upgrade it using <span class="inline-code">ghcup</span>.
If you installed the <span class="inline-code">cabal</span> executable using a different method,
you can upgrade it by running:
<code>
<span class="code-unselectable"data-text="$ "></span>cabal install cabal-install
</code><br>
This will install the cabal executable in cabal's <span class="inline-code">installdir</span>
(usually <span class="inline-code">~/.local/bin</span>). In order to use this executable,
you have to make sure that this directory appears in the <span class="inline-code">$PATH</span>
variable before the location where your current <span class="inline-code">cabal</span> executable is located.
You can check which version of the <span class="inline-code">cabal</span> executable
you are running by executing the command below.
<code>
<span class="code-unselectable" data-text="$ ">cabal --version</span>
</code>
</p>
<p>
If the update failed for any reason, see the <a href="#troubleshooting">Update Troubleshooting</a>
section below.
</p>
<h2>Quick Start Guide</h2>
<p>Start by installing the <span class="inline-code">cabal</span> executable
(see <a href="#install-upgrade">the previous section</a>) and the Haskell compiler
<span class="inline-code">ghc</span>.
It is also recommended to use <a href="https://www.haskell.org/ghcup/">ghcup</a> to install
<span class="inline-code">ghc</span>.
</p>
<h3>Starting a new project</h3>
<p>
<code>
<span class="code-unselectable"data-text="$ "></span>mkdir myproject && cd myproject<br/>
<span class="code-unselectable"data-text="$ "></span>cabal init<br/>
<span class="code-unselectable"data-text="$ "></span>cabal run<br/>
</code>
</p>
<p>
<ul>
<li>The <span class="inline-code">cabal init</span> command will create all the needed files for an executable.</li>
<li>The <span class="inline-code">cabal run</span> will build and run the executable in the project.</li>
</ul>
</p>
<h2>Documentation</h2>
<ul>
<li><a href="https://cabal.readthedocs.io">Cabal User Guide</a></li>
<li><a href="FAQ.html">FAQ and Troubleshooting</a> - commonly encountered issues and how to resolve them</li>
</ul>
<h2>Related Pages</h2>
<ul>
<li><a href="http://hackage.haskell.org/">Hackage</a>: the Haskell Package Database
<li><a href="http://haskell.org/haskellwiki/Upgrading_packages">Updating packages to work with recent Cabal and GHC versions</a>
<li><a href="https://github.com/haskell/cabal/issues?utf8=%E2%9C%93&q=is%3Aopen">Browse open issues or report a new bug</a>
<li><a href="code.html">Source code</a> for development versions.
<li>Questions can be <a href="mailto:libraries@haskell.org">sent</a> to the <a href="http://www.haskell.org/mailman/listinfo/libraries">Haskell libraries mailing list</a>
<li>Development discussion takes place on the <a href="http://www.haskell.org/mailman/listinfo/cabal-devel">cabal-devel</a> mailing list</li>
<li><a href="http://www.haskell.org/haskellwiki/Applications_and_libraries">Applications and Libraries</a> for Haskell</li>
</ul>
<h2><a href="#troubleshooting">Update Troubleshooting</a></h2>
<p>
Before you try anything else, you may want to refresh the package index:
<code>
<span class="code-unselectable"data-text="$ "></span>cabal update
</code><br/>
If you already have a new-ish version of cabal
you can use the v2/new commands. Try the following:
<code>
<span class="code-unselectable"data-text="$ "></span>cabal new-install Cabal cabal-install
</code><br/>
If this works, update the <span class="inline-code">cabal</span> command on
your <span class="inline-code">$PATH</span> with the version installed.
Some alternative installation methods from source code are described
in <a href="https://github.com/haskell/cabal/blob/master/README.md">the Cabal source repository</a>.
</p>
<p>
Particularly when upgrading from old versions, you may see:
</p>
<p>
<b> ERROR: cabal: The following packages are likely to be broken by the reinstalls: ... </b><br/>
<b>Use --force-reinstalls if you want to install anyway.</b><br/>
</p>
<p>
This can happen if your package archive gets into a broken state. How to
fix this depends on the situation. Sometimes re-running the command with
<span class="inline-code">--force-reinstalls</span> works, other times you
have to remove your whole package archive and start over again.
</p>
<p>
Thankfully this doesn't happen very often. If you run into this issue and
you want to preserve your local package archive, ask a question, e.g.,
on StackOverflow.
</p>
</body>
</html>