slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: devguide: rewrite setup docs

Browse Source
This commit is contained in:
Simon Michael 2015-08-24 07:42:49 -07:00
parent 62f0b879e5
commit edd1d4268b
1 changed files with 218 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

350
doc/developer-guide.md
View File

@ -77,14 +77,28 @@ libghc-hledger-lib-prof
## How to.. ## How to..
Here are some suggested procedures to help you quickly (re)engage ### Do user testing
with the project and get things done.
- review and critique our documentation and web presence
- test the procedures on [download](download) and on this page
- check that the hledger binaries run your platform, and `hledger test` reports no failures
- test the hledger tools' functionality, usability, browser compatibility, ui layout etc.
- discuss/report problems via irc/mail list/bug tracker
### Get help
- for quick help or if you're not sure about the problem,
you can ask on the [#hledger](http://irc.hledger.org) (irc.hledger.org) IRC channel
or the [mail list](http://list.hledger.org) (list.hledger.org).
If #hledger does not respond quickly, you can leave the window open and check back later, or leave your email address.
- check the open and closed issues in the [bug tracker](http://bugs.hledger.org) (bugs.hledger.org). Sometimes the problem has been fixed in git but not yet released.
<!-- - test and share problem journal snippets at paste . hledger.org -->
### Suggest enhancements ### Suggest enhancements
Suggestions and feature requests (aka wishes) are very welcome, but we Suggestions and feature requests are welcome, but we don't want them to pile up in the issue tracker obscuring higher-priority tasks.
don't want them to pile up in the issue tracker obscuring bugs and So consider these alternatives:
higher-priority tasks. So before opening a github issue, first consider:
1. The [#hledger](http://irc.hledger.org) (irc.hledger.org) IRC channel on freenode 1. The [#hledger](http://irc.hledger.org) (irc.hledger.org) IRC channel on freenode
and the [mail list](http://list.hledger.org) (list.hledger.org) are excellent places for discussing and refining ideas. and the [mail list](http://list.hledger.org) (list.hledger.org) are excellent places for discussing and refining ideas.
@ -93,82 +107,62 @@ higher-priority tasks. So before opening a github issue, first consider:
2. The [trello board](http://trello.hledger.org) (trello.hledger.org) is a good place 2. The [trello board](http://trello.hledger.org) (trello.hledger.org) is a good place
for storing and prioritising backlog and wishlist items of all kinds. for storing and prioritising backlog and wishlist items of all kinds.
3. The [bug tracker](http:///bugs.hledger.org) (bugs.hledger.org) on github 3. The [bug tracker](http:///bugs.hledger.org) (bugs.hledger.org) on github
is best used for issues with the existing product or docs. If you're not sure if you're reporting is mostly used for reporting problems with the existing product or docs.
a bug or not, it's fine to post it here. If you're not sure if it's a problem or not, it's fine to report it.
When enhancement requests land in the bug tracker, they get the WISH label, and are excluded from the default view at [bugs.hledger.org](http://bugs.hledger.org).
When wishes land in the bug tracker, they get the WISH label, and
these are excluded from the default view given by bugs.hledger.org.
### Report problems ### Report bugs
- for quick help or if you're not sure about the problem, - get to know the bug tracker (on github) and its contents.
you can ask on the [#hledger](http://irc.hledger.org) (irc.hledger.org) IRC channel Some convenient url shortcuts:\
or the [mail list](http://list.hledger.org) (list.hledger.org). [`bugs.hledger.org`](http://bugs.hledger.org) - show non-wishlist issues \
If #hledger does not respond quickly, you can leave the window open and check back later, or leave your email address. `bugs.hledger.org/N` - jump to issue #N
- check the open and closed issues in the [bug tracker](http://bugs.hledger.org) (bugs.hledger.org). Sometimes the problem has been fixed in git but not yet released. - research and update existing issues
- report new issues in the bug tracker (shortcut: [bugs.hledger.org/new](http://bugs.hledger.org/new)) - report a bug: [`bugs.hledger.org/new`](http://bugs.hledger.org/new)
<!-- - test and share problem journal snippets at paste . hledger.org --> ### Install stack and git
### Help with testing [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.
- review and test our documentation and web presence You don't need to use stack, if you are already expert with the older
- download and test the binaries on your platform cabal tool, or even just GHC, but I won't attempt to document those
- test installing via cabal procedures; these docs assume you have downloaded and installed stack.
- use the tools and test functionality, usability, browser compatibility, ui layout etc.
- check that `hledger test` reports no failures
- [run the developer tests](#how-to-run-the-tests)
- discuss/report problems via irc/mail list/bug tracker
### Help with bug tracking [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.
- get to know the [bug tracker](http://bugs.hledger.org) and its contents ### Install other optional tools
- research and update issues
- some convenient url shortcuts:\
[`bugs.hledger.org`](http://bugs.hledger.org)\
[`bugs.hledger.org/new`](http://bugs.hledger.org/new)\
`bugs.hledger.org/N`
### Set up for development Up-to-date `alex`, `happy`, and `haddock` tools are required, but `stack` should install those for you.
1. Download and install [stack](https://github.com/commercialhaskell/stack/wiki/Downloads). Here are some optional extra tools:
This builds haskell projects and can also install GHC (and on windows, git) if needed.
2. Get the hledger repo:
```{.shell .bold} - `shelltestrunner` is useful for running functional tests.
$ git clone https://github.com/simonmichael/hledger.git - `hasktags` is an easy way to generate editor tag files for quick source code navigation.
$ cd hledger - `profiteur` is for reporting stack profiles.
``` - `hpack` regenerates cabal files when package.yaml files have been updated.
- `hoogle` is for searching source code.
3. Install [GNU Make](http://www.gnu.org/software/make) and other optional extra tools (see the Makefile for a list): You can install them all with:
```shell ```shell
$ stack install shelltestrunner hasktags profiteur hpack $ stack install shelltestrunner hasktags profiteur hpack hoogle
``` ```
4. Run `make` or `stack --help` to see some suggested commands: ### Get the latest hledger source
```{.shell .bold} ```{.shell .bold}
$ make $ git clone code.hledger.org hledger # aka github.com/simonmichael/hledger.git
Makefile:37: -------------------- hledger make rules -------------------- $ cd hledger
Makefile:39: make [help] -- list documented rules in this makefile. make -n RULE shows more detail. ```
Makefile:204: (INSTALLING:)
Makefile:206: make install -- download dependencies and install hledger executables to ~/.local/bin or equivalent (with stack)
Makefile:231: (BUILDING:)
Makefile:235: make build -- download dependencies and build hledger executables (with stack)
Makefile:304: make hledgerdev -- quickly build the hledger executable (with ghc and -DDEVELOPMENT)
...
$ stack --help
Available commands:
build Build the project(s) in this directory/configuration
install Build executables and install to a user path
test Build and test the project(s) in this
directory/configuration
bench Build and benchmark the project(s) in this
directory/configuration
...
```
<!--
Old instructions: Old instructions:
1. Get [GHC](https://www.haskell.org/ghc/) and [cabal-install](http://hackage.haskell.org/package/cabal-install) installed. 1. Get [GHC](https://www.haskell.org/ghc/) and [cabal-install](http://hackage.haskell.org/package/cabal-install) installed.
@ -235,75 +229,98 @@ Old instructions:
and as quickly as possible, without optimizations (the "dev" suffix is a reminder of this). and as quickly as possible, without optimizations (the "dev" suffix is a reminder of this).
I use and recommend this method for development, as it crosses package boundaries and ensures you are building the latest code. I use and recommend this method for development, as it crosses package boundaries and ensures you are building the latest code.
However it needs some files generated by cabal build, which is why we did that first. However it needs some files generated by cabal build, which is why we did that first.
### Get your changes accepted
Follow the usual github workflow:
- fork the main hledger repo on github,
- git clone it to your local machine,
- git commit, after (?) pulling and merging the latest upstream changes
- git push back to github,
- open a pull request on github,
- follow up on any discussion there.
If you're new to this process, [help.github.com](http://help.github.com) may be useful.
### Improve the documentation
- get familiar with the website and documentation online, review and test
- get familiar with the site/doc source files (see Makefile)
- set up for hledger development
- send patches with names prefixed with "doc: " (or "site: ")
### Use the REPL (GHCI)
These all work from the main hledger source directory (at least).
First, ensure all required dependencies are installed with these
commands. (You might also need to install some system libs like
terminfo or curses.)
```{.shell .bold}
$ stack test
$ stack bench
```
Get a GHCI prompt for hledger-lib:
```{.shell .bold}
$ stack ghci hledger-lib
```
Get a GHCI prompt for hledger:
```{.shell .bold}
$ stack ghci hledger
```
Get a GHCI prompt for hledger-web:
```{.shell .bold}
$ stack ghci hledger-web
```
hledger-web also needs to find some things in its current directory (like the static/ directory).
This normally just works, if not please [send details](https://github.com/simonmichael/hledger/issues/274).
Get a GHCI prompt for hledger and hledger-lib:
```{.shell .bold}
$ make ghci
```
Get a GHCI prompt for hledger-web, hledger and hledger-lib:
```{.shell .bold}
$ make ghci-web
```
<!--
For the dev.hs developer script:
```{.shell .bold}
$ make ghci-dev
```
--> -->
### Use the Makefile
A Makefile is provided to make common developer tasks easy to remember,
and to insulate us a little from the ever-evolving Haskell tools ecosystem.
Using it is entirely optional, but recommended.
You'll need [GNU Make](http://www.gnu.org/software/make) installed.
The Makefile is self-documenting. Run `make` to see a list of the main make rules:
```{.shell}
$ make
Makefile:37: -------------------- hledger make rules --------------------
Makefile:39: make [help] -- list documented rules in this makefile. make -n RULE shows more detail.
Makefile:204: (INSTALLING:)
Makefile:206: make install -- download dependencies and install hledger executables to ~/.local/bin or equivalent (with stack)
Makefile:231: (BUILDING:)
Makefile:235: make build -- download dependencies and build hledger executables (with stack)
Makefile:304: make hledgerdev -- quickly build the hledger executable (with ghc and -DDEVELOPMENT)
...
```
To see what a make rule will do without actually doing it, use the `-n` flag:
```{.shell}
$ make build -n
stack build
```
```{.shell}
$ make test -n
(stack test \
&& echo pkgtest PASSED) || echo pkgtest FAILED
(stack exec hledger test \
&& echo builtintest PASSED) || echo builtintest FAILED
(COLUMNS=80 PATH=`pwd`/bin:/home/simon/src/hledger/bin:/home/simon/src/hledger/extra:/home/simon/.local/bin:/home/simon/.cabal/bin:/opt/ghc/7.10.1/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/var/lib/gems/1.9.1/bin stack exec -- shelltest --execdir -- -j16 --hide-successes tests \
&& 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.26.98: configure
hledger-lib-0.26.98: build
hledger-lib-0.26.98: install
hledger-0.26.98: configure
hledger-0.26.98: 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.26.98: 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.)
### Run benchmarks ### Run benchmarks
Benchmarks are standard performance measurements, Benchmarks are standard performance measurements,
@ -469,7 +486,7 @@ tools/generatejournal 10000 10000 10 >data/10000x10000x10.journal
tools/generatejournal 100000 1000 10 >data/100000x1000x10.journal tools/generatejournal 100000 1000 10 >data/100000x1000x10.journal
``` ```
### Run tests ### Run developer tests
This command will install haskell dependencies (you might need to This command will install haskell dependencies (you might need to
install additional system dependencies yourself) and run the package install additional system dependencies yourself) and run the package
@ -510,6 +527,60 @@ $ make haddocktest
- write test, verify expected result - write test, verify expected result
- get it committed - get it committed
### Use the REPL (GHCI)
These all work from the main hledger source directory (at least).
First, ensure all required dependencies are installed with these
commands. (You might also need to install some system libs like
terminfo or curses.)
```{.shell .bold}
$ stack test
$ stack bench
```
Get a GHCI prompt for hledger-lib:
```{.shell .bold}
$ stack ghci hledger-lib
```
Get a GHCI prompt for hledger:
```{.shell .bold}
$ stack ghci hledger
```
Get a GHCI prompt for hledger-web:
```{.shell .bold}
$ stack ghci hledger-web
```
hledger-web also needs to find some things in its current directory (like the static/ directory).
This normally just works, if not please [send details](https://github.com/simonmichael/hledger/issues/274).
Get a GHCI prompt for hledger and hledger-lib:
```{.shell .bold}
$ make ghci
```
Get a GHCI prompt for hledger-web, hledger and hledger-lib:
```{.shell .bold}
$ make ghci-web
```
<!--
For the dev.hs developer script:
```{.shell .bold}
$ make ghci-dev
```
-->
### Improve the documentation
- get familiar with the website and documentation online, review and test
- get familiar with the site/doc source files (see Makefile)
- get the latest hledger source
- send patches with names prefixed with "doc: " (or "site: ")
### Fix a bug or add a feature ### Fix a bug or add a feature
- research, discuss, validate the issue/feature on irc/list/bug tracker - research, discuss, validate the issue/feature on irc/list/bug tracker
@ -519,6 +590,19 @@ $ make haddocktest
- include any related issue numbers in the patch name, eg: "fix for blah blah (#NNN)" - include any related issue numbers in the patch name, eg: "fix for blah blah (#NNN)"
- get it committed - get it committed
### Get your changes accepted
Follow the usual github workflow:
- fork the main hledger repo on github,
- git clone it to your local machine,
- git commit, after (?) pulling and merging the latest upstream changes
- git push back to github,
- open a pull request on github,
- follow up on any discussion there.
If you're new to this process, [help.github.com](http://help.github.com) may be useful.
### Become a contributor ### Become a contributor
- after getting one or more patches committed, read and sign the [contributor list & agreement](contributors.html) - after getting one or more patches committed, read and sign the [contributor list & agreement](contributors.html)