diff --git a/.gitignore b/.gitignore index e76b2e3cc7..f3cafdcf39 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ tags /*.iml /src/highlight.js /src/style.css +/doc/_build diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac3d6b38b6..2844060d68 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,5 @@ +# Contributors Guide + ## Bug Reports When reporting a bug, please write in the following format: diff --git a/ChangeLog.md b/ChangeLog.md index d931baafd4..278e74a0d8 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,3 +1,5 @@ +# Changelog + ## Unreleased changes Major changes: @@ -17,7 +19,7 @@ Major changes: * GHCJS can now be used with stackage snapshots via the new `compiler` field. * Windows installers are now available: - [download them here](https://github.com/commercialhaskell/stack/blob/release/doc/install_and_upgrade.md#windows) + [download them here](http://docs.haskellstack.org/en/stable/install_and_upgrade.html#windows) [#613](https://github.com/commercialhaskell/stack/issues/613) * Docker integration works with non-FPComplete generated images [#531](https://github.com/commercialhaskell/stack/issues/531) @@ -86,7 +88,7 @@ Bug fixes: * Fix: unlisted files in tests and benchmarks trigger extraneous second build [#838](https://github.com/commercialhaskell/stack/issues/838) -## v0.1.6.0 +## 0.1.6.0 Major changes: @@ -231,7 +233,7 @@ Major changes: * Respect TemplateHaskell addDependentFile dependency changes ([#105](https://github.com/commercialhaskell/stack/issues/105)) * TH dependent files are taken into account when determining whether a package needs to be built. * Overhauled target parsing, added `--test` and `--bench` options [#651](https://github.com/commercialhaskell/stack/issues/651) - * For details, see [Build commands documentation](doc/build_command.md) + * For details, see [Build commands documentation](http://docs.haskellstack.org/en/stable/build_command.html) Other enhancements: diff --git a/README.md b/README.md index 97be15a4ca..eea8f90cfb 100644 --- a/README.md +++ b/README.md @@ -4,201 +4,8 @@ [![Windows build status](https://ci.appveyor.com/api/projects/status/c1c7uvmw6x1dupcl?svg=true)](https://ci.appveyor.com/project/snoyberg/stack) [![Release](https://img.shields.io/github/release/commercialhaskell/stack.svg)](https://github.com/commercialhaskell/stack/releases) -`stack` is a cross-platform program for developing Haskell -projects. It is aimed at Haskellers both new and experienced. +`stack` is a cross-platform program for developing Haskell projects. It is aimed +at Haskellers both new and experienced. - - -It features: - -* Installing GHC automatically, in an isolated location. -* Installing packages needed for your project. -* Building your project. -* Testing your project. -* Benchmarking your project. - -#### How to install - -Downloads are available by operating system: - -* [Windows](https://github.com/commercialhaskell/stack/blob/release/doc/install_and_upgrade.md#windows) -* [Mac OS X](https://github.com/commercialhaskell/stack/blob/release/doc/install_and_upgrade.md#mac-os-x) -* [Ubuntu](https://github.com/commercialhaskell/stack/blob/release/doc/install_and_upgrade.md#ubuntu) -* [Debian](https://github.com/commercialhaskell/stack/blob/release/doc/install_and_upgrade.md#debian) -* [CentOS / Red Hat / Amazon Linux](https://github.com/commercialhaskell/stack/blob/release/doc/install_and_upgrade.md#centos--red-hat--amazon-linux) -* [Fedora](https://github.com/commercialhaskell/stack/blob/release/doc/install_and_upgrade.md#fedora) -* [Arch Linux](https://github.com/commercialhaskell/stack/blob/release/doc/install_and_upgrade.md#arch-linux) -* [NixOS](https://github.com/commercialhaskell/stack/blob/release/doc/install_and_upgrade.md#nixos) -* [Linux (general)](https://github.com/commercialhaskell/stack/blob/release/doc/install_and_upgrade.md#linux) - -[Upgrade instructions](https://github.com/commercialhaskell/stack/blob/release/doc/install_and_upgrade.md#upgrade) - -Note: if you are using cabal-install to install stack, you may need to pass a -constraint to work around a -[Cabal issue](https://github.com/haskell/cabal/issues/2759): `cabal install ---constraint 'mono-traversable >= 0.9' stack`. - -#### Quick Start Guide - -First you need to [install it (see previous section)](#how-to-install). - -##### Start your new project: - -~~~ {.bash} -stack new my-project -cd my-project -stack setup -stack build -stack exec my-project-exe -~~~ - -- The `stack new` command will create a new directory containing all -the needed files to start a project correctly. -- The `stack setup` will download the compiler if necessary in an isolated - location (default `~/.stack`) that won't interfere with any system-level - installations. (For information on installation paths, please use the `stack - path` command.). -- The `stack build` command will build the minimal project. -- `stack exec my-project-exe` will execute the command. -- If you just want to install an executable using stack, then all you have to do -is`stack install `. - -If you want to launch a REPL: - -~~~ {.bash} -stack ghci -~~~ - - -Run `stack` for a complete list of commands. - -##### Workflow - -The `stack new` command should have created the following files: - -~~~ -. -├── LICENSE -├── Setup.hs -├── app -│   └── Main.hs -├── my-project.cabal -├── src -│   └── Lib.hs -├── stack.yaml -└── test - └── Spec.hs - - 3 directories, 7 files -~~~ - -So to manage your library: - -1. Edit files in the `src/` directory. - -The `app` directory should preferably contains only files related to -executables. - -2. If you need to include another library (for example the package [`text`](https://hackage.haskell.org/package/text): - - - Add the package `text` to the file `my-project.cabal` - in the section `build-depends: ...`. - - run `stack build` another time - -3. If you get an error that tells you your package isn't in the LTS. - Just try to add a new version in the `stack.yaml` file in the `extra-deps` section. - -It was a really fast introduction on how to start to code in Haskell using `stack`. -If you want to go further, we highly recommend you to read the [`stack` guide](https://github.com/commercialhaskell/stack/blob/release/doc/GUIDE.md). - -#### How to contribute - -This assumes that you have already installed a version of stack, and have `git` -installed. - -1. Clone `stack` from git with - `git clone https://github.com/commercialhaskell/stack.git`. -2. Enter into the stack folder with `cd stack`. -3. Build `stack` using a pre-existing `stack` install with - `stack setup && stack build`. -4. Once `stack` finishes building, check the stack version with - `stack --version`. Make sure the version is the latest. -5. Look for issues tagged with - [`newcomer` and `awaiting-pr` labels](https://github.com/commercialhaskell/stack/issues?q=is%3Aopen+is%3Aissue+label%3Anewcomer+label%3A%22awaiting+pr%22) - -Build from source as a one-liner: - -```bash -git clone https://github.com/commercialhaskell/stack.git && \ -cd stack && \ -stack setup && \ -stack build -``` - -#### Complete guide to stack - -This repository also contains a complete [user guide to using stack -](https://github.com/commercialhaskell/stack/blob/release/doc/GUIDE.md), covering all of the most common use cases. - - -#### Questions, Feedback, Discussion - -* For frequently asked questions about detailed or specific use-cases, please - see [the FAQ](https://github.com/commercialhaskell/stack/blob/release/doc/faq.md). -* For general questions, comments, feedback and support please write - to [the stack mailing list](https://groups.google.com/d/forum/haskell-stack). -* For bugs, issues, or requests please - [open an issue](https://github.com/commercialhaskell/stack/issues/new). -* When using Stack Overflow, please use [the haskell-stack - tag](http://stackoverflow.com/questions/tagged/haskell-stack). - -#### Why stack? - -stack is a project of the [Commercial Haskell](http://commercialhaskell.com/) -group, spearheaded by [FP Complete](https://www.fpcomplete.com/). It is -designed to answer the needs of commercial Haskell users, hobbyist Haskellers, -and individuals and companies thinking about starting to use Haskell. It is -intended to be easy to use for newcomers, while providing the customizability -and power experienced developers need. - -While stack itself has been around since June of 2015, it is based on codebases -used by FP Complete for its corporate customers and internally for years prior. -stack is a refresh of that codebase combined with other open source efforts -like [stackage-cli](https://github.com/fpco/stackage-cli) to meet the needs of -users everywhere. - -A large impetus for the work on stack was a [large survey of people interested -in -Haskell](https://www.fpcomplete.com/blog/2015/05/thousand-user-haskell-survey), -which rated build issues as a major concern. The stack team hopes that stack -can address these concerns. - -
- -## Documentation Table Of Contents - -* Project Documentation - * [Maintainer Guide](https://github.com/commercialhaskell/stack/blob/release/doc/MAINTAINER_GUIDE.md): includes releasing information - * [Signing Key](https://github.com/commercialhaskell/stack/blob/release/doc/SIGNING_KEY.md): downloadable stack binaries are signed - with this key -* Tool Documentation - * [Build Command](https://github.com/commercialhaskell/stack/blob/release/doc/build_command.md): reference for the syntax of the - build command and the command line targets - * [Dependency Visualization](https://github.com/commercialhaskell/stack/blob/release/doc/dependency_visualization.md): uses Graphviz - * [Docker Integration](https://github.com/commercialhaskell/stack/blob/release/doc/docker_integration.md) - * [FAQ](https://github.com/commercialhaskell/stack/blob/release/doc/faq.md): frequently asked questions about detailed or specific - use-cases - * [Install/Upgrade](https://github.com/commercialhaskell/stack/blob/release/doc/install_and_upgrade.md): a list of downloads - available by operating system, installation instructions, and upgrade - instructions - * [Nonstandard Project Initialization](https://github.com/commercialhaskell/stack/blob/release/doc/nonstandard_project_init.md) - * [Shell Autocompletion](https://github.com/commercialhaskell/stack/blob/release/doc/shell_autocompletion.md) - * [User Guide](https://github.com/commercialhaskell/stack/blob/release/doc/GUIDE.md): in-depth tutorial covering the most common use - cases and all major stack features (requires no prior Haskell tooling - experience) - * [YAML Configuration](https://github.com/commercialhaskell/stack/blob/release/doc/yaml_configuration.md): reference for writing - `stack.yaml` files -* Advanced Documentation - * [Architecture](https://github.com/commercialhaskell/stack/blob/release/doc/architecture.md): reference for people curious about - stack internals, wanting to get involved deeply in the codebase, or - wanting to use stack in unusual ways +See [haskellstack.org](http://haskellstack.org) or the `doc` directory for more +information. diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md new file mode 120000 index 0000000000..44fcc63439 --- /dev/null +++ b/doc/CONTRIBUTING.md @@ -0,0 +1 @@ +../CONTRIBUTING.md \ No newline at end of file diff --git a/doc/ChangeLog.md b/doc/ChangeLog.md new file mode 120000 index 0000000000..41c10a6111 --- /dev/null +++ b/doc/ChangeLog.md @@ -0,0 +1 @@ +../ChangeLog.md \ No newline at end of file diff --git a/doc/GUIDE.md b/doc/GUIDE.md index 953c212e8d..756f50f525 100644 --- a/doc/GUIDE.md +++ b/doc/GUIDE.md @@ -1,3 +1,5 @@ +# User guide + stack is a modern, cross-platform build tool for Haskell code. This guide takes a new stack user through the typical workflows. This guide @@ -46,7 +48,7 @@ all commands work cross-platform, unless explicitly stated otherwise. ## Downloading and Installation The [documentation dedicated to downloading -stack](install_and_upgrade.md) has the most +stack](install_and_upgrade.html) has the most up-to-date information for a variety of operating systems, including multiple GNU/Linux flavors. Instead of repeating that content here, please go check out that page and come back here when you can successfully run `stack --version`. @@ -389,7 +391,7 @@ containing the module in question is not available. To tell stack to use text, you need to add it to your .cabal file — specifically in your build-depends section, like this: -```cabal +``` library hs-source-dirs: src exposed-modules: Lib @@ -617,7 +619,7 @@ At the time of writing: * Experimental custom snapshot support The most up-to-date information can always be found in the -[stack.yaml documentation](yaml_configuration.md#resolver). +[stack.yaml documentation](yaml_configuration.html#resolver). ## Existing projects @@ -723,7 +725,7 @@ Please choose one of the following commands to get started. stack init --resolver lts-2.22 You'll then need to add some extra-deps. See the -[stack.yaml documentation](yaml_configuration.md#extra-deps). +[stack.yaml documentation](yaml_configuration.html#extra-deps). You can also try falling back to a dependency solver with: @@ -1026,7 +1028,7 @@ to build. We're not going to cover the full generality of these arguments here; instead, there's [documentation covering the full build command -syntax](build_command.md). +syntax](build_command.html). Here, we'll just point out a few different types of arguments: * You can specify a *package name*, e.g. `stack build vector`. @@ -1163,7 +1165,7 @@ In addition to local directories, you can also refer to packages available in a Git repository or in a tarball over HTTP/HTTPS. This can be useful for using a modified version of a dependency that hasn't yet been released upstream. This is a slightly more advanced usage that we won't go into detail with here, but it's -covered in the [stack.yaml documentation](yaml_configuration.md#packages). +covered in the [stack.yaml documentation](yaml_configuration.html#packages). ## Flags and GHC options @@ -1251,7 +1253,7 @@ confusion. Final point: if you have GHC options that you'll be regularly passing to your packages, you can add them to your stack.yaml file (starting with stack-0.1.4.0). See [the documentation section on -ghc-options](yaml_configuration.md#ghc-options) +ghc-options](yaml_configuration.html#ghc-options) for more information. ## path @@ -1509,9 +1511,9 @@ There are lots of resources available for learning more about stack: * `stack --help` * `stack --version` — identify the version and Git hash of the stack executable * `--verbose` (or `-v`) — much more info about internal operations (useful for bug reports) -* The [README](https://github.com/commercialhaskell/stack#readme) +* The [home page](http://haskellstack.org) * The [stack mailing list](https://groups.google.com/d/forum/haskell-stack) -* The [the FAQ](faq.md) +* The [the FAQ](faq.html) * The [stack wiki](https://github.com/commercialhaskell/stack/wiki) * The [haskell-stack tag on Stack Overflow](http://stackoverflow.com/questions/tagged/haskell-stack) * [Another getting started with stack tutorial](http://seanhess.github.io/2015/08/04/practical-haskell-getting-started.html) @@ -1568,7 +1570,7 @@ getting type information in Emacs. For more information, see If you'd like to get some insight into the dependency tree of your packages, you can use the `stack dot` command and Graphviz. More information is -[available in the Dependency visualization documentation](dependency_visualization.md). +[available in the Dependency visualization documentation](dependency_visualization.html). ### Travis with caching @@ -1654,7 +1656,7 @@ code inside a Docker image, which means: a large initial download, but much faster builds For more information, see -[the Docker-integration documentation](docker_integration.md). +[the Docker-integration documentation](docker_integration.html). stack can also generate Docker images for you containing your built executables. This feature is great for automating deployments from CI. This feature is not diff --git a/doc/MAINTAINER_GUIDE.md b/doc/MAINTAINER_GUIDE.md index 05d6998414..7e148f83cc 100644 --- a/doc/MAINTAINER_GUIDE.md +++ b/doc/MAINTAINER_GUIDE.md @@ -1,3 +1,5 @@ +# Maintainer guide + ## Pre-release checks The following should be tested minimally before a release is considered good @@ -20,8 +22,8 @@ to go: * Search for old Stack version, unstable stack version, and the next "obvious" version in sequence (if doing a non-obvious jump) and replace with new version -* Ensure all `doc/*.md` files are listed in `stack.cabal`'s 'extra-source-files` -* Ensure all documentation pages listed in `mkdocs.yaml` + * Look for any links to "latest" documentation, replace with version tag +* Ensure all documentation pages listed in `doc/index.rst` * Check that any new Linux distribution versions added to `etc/scripts/release.hs` and `etc/scripts/vagrant-releases.sh` * Check that no new entries need to be added to @@ -61,6 +63,8 @@ for requirements to perform the release, and more details about the tool. * Reset the `release` branch to the released commit, e.g.: `git checkout release && git merge --ff-only vX.Y.Z && git push origin release` +* Update the `stable` branch + * Publish Github release * Edit @@ -69,6 +73,10 @@ for requirements to perform the release, and more details about the tool. * Upload package to Hackage: `stack upload . --pvp-bounds=both` +* Activate version for new release tag on + [readthedocs.org](https://readthedocs.org/projects/stack/versions/), and + ensure that stable documentation has updated + * On a machine with Vagrant installed: * Run `etc/scripts/vagrant-distros.sh` @@ -82,16 +90,17 @@ for requirements to perform the release, and more details about the tool. * Be sure to update the SHA sum * The commit message should just be `haskell-stack ` -* [Build new MinGHC distribution](#build_minghc) +* [Build new MinGHC distribution](#update-minghc) -* [Upload haddocks to Hackage](#upload_haddocks), if hackage couldn't build on its own +* [Upload haddocks to Hackage](#upload-haddocks-to-hackage), if hackage couldn't + build on its own * Announce to haskell-cafe@haskell.org, haskell-stack@googlegroups.com, commercialhaskell@googlegroups.com mailing lists -# Extra steps +## Extra steps -## Upload haddocks to Hackage +### Upload haddocks to Hackage * Set `STACKVER` environment variable to the Stack version (e.g. `0.1.6.0`) * Run: @@ -112,7 +121,7 @@ curl -X PUT \ "https://hackage.haskell.org/package/stack-$STACKVER/docs" ``` -## Update MinGHC +### Update MinGHC Full details of prerequisites and steps for building MinGHC are in its [README](https://github.com/fpco/minghc#building-installers). What follows is an diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000000..54e23a8b82 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,170 @@ +# The Haskell Tool Stack + +`stack` is a cross-platform program for developing Haskell +projects. It is aimed at Haskellers both new and experienced. + + + +It features: + +* Installing GHC automatically, in an isolated location. +* Installing packages needed for your project. +* Building your project. +* Testing your project. +* Benchmarking your project. + +#### How to install + +Downloads are available by operating system: + +* [Windows](install_and_upgrade.html#windows) +* [Mac OS X](install_and_upgrade.html#mac-os-x) +* [Ubuntu](install_and_upgrade.html#ubuntu) +* [Debian](install_and_upgrade.html#debian) +* [CentOS / Red Hat / Amazon Linux](install_and_upgrade.html#centos-red-hat-amazon-linux) +* [Fedora](install_and_upgrade.html#fedora) +* [Arch Linux](install_and_upgrade.html#arch-linux) +* [NixOS](install_and_upgrade.html#nixos) +* [Linux (general)](install_and_upgrade.html#linux) + +[Upgrade instructions](install_and_upgrade.html#upgrade) + +Note: if you are using cabal-install to install stack, you may need to pass a +constraint to work around a +[Cabal issue](https://github.com/haskell/cabal/issues/2759): `cabal install +--constraint 'mono-traversable >= 0.9' stack`. + +#### Quick Start Guide + +First you need to [install it (see previous section)](#how-to-install). + +##### Start your new project: + +```bash +stack new my-project +cd my-project +stack setup +stack build +stack exec my-project-exe +``` + +- The `stack new` command will create a new directory containing all +the needed files to start a project correctly. +- The `stack setup` will download the compiler if necessary in an isolated + location (default `~/.stack`) that won't interfere with any system-level + installations. (For information on installation paths, please use the `stack + path` command.). +- The `stack build` command will build the minimal project. +- `stack exec my-project-exe` will execute the command. +- If you just want to install an executable using stack, then all you have to do +is`stack install `. + +If you want to launch a REPL: + +```bash +stack ghci +``` + + +Run `stack` for a complete list of commands. + +##### Workflow + +The `stack new` command should have created the following files: + +``` +. +├── LICENSE +├── Setup.hs +├── app +│   └── Main.hs +├── my-project.cabal +├── src +│   └── Lib.hs +├── stack.yaml +└── test + └── Spec.hs + + 3 directories, 7 files +``` + +So to manage your library: + +1. Edit files in the `src/` directory. + +The `app` directory should preferably contains only files related to +executables. + +2. If you need to include another library (for example the package [`text`](https://hackage.haskell.org/package/text): + + - Add the package `text` to the file `my-project.cabal` + in the section `build-depends: ...`. + - run `stack build` another time + +3. If you get an error that tells you your package isn't in the LTS. + Just try to add a new version in the `stack.yaml` file in the `extra-deps` section. + +It was a really fast introduction on how to start to code in Haskell using `stack`. +If you want to go further, we highly recommend you to read the [`stack` guide](GUIDE.html). + +#### How to contribute + +This assumes that you have already installed a version of stack, and have `git` +installed. + +1. Clone `stack` from git with + `git clone https://github.com/commercialhaskell/stack.git`. +2. Enter into the stack folder with `cd stack`. +3. Build `stack` using a pre-existing `stack` install with + `stack setup && stack build`. +4. Once `stack` finishes building, check the stack version with + `stack --version`. Make sure the version is the latest. +5. Look for issues tagged with + [`newcomer` and `awaiting-pr` labels](https://github.com/commercialhaskell/stack/issues?q=is%3Aopen+is%3Aissue+label%3Anewcomer+label%3A%22awaiting+pr%22) + +Build from source as a one-liner: + +```bash +git clone https://github.com/commercialhaskell/stack.git && \ +cd stack && \ +stack setup && \ +stack build +``` + +#### Complete guide to stack + +This repository also contains a complete [user guide to using stack +](GUIDE.html), covering all of the most common use cases. + + +#### Questions, Feedback, Discussion + +* For frequently asked questions about detailed or specific use-cases, please + see [the FAQ](faq.html). +* For general questions, comments, feedback and support please write + to [the stack mailing list](https://groups.google.com/d/forum/haskell-stack). +* For bugs, issues, or requests please + [open an issue](https://github.com/commercialhaskell/stack/issues/new). +* When using Stack Overflow, please use [the haskell-stack + tag](http://stackoverflow.com/questions/tagged/haskell-stack). + +#### Why stack? + +stack is a project of the [Commercial Haskell](http://commercialhaskell.com/) +group, spearheaded by [FP Complete](https://www.fpcomplete.com/). It is +designed to answer the needs of commercial Haskell users, hobbyist Haskellers, +and individuals and companies thinking about starting to use Haskell. It is +intended to be easy to use for newcomers, while providing the customizability +and power experienced developers need. + +While stack itself has been around since June of 2015, it is based on codebases +used by FP Complete for its corporate customers and internally for years prior. +stack is a refresh of that codebase combined with other open source efforts +like [stackage-cli](https://github.com/fpco/stackage-cli) to meet the needs of +users everywhere. + +A large impetus for the work on stack was a [large survey of people interested +in +Haskell](https://www.fpcomplete.com/blog/2015/05/thousand-user-haskell-survey), +which rated build issues as a major concern. The stack team hopes that stack +can address these concerns. diff --git a/doc/SIGNING_KEY.md b/doc/SIGNING_KEY.md index 12c40453e4..bce4a5b136 100644 --- a/doc/SIGNING_KEY.md +++ b/doc/SIGNING_KEY.md @@ -1,3 +1,5 @@ +# Signing key + Releases are signed with this key: ``` @@ -31,4 +33,4 @@ F3mtEFEtmJ6ljSks5tECxfJFvQlkpILBbGvHfuljKMeaj+iN+bsHmV4em/ELB1ku N9Obs/bFDBMmQklIdLP7dOunDjY4FwwcFcXdNyg= =YUsC -----END PGP PUBLIC KEY BLOCK----- -``` \ No newline at end of file +``` diff --git a/doc/architecture.md b/doc/architecture.md index a016b35591..978af5f651 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -1,3 +1,5 @@ +# Architecture + ## Terminology * Package identifier: a package name and version, e.g. text-1.2.1.0 diff --git a/doc/build_command.md b/doc/build_command.md index bc5107697e..ce93506edb 100644 --- a/doc/build_command.md +++ b/doc/build_command.md @@ -1,3 +1,5 @@ +# Build command + ## Overview The primary command you use in stack is build. This page describes the details diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000000..4ef272c2e9 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,288 @@ +# -*- coding: utf-8 -*- +# +# stack documentation build configuration file, created by +# sphinx-quickstart on Mon Nov 23 13:24:36 2015. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import shlex +from recommonmark.parser import CommonMarkParser + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +source_suffix = ['.md', '.rst'] + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'stack' +copyright = u'2015, Stack contributors' +author = u'Stack contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +# version = 'latest' +# The full version, including alpha/beta/rc tags. +# release = 'latest' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'stackdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'stack.tex', u'stack Documentation', + u'Stack contributors', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'stack', u'stack Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'stack', u'stack Documentation', + author, 'stack', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + +source_parsers = { + '.md': CommonMarkParser, +} diff --git a/doc/dependency_visualization.md b/doc/dependency_visualization.md index 110dd6115e..60cb1d2a66 100644 --- a/doc/dependency_visualization.md +++ b/doc/dependency_visualization.md @@ -1,3 +1,5 @@ +# Dependency visualization + You can use stack to visualize the dependencies between your packages and optionally also external dependencies. As an example, let's look at `wreq`: diff --git a/doc/docker_integration.md b/doc/docker_integration.md index dbd5122967..0f42b6178f 100644 --- a/doc/docker_integration.md +++ b/doc/docker_integration.md @@ -1,4 +1,4 @@ -Using Docker with Stack +Docker integration =============================================================================== `stack` has support for automatically performing builds inside a Docker @@ -379,7 +379,7 @@ process. You could also use a Dockerfile to make this reusable. Consult the [Docker user guide](https://docs.docker.com/userguide/) for more on creating Docker images. -### Custom images +### Custom images The easiest way to create your own custom image us by extending FP Complete's images, but if you prefer to start from scratch, most images that include the diff --git a/doc/faq.md b/doc/faq.md index 4ec1dbebf4..e574dae3b9 100644 --- a/doc/faq.md +++ b/doc/faq.md @@ -1,10 +1,12 @@ +# FAQ + So that this doesn't become repetitive: for the reasons behind the answers -below, see the [Architecture](architecture.md) page. The goal of the answers here is to be as +below, see the [Architecture](architecture.html) page. The goal of the answers here is to be as helpful and concise as possible. #### Where is stack installed and will it interfere with `ghc` (etc) I already have installed? -Stack itself is installed in normal system locations based on the mechanism you used (see the [Install and upgrade](install_and_upgrade.md) page). Stack installs the Stackage libraries in `~/.stack` and any project libraries or extra dependencies in a `.stack-work` directory within each project's directory. None of this should affect any existing Haskell tools at all. +Stack itself is installed in normal system locations based on the mechanism you used (see the [Install and upgrade](install_and_upgrade.html) page). Stack installs the Stackage libraries in `~/.stack` and any project libraries or extra dependencies in a `.stack-work` directory within each project's directory. None of this should affect any existing Haskell tools at all. #### What is the relationship between stack and cabal? @@ -153,7 +155,7 @@ Like all other targets, `stack test` runs test suites in parallel by default. Th #### Can I get bash autocompletion? -Yes, see the [shell-autocompletion documentation](shell_autocompletion.md) +Yes, see the [shell-autocompletion documentation](shell_autocompletion.html) #### How do I update my package index? @@ -174,7 +176,7 @@ of those three. Updating the index will have no impact on stack's behavior. #### I have a custom package index I'd like to use, how do I do so? -You can configure this in your stack.yaml. See [YAML configuration](yaml_configuration.md). +You can configure this in your stack.yaml. See [YAML configuration](yaml_configuration.html). #### How can I make sure my project builds against multiple ghc versions? @@ -202,11 +204,11 @@ $ STACK_YAML=stack-7.10.yaml stack build # builds using the given yaml file #### I heard you can use this with Docker? Yes, stack supports using Docker with images that contain preinstalled Stackage -packages and the tools. See [Docker integration](docker_integration.md) for details. +packages and the tools. See [Docker integration](docker_integration.html) for details. #### How do I use this with Travis CI? -See the [Travis section in the GUIDE](GUIDE.md#travis-with-caching) +See the [Travis section in the GUIDE](GUIDE.html#travis-with-caching) #### What is licensing restrictions on Windows? diff --git a/doc/ghcjs.md b/doc/ghcjs.md index 50d72c3b4c..7891adb2dc 100644 --- a/doc/ghcjs.md +++ b/doc/ghcjs.md @@ -32,7 +32,7 @@ setup-info: url: "https://github.com/fizruk/ghcjs/releases/download/v0.2.0.20151001/ghcjs-0.2.0.20151001.tar.gz" ``` -or for the 2015-10-29 master branch +or for the 2015-10-29 master branch ```yaml compiler: ghcjs-0.2.0.20151029_ghc-7.10.2 compiler-check: match-exact diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000000..fde26ac7bf --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,36 @@ +The Haskell Tool Stack +====================== + +Documentation table of contents +------------------------------- + +.. toctree:: + + README.md + ChangeLog.md + CONTRIBUTING.md + +.. toctree:: + :caption: Project documentation + + MAINTAINER_GUIDE.md + SIGNING_KEY.md + +.. toctree:: + :caption: Tool documentation + + build_command.md + dependency_visualization.md + docker_integration.md + faq.md + ghcjs.md + install_and_upgrade.md + nonstandard_project_init.md + shell_autocompletion.md + GUIDE.md + yaml_configuration.md + +.. toctree:: + :caption: Advanced documentation + + architecture.md diff --git a/doc/install_and_upgrade.md b/doc/install_and_upgrade.md index 5fc273bf90..8d84b157dd 100644 --- a/doc/install_and_upgrade.md +++ b/doc/install_and_upgrade.md @@ -1,12 +1,14 @@ +# Install/upgrade + Distribution packages are available for [Ubuntu](#ubuntu), [Debian](#debian), -[CentOS / Red Hat](#centos--red-hat), [Fedora](#fedora) and +[CentOS / Red Hat / Amazon Linux](#centos-red-hat-amazon-linux), [Fedora](#fedora) and [Arch Linux](#arch-linux). Binaries for other operating systems are listed below, and available on [the Github releases page](https://github.com/fpco/stack/releases). For the future, we are open to supporting more OSes (to request one, please [submit an issue](https://github.com/commercialhaskell/stack/issues/new)). -Binary packages are signed with this [signing key](SIGNING_KEY.md). +Binary packages are signed with this [signing key](SIGNING_KEY.html). If you are writing a script that needs to download the latest binary, you can find links that always point to the latest bindists @@ -37,8 +39,8 @@ will make `stack install` and `stack upgrade` work correctly out of the box. * Download the latest release: - * [Windows 32-bit](https://www.stackage.org/stack/windows-i386) - * [Windows 64-bit](https://www.stackage.org/stack/windows-x86_64) + * [Windows 32-bit](https://www.stackage.org/stack/windows-i386) + * [Windows 64-bit](https://www.stackage.org/stack/windows-x86_64) * Unpack the archive and place `stack.exe` somewhere on your `%PATH%` (see [Path section below](#path)) and you can then run `stack` on the command line. @@ -52,7 +54,7 @@ such. ## Mac OS X -### Using brew +### Using Homebrew If you have a popular [brew](http://brew.sh/) tool installed, you can just do: @@ -75,33 +77,33 @@ Yosemite and Mavericks as well, and may also work on older versions (YMMV). *note*: for 32-bit, use the [generic Linux option](#linux) -1. Get the FP Complete key: + 1. Get the FP Complete key: - wget -q -O- https://s3.amazonaws.com/download.fpcomplete.com/ubuntu/fpco.key | sudo apt-key add - + sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 575159689BEFB442 -2. Add the appropriate source repository (if not sure, run ``lsb_release -a`` to find out your Ubuntu version): + 2. Add the appropriate source repository (if not sure, run ``lsb_release -a`` to find out your Ubuntu version): - * Ubuntu 15.10 (amd64): + * Ubuntu 15.10 (amd64): echo 'deb http://download.fpcomplete.com/ubuntu/wily stable main'|sudo tee /etc/apt/sources.list.d/fpco.list - * Ubuntu 15.04 (amd64): + * Ubuntu 15.04 (amd64): echo 'deb http://download.fpcomplete.com/ubuntu/vivid stable main'|sudo tee /etc/apt/sources.list.d/fpco.list - * Ubuntu 14.10 (amd64) + * Ubuntu 14.10 (amd64) echo 'deb http://download.fpcomplete.com/ubuntu/utopic stable main'|sudo tee /etc/apt/sources.list.d/fpco.list - * Ubuntu 14.04 (amd64) + * Ubuntu 14.04 (amd64) echo 'deb http://download.fpcomplete.com/ubuntu/trusty stable main'|sudo tee /etc/apt/sources.list.d/fpco.list - * Ubuntu 12.04 (amd64) + * Ubuntu 12.04 (amd64) echo 'deb http://download.fpcomplete.com/ubuntu/precise stable main'|sudo tee /etc/apt/sources.list.d/fpco.list -3. Update apt and install + 3. Update apt and install sudo apt-get update && sudo apt-get install stack -y @@ -109,21 +111,21 @@ Yosemite and Mavericks as well, and may also work on older versions (YMMV). *note*: for 32-bit, use the [generic Linux option](#linux) -1. Get the FP Complete key: + 1. Get the FP Complete key: wget -q -O- https://s3.amazonaws.com/download.fpcomplete.com/debian/fpco.key | sudo apt-key add - -2. Add the appropriate source repository: + 2. Add the appropriate source repository: - * Debian 8 (amd64): + * Debian 8 (amd64): echo 'deb http://download.fpcomplete.com/debian/jessie stable main'|sudo tee /etc/apt/sources.list.d/fpco.list - * Debian 7 (amd64) + * Debian 7 (amd64) echo 'deb http://download.fpcomplete.com/debian/wheezy stable main'|sudo tee /etc/apt/sources.list.d/fpco.list -3. Update apt and install + 3. Update apt and install sudo apt-get update && sudo apt-get install stack -y @@ -131,17 +133,17 @@ Yosemite and Mavericks as well, and may also work on older versions (YMMV). *note*: for 32-bit, use the [generic Linux option](#linux) -1. Add the appropriate source repository: + 1. Add the appropriate source repository: - * CentOS 7 / RHEL 7 (x86_64) + * CentOS 7 / RHEL 7 (x86_64) curl -sSL https://s3.amazonaws.com/download.fpcomplete.com/centos/7/fpco.repo | sudo tee /etc/yum.repos.d/fpco.repo - * CentOS 6 / RHEL 6 (x86_64) + * CentOS 6 / RHEL 6 (x86_64) curl -sSL https://s3.amazonaws.com/download.fpcomplete.com/centos/6/fpco.repo | sudo tee /etc/yum.repos.d/fpco.repo -2. Install: + 2. Install: sudo yum -y install stack @@ -149,29 +151,29 @@ Yosemite and Mavericks as well, and may also work on older versions (YMMV). *note*: for 32-bit, you can use this [Fedora Copr repo](https://copr.fedoraproject.org/coprs/petersen/stack/) which can be enabled with: - sudo dnf copr enable petersen/stack + sudo dnf copr enable petersen/stack -1. Add the appropriate source repository: + 1. Add the appropriate source repository: - * Fedora 23 (x86_64) + * Fedora 23 (x86_64) curl -sSL https://s3.amazonaws.com/download.fpcomplete.com/fedora/23/fpco.repo | sudo tee /etc/yum.repos.d/fpco.repo - * Fedora 22 (x86_64) + * Fedora 22 (x86_64) curl -sSL https://s3.amazonaws.com/download.fpcomplete.com/fedora/22/fpco.repo | sudo tee /etc/yum.repos.d/fpco.repo - * Fedora 21 (x86_64) + * Fedora 21 (x86_64) curl -sSL https://s3.amazonaws.com/download.fpcomplete.com/fedora/21/fpco.repo | sudo tee /etc/yum.repos.d/fpco.repo -2. Install: + 2. Install: - * Fedora 22 and above + * Fedora 22 and above sudo dnf -y install stack - * Fedora < 22 + * Fedora < 22 sudo yum -y install stack @@ -191,23 +193,23 @@ If you use the [ArchHaskell repository](https://wiki.archlinux.org/index.php/Arc Users who follow the `nixos-unstable` channel or the Nixpkgs `master` branch can install the latest `stack` release into their profile by running: - nix-env -f "" -iA haskellPackages.stack + nix-env -f "" -iA haskellPackages.stack Alternatively, the package can be built from source as follows. -1. Clone the git repo: + 1. Clone the git repo: - git clone https://github.com/commercialhaskell/stack.git + git clone https://github.com/commercialhaskell/stack.git -2. Create a `shell.nix` file: + 2. Create a `shell.nix` file: - cabal2nix --shell ./. --no-check --no-haddock > shell.nix + cabal2nix --shell ./. --no-check --no-haddock > shell.nix - Note that the tests fail on NixOS, so disable them with `--no-check`. Also, haddock currently doesn't work for stack, so `--no-haddock` disables it. + Note that the tests fail on NixOS, so disable them with `--no-check`. Also, haddock currently doesn't work for stack, so `--no-haddock` disables it. -3. Install stack to your user profile: + 3. Install stack to your user profile: - nix-env -i -f shell.nix + nix-env -i -f shell.nix For more information on using Stack together with Nix, please see [the NixOS manual section on @@ -219,13 +221,13 @@ Stack](http://nixos.org/nixpkgs/manual/#using-stack-together-with-nix). * Download the latest release: - * [Linux 64-bit, standard](https://www.stackage.org/stack/linux-x86_64) - * [Linux 32-bit, standard](https://www.stackage.org/stack/linux-i386) + * [Linux 64-bit, standard](https://www.stackage.org/stack/linux-x86_64) + * [Linux 32-bit, standard](https://www.stackage.org/stack/linux-i386) If you are on an older distribution that only includes libgmp4 (libgmp.so.3), such as CentOS/RHEL/Amazon Linux 6.x, use one of these instead: - * [Linux 64-bit, libgmp4](https://www.stackage.org/stack/linux-x86_64-gmp4) - * [Linux 32-bit, libgmp4](https://www.stackage.org/stack/linux-i386-gmp4) + * [Linux 64-bit, libgmp4](https://www.stackage.org/stack/linux-x86_64-gmp4) + * [Linux 32-bit, libgmp4](https://www.stackage.org/stack/linux-i386-gmp4) * Extract the archive and place `stack` somewhere on your `$PATH` (see [Path section below](#path)) diff --git a/doc/nonstandard_project_init.md b/doc/nonstandard_project_init.md index aa77301917..674806f60d 100644 --- a/doc/nonstandard_project_init.md +++ b/doc/nonstandard_project_init.md @@ -1,13 +1,15 @@ -# Introduction +# Non-standard project initialization + +## Introduction The purpose of this page is to collect information about issues that arise when users either have an existing cabal project or another nonstandard setup such as a private hackage database. -# Using a Cabal File +## Using a Cabal File New users may be confused by the fact that you must add dependencies to the package's cabal file, even in the case when you have already listed the package in the `stack.yaml`. In most cases, dependencies for your package that are in the Stackage snapshot need *only* be added to the cabal file. stack makes heavy use of Cabal the library under the hood. In general, your stack packages should also end up being valid cabal-install packages. -## Issues Referenced +### Issues Referenced - https://github.com/commercialhaskell/stack/issues/105 -# Passing Flags to Cabal +## Passing Flags to Cabal Any build command, `bench`, `install`, `haddock`, `test`, etc. takes a `--flag` option which passes flags to cabal. Another way to do this is using the flags field in a `stack.yaml`, with the option to specify flags on a per package basis. @@ -28,7 +30,7 @@ It is also possible to pass the same flag to multiple packages, i.e. `stack buil Currently one needs to list all of your modules that interpret flags in the `other-modules` section of a cabal file. `cabal-install` has a different behavior currently and doesn't require that the modules be listed. This may change in a future release. -## Issues Referenced +### Issues Referenced - https://github.com/commercialhaskell/stack/issues/191 - https://github.com/commercialhaskell/stack/issues/417 - https://github.com/commercialhaskell/stack/issues/335 @@ -36,7 +38,7 @@ Currently one needs to list all of your modules that interpret flags in the `oth - https://github.com/commercialhaskell/stack/issues/365 - https://github.com/commercialhaskell/stack/issues/105 -# Selecting a Resolver +## Selecting a Resolver `stack init` or `stack new` will try to default to the current Haskell LTS present on `https://www.stackage.org/snapshots` if no snapshot has been previously used locally, and to the latest LTS snapshot locally used for a build otherwise. Using an incorrect resolver can cause a build to fail if the version of GHC it requires is not present. @@ -45,11 +47,11 @@ Alternatively the `--resolver` option can be used with the name of any snapshots :TODO: Document `--solver` -## Issues Referenced +### Issues Referenced - https://github.com/commercialhaskell/stack/issues/468 - https://github.com/commercialhaskell/stack/issues/464 -# Using git Repositories +## Using git Repositories stack has support for packages that reside in remote git locations. Example: @@ -62,31 +64,31 @@ packages: commit: 8debedd3fcb6525ac0d7de2dd49217dce2abc0d9 ``` -## Issues Referenced +### Issues Referenced - https://github.com/commercialhaskell/stack/issues/254 - https://github.com/commercialhaskell/stack/issues/199 -# Private Hackage +## Private Hackage Working with a private Hackage is currently supported in certain situations. There exist special entries in `stack.yaml` that may help you. In a `stack.yaml` file, it is possible to add lines for packages in your database referencing the sdist locations via an `http` entry, or to use a `Hackage` entry. The recommended stack workflow is to use git submodules instead of a private Hackage. Either by using git submodules and listing the directories in the packages section of `stack.yaml`, or by adding the private dependencies as git URIs with a commit SHA to the `stack.yaml`. This has the large benefit of eliminating the need to manage a Hackage database and pointless version bumps. -For further information see [YAML configuration](yaml_configuration.md) +For further information see [YAML configuration](yaml_configuration.html) -## Issues Referenced +### Issues Referenced - https://github.com/commercialhaskell/stack/issues/445 - https://github.com/commercialhaskell/stack/issues/565 -# Custom Snapshots +## Custom Snapshots Currently WIP? -## Issues Referenced +### Issues Referenced - https://github.com/commercialhaskell/stack/issues/111 - https://github.com/commercialhaskell/stack/issues/253 - https://github.com/commercialhaskell/stack/issues/137 -# Intra-package Targets +## Intra-package Targets stack supports intra-package targets, similar to `cabal build COMPONENTS` for situations when you don't want to build every target inside your package. Example: @@ -97,5 +99,5 @@ stack test stack:test:stack-integration-test Note: this does require prefixing the component name with the package name. -## Issues referenced +### Issues referenced - https://github.com/commercialhaskell/stack/issues/201 diff --git a/doc/shell_autocompletion.md b/doc/shell_autocompletion.md index 3848787d1d..142195eade 100644 --- a/doc/shell_autocompletion.md +++ b/doc/shell_autocompletion.md @@ -1,4 +1,4 @@ -## Shell auto-completion: +# Shell Auto-completion Note: if you installed a package for you Linux distribution, the bash completion file was automatically installed (you may need the `bash-completion` package to @@ -6,7 +6,7 @@ have it take effect). The following adds support for shell tab completion for standard Stack arguments, although completion for filenames and executables etc. within stack is still lacking (see [issue 823](https://github.com/commercialhaskell/stack/issues/832)). -### for bash users +## for bash users you need to run following command ``` @@ -14,7 +14,7 @@ eval "$(stack --bash-completion-script stack)" ``` You can also add it to your `.bashrc` file if you want. -### for ZSH users: +## for ZSH users: documentation says: > Zsh can handle bash completions functions. The latest development version of zsh has a function bashcompinit, that when run will allow zsh to read bash completion specifications and functions. This is documented in the zshcompsys man page. To use it all **you need to do is run bashcompinit at any time after compinit**. It will define complete and compgen functions corresponding to the bash builtins. diff --git a/doc/yaml_configuration.md b/doc/yaml_configuration.md index 9e1efcf613..744e0f78ea 100644 --- a/doc/yaml_configuration.md +++ b/doc/yaml_configuration.md @@ -36,7 +36,7 @@ packages: - some-directory - https://example.com/foo/bar/baz-0.0.2.tar.gz - location: - git: git@github.com:commercialhaskell/stack + git: git@github.com:commercialhaskell/stack.git commit: 6a86ee32e5b869a877151f74064572225e1a0398 - location: hg: https://example.com/hg/repo diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index 3d2a431cd5..0000000000 --- a/mkdocs.yml +++ /dev/null @@ -1,20 +0,0 @@ -site_name: stack - The Haskell Tool Stack -pages: -- 'Home': README.md -- 'Guide': doc/GUIDE.md -- 'YAML configuration': doc/yaml_configuration.md -- 'FAQ': doc/faq.md -- 'Build command': doc/build_command.md -- 'Contributers guide': CONTRIBUTING.md -- 'Architecture': doc/architecture.md -- 'Dependency visualization': doc/dependency_visualization.md -- 'Docker integration': doc/docker_integration.md -- 'GHCJS': doc/ghcjs.md -- 'Install and upgrade': doc/install_and_upgrade.md -- 'Maintainer guide': doc/MAINTAINER_GUIDE.md -- 'Non-standard project initialization': doc/nonstandard_project_init.md -- 'Shell auto-complation': doc/shell_autocompletion.md -- 'Signing key': doc/SIGNING_KEY.md -- 'Changelog': ChangeLog.md -theme: readthedocs -docs_dir: '.' \ No newline at end of file diff --git a/stack.cabal b/stack.cabal index 72cfca96dd..b247f08d47 100644 --- a/stack.cabal +++ b/stack.cabal @@ -13,23 +13,10 @@ maintainer: manny@fpcomplete.com category: Development build-type: Simple cabal-version: >=1.10 -homepage: https://github.com/commercialhaskell/stack +homepage: http://haskellstack.org extra-source-files: CONTRIBUTING.md ChangeLog.md README.md - doc/GUIDE.md - doc/MAINTAINER_GUIDE.md - doc/SIGNING_KEY.md - doc/architecture.md - doc/build_command.md - doc/dependency_visualization.md - doc/docker_integration.md - doc/faq.md - doc/ghcjs.md - doc/install_and_upgrade.md - doc/nonstandard_project_init.md - doc/shell_autocompletion.md - doc/yaml_configuration.md -- Glob would be nice, but apparently Cabal doesn't support it: -- cabal: filepath wildcard 'test/package-dump/*.txt' does not match any files. @@ -327,4 +314,4 @@ test-suite stack-integration-test source-repository head type: git - location: https://github.com/commercialhaskell/stack + location: https://github.com/commercialhaskell/stack.git