From 72993a3f59ba3e405c58eb2cde4e8e1b725ae588 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 27 Apr 2017 17:36:20 -0700 Subject: [PATCH] site: contributing: rewrite building how-to --- site/contributing.md | 235 +++++++++++++------------------------------ 1 file changed, 68 insertions(+), 167 deletions(-) diff --git a/site/contributing.md b/site/contributing.md index 4a7ad5d84..5f02a6c92 100644 --- a/site/contributing.md +++ b/site/contributing.md @@ -8,6 +8,7 @@ New contributors are always welcome. Jump in! Or [ask us](/docs.html#getting-help) to help you find a task. + ## Get started as a... ### Funder @@ -28,6 +29,7 @@ build your prosperity consciousness! - Test installation on platforms you have access to - Run the latest release or developer build +- Test examples and advice in the docs - Report packaging, documentation, UX, functional bugs - Report and help analyse problems via irc/mail list/bug tracker @@ -302,124 +304,84 @@ $ make haddocktest #### Do code review -- review and discuss new pull requests and commits on github +- review and discuss new [pull requests](http://prs.hledger.org) and commits on github - set up for development and test the latest changes in your own repo - read the existing [code docs and source](#quick-links) - send feedback or discuss via irc or list -#### Install stack and git - -[stack](https://github.com/commercialhaskell/stack/wiki/Downloads) is -the recommended tool for building hledger from source. -It builds haskell projects, installing required haskell libraries as needed. -It can also install GHC (the compiler) and (on windows) git, if needed. - -You don't need to use stack, if you are already expert with the older -cabal tool, or even just GHC, but I won't attempt to document those -procedures; these docs assume you have downloaded and installed stack. - -On Windows, you should choose the 64-bit stack download if you will be -processing >50,000 transactions at a time with hledger -([#275](https://github.com/simonmichael/hledger/issues/275)). - -[git](http://git-scm.com) is the revision control tool you'll need to -fetch the latest hledger source and submit changes. On windows, stack -can install it for you. These docs assume you have installed git and -know a little about how to use it. - -#### Install other optional tools - -Up-to-date `alex`, `happy`, and `haddock` tools are required, but `stack` should install those for you. - -Here are some optional extra tools: - -- `shelltestrunner` is useful for running functional tests. -- `hasktags` is an easy way to generate editor tag files for quick source code navigation. -- `profiteur` is for reporting stack profiles. -- `hpack` regenerates cabal files when package.yaml files have been updated. -- `hoogle` is for searching source code. - -You can install them all with: +#### Build hledger ```shell -$ stack install shelltestrunner hasktags profiteur hpack hoogle +$ git clone http://github.com/simonmichael/hledger hledger && cd hledger && stack install # or git: ``` -#### Get the latest hledger source +Or in more detail: + +**1. Get tools** + +1. [`stack`](https://github.com/commercialhaskell/stack/wiki/Downloads) +is the recommended tool for building hledger. It will also install +haskell tools and libraries as needed. You can use cabal-install +instead of stack if you prefer, but that requires more expertise; +the hledger docs assume stack. +The [download](/download.html#b) page has more tips. + +2. [`git`](http://git-scm.com) is the version control tool needed to +fetch the hledger source and submit changes. On Windows, stack will +install this as well. + +3. Optional tools to consider: + + - `alex`, `happy`, `haddock` and `hpack` - reasonably up-to-date + versions of these tools are required; stack ensures this automatically. + + - `ghcid` is a very useful tool that gives real-time feedback as you make code changes. + + - `hasktags` is an easy way to generate tag files for quick source code navigation in editors like Emacs and vi. + + - `shelltestrunner` is required if you want to run hledger's functional tests. + + ```shell + $ stack install ghcid hasktags shelltestrunner + ``` + +**2. Get the source** + +```shell +$ git clone http://github.com/simonmichael/hledger hledger # or git: +``` + +**3. Build/install** ```shell -$ git clone code.hledger.org hledger # aka github.com/simonmichael/hledger.git $ cd hledger +$ stack install ``` - +- identify what to test +- choose the test type: unit ? functional ? benchmark ? +- currently expected to pass or fail ? +- figure out where it goes +- write test, verify expected result +- get it committed #### Use the Makefile @@ -458,68 +420,6 @@ $ make test -n && echo functest PASSED) || echo functest FAILED ``` -#### Build or install hledger - -Run `make` to see a list of build rules. You probably want `build` or `install`. - -`make build` runs stack build, which downloads required haskell -dependencies and builds all hledger packages. -The resulting executables will be somewhere under .stack-work, eg in -`.stack-work/install/i386-linux/lts-3.0/7.10.2/bin/`. - -```shell -$ make build -stack build -hledger-lib-0.27: configure -hledger-lib-0.27: build -hledger-lib-0.27: install -hledger-0.27: configure -hledger-0.27: build -Progress: 1/4 -... -``` - -Note stack will install required haskell libraries, but not C -libraries such as curses or terminfo. If you get a build error, it is -likely because one of these is missing, in which case you must -identify and install it yourself using your system's package -manager. This is usually a bit harder on Windows. - -`make install` runs stack install, which does everything stack build does and also -copies the executables to `~/.local/bin` or the Windows equivalent. -You should make sure this directory is in your `$PATH`, so that you can just type -`hledger` to run the latest. -```shell -$ make install -stack install -NOTE: the install command is functionally equivalent to 'build --copy-bins' -hledger-0.27: build -... -Copied executables to /Users/simon/.local/bin/: -- hledger-web -- hledger-ui -- hledger -``` - -You can save time and effort by building just the package(s) you're interested in. -To install just the hledger command-line tool, but not hledger-ui or (especially costly) -hledger-web, do: -```shell -$ stack install hledger -``` - -(This looks like the [download page](download) command for installing the latest hledger release from Stackage. -The difference is, here we are running it inside the hledger source tree, so the source version will be installed.) - -#### Add a test - -- identify what to test -- choose the test type: unit ? functional ? benchmark ? -- currently expected to pass or fail ? -- figure out where it goes -- write test, verify expected result -- get it committed - #### Use the REPL (GHCI) These all work from the main hledger source directory (at least). @@ -595,10 +495,10 @@ Follow the usual github workflow: If you're new to this process, [help.github.com](http://help.github.com) may be useful. -#### Join the contributors list +#### Add yourself to the contributor list -- after getting one or more patches committed, read and sign the [contributor list & agreement](contributors.html) -- or, [ask](#how-to-get-help) to be added +- after getting something into the master branch, read and sign the [contributor list & agreement](contributors.html) +- or, [ask](/docs.html#get-help) to be added ### Technical Writer @@ -786,8 +686,8 @@ don't run make setversion. - [tweet] -## Project overview +## Project overview ### Mission, principles, goals The hledger project aims to produce: @@ -871,8 +771,8 @@ Dev sprint/party #2 was on 2015/10/10. -## Code architecture +## Code architecture ### hledger There are two core cabal packages: @@ -1017,6 +917,7 @@ makefile for instructions). This rebuilds automatically when haskell files change in any of the hledger{-lib,,-web} packages. + ## Quick links