running addon source files from outside the source tree can fail

[simonmichael]

If you clone the hledger source, add bin/ to your PATH, and try to run one of the addons without compiling it first (with make addons or bin/compile.sh), from some directory outside the hledger source tree, it may fail because in that case stack can select some incompatible version of the hledger libraries.

[simonmichael]

Solutions ?

1. Add a version number to the packages in the stack command, eg

#!/usr/bin/env stack
{- stack runghc --verbosity info
  --package hledger-lib-1.2
  --package hledger-1.2
  --package cmdargs
  --package text
-}
...

This helps avoid the problem. Downsides: it assumes there is a released version of hledger that's compatible; if the addon depends on unreleased hledger changes, it will fail. Secondly, now if you try to run the uncompiled addon while inside the hledger source tree, you get a confusing error:

The following errors occurred while parsing the build targets:
- hledger-lib target has a specific version number, but it is a local package.
To avoid confusion, we will not install the specified version or build the local one.
To build the local package, specify the target without an explicit version.
- hledger target has a specific version number, but it is a local package.
To avoid confusion, we will not install the specified version or build the local one.
To build the local package, specify the target without an explicit version.

2. To avoid the second problem, maybe we could instead specify a stackage snapshot containing a sufficiently new hledger version:

#!/usr/bin/env stack
{- stack runghc --verbosity info
  --resolver nightly-2017-06-15
  --package hledger-lib
  --package hledger
  --package cmdargs
  --package text
-}
...

But that's not robust:

$ hledger budget.hs

Error: While constructing the build plan, the following exceptions were encountered:

In the dependencies for hledger-1.2:
    megaparsec-5.3.0 must match >=5.0 && <5.3 (latest applicable is 5.2.0)

In the dependencies for hledger-lib-1.2:
    megaparsec-5.3.0 must match >=5.0 && <5.3 (latest applicable is 5.2.0)
needed due to hledger-1.2 -> hledger-lib-1.2

3. It works better with stack's new script command:

#!/usr/bin/env stack
{- stack script --verbosity info
  --resolver nightly-2017-06-15
  --package hledger-lib
  --package hledger
  --package cmdargs
  --package text
-}
...

Downsides: requires a recent version of stack (1.4+). Snapshot specifications will need ongoing maintenance. The snapshot will sometimes have to be newer than the one in hledger/stack.yaml, causing wasteful building of a whole new set of stackage packages. Requires a compatible released version of hledger that's in some stackage snapshot.

4. Explain clearly by docs or automatic warning that addons may not work when run this way, and that scripts should be compiled for robustness outside the hledger source tree. Downsides: another roadbump, fails at goal of making it easy to play around with interpreted scripts.

5. Move these addons into the hledger package proper, as new executables or as builtin commands. Solves this problem, and brings usability benefits, for the current addons. But, will happen again as we add new experimental addons, unless we always add them to the official hledger package, which defeats the goal of modular, quick-building, flagless packages.

[simonmichael]

I think this is sufficiently documented, eg at https://hledger.org/scripts.html#install-scripts and in most script headers.