doc/readme-qt.rst

   1 Bitcoin-Qt: Qt4 GUI for Bitcoin
   2 ===============================
   3
   4 Build instructions
   5 ===================
   6
   7 Debian
   8 -------
   9
  10 First, make sure that the required packages for Qt4 development of your
  11 distribution are installed, these are
  12
  13 ::
  14
  15 for Debian and Ubuntu  <= 11.10 :
  16
  17 ::
  18
  19     apt-get install qt4-qmake libqt4-dev build-essential libboost-dev libboost-system-dev \
  20         libboost-filesystem-dev libboost-program-options-dev libboost-thread-dev \
  21         libssl-dev libdb4.8++-dev
  22
  23 for Ubuntu >= 12.04 (please read the 'Berkely DB version warning' below):
  24
  25 ::
  26
  27     apt-get install qt4-qmake libqt4-dev build-essential libboost-dev libboost-system-dev \
  28         libboost-filesystem-dev libboost-program-options-dev libboost-thread-dev \
  29         libssl-dev libdb++-dev libminiupnpc-dev
  30
  31 then execute the following:
  32
  33 ::
  34
  35     qmake
  36     make
  37
  38 Alternatively, install `Qt Creator`_ and open the `bitcoin-qt.pro` file.
  39
  40 An executable named `bitcoin-qt` will be built.
  41
  42 .. _`Qt Creator`: http://qt-project.org/downloads/
  43
  44 Windows
  45 --------
  46
  47 Windows build instructions:
  48
  49 - Download the `Qt Windows SDK`_ and install it. You don't need the Symbian stuff, just the desktop Qt.
  50
  51 - Download and extract the `dependencies archive`_  [#]_, or compile openssl, boost and dbcxx yourself.
  52
  53 - Copy the contents of the folder "deps" to "X:\\QtSDK\\mingw", replace X:\\ with the location where you installed the Qt SDK. Make sure that the contents of "deps\\include" end up in the current "include" directory.
  54
  55 - Open the bitcoin-qt.pro file in Qt Creator and build as normal (ctrl-B)
  56
  57 .. _`Qt Windows SDK`: http://qt-project.org/downloads/
  58 .. _`dependencies archive`: https://download.visucore.com/bitcoin/qtgui_deps_1.zip
  59 .. [#] PGP signature: https://download.visucore.com/bitcoin/qtgui_deps_1.zip.sig (signed with RSA key ID `610945D0`_)
  60 .. _`610945D0`: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x610945D0
  61
  62
  63 Mac OS X
  64 --------
  65
  66 - Download and install the `Qt Mac OS X SDK`_. It is recommended to also install Apple's Xcode with UNIX tools.
  67
  68 - Download and install `MacPorts`_.
  69
  70 - Execute the following commands in a terminal to get the dependencies:
  71
  72 ::
  73
  74         sudo port selfupdate
  75         sudo port install boost db48 miniupnpc
  76
  77 - Open the bitcoin-qt.pro file in Qt Creator and build as normal (cmd-B)
  78
  79 .. _`Qt Mac OS X SDK`: http://qt-project.org/downloads/
  80 .. _`MacPorts`: http://www.macports.org/install.php
  81
  82
  83 Build configuration options
  84 ============================
  85
  86 UPnP port forwarding
  87 ---------------------
  88
  89 To use UPnP for port forwarding behind a NAT router (recommended, as more connections overall allow for a faster and more stable bitcoin experience), pass the following argument to qmake:
  90
  91 ::
  92
  93     qmake "USE_UPNP=1"
  94
  95 (in **Qt Creator**, you can find the setting for additional qmake arguments under "Projects" -> "Build Settings" -> "Build Steps", then click "Details" next to **qmake**)
  96
  97 This requires miniupnpc for UPnP port mapping.  It can be downloaded from
  98 http://miniupnp.tuxfamily.org/files/.  UPnP support is not compiled in by default.
  99
 100 Set USE_UPNP to a different value to control this:
 101
 102 +------------+--------------------------------------------------------------------------+
 103 | USE_UPNP=- | no UPnP support, miniupnpc not required;                                 |
 104 +------------+--------------------------------------------------------------------------+
 105 | USE_UPNP=0 | (the default) built with UPnP, support turned off by default at runtime; |
 106 +------------+--------------------------------------------------------------------------+
 107 | USE_UPNP=1 | build with UPnP support turned on by default at runtime.                 |
 108 +------------+--------------------------------------------------------------------------+
 109
 110 Notification support for recent (k)ubuntu versions
 111 ---------------------------------------------------
 112
 113 To see desktop notifications on (k)ubuntu versions starting from 10.04, enable usage of the
 114 FreeDesktop notification interface through DBUS using the following qmake option:
 115
 116 ::
 117
 118     qmake "USE_DBUS=1"
 119
 120 Generation of QR codes
 121 -----------------------
 122
 123 libqrencode may be used to generate QRCode images for payment requests.
 124 It can be downloaded from http://fukuchi.org/works/qrencode/index.html.en, or installed via your package manager. Pass the USE_QRCODE
 125 flag to qmake to control this:
 126
 127 +--------------+--------------------------------------------------------------------------+
 128 | USE_QRCODE=0 | (the default) No QRCode support - libarcode not required                 |
 129 +--------------+--------------------------------------------------------------------------+
 130 | USE_QRCODE=1 | QRCode support enabled                                                   |
 131 +--------------+--------------------------------------------------------------------------+
 132
 133
 134 Berkely DB version warning
 135 ==========================
 136
 137 A warning for people using the *static binary* version of Bitcoin on a Linux/UNIX-ish system (tl;dr: **Berkely DB databases are not forward compatible**).
 138
 139 The static binary version of Bitcoin is linked against libdb4.8 (see also `this Debian issue`_).
 140
 141 Now the nasty thing is that databases from 5.X are not compatible with 4.X.
 142
 143 If the globally installed development package of Berkely DB installed on your system is 5.X, any source you
 144 build yourself will be linked against that. The first time you run with a 5.X version the database will be upgraded,
 145 and 4.X cannot open the new format. This means that you cannot go back to the old statically linked version without
 146 significant hassle!
 147
 148 .. _`this Debian issue`: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=621425
 149
 150 Ubuntu 11.10 warning
 151 ====================
 152
 153 Ubuntu 11.10 has a package called 'qt-at-spi' installed by default.  At the time of writing, having that package
 154 installed causes bitcoin-qt to crash intermittently.  The issue has been reported as `launchpad bug 857790`_, but
 155 isn't yet fixed.
 156
 157 Until the bug is fixed, you can remove the qt-at-spi package to work around the problem, though this will presumably
 158 disable screen reader functionality for Qt apps:
 159
 160 ::
 161
 162     sudo apt-get remove qt-at-spi
 163
 164 .. _`launchpad bug 857790`: https://bugs.launchpad.net/ubuntu/+source/qt-at-spi/+bug/857790