- Get developer tools
- Get the code
- Review code
- Build in place
- Run in place
- Build and install
- Run package tests
- Run package benchmarks
- Run quickbench benchmarks
- Run functional tests
- Run haddock tests
- Simulate Travis tests
- Test with all supported GHC versions/stackage snapshots
- Use GHCI
- Add a test
- Fix a bug or add a feature
- Get your changes accepted
- Add yourself to the contributor list
- Work on docs
- Use ghcid for watching GHC/GHCI
- Use --file-watch for watching stack
- Use entr for watching arbitrary commands
git is installed. On Windows, it comes with stack.
Here are some useful optional tools:
- GNU Make: to use the convenient Make rules.
entrruns arbitrary commands when files change.
ghcidgives real-time GHC feedback as you make code changes.
shelltestrunnerruns hledger's functional tests.
quickbenchmeasures and reports time taken by commands.
hasktagsgenerates tag files for quick code navigation in editors like Emacs and vim.
- For browsing and editing Haskell code, popular tools include: Emacs, Vim, IDEA, VS Code, Atom..
stack install ghcid shelltestrunner hasktags git clone https://github.com/simonmichael/quickbench; cd quickbench; stack install # must run in source dir
git clone https://github.com/simonmichael/hledger cd hledger
- review and discuss new pull requests and commits on github
- build hledger and test the latest changes in your own repo
- read the existing code docs and source
- send feedback or discuss via IRC or mail list
See also https://hledger.org/download.html#c.-build-the-development-version .
stack build # hledger hledger-ui ...
This fetches the required GHC version and haskell dependencies from the default stackage snapshot (configured in
then builds all hledger packages.
This can take a while! To save time, you can build individual packages, eg just the CLI and TUI.
Note stack does not fetch C libraries such as curses or terminfo, which you might need to install yourself, using your system's package manager. In case of trouble, see download.
If you want to use an older snapshot/GHC for some reason, specify one of the older stack-*.yaml files:
stack --stack-yaml stack8.2.yaml build
stack exec -- hledger # ARGS... stack exec -- hledger-ui # ARGS... stack exec -- which hledger
This builds and also copies the hledger executables to
~/.local/bin or the Windows equivalent
(which you should add to your
stack install # hledger hledger-ui ...
Runs any HUnit/doctest/easytest tests defined by each hledger package.
stack test # hledger ...
Runs any performance reports defined by each hledger package.
stack bench # hledger ...
Times the end-user commands in
bench.sh using quickbench.
Runs the shelltestrunner tests defined in hledger/test/, which test the hledger CLI.
Checks for anything that would break haddock doc generation.
Checks for the unit-tests embedded in documentation.
Locally runs tests similar to what we run on Travis CI.
GHCI is GHC's REPL, useful for exploring and calling code interactively.
If you try to run GHCI (or things based on it, like ghcid)
right after cloning the hledger repo, you might see an error about CPP macros, eg like
To fix this, build the hledger packages once, eg
stack build hledger might be enough, depending what you are doing.)
cd hledger-lib; stack ghci hledger-lib
Changing into the package directory isn't actually needed, but it enables a custom .ghci script which sets a more useful short prompt.
cd hledger; stack ghci hledger
cd hledger-ui; stack ghci hledger-ui
cd hledger-web; 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.
- 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
- research, discuss, validate the issue/feature on irc/list/bug tracker
- look for related tests, run the tests and check they are passing
- add a test ?
- develop a patch
- include any related issue numbers in the patch name, eg: "fix for blah blah (#NNN)"
- get it committed
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 may be useful.
- after getting something into the master branch, read and sign the contributor list & agreement. Or, ask to be added.
- give yourself a high five!
Most docs tasks are handled by Shake.
./Shake manuals stack build
ghcid is the most reliable and fastest way to see GHC's feedback, and optionally run tests or a GHCI command, as you edit. We run it via make, for convenience and to watch multiple packages rather than just one. Run
make help-ghcid to list related rules.
ghcid -c 'make ghci' -T ':main -f a.j bal --budget -N'
stack's --file-watch flag will re-run build/test/bench when source files or package.yaml/cabal files change. Eg:
stack test hledger --file-watch
If you find that adding --fast makes this any faster, please update this.
entr is the most robust cross-platform tool for watching files and running a command when they change. Note its first argument must be an executable program, to run a shell command or multiple commands use
bash -c "...".
ls hledger/test/budget/budget.test | entr bash -c 'clear; COLUMNS=80 stack exec -- shelltest --execdir hledger/test/budget/budget.test -i12'