From fcf9a04224fed910d01cf6f4d9c2d1bdc7c085af Mon Sep 17 00:00:00 2001 From: Vladislav Zavialov Date: Sun, 24 Jan 2021 18:33:33 +0300 Subject: Update cabal.project and README build instructions --- README.md | 24 +++++------------------- 1 file changed, 5 insertions(+), 19 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index e9ff09ca..d19113c9 100644 --- a/README.md +++ b/README.md @@ -41,11 +41,13 @@ Note: before building `haddock`, you need to build the subprojects `haddock-library` and `haddock-api`, in this order! The `cabal v2-build` takes care of this automatically. -#### Using [`cabal v2-build`][cabal v2] +#### Using `cabal` + +Requires cabal `>= 3.4` and GHC `== 9.0`: ```bash -cabal v2-build -w ghc-8.10.1 -cabal v2-test -w ghc-8.10.1 all +cabal build all --enable-tests +cabal test all ``` #### Using `stack` @@ -57,22 +59,6 @@ export HADDOCK_PATH="$(stack exec which haddock)" stack test ``` -#### Using Cabal sandboxes (deprecated) - -```bash -cabal sandbox init -cabal sandbox add-source haddock-library -cabal sandbox add-source haddock-api -cabal sandbox add-source haddock-test -# adjust -j to the number of cores you want to use -cabal install -j4 --dependencies-only --enable-tests -cabal configure --enable-tests -cabal build -j4 -# run the test suite -export HADDOCK_PATH="dist/build/haddock/haddock" -cabal test -``` - ### Git Branches If you're a GHC developer and want to update Haddock to work with your changes, -- cgit v1.2.3 From d843746143a4c31242c08d7e6071ecaf7e8e5970 Mon Sep 17 00:00:00 2001 From: Hécate Moonlight Date: Fri, 5 Feb 2021 16:40:35 +0100 Subject: Add a CONTRIBUTING.md file --- CONTRIBUTING.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 57 ++------------------------------------------------- 2 files changed, 65 insertions(+), 55 deletions(-) create mode 100644 CONTRIBUTING.md (limited to 'README.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..6a396c41 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,63 @@ +# Contributing to Haddock + +Thank you for contributing to Haddock! Here is the information you will need in +order to make your contribution + +## Reporting issues + +Please open a ticket if you get an unexpected behaviour from Haddock! +You should ideally include a [Short, Self Contained, Correct (Compilable), Example][SSCCE] +in your ticket, so that the maintainers may easily reproduce your issue. + +## Hacking + +To get started you'll need the latest GHC release installed. + +Clone the repository: + +```bash +git clone https://github.com/haskell/haddock.git +cd haddock +``` + +### Git Branches + +Please **always** base your pull request on the current GHC version branch +(`ghc-9.0` for instance). The PR will be forward-ported to `ghc-head` +so that GHC can use it. + +### Building the packages + +#### Using `cabal` + +Requires cabal `>= 3.4` and GHC `== 9.0`: + +```bash +cabal v2-build all --enable-tests +cabal v2-test all +``` + +#### Using `stack` + +```bash +stack init +stack build +export HADDOCK_PATH="$(stack exec which haddock)" +stack test +``` + +### Updating golden testsuite outputs + +If you've changed Haddock's output, you will probably need to accept the new +output of Haddock's golden test suites (`html-test`, `latex-test`, +`hoogle-test`, and `hypsrc-test`). This can be done by passing the `--accept` +argument to these test suites. With a new enough version of `cabal-install`: + +``` +cabal v2-test html-test latex-test hoogle-test hypsrc-test \ + --test-option='--accept' +``` + + +[SSCCE]: http://sscce.org/ + diff --git a/README.md b/README.md index d19113c9..69763a52 100644 --- a/README.md +++ b/README.md @@ -21,62 +21,9 @@ This project consists of three packages: ## Contributing -Please create issues when you have any problems and pull requests if you have -some code. +See [CONTRIBUTING.md](CONTRIBUTING.md) to see how to make contributions to the +project. -## Hacking - -To get started you'll need the latest GHC release installed. - -Clone the repository: - -```bash -git clone https://github.com/haskell/haddock.git -cd haddock -``` - -and then proceed using your favourite build tool. - -Note: before building `haddock`, you need to build the subprojects -`haddock-library` and `haddock-api`, in this order! -The `cabal v2-build` takes care of this automatically. - -#### Using `cabal` - -Requires cabal `>= 3.4` and GHC `== 9.0`: - -```bash -cabal build all --enable-tests -cabal test all -``` - -#### Using `stack` - -```bash -stack init -stack build -export HADDOCK_PATH="$(stack exec which haddock)" -stack test -``` - -### Git Branches - -If you're a GHC developer and want to update Haddock to work with your changes, -you should be working on the `ghc-head` branch. See instructions at - -for an example workflow. - -### Updating golden testsuite outputs - -If you've changed Haddock's output, you will probably need to accept the new -output of Haddock's golden test suites (`html-test`, `latex-test`, -`hoogle-test`, and `hypsrc-test`). This can be done by passing the `--accept` -argument to these test suites. With a new enough version of `cabal-install`: - -``` -cabal v2-test html-test latex-test hoogle-test hypsrc-test \ - --test-option='--accept' -``` [CI page]: https://travis-ci.org/haskell/haddock [CI badge]: https://travis-ci.org/haskell/haddock.svg?branch=ghc-8.10 -- cgit v1.2.3