Skip to content

Commit 9375334

Browse files
mpilgremmpilgrem
committed
Merge branch 'stable'
2 parents 1c00228 + 5cb1ecb commit 9375334

File tree

2 files changed

+172
-23
lines changed

2 files changed

+172
-23
lines changed

‎doc/tutorial/index.md

Lines changed: 166 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -12,35 +12,179 @@ This guide to getting started takes a new Stack user through the ways that Stack
1212
is typically used. It will not teach Haskell or involve much code, and it
1313
requires no prior experience of Stack or other Haskell tools.
1414

15-
??? question "What are other Haskell tools?"
16-
17-
Haskell code is compiled by the
18-
[Glasgow Haskell Compiler](https://www.haskell.org/ghc/) (GHC), which can
19-
also be used interactively. Stack can manage versions of GHC. GHC provides
20-
commands such as `ghc`, `ghci`, `runghc` and `ghc-pkg`.
21-
22-
Cabal (the tool) is a tool provided by the
23-
[`cabal-install`](https://hackage.haskell.org/package/cabal-install) Haskell
24-
package. It aims to simplify the process of managing Haskell software by
25-
automating the fetching, configuration, compilation and installation of
26-
Haskell libraries and programs. These are goals that Stack shares. Stack can
27-
be used independently of Cabal (the tool) but users can also use both, if
28-
they wish.
29-
30-
Haskell Language Server (HLS) is an implementation of the Language Server
31-
Protocol for Haskell and used by Haskell extensions for code editors.
32-
33-
[GHCup](https://www.haskell.org/ghcup/) is a tool that can manage other
34-
Haskell tools, including Stack, GHC, HLS and Cabal (the tool). Stack can use
35-
GHCup to manage versions of GHC, as well as manage GHC directly.
36-
3715
Terms used in the guide will be explained as they are introduced and are also
3816
defined in the [glossary](../glossary.md).
3917

4018
Some of Stack's features will not be needed regularly or by all users. Other
4119
parts of Stack's documentation include its [commands](../commands/index.md) and
4220
its [configuration](../configure/index.md).
4321

22+
## Other Haskell tools
23+
24+
First, simplifying greatly, lets briefly place Stack and other Haskell tools in
25+
the Haskell landscape.
26+
27+
Haskell was specified in the
28+
[Haskell 98 Language and Library Reports](https://www.haskell.org/onlinereport/),
29+
first published in February 1999, and further specified in the
30+
[Haskell 2010 Language Report](https://www.haskell.org/onlinereport/haskell2010/),
31+
published in April 2010. Extensions to the language have been developed (see
32+
below).
33+
34+
The Haskell compiler is **GHC** (the
35+
[Glasgow Haskell Compiler](https://www.haskell.org/ghc/)). It can compile
36+
Haskell code into executable and other binary files. GHC can also be used
37+
interactively (**GHCi**) and Stack supports such use.
38+
39+
~~~mermaid
40+
flowchart LR
41+
code@{ shape: docs, label: "Haskell code" }
42+
ghc[GHC]
43+
binaries@{ shape: docs, label: "Executable and other binary files" }
44+
code --> ghc --> binaries
45+
~~~
46+
47+
Haskell code can be organised into *packages*. A Haskell package also includes a
48+
file that describes the package's contents. The most established description
49+
format is known as a
50+
[Cabal file](https://cabal.readthedocs.io/en/stable/file-format-changelog.html).
51+
The [**Hpack** project](https://github.com/sol/hpack) provides a modern
52+
alternative format (in a file named `package.yaml`) and a library and
53+
application that translates from that format to the legacy format. Stack has
54+
built-in support for Hpack. Other build tools (see below) do not.
55+
56+
~~~mermaid
57+
flowchart LR
58+
packageYaml@{ shape: doc, label: "package.yaml" }
59+
hpack[Hpack]
60+
cabalFile@{ shape: doc, label: "Cabal file" }
61+
packageYaml --> hpack --> cabalFile
62+
~~~
63+
64+
The code in a Haskell package is organised into *components*, including
65+
components known as *libraries*. Historically, a package had no more than one
66+
library component. The Cabal specification has developed to allow a package to
67+
have named *sub-library* components as well as a main library.
68+
69+
The code in a Haskell package can depend on the libraries in the same package
70+
or in another package. These are known as its *dependencies*.
71+
72+
Two important public databases are **Hackage**
73+
[(the Haskell Package Repository)](https://hackage.haskell.org/) and
74+
[**Stackage**](https://hackage.haskell.org/).
75+
76+
~~~mermaid
77+
flowchart LR
78+
hackage@{ shape: lin-cyl, label: "Hackage
79+
(packages)" }
80+
stackage@{ shape: lin-cyl, label: "Stackage
81+
(snapshots)" }
82+
hackage --> stackage
83+
~~~
84+
85+
Hackage is a database of Haskell packages, each identified by a name and version
86+
number. Stackage is a database of collections of Haskell package versions on
87+
Hackage that are known, by testing, to work well together and with a specific
88+
version of GHC. Those collections are known as *snapshots*. Stack can unpack
89+
packages from, and upload packages to, Hackage and builds making use of
90+
snapshots from Stackage.
91+
92+
GHC comes with the libraries of certain Haskell packages (known as
93+
*boot packages*) already installed in its global database of installed
94+
libraries. These include the library of the
95+
[package `base`](https://hackage.haskell.org/package/base), which
96+
is a dependency of almost all other packages, and the library of
97+
[package `Cabal`](https://hackage.haskell.org/package/Cabal), which provides
98+
code to build packages and components of packages using GHC.
99+
100+
GHC comes with an application
101+
[**Haddock**](https://haskell-haddock.readthedocs.io/latest/) that automatically
102+
generates web page and other documentation from annotated Haskell code. The
103+
Hackage and Stackage websites display that documentation. Stack supports the use
104+
of Haddock.
105+
106+
~~~mermaid
107+
flowchart LR
108+
code@{ shape: docs, label: "Haskell code" }
109+
haddock[Haddock]
110+
docs@{ shape: docs, label: "Documentation" }
111+
code --> haddock --> docs
112+
~~~
113+
114+
**Hoogle** is a [website](https://hoogle.haskell.org/) and an
115+
[application](https://hackage.haskell.org/package/hoogle) that allows its users
116+
to search for the library components of Haskell packages, the modules they
117+
expose, and functions and types exported by modules. Stack supports the use of
118+
Hoogle on the command line.
119+
120+
GHC is described in its
121+
[User Guide](https://downloads.haskell.org/ghc/latest/docs/users_guide/). It can
122+
be used directly but it is a complex application with many flags and options.
123+
These include flags to specify extensions to the Haskell language. Haskell
124+
*build tools* are applications that make it easier to use GHC, including by
125+
applying sensible defaults. Stack is such a build tool. Stack itself uses
126+
the Cabal library to build.
127+
128+
~~~mermaid
129+
flowchart LR
130+
stack[Stack]
131+
cabal["Cabal (the library)"]
132+
code@{ shape: docs, label: "Haskell code" }
133+
ghc[GHC]
134+
binaries@{ shape: docs, label: "Executable and other files" }
135+
subgraph buildtool ["Build tool"]
136+
direction TB
137+
stack --> cabal --> ghc
138+
end
139+
code --> buildtool --> binaries
140+
~~~
141+
142+
When Haskell code changes, GHC and build tools aim to minimise what needs to be
143+
re-compiled.
144+
145+
A Stack project may comprise only a single package, but Stack can also handle
146+
multi-package projects.
147+
148+
Another build tool is **Cabal** (the tool) (named after the library). It is
149+
provided by the
150+
[`cabal-install`](https://hackage.haskell.org/package/cabal-install)
151+
Haskell package. Stack can be used independently of Cabal (the tool) but users
152+
can also use both, if they wish.
153+
154+
Some popular code editors (including
155+
[Visual Studio Code](https://code.visualstudio.com/)) have extensions that
156+
support Haskell coding by providing an integrated development environment (IDE).
157+
Those extensions use **HLS** (the
158+
[Haskell Language Server](https://haskell-language-server.readthedocs.io/en/stable/)),
159+
an application that implements the Language Server Protocol for Haskell.
160+
161+
Stack can manage versions of GHC and upgrade/downgrade Stack itself and is, in
162+
that sense, an *installer* of those applications as well as a build tool.
163+
However, Cabal (the tool) is not an installer and versions of HLS applicable to
164+
versions of GHC also need to be installed.
165+
[**GHCup**](https://www.haskell.org/ghcup/) is an installer of versions of GHC,
166+
HLS, Stack and Cabal (the tool) built for various operating systems and machine
167+
architectures. Stack can be configured to manage versions of GHC by using GHCup.
168+
169+
~~~mermaid
170+
flowchart TD
171+
ghcUp["GHCup
172+
installer"]
173+
ghc["GHC
174+
compiler"]
175+
hls["HLS
176+
IDE tool"]
177+
stack["Stack
178+
build tool, installer"]
179+
cabal["Cabal (the tool)
180+
build tool"]
181+
ghcUp -.-> ghc
182+
ghcUp -.-> hls
183+
ghcUp -.-> stack
184+
stack -- "(optional) to fetch GHC" --> ghcUp
185+
ghcUp -.-> cabal
186+
~~~
187+
44188
## Setting up
45189

46190
The goal of setting up is a `stack` executable on the PATH. As we will see, when

‎mkdocs.yml

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ extra_javascript:
3030
# Read the Docs requires JQuery for its JavaScript code to inject the flyout
3131
# menu. Material for MkDocs does not come with JQuery.
3232
- 'https://code.jquery.com/jquery-3.6.1.min.js'
33+
- https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js
3334
exclude_docs: |
3435
/maintainers/archive/
3536
/maintainers/stack_errors.md
@@ -161,7 +162,11 @@ markdown_extensions:
161162
anchor_linenums: true
162163
- pymdownx.inlinehilite
163164
- pymdownx.snippets
164-
- pymdownx.superfences
165+
- pymdownx.superfences:
166+
custom_fences:
167+
- name: mermaid
168+
class: mermaid
169+
format: !!python/name:pymdownx.superfences.fence_code_format
165170
- pymdownx.tabbed:
166171
alternate_style: true
167172
- toc:

0 commit comments

Comments
 (0)