Skip to content

Commit e9a3f90

Browse files
mpilgremmpilgrem
committed
Tidy up and update doc/README.md 
1 parent a638e81 commit e9a3f90

File tree

1 file changed

+173
-147
lines changed

1 file changed

+173
-147
lines changed

‎doc/README.md

Lines changed: 173 additions & 147 deletions
Original file line numberDiff line numberDiff line change
@@ -2,219 +2,245 @@
22

33
# The Haskell Tool Stack
44

5-
Stack is a cross-platform program for developing Haskell
6-
projects. It is aimed at Haskellers both new and experienced.
5+
Stack is a cross-platform program for developing
6+
[Haskell](https://www.haskell.org/) projects. It is aimed at Haskellers both new
7+
and experienced. It aims to support fully users on Linux, macOS and Windows.
78

89
<img src="https://i.imgur.com/WW69oTj.gif" width="50%" align="right">
910

10-
It features:
11+
Stack features:
1112

12-
* Installing GHC automatically, in an isolated location.
13+
* Installing the [Glasgow Haskell Compiler (GHC)](https://www.haskell.org/ghc/)
14+
automatically, in an isolated location.
1315
* Installing packages needed for your project.
1416
* Building your project.
1517
* Testing your project.
1618
* Benchmarking your project.
1719

18-
#### How to install
20+
## How to install Stack
1921

20-
Stack can be installed on most Unix-like (Un*x) operating systems, including
21-
macOS, and on Windows.
22+
Stack can be installed on most Unix-like operating systems, including macOS, and
23+
on Windows.
2224

23-
For most Un*x operating systems, the easiest way to install is to run:
25+
For most Unix-like operating systems, the easiest way to install Stack is to
26+
run:
2427

2528
curl -sSL https://get.haskellstack.org/ | sh
2629

2730
or:
2831

2932
wget -qO- https://get.haskellstack.org/ | sh
3033

31-
On Windows, you can download and install the
32-
[Windows 64-bit Installer](https://get.haskellstack.org/stable/windows-x86_64-installer.exe).
33-
Note that systems with antivirus software may need `stack` added to the list of "trusted" applications.
34+
On 64-bit Windows, you can download and install the
35+
[Windows installer](https://get.haskellstack.org/stable/windows-x86_64-installer.exe).
36+
Note that systems with antivirus software may need to add Stack to the list of
37+
'trusted' applications.
3438

3539
For other operating systems and direct downloads, check out the
3640
[install and upgrade guide](install_and_upgrade.md).
3741

38-
Note that the [get.haskellstack.org](https://get.haskellstack.org/)
39-
script will ask for root access using `sudo` in order to use your
40-
platform's package manager to install dependencies and to install to
41-
`/usr/local/bin`. If you prefer more control, follow the manual
42-
installation instructions in the
43-
[install and upgrade guide](install_and_upgrade.md).
42+
The [get.haskellstack.org](https://get.haskellstack.org/) script referred to
43+
above will ask for root access using `sudo`. It needs such access in order to
44+
use your platform's package manager to install dependencies and to install to
45+
`/usr/local/bin`. If you prefer more control, follow the manual installation
46+
instructions in the [install and upgrade guide](install_and_upgrade.md).
4447

45-
#### How to upgrade
48+
## How to upgrade Stack
4649

47-
If you already have `stack` installed, upgrade it to the latest version
48-
by running:
50+
If you already have Stack installed, you can upgrade it to the latest version
51+
by the command:
4952

5053
stack upgrade
5154

55+
## Quick Start guide
56+
57+
For an immediate experience of using Stack to build an executable with Haskell,
58+
first you need to follow the [guide to install Stack](#how-to-install-Stack).
59+
60+
### Start your new project
61+
62+
To start a new project named `my-project`, issue these four commands in a
63+
terminal:
64+
65+
stack new my-project
66+
cd my-project
67+
stack build
68+
stack exec my-project-exe
5269

53-
#### Quick Start Guide
5470

55-
First you need to [install it (see previous section)](#how-to-install).
71+
- The `stack new my-project` command will create a new directory, named
72+
`my-project`, that contains all the files needed to start a project correctly,
73+
using a default template.
74+
- The `cd my-project` command will change to that directory.
75+
- The `stack build` command will build the template project and create an
76+
executable named `my-project-exe`. First, if necessary, Stack will download
77+
the necessary GHC compiler in an isolated location. That won't interfere with
78+
any system-level installations of GHC.
79+
- The `stack exec my-project-exe` command will run (execute) the built
80+
executable, in Stack's environment.
5681

57-
##### Start your new project:
82+
For a complete list of Stack's commands and options, simply command:
5883

59-
```bash
60-
stack new my-project
61-
cd my-project
62-
stack setup
63-
stack build
64-
stack exec my-project-exe
65-
```
84+
stack
6685

67-
- The `stack new` command will create a new directory containing all
68-
the needed files to start a project correctly.
69-
- The `stack setup` will download the compiler if necessary in an isolated
70-
location (default `~/.stack`) that won't interfere with any system-level
71-
installations. (For information on installation paths, please use the
72-
`stack path` command.).
73-
- The `stack build` command will build the minimal project.
74-
- `stack exec my-project-exe` will execute the command.
75-
- If you just want to install an executable using stack, then all you have to do
76-
is `stack install <package-name>`.
86+
For help on a particular Stack command, for example `stack build`, command:
7787

78-
If you want to launch a REPL:
88+
stack build --help
7989

80-
```bash
81-
stack ghci
82-
```
90+
If you want to launch a run-eval-print loop (REPL), then command:
8391

84-
Run `stack` for a complete list of commands.
92+
stack ghci
8593

86-
##### Workflow
94+
If you want to use Stack to install an executable provided by a Haskell package,
95+
then all you have to do is command:
8796

88-
The `stack new` command should have created the following files:
97+
stack install <package-name>
8998

90-
```
99+
### Workflow
100+
101+
The `stack new my-project` command above should have created the following files
102+
and directories:
103+
104+
~~~
91105
.
92106
├── app
93107
│   └── Main.hs
94-
├── ChangeLog.md
95-
├── LICENSE
96-
├── my-project.cabal
97-
├── package.yaml
98-
├── README.md
99-
├── Setup.hs
100108
├── src
101109
│   └── Lib.hs
110+
├── test
111+
│ └── Spec.hs
112+
├── Setup.hs
113+
├── package.yaml
114+
├── my-project.cabal
102115
├── stack.yaml
103-
└── test
104-
└── Spec.hs
116+
├── README.md
117+
├── ChangeLog.md
118+
├── LICENSE
119+
└── .gitignore
120+
~~~
105121

106-
3 directories, 10 files
107-
```
122+
(The `stack build` command will have created other directories and files.)
108123

109-
So to manage your library:
124+
The Haskell code for the executable/application is in `Main.hs`. The
125+
source code for the library that it uses is in `Lib.hs`. The contents of
126+
`my-project.cabal` describes the project. That file is generated by the contents
127+
of `package.yaml`.
110128

111-
1. Edit files in the `src/` directory.
129+
To manage your library:
130+
131+
1. Edit source files in the `src` directory.
112132

113133
The `app` directory should preferably contain only files related to
114134
executables.
115135

116-
2. If you need to include another library (for example the package
117-
[`text`](https://hackage.haskell.org/package/text)):
136+
2. Your developing project may need to depend on a library provided by another
137+
Haskell package.
138+
139+
- Add the name of that new package to the file `package.yaml`, in its
140+
`dependencies:` section.
141+
- Run `stack build` again. Stack will use `package.yaml` to create an
142+
updated `my-project.cabal` for you.
143+
144+
If desired, you can delete the `package.yaml` file and update the
145+
`my-project.cabal` file directly. Stack will then use that file.
146+
147+
3. If you get an error message that tells you that the Stack configuration has
148+
no specified version of your added package, follow Stack's likely
149+
recommandation to add a specific version of that package in the `stack.yaml`
150+
file, in its `extra-deps:` section.
151+
152+
That was a really fast introduction on how to start to code in Haskell using
153+
Stack. If you want to go further, we highly recommend you read the
154+
[Stack User Guide](GUIDE.md).
155+
156+
## Complete guide to Stack
157+
158+
A complete [user guide to Stack](GUIDE.md) is available, covering all of
159+
the most common ways to use Stack.
160+
161+
## Why Stack?
162+
163+
Stack is a build tool for Haskell designed to answer the needs of Haskell users
164+
new and experienced alike. It has a strong focus on reproducible build plans,
165+
multi-package projects, and a consistent, easy-to-learn interface, while
166+
providing the customizability and power experienced developers need.
167+
168+
As a build tool, Stack does not stand alone. It is built on the great work
169+
provided by:
170+
171+
* The __Glasgow Haskell Compiler__ ([GHC](https://www.haskell.org/ghc/)), the
172+
premier Haskell compiler. Stack will manage your GHC installations and
173+
automatically select the appropriate compiler version for your project.
174+
* The __Cabal build system__, a specification for defining Haskell packages,
175+
together with a [library](https://hackage.haskell.org/package/Cabal) for
176+
performing builds.
177+
* The __Hackage Haskell Package Repository__, a
178+
[repository](https://hackage.haskell.org/) providing thousands of open source
179+
libraries and applications to help you get your work done.
180+
* The __Stackage package collection__, a
181+
[curated set of packages](https://www.stackage.org/) from Hackage which are
182+
regularly tested for compatibility. Stack defaults to using Stackage
183+
package sets to avoid dependency problems.
184+
185+
Stack is provided by a team of volunteers and companies under the auspices of
186+
the [Commercial Haskell](http://commercialhaskell.com/) group. The project was
187+
spearheaded by [FP Complete](https://www.fpcomplete.com/) to answer the needs of
188+
commercial Haskell users, and has since become a thriving open source project
189+
meeting the needs of Haskell users of all stripes.
118190

119-
- Add the package `text` to the file `package.yaml`
120-
in the section `dependencies: ...`.
121-
- Run `stack build` another time.
122-
- `stack build` will update my-project.cabal for you.
123-
If desired you can update the .cabal file manually
124-
and stack will use .cabal instead of package.yaml.
191+
If you'd like to get involved with Stack, check out the
192+
[newcomer friendly](https://github.com/commercialhaskell/stack/issues?q=is%3Aopen+is%3Aissue+label%3a%22newcomer+friendly%22)
193+
label on the GitHub issue tracker.
125194

126-
3. If you get an error that tells you your package isn't in the LTS.
127-
Just try to add a new version in the `stack.yaml` file in the `extra-deps` section.
195+
## Questions, feedback, and discussion
128196

129-
That was a really fast introduction on how to start to code in Haskell using `stack`.
130-
If you want to go further, we highly recommend you to read the [`stack` guide](GUIDE.md).
197+
* For answers to frequently asked questions about Stack, please see the
198+
[FAQ](faq.md).
199+
* For general questions, comments, feedback and support, please post to the
200+
[Haskell Community](https://discourse.haskell.org/about).
201+
* For bugs, issues, or requests, please
202+
[open an issue](https://github.com/commercialhaskell/stack/issues/new).
203+
* When using Stack Overflow, please use the
204+
[haskell-stack](http://stackoverflow.com/questions/tagged/haskell-stack) tag.
131205

132-
#### How to contribute
206+
## How to contribute to the maintenance or development of Stack
133207

134-
This assumes that you have already installed a version of stack, and have `git`
135-
installed.
208+
The following assumes that you already have installed a version of Stack and the
209+
[Git application](https://git-scm.com/).
136210

137-
1. Clone `stack` from git with
211+
1. Clone the `stack` repository from GitHub with the command:
138212
`git clone https://github.com/commercialhaskell/stack.git`.
139-
2. Enter into the stack folder with `cd stack`.
140-
3. Build `stack` using a pre-existing `stack` install with
141-
`stack setup && stack build`.
142-
4. Once `stack` finishes building, check the stack version with
143-
`stack exec stack -- --version`. Make sure the version is the latest.
144-
5. Look for issues tagged with
213+
2. Enter into the cloned `stack` directory with command `cd stack`.
214+
3. Build the `stack` executable using a pre-existing installation of Stack with
215+
command `stack build`.
216+
4. Once the `stack` executable has been built, check its version with the
217+
command `stack exec -- stack --version`. Make sure the version is the latest.
218+
5. In the GitHub respository's issue tracker, look for issues tagged with
145219
[newcomer friendly](https://github.com/commercialhaskell/stack/issues?q=is%3Aopen+is%3Aissue+label%3a%22newcomer+friendly%22)
146220
and
147221
[awaiting pull request](https://github.com/commercialhaskell/stack/issues?q=is%3Aopen+is%3Aissue+label%3A%22awaiting+pull+request%22)
148222
labels.
149223

150-
Build from source as a one-liner:
151-
152-
```bash
153-
git clone https://github.com/commercialhaskell/stack.git && \
154-
cd stack && \
155-
stack setup && \
156-
stack build
157-
```
224+
If you need to check your changes quickly run `stack ghci` and then this command
225+
at the REPL's prompt:
158226

159-
If you need to check your changes quickly run:
227+
:main --stack-root=<path_to_root> --stack-yaml=<path_to_stack.yaml> <COMMAND>
160228

161-
```bash
162-
stack ghci
163-
λ: :main --stack-root /path/to/root/ --stack-yaml /path/to/stack.yaml COMMAND
164-
```
229+
This allows you to set a special Stack root (instead of the default Stack root)
230+
and to target your commands at a particular `stack.yaml` file instead of the one
231+
found in the current directory.
165232

166-
This allows you to set a special stack root (instead of `~/.stack/` or, on
167-
Windows, `%LOCALAPPDATA%\Programs\stack`) and to target your commands at a
168-
particular `stack.yaml` instead of the one found in the current directory.
233+
## How to uninstall
169234

170-
#### Complete guide to stack
235+
To uninstall Stack, it should be sufficient to:
171236

172-
This repository also contains a complete [user guide to using
173-
stack](GUIDE.md), covering all of the most common use cases.
174-
175-
176-
#### Questions, Feedback, Discussion
177-
178-
* For frequently asked questions about detailed or specific use-cases, please
179-
see [the FAQ](faq.md).
180-
* For general questions, comments, feedback and support, please write
181-
to [the stack mailing list](https://groups.google.com/d/forum/haskell-stack).
182-
* For bugs, issues, or requests, please
183-
[open an issue](https://github.com/commercialhaskell/stack/issues/new).
184-
* When using Stack Overflow, please use [the haskell-stack
185-
tag](http://stackoverflow.com/questions/tagged/haskell-stack).
186-
187-
#### Why Stack?
188-
189-
Stack is a build tool for Haskell designed to answer the needs of
190-
Haskell users new and experienced alike. It has a strong focus on
191-
reproducible build plans, multi-package projects, and a consistent,
192-
easy-to-learn interface, while providing the customizability and
193-
power experienced developers need. As a build tool, Stack does not
194-
stand alone. It is built on the great work provided by:
195-
196-
* The __Glasgow Haskell Compiler__ (GHC), the premier Haskell
197-
compiler. Stack will manage your GHC installations and automatically
198-
select the appropriate compiler version for your project.
199-
* The __Cabal build system__, a specification for defining Haskell
200-
packages, together with a library for performing builds.
201-
* The __Hackage package repository__, providing more than ten thousand
202-
open source libraries and applications to help you get your work
203-
done.
204-
* The __Stackage package collection__, a curated set of packages from
205-
Hackage which are regularly tested for compatibility. Stack defaults
206-
to using Stackage package sets to avoid dependency problems.
207-
208-
Stack is provided by a team of volunteers and companies under the
209-
auspices of the [Commercial Haskell](http://commercialhaskell.com/)
210-
group. The project was spearheaded by
211-
[FP Complete](https://www.fpcomplete.com/) to answer the needs of
212-
commercial Haskell users, and has since become a thriving open source
213-
project meeting the needs of Haskell users of all stripes.
214-
215-
If you'd like to get involved with Stack, check out the
216-
[newcomer friendly](https://github.com/commercialhaskell/stack/issues?q=is%3Aopen+is%3Aissue+label%3a%22newcomer+friendly%22)
217-
label on the Github issue tracker.
237+
1. Delete the Stack root folder (see `stack path --stack-root`, before you
238+
uninstall).
239+
2. On Windows, delete the folder containing Stack's tools (see
240+
`stack path --programs`, before you uninstall), which is located outside of
241+
the Stack root folder
242+
3. Delete the `stack` executable (see `which stack`, on Unix-like operating
243+
systems, or `where.exe stack`, on Windows).
218244

219-
#### How to uninstall
220-
Removing ``~/.stack`` and ``/usr/local/bin/stack`` should be sufficient. You may want to delete ``.stack-work`` folders in any Haskell projects that you have built.
245+
You may also want to delete ``.stack-work`` folders in any Haskell projects that
246+
you have built using Stack.

0 commit comments

Comments
 (0)