1# INSTALL
2
3To build this code after doing a Git clone, run:
4
5    $ ./acprep dependencies
6    $ ./acprep update
7
8If anything goes wrong, see "COMMON CONFIGURE/BUILD PROBLEMS" below.
9
10If you try to configure and build without running acprep first, you are
11almost certainly going to run into problems.  In future, you can run
12`acprep update` again and again, and it will keep you updated to the
13very latest version.
14
15Now install it:
16
17    $ sudo make install
18
19
20## COMMON CONFIGURE / BUILD PROBLEMS
21
22To build and install Ledger requires several dependencies on various
23platforms.  You can install these dependencies very simply for most of them
24using:
25
26    $ ./acprep dependencies
27
28The first order of business if acprep update doesn't work is to find out where
29things went wrong.  So follow these steps to produce a bug report I can track
30down easily:
31
32    $ ./acprep --debug update          # shows what acprep was thinking
33    $ $EDITOR CMakeCache.txt           # shows what cmake was thinking
34
35With the contents of config.log, and the output from acprep --debug update,
36it's usually fairly obvious where things have gone astray.
37
38
39## F.A.Q.
40
41
42Q: The build fails saying it can't find `utf8.h`
43
44A: You didn't run `./acprep update`.
45
46----------------------------------------------------------------------
47
48Q: `./acprep update` gives errors or `./acprep dependencies` fails
49
50A: You're probably missing some dependency libraries.  If you tried
51  `./acprep dependencies` already and that didn't solve the problem,
52  then you may need to install dependencies by hand.  On a Debian
53  GNU/Linux system (or Debian-based system such as Ubuntu), something
54  like this should work (as root):
55
56    $ sudo apt-get install build-essential cmake texinfo python-dev \
57        zlib1g-dev libbz2-dev libgmp3-dev gettext libmpfr-dev \
58        libboost-date-time-dev libboost-filesystem-dev \
59        libboost-graph-dev libboost-iostreams-dev \
60        libboost-python-dev libboost-regex-dev libboost-test-dev \
61        doxygen libedit-dev libmpc-dev tzdata
62
63----------------------------------------------------------------------
64
65Q: Configure fails saying it can't find boost_regex
66
67A: Look in config.log and search for "boost_regex", then scroll down a bit
68  until you see the exact compile error.  Usually it's failing because
69  your include directory is different from anything acprep is expecting to
70  see.  It could also be failing because your Boost libraries have a
71  custom "suffix" on them.
72
73  Let's say your Boost was installed in ~/boost, and every library has the
74  suffix `-xgcc42`.  This is what you would run:
75
76    $ CPPFLAGS=-I$HOME/boost acprep --boost=xgcc42 update
77
78----------------------------------------------------------------------
79
80Q: Configure fails saying it can't find MPFR
81
82A: You need MPFR version 2.4.0 or higher.  This version does not come with
83  most Debian distributions, so you will need to build it.  The
84  relevant packages are `libmpfr-dev` and `libmpfr-dbg`.  See also
85  the question above about what to do if `./acprep update` gives
86  errors or `./acprep dependencies` fails.
87
88----------------------------------------------------------------------
89
90Q: I'm seeing a segfault deep inside the boost_regex code!
91
92A: Actually, the real segfault is in libstdc++'s facet code.  It's being
93  caused by using a debug Boost with a non-debug build of Ledger, or
94  vice-versa.
95
96----------------------------------------------------------------------
97
98Q: Something else fails, or Ledger crashes on startup
99
100A: This, I am most interested in hearing about.  Please file a bug at the
101  Ledger Issue Tracker, https://github.com/ledger/ledger/issues.  The more
102  details you can provide, the better.  Also, if Ledger is crashing, try
103  running it under gdb like so:
104
105    $ gdb ledger
106    (gdb) run <ARGS TO LEDGER>
107    ... runs till crash ...
108    (gdb) bt
109
110  Put that backtrace output, and the output from `ledger --version`
111  in the bug report.
112
113----------------------------------------------------------------------
114
115Q: Whenever I try to use the Python support, I get a segfault
116
117A: Make sure that the boost_python library you linked against is using the
118  exact same Python as the Ledger executable.  In particular I see this
119  bug on macOS systems where boost_python is linked against the default
120  Python, while Ledger is linked against the version provided by MacPorts.
121  Or vice versa.
122
123  Solution: Use one or the other.  If you prefer the system Python, run
124  `port deactivate -f python26`, to get MacPorts' version out of the way.
125  You'll then need to delete the Ledger binary and run `make` to relink
126  it.
127
128----------------------------------------------------------------------
129
130Q: When I run `make check`, the Python unit tests always crash
131
132A: This can happen for the same reason as above.  It can also happen if you
133  have ICU support enabled.  This is a bug I'm still trying to track down.
134
135----------------------------------------------------------------------
136
137Q: My distribution has versions of Boost and/or CMake that are too old for
138  Ledger.  How do I build my own Boost and/or CMake binaries that will
139  work properly with Ledger?  Thereafter, how do I configure Ledger
140  properly to use those newly built verisons of Boost and/or CMake?
141
142A: Here's commands that one user used to make this work, for Boost 1.51.0
143  on Debian GNU/Linux 6.0.x (aka Debian squeeze).  It's likely to work ok
144  for other versions of Boost as well.  YMMV on other distributions and/or
145  other Debian distribution versions, though.
146
147  - Preparing and building Boost
148
149        $ export BOOST_VERSION=1.57.0
150        $ cd /somewhere/you/want/to/build/boost
151        $ wget -N http://iweb.dl.sourceforge.net/project/boost/boost/$BOOST_VERSION/boost_${BOOST_VERSION//./_}.tar.bz2
152        $ tar xvf boost_${BOOST_VERSION//./_}.tar.bz2
153        $ cd boost_${BOOST_VERSION//./_}
154        $ ./bootstrap.sh
155        $ ./b2 --build-type=complete --layout=tagged --prefix=/where/you/want/boost/installed
156        $ ./b2 --build-type=complete --layout=tagged --prefix=/where/you/want/boost/installed install
157
158  - Preparing and building CMake
159
160        $ export CMAKE_VERSION=3.1.0
161        $ cd /somewhere/you/want/to/build/cmake
162        $ wget -N http://www.cmake.org/files/v${CMAKE_VERSION:0:3}/cmake-${CMAKE_VERSION}.tar.gz
163        $ tar xvf cmake-${CMAKE_VERSION}.tar.gz
164        $ cd cmake-${CMAKE_VERSION}
165        $ ./configure --prefix=/where/you/want/cmake/installed/
166        $ make
167        $ make install
168
169  - Building Ledger using the CMake and/or Boost as installed above
170
171        $ cd /path/to/ledger/sources
172        $ env PATH=/where/you/want/cmake/installed/bin:$PATH  BOOST_ROOT=/where/you/want/boost/installed PREFIX=/where/you/want/ledger/installed $SHELL
173        $ ./acprep --prefix=$PREFIX --debug --python config
174        $ ./acprep --prefix=$PREFIX --debug --python make
175        $ ./acprep --prefix=$PREFIX --debug --python install
176