diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.md | 58 | ||||
| -rw-r--r-- | doc/Tor.txt | 92 | ||||
| -rw-r--r-- | doc/assets-attribution.md | 104 | ||||
| -rw-r--r-- | doc/assets-attribution.txt | 58 | ||||
| -rw-r--r-- | doc/build-msw.md | 25 | ||||
| -rw-r--r-- | doc/build-osx.md | 33 | ||||
| -rw-r--r-- | doc/build-unix.md | 70 | ||||
| -rw-r--r-- | doc/files.md (renamed from doc/files.txt) | 12 | ||||
| -rw-r--r-- | doc/multiwallet-qt.md | 14 | ||||
| -rw-r--r-- | doc/readme-qt.rst | 163 | ||||
| -rw-r--r-- | doc/release-process.md | 35 | ||||
| -rw-r--r-- | doc/tor.md | 90 | ||||
| -rw-r--r-- | doc/translation_process.md | 11 | ||||
| -rw-r--r-- | doc/unit-tests.md | 37 |
14 files changed, 335 insertions, 467 deletions
diff --git a/doc/README.md b/doc/README.md index cdd31057ad..068ed988d1 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,26 +1,23 @@ -Bitcoin 0.8.2 BETA +Bitcoin 0.8.2 BETA ==================== Copyright (c) 2009-2013 Bitcoin Developers -Distributed under the MIT/X11 software license, see the accompanying -file COPYING or http://www.opensource.org/licenses/mit-license.php. +License +--------------------- +Distributed under the [MIT/X11 software license](http://www.opensource.org/licenses/mit-license.php). This product includes software developed by the OpenSSL Project for use in the [OpenSSL Toolkit](http://www.openssl.org/). This product includes cryptographic software written by Eric Young ([eay@cryptsoft.com](mailto:eay@cryptsoft.com)), and UPnP software written by Thomas Bernard. - -Intro +Setup --------------------- -Bitcoin is a free open source peer-to-peer electronic cash system that is -completely decentralized, without the need for a central server or trusted -parties. Users hold the crypto keys to their own money and transact directly -with each other, with the help of a P2P network to check for double-spending. +[Bitcoin-Qt](http://bitcoin.org/en/download) is the original Bitcoin client and it builds the backbone of the network. However, it downloads and stores the entire history of Bitcoin transactions (which is currently several GBs); depending on the speed of your computer and network connection, the synchronization process can take anywhere from a few hours to a day or more. +### Unix -Setup ---------------------- You need the Qt4 run-time libraries to run Bitcoin-Qt. On Debian or Ubuntu: - `sudo apt-get install libqtgui4` + + sudo apt-get install libqtgui4 Unpack the files into a directory and run: @@ -29,18 +26,41 @@ Unpack the files into a directory and run: - bin/64/bitcoin-qt (GUI, 64-bit) - bin/64/bitcoind (headless, 64-bit) -See the documentation at the [Bitcoin Wiki](https://en.bitcoin.it/wiki/Main_Page) -for help and more information. -Other Pages +### Windows + +Unpack the files into a directory and run bitcoin-qt.exe. + +### Need Help? + +* See the documentation at the [Bitcoin Wiki](https://en.bitcoin.it/wiki/Main_Page) +for help and more information. +* Ask for help on [#bitcoin](http://webchat.freenode.net?channels=bitcoin) on Freenode. If you don't have an IRC client use [webchat here](http://webchat.freenode.net?channels=bitcoin). +* Ask for help on the [BitcoinTalk](https://bitcointalk.org/) forums, in the [technical support board](https://bitcointalk.org/index.php?board=4.0). + +Building --------------------- -- [Unix Build Notes](build-unix.md) +The following are developer notes on how to build Bitcoin on your native platform. They are not complete guide, but include notes on the necessary libraries, compile flags, etc. + - [OSX Build Notes](build-osx.md) +- [Unix Build Notes](build-unix.md) - [Windows Build Notes](build-msw.md) + +Development +--------------------- +The Bitcoin repo's [root README](https://github.com/bitcoin/bitcoin/blob/master/README.md) contains relevant information on the development process and automated testing. + - [Coding Guidelines](coding.md) -- [Release Process](release-process.md) -- [Release Notes](release-notes.md) - [Multiwallet Qt Development](multiwallet-qt.md) +- [Release Notes](release-notes.md) +- [Release Process](release-process.md) +- [Source Code Documentation (External Link)](https://dev.visucore.com/bitcoin/doxygen/) +- [Translation Process](translation_process.md) - [Unit Tests](unit-tests.md) -- [Translation Process](translation_process.md)
\ No newline at end of file + +Other Pages +--------------------- +- [Assets Attribution](assets-attribution.md) +- [Files](files.md) +- [Tor Support](tor.md) diff --git a/doc/Tor.txt b/doc/Tor.txt deleted file mode 100644 index 386e3b5466..0000000000 --- a/doc/Tor.txt +++ /dev/null @@ -1,92 +0,0 @@ -TOR SUPPORT IN BITCOIN -====================== - -It is possible to run Bitcoin as a Tor hidden service, and connect to such services. - -The following directions assume you have a Tor proxy running on port 9050. Many distributions -default to having a SOCKS proxy listening on port 9050, but others may not. -In particular, the Tor Browser Bundle defaults to listening on a random port. See -https://www.torproject.org/docs/faq.html.en#TBBSocksPort for how to properly -configure Tor. - - -1. Run bitcoin behind a Tor proxy ---------------------------------- - -The first step is running Bitcoin behind a Tor proxy. This will already make all -outgoing connections be anonimized, but more is possible. - --socks=5 SOCKS5 supports connecting-to-hostname, which can be used instead - of doing a (leaking) local DNS lookup. SOCKS5 is the default, - but SOCKS4 does not support this. (SOCKS4a does, but isn't - implemented). - --proxy=ip:port Set the proxy server. If SOCKS5 is selected (default), this proxy - server will be used to try to reach .onion addresses as well. - --tor=ip:port Set the proxy server to use for tor hidden services. You do not - need to set this if it's the same as -proxy. You can use -notor - to explicitly disable access to hidden service. - --listen When using -proxy, listening is disabled by default. If you want - to run a hidden service (see next section), you'll need to enable - it explicitly. - --connect=X When behind a Tor proxy, you can specify .onion addresses instead --addnode=X of IP addresses or hostnames in these parameters. It requires --seednode=X SOCKS5. In Tor mode, such addresses can also be exchanged with - other P2P nodes. - -In a typical situation, this suffices to run behind a Tor proxy: - - ./bitcoin -proxy=127.0.0.1:9050 - - -2. Run a bitcoin hidden server ------------------------------- - -If you configure your Tor system accordingly, it is possible to make your node also -reachable from the Tor network. Add these lines to your /etc/tor/torrc (or equivalent -config file): - - HiddenServiceDir /var/lib/tor/bitcoin-service/ - HiddenServicePort 8333 127.0.0.1:8333 - -The directory can be different of course, but (both) port numbers should be equal to -your bitcoind's P2P listen port (8333 by default). - --externalip=X You can tell bitcoin about its publicly reachable address using - this option, and this can be a .onion address. Given the above - configuration, you can find your onion address in - /var/lib/tor/bitcoin-service/hostname. Onion addresses are given - preference for your node to advertize itself with, for connections - coming from unroutable addresses (such as 127.0.0.1, where the - Tor proxy typically runs). - --listen You'll need to enable listening for incoming connections, as this - is off by default behind a proxy. - --discover When -externalip is specified, no attempt is made to discover local - IPv4 or IPv6 addresses. If you want to run a dual stack, reachable - from both Tor and IPv4 (or IPv6), you'll need to either pass your - other addresses using -externalip, or explicitly enable -discover. - Note that both addresses of a dual-stack system may be easily - linkable using traffic analysis. - -In a typical situation, where you're only reachable via Tor, this should suffice: - - ./bitcoind -proxy=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -listen - -(obviously, replace the Onion address with your own). If you don't care too much -about hiding your node, and want to be reachable on IPv4 as well, additionally -specify: - - ./bitcoind ... -discover - -and open port 8333 on your firewall (or use -upnp). - -If you only want to use Tor to reach onion addresses, but not use it as a proxy -for normal IPv4/IPv6 communication, use: - - ./bitcoin -tor=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -discover - diff --git a/doc/assets-attribution.md b/doc/assets-attribution.md new file mode 100644 index 0000000000..e85e74522d --- /dev/null +++ b/doc/assets-attribution.md @@ -0,0 +1,104 @@ +The following is a list of assets used in the bitcoin source and their proper attribution. + +[Wladimir van der Laan](https://github.com/laanwj) +----------------------- +#### Info +* License: MIT +### Assets Used + + src/qt/res/icons/clock*.png, src/qt/res/icons/tx*.png, + src/qt/res/src/clock_green.svg, src/qt/res/src/clock1.svg, + src/qt/res/src/clock2.svg, src/qt/res/src/clock3.svg, + src/qt/res/src/clock4.svg, src/qt/res/src/clock5.svg, + src/qt/res/src/inout.svg, src/qt/res/src/questionmark.svg + +[David Vignoni](www.icon-king.com) +----------------------- + +### Info +* Icon Pack: NUVOLA ICON THEME for KDE 3.x +* Designer: David Vignoni (david@icon-king.com) +* License: LGPL +* Site: [http://www.icon-king.com/projects/nuvola/](http://www.icon-king.com/projects/nuvola/) + +### Assets Used + src/qt/res/icons/address-book.png, src/qt/res/icons/export.png, + src/qt/res/icons/history.png, src/qt/res/icons/key.png, + src/qt/res/icons/lock_*.png, src/qt/res/icons/overview.png, + src/qt/res/icons/receive.png, src/qt/res/icons/send.png, + src/qt/res/icons/synced.png, src/qt/res/icons/filesave.png + +schollidesign +----------------------- + +### Info +* Icon Pack: Human-O2 +* Designer: schollidesign +* License: GNU/GPL +* Site: [http://findicons.com/icon/93743/blocks_gnome_netstatus_0](http://findicons.com/icon/93743/blocks_gnome_netstatus_0) + +### Assets Used + src/qt/res/icons/connect*.png + +md2k7 +----------------------- + +### Info +* Designer: md2k7 +* Site: https://bitcointalk.org/index.php?topic=15276.0 +* License: You are free to do with these icons as you wish, including selling, + copying, modifying etc. +* License: MIT + +### Assets Used + src/qt/res/icons/transaction*.png + +[Everaldo.com](http://www.everaldo.com) +----------------------- + +### Info +* Designer: [http://www.everaldo.com](http://www.everaldo.com) +* Icon Pack: Crystal SVG +* License: LGPL + +### Assets Used + src/qt/res/icons/configure.png, src/qt/res/icons/quit.png, + src/qt/res/icons/editcopy.png, src/qt/res/icons/editpaste.png, + src/qt/res/icons/add.png, src/qt/res/icons/edit.png, + src/qt/res/icons/remove.png (edited) + +Everaldo (Everaldo Coelho) +----------------------- + +### Info +* Icon Pack: Kids +* Designer: Everaldo (Everaldo Coelho) +* License: GNU/GPL +* Site: [http://findicons.com/icon/17102/reload?id=17102](http://findicons.com/icon/17102/reload?id=17102) +### Assets Used + scripts/img/reload.xcf (modified), src/qt/res/movies/update_spinner.mng + +[Vignoni David](http://www.oxygen-icons.org/) +----------------------- + +### Info +* Designer: Vignoni David +* Site: http://www.oxygen-icons.org/ +* License: Oxygen icon theme is dual licensed. You may copy it under the Creative Common Attribution-ShareAlike 3.0 License or the GNU Library General Public License. + +### Assets Used + src/qt/res/icons/debugwindow.png + +Jonas Schnelli +----------------------- + +### Info +* Designer: Jonas Schnelli (based on the original bitcoin logo from Bitboy) +* License: MIT + +### Assets Used + src/qt/res/icons/bitcoin.icns, src/qt/res/src/bitcoin.svg, + src/qt/res/src/bitcoin.ico, src/qt/res/src/bitcoin.png, + src/qt/res/src/bitcoin_testnet.png, docs/bitcoin_logo_doxygen.png, + src/qt/res/icons/toolbar.png, src/qt/res/icons/toolbar_testnet.png, + src/qt/res/images/splash.png, src/qt/res/images/splash_testnet.png
\ No newline at end of file diff --git a/doc/assets-attribution.txt b/doc/assets-attribution.txt deleted file mode 100644 index 2069c5d6e0..0000000000 --- a/doc/assets-attribution.txt +++ /dev/null @@ -1,58 +0,0 @@ -Icon: src/qt/res/icons/clock*.png, src/qt/res/icons/tx*.png, - src/qt/res/src/clock_green.svg, src/qt/res/src/clock1.svg, - src/qt/res/src/clock2.svg, src/qt/res/src/clock3.svg, - src/qt/res/src/clock4.svg, src/qt/res/src/clock5.svg, - src/qt/res/src/inout.svg, src/qt/res/src/questionmark.svg -Designer: Wladimir van der Laan -License: MIT - -Icon: src/qt/res/icons/address-book.png, src/qt/res/icons/export.png, - src/qt/res/icons/history.png, src/qt/res/icons/key.png, - src/qt/res/icons/lock_*.png, src/qt/res/icons/overview.png, - src/qt/res/icons/receive.png, src/qt/res/icons/send.png, - src/qt/res/icons/synced.png, src/qt/res/icons/filesave.png -Icon Pack: NUVOLA ICON THEME for KDE 3.x -Designer: David Vignoni (david@icon-king.com) - ICON KING - www.icon-king.com -License: LGPL -Site: http://www.icon-king.com/projects/nuvola/ - -Icon: src/qt/res/icons/connect*.png -Icon Pack: Human-O2 -Designer: schollidesign -License: GNU/GPL -Site: http://findicons.com/icon/93743/blocks_gnome_netstatus_0 - -Icon: src/qt/res/icons/transaction*.png -Designer: md2k7 -Site: https://bitcointalk.org/index.php?topic=15276.0 -License: You are free to do with these icons as you wish, including selling, - copying, modifying etc. -License: MIT - -Icon: src/qt/res/icons/configure.png, src/qt/res/icons/quit.png, - src/qt/res/icons/editcopy.png, src/qt/res/icons/editpaste.png, - src/qt/res/icons/add.png, src/qt/res/icons/edit.png, - src/qt/res/icons/remove.png (edited) -Designer: http://www.everaldo.com -Icon Pack: Crystal SVG -License: LGPL - -Icon: scripts/img/reload.xcf (modified), src/qt/res/movies/update_spinner.mng -Icon Pack: Kids -Designer: Everaldo (Everaldo Coelho) -License: GNU/GPL -Site: http://findicons.com/icon/17102/reload?id=17102 - -Icon: src/qt/res/icons/debugwindow.png -Designer: Vignoni David -Site: http://www.oxygen-icons.org/ -License: Oxygen icon theme is dual licensed. You may copy it under the Creative Common Attribution-ShareAlike 3.0 License or the GNU Library General Public License. - -Icon: src/qt/res/icons/bitcoin.icns, src/qt/res/src/bitcoin.svg, - src/qt/res/src/bitcoin.ico, src/qt/res/src/bitcoin.png, - src/qt/res/src/bitcoin_testnet.png, docs/bitcoin_logo_doxygen.png, - src/qt/res/icons/toolbar.png, src/qt/res/icons/toolbar_testnet.png, - src/qt/res/images/splash.png, src/qt/res/images/splash_testnet.png -Designer: Jonas Schnelli (based on the original bitcoin logo from Bitboy) -License: MIT diff --git a/doc/build-msw.md b/doc/build-msw.md index b7abe28877..d348ad7cc3 100644 --- a/doc/build-msw.md +++ b/doc/build-msw.md @@ -1,17 +1,9 @@ -Copyright (c) 2009-2013 Bitcoin Developers - -Distributed under the MIT/X11 software license, see the accompanying -file COPYING or http://www.opensource.org/licenses/mit-license.php. -This product includes software developed by the OpenSSL Project for use in the [OpenSSL Toolkit](http://www.openssl.org/). This product includes -cryptographic software written by Eric Young ([eay@cryptsoft.com](mailto:eay@cryptsoft.com)), and UPnP software written by Thomas Bernard. - - -See readme-qt.rst for instructions on building Bitcoin-Qt, the -graphical user interface. - WINDOWS BUILD NOTES =================== +See [readme-qt.md](readme-qt.md) for instructions on building Bitcoin-Qt, the +graphical user interface. + Compilers Supported ------------------- TODO: What works? @@ -22,11 +14,12 @@ Dependencies ------------ Libraries you need to download separately and build: - default path download -OpenSSL \openssl-1.0.1c-mgw http://www.openssl.org/source/ -Berkeley DB \db-4.8.30.NC-mgw http://www.oracle.com/technology/software/products/berkeley-db/index.html -Boost \boost-1.50.0-mgw http://www.boost.org/users/download/ -miniupnpc \miniupnpc-1.6-mgw http://miniupnp.tuxfamily.org/files/ + name default path download + -------------------------------------------------------------------------------------------------------------------- + OpenSSL \openssl-1.0.1c-mgw http://www.openssl.org/source/ + Berkeley DB \db-4.8.30.NC-mgw http://www.oracle.com/technology/software/products/berkeley-db/index.html + Boost \boost-1.50.0-mgw http://www.boost.org/users/download/ + miniupnpc \miniupnpc-1.6-mgw http://miniupnp.tuxfamily.org/files/ Their licenses: diff --git a/doc/build-osx.md b/doc/build-osx.md index 1fc33b15a3..271f8f55bd 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -1,38 +1,15 @@ -Mac OS X bitcoind build instructions +Mac OS X Build Instructions and Notes ==================================== - -Authors -------- - -* Laszlo Hanyecz <solar@heliacal.net> -* Douglas Huff <dhuff@jrbobdobbs.org> -* Colin Dean <cad@cad.cx> -* Gavin Andresen <gavinandresen@gmail.com> - -License -------- - -Copyright (c) 2009-2012 Bitcoin Developers - -Distributed under the MIT/X11 software license, see the accompanying -file COPYING or http://www.opensource.org/licenses/mit-license.php. - -This product includes software developed by the OpenSSL Project for use in -the OpenSSL Toolkit (http://www.openssl.org/). - -This product includes cryptographic software written by -Eric Young (eay@cryptsoft.com) and UPnP software written by Thomas Bernard. +This guide will show you how to build bitcoind(headless client) for OSX. Notes ----- -See `doc/readme-qt.rst` for instructions on building Bitcoin-Qt, the +* See [readme-qt.md](readme-qt.md) for instructions on building Bitcoin-Qt, the graphical user interface. - -Tested on OS X 10.5 through 10.8 on Intel processors only. PPC is not +* Tested on OS X 10.5 through 10.8 on Intel processors only. PPC is not supported because it is big-endian. - -All of the commands should be executed in a Terminal application. The +* All of the commands should be executed in a Terminal application. The built-in one is located in `/Applications/Utilities`. Preparation diff --git a/doc/build-unix.md b/doc/build-unix.md index 6181bb255d..422b46cc3a 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -1,20 +1,16 @@ -Copyright (c) 2009-2013 Bitcoin Developers - -Distributed under the MIT/X11 software license, see the accompanying -file COPYING or http://www.opensource.org/licenses/mit-license.php. -This product includes software developed by the OpenSSL Project for use in the [OpenSSL Toolkit](http://www.openssl.org/). This product includes -cryptographic software written by Eric Young ([eay@cryptsoft.com](mailto:eay@cryptsoft.com)), and UPnP software written by Thomas Bernard. - UNIX BUILD NOTES ==================== +Some notes on how to build Bitcoin in Unix. To Build --------------------- - cd src/ - make -f makefile.unix # Headless bitcoin + ./autogen.sh + ./configure + make -See readme-qt.rst for instructions on building Bitcoin-Qt, the graphical user interface. +This will build bitcoin-qt as well if the dependencies are met. +See [readme-qt.md](readme-qt.md) for more information. Dependencies --------------------- @@ -25,18 +21,21 @@ Dependencies libdb4.8 Berkeley DB Blockchain & wallet storage libboost Boost C++ Library miniupnpc UPnP Support Optional firewall-jumping support + qt GUI GUI toolkit + protobuf Payments in GUI Data interchange format used for payment protocol + libqrencode QR codes in GUI Optional for generating QR codes [miniupnpc](http://miniupnp.free.fr/) may be used for UPnP port mapping. It can be downloaded from [here]( http://miniupnp.tuxfamily.org/files/). UPnP support is compiled in and -turned off by default. Set USE_UPNP to a different value to control this: +turned off by default. See the configure options for upnp behavior desired: - USE_UPNP= No UPnP support miniupnp not required - USE_UPNP=0 (the default) UPnP support turned off by default at runtime - USE_UPNP=1 UPnP support turned on by default at runtime + --with-miniupnpc No UPnP support miniupnp not required + --disable-upnp-default (the default) UPnP support turned off by default at runtime + --enable-upnp-default UPnP support turned on by default at runtime IPv6 support may be disabled by setting: - USE_IPV6=0 Disable IPv6 support + --disable-ipv6 Disable IPv6 support Licenses of statically linked libraries: Berkeley DB New BSD license with additional requirement that linked @@ -50,21 +49,25 @@ Licenses of statically linked libraries: - Berkeley DB 4.8.30.NC - Boost 1.37 - miniupnpc 1.6 +- qt 4.8.3 +- protobuf 2.5.0 +- libqrencode 3.2.0 Dependency Build Instructions: Ubuntu & Debian ---------------------------------------------- Build requirements: sudo apt-get install build-essential + sudo apt-get install libtool autotools-dev sudo apt-get install libssl-dev -for Ubuntu 12.04: +for Ubuntu 12.04 and later: sudo apt-get install libboost-all-dev db4.8 packages are available [here](https://launchpad.net/~bitcoin/+archive/bitcoin). - Ubuntu precise has packages for libdb5.1-dev and libdb5.1++-dev, + Ubuntu 12.04 and later have packages for libdb5.1-dev and libdb5.1++-dev, but using these will break binary wallet compatibility, and is not recommended. for other Ubuntu & Debian: @@ -76,23 +79,24 @@ for other Ubuntu & Debian: Optional: - sudo apt-get install libminiupnpc-dev (see USE_UPNP compile flag) + sudo apt-get install libminiupnpc-dev (see --with-miniupnpc and --enable-upnp-default) +Dependencies for the GUI: Ubuntu & Debian +----------------------------------------- -Dependency Build Instructions: Gentoo -------------------------------------- +If you want to build Bitcoin-Qt, make sure that the required packages for Qt development +are installed. Qt 4 is currently necessary to build the GUI. -Note: If you just want to install bitcoind on Gentoo, you can add the Bitcoin overlay and use your package manager: +To build with Qt 4 you need the following: - layman -a bitcoin && emerge bitcoind - emerge -av1 --noreplace boost glib openssl sys-libs/db:4.8 + apt-get install libqt4-dev libprotobuf-dev -Take the following steps to build (no UPnP support): +libqrencode (optional) can be installed with: - cd ${BITCOIN_DIR}/src - make -f makefile.unix USE_UPNP= USE_IPV6=1 BDB_INCLUDE_PATH='/usr/include/db4.8' - strip bitcoind + apt-get install libqrencode-dev +Once these are installed, they will be found by configure and a bitcoin-qt executable will be +built by default. Notes ----- @@ -129,7 +133,13 @@ If you need to build Boost yourself: Security -------- To help make your bitcoin installation more secure by making certain attacks impossible to -exploit even if a vulnerability is found, you can take the following measures: +exploit even if a vulnerability is found, binaries are hardened by default. +This can be disabled with: + +./configure --enable-hardening + + +Hardening enables the following features: * Position Independent Executable Build position independent code to take advantage of Address Space Layout Randomization @@ -141,10 +151,6 @@ exploit even if a vulnerability is found, you can take the following measures: On an Amd64 processor where a library was not compiled with -fPIC, this will cause an error such as: "relocation R_X86_64_32 against `......' can not be used when making a shared object;" - To build with PIE, use: - - make -f makefile.unix ... -e PIE=1 - To test that you have built PIE executable, install scanelf, part of paxutils, and use: scanelf -e ./bitcoin diff --git a/doc/files.txt b/doc/files.md index 5d4cdabf8d..80195535bb 100644 --- a/doc/files.txt +++ b/doc/files.md @@ -1,4 +1,5 @@ -Used in 0.8.0: +Used in 0.8.0 +--------------------- * wallet.dat: personal wallet (BDB) with keys and transactions * peers.dat: peer IP address database (custom format); since 0.7.0 * blocks/blk000??.dat: block data (custom, 128 MiB per file); since 0.8.0 @@ -7,13 +8,16 @@ Used in 0.8.0: * chainstate/*; block chain state database (LevelDB); since 0.8.0 * database/*: BDB database environment; only used for wallet since 0.8.0 -Only used in pre-0.8.0: +Only used in pre-0.8.0 +--------------------- * blktree/*; block chain index (LevelDB); since pre-0.8, replaced by blocks/index/* in 0.8.0 * coins/*; unspent transaction output database (LevelDB); since pre-0.8, replaced by chainstate/* in 0.8.0 -Only used before 0.8.0: +Only used before 0.8.0 +--------------------- * blkindex.dat: block chain index database (BDB); replaced by {chainstate/*,blocks/index/*,blocks/rev000??.dat} in 0.8.0 * blk000?.dat: block data (custom, 2 GiB per file); replaced by blocks/blk000??.dat in 0.8.0 -Only used before 0.7.0: +Only used before 0.7.0 +--------------------- * addr.dat: peer IP address database (BDB); replaced by peers.dat in 0.7.0 diff --git a/doc/multiwallet-qt.md b/doc/multiwallet-qt.md index 8d695552b5..3caab81807 100644 --- a/doc/multiwallet-qt.md +++ b/doc/multiwallet-qt.md @@ -4,7 +4,7 @@ Multiwallet Qt Development and Integration Strategy In order to support loading of multiple wallets in bitcoin-qt, a few changes in the UI architecture will be needed. Fortunately, only four of the files in the existing project are affected by this change. -Three new classes have been implemented in three new .h/.cpp file pairs, with much of the functionality that was previously +Two new classes have been implemented in two new .h/.cpp file pairs, with much of the functionality that was previously implemented in the BitcoinGUI class moved over to these new classes. The two existing files most affected, by far, are bitcoingui.h and bitcoingui.cpp, as the BitcoinGUI class will require @@ -12,7 +12,7 @@ some major retrofitting. Only requiring some minor changes is bitcoin.cpp. -Finally, three new headers and source files will have to be added to bitcoin-qt.pro. +Finally, two new headers and source files will have to be added to bitcoin-qt.pro. Changes to class BitcoinGUI --------------------------- @@ -23,13 +23,9 @@ A new class called *WalletView* inheriting from QStackedWidget has been written these page views. In addition to owning these five page views, a WalletView also has a pointer to a WalletModel instance. This allows the construction of multiple WalletView objects, each rendering a distinct wallet. -A second class called *WalletStack*, also inheriting from QStackedWidget, has been written to handle switching focus between -different loaded wallets. In its current implementation, as a QStackedWidget, only one wallet can be viewed at a time - -but this can be changed later. - -A third class called *WalletFrame* inheriting from QFrame has been written as a container for embedding all wallet-related -controls into BitcoinGUI. At present it just contains a WalletStack instance and does little more than passing on messages -from BitcoinGUI to the WalletStack, which in turn passes them to the individual WalletViews. It is a WalletFrame instance +A second class called *WalletFrame* inheriting from QFrame has been written as a container for embedding all wallet-related +controls into BitcoinGUI. At present it contains the WalletView instances for the wallets and does little more than passing on messages +from BitcoinGUI to the currently selected WalletView. It is a WalletFrame instance that takes the place of what used to be centralWidget in BitcoinGUI. The purpose of this class is to allow future refinements of the wallet controls with minimal need for further modifications to BitcoinGUI, thus greatly simplifying merges while reducing the risk of breaking top-level stuff. diff --git a/doc/readme-qt.rst b/doc/readme-qt.rst deleted file mode 100644 index 95cb33650f..0000000000 --- a/doc/readme-qt.rst +++ /dev/null @@ -1,163 +0,0 @@ -Bitcoin-Qt: Qt4 GUI for Bitcoin -=============================== - -Build instructions -=================== - -Debian -------- - -First, make sure that the required packages for Qt4 development of your -distribution are installed, these are - -:: - -for Debian and Ubuntu <= 11.10 : - -:: - - apt-get install qt4-qmake libqt4-dev build-essential libboost-dev libboost-system-dev \ - libboost-filesystem-dev libboost-program-options-dev libboost-thread-dev \ - libssl-dev libdb4.8++-dev - -for Ubuntu >= 12.04 (please read the 'Berkely DB version warning' below): - -:: - - apt-get install qt4-qmake libqt4-dev build-essential libboost-dev libboost-system-dev \ - libboost-filesystem-dev libboost-program-options-dev libboost-thread-dev \ - libssl-dev libdb++-dev libminiupnpc-dev - -For Qt 5 you need the following, otherwise you get an error with lrelease when running qmake: - -:: - - apt-get install qt5-qmake libqt5gui5 libqt5core5 libqt5dbus5 qttools5-dev-tools - -then execute the following: - -:: - - qmake - make - -Alternatively, install `Qt Creator`_ and open the `bitcoin-qt.pro` file. - -An executable named `bitcoin-qt` will be built. - -.. _`Qt Creator`: http://qt-project.org/downloads/ - -Mac OS X --------- - -- Download and install the `Qt Mac OS X SDK`_. It is recommended to also install Apple's Xcode with UNIX tools. - -- Download and install either `MacPorts`_ or `HomeBrew`_. - -- Execute the following commands in a terminal to get the dependencies using MacPorts: - -:: - - sudo port selfupdate - sudo port install boost db48 miniupnpc - -- Execute the following commands in a terminal to get the dependencies using HomeBrew: - -:: - - brew update - brew install boost miniupnpc openssl berkeley-db4 - -- If using HomeBrew, edit `bitcoin-qt.pro` to account for library location differences. There's a diff in `contrib/homebrew/bitcoin-qt-pro.patch` that shows what you need to change, or you can just patch by doing - - patch -p1 < contrib/homebrew/bitcoin.qt.pro.patch - -- Open the bitcoin-qt.pro file in Qt Creator and build as normal (cmd-B) - -.. _`Qt Mac OS X SDK`: http://qt-project.org/downloads/ -.. _`MacPorts`: http://www.macports.org/install.php -.. _`HomeBrew`: http://mxcl.github.io/homebrew/ - - -Build configuration options -============================ - -UPnP port forwarding ---------------------- - -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: - -:: - - qmake "USE_UPNP=1" - -(in **Qt Creator**, you can find the setting for additional qmake arguments under "Projects" -> "Build Settings" -> "Build Steps", then click "Details" next to **qmake**) - -This requires miniupnpc for UPnP port mapping. It can be downloaded from -http://miniupnp.tuxfamily.org/files/. UPnP support is not compiled in by default. - -Set USE_UPNP to a different value to control this: - -+------------+--------------------------------------------------------------------------+ -| USE_UPNP=- | no UPnP support, miniupnpc not required; | -+------------+--------------------------------------------------------------------------+ -| USE_UPNP=0 | (the default) built with UPnP, support turned off by default at runtime; | -+------------+--------------------------------------------------------------------------+ -| USE_UPNP=1 | build with UPnP support turned on by default at runtime. | -+------------+--------------------------------------------------------------------------+ - -Notification support for recent (k)ubuntu versions ---------------------------------------------------- - -To see desktop notifications on (k)ubuntu versions starting from 10.04, enable usage of the -FreeDesktop notification interface through DBUS using the following qmake option: - -:: - - qmake "USE_DBUS=1" - -Generation of QR codes ------------------------ - -libqrencode may be used to generate QRCode images for payment requests. -It can be downloaded from http://fukuchi.org/works/qrencode/index.html.en, or installed via your package manager. Pass the USE_QRCODE -flag to qmake to control this: - -+--------------+--------------------------------------------------------------------------+ -| USE_QRCODE=0 | (the default) No QRCode support - libarcode not required | -+--------------+--------------------------------------------------------------------------+ -| USE_QRCODE=1 | QRCode support enabled | -+--------------+--------------------------------------------------------------------------+ - - -Berkely DB version warning -========================== - -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**). - -The static binary version of Bitcoin is linked against libdb4.8 (see also `this Debian issue`_). - -Now the nasty thing is that databases from 5.X are not compatible with 4.X. - -If the globally installed development package of Berkely DB installed on your system is 5.X, any source you -build yourself will be linked against that. The first time you run with a 5.X version the database will be upgraded, -and 4.X cannot open the new format. This means that you cannot go back to the old statically linked version without -significant hassle! - -.. _`this Debian issue`: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=621425 - -Ubuntu 11.10 warning -==================== - -Ubuntu 11.10 has a package called 'qt-at-spi' installed by default. At the time of writing, having that package -installed causes bitcoin-qt to crash intermittently. The issue has been reported as `launchpad bug 857790`_, but -isn't yet fixed. - -Until the bug is fixed, you can remove the qt-at-spi package to work around the problem, though this will presumably -disable screen reader functionality for Qt apps: - -:: - - sudo apt-get remove qt-at-spi - -.. _`launchpad bug 857790`: https://bugs.launchpad.net/ubuntu/+source/qt-at-spi/+bug/857790 diff --git a/doc/release-process.md b/doc/release-process.md index dc2101e1c1..9e0b860a8c 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -31,26 +31,34 @@ Release Process export SIGNER=(your gitian key, ie bluematt, sipa, etc) export VERSION=(new version, e.g. 0.8.0) - cd ./gitian-builder + pushd ./bitcoin + git checkout v${VERSION} + popd + pushd ./gitian-builder Fetch and build inputs: (first time, or when dependency versions change) mkdir -p inputs; cd inputs/ wget 'http://miniupnp.free.fr/files/download.php?file=miniupnpc-1.6.tar.gz' -O miniupnpc-1.6.tar.gz - wget 'http://www.openssl.org/source/openssl-1.0.1c.tar.gz' + wget 'https://www.openssl.org/source/openssl-1.0.1c.tar.gz' wget 'http://download.oracle.com/berkeley-db/db-4.8.30.NC.tar.gz' - wget 'http://zlib.net/zlib-1.2.6.tar.gz' - wget 'ftp://ftp.simplesystems.org/pub/libpng/png/src/libpng-1.5.9.tar.gz' - wget 'http://fukuchi.org/works/qrencode/qrencode-3.2.0.tar.bz2' - wget 'http://downloads.sourceforge.net/project/boost/boost/1.50.0/boost_1_50_0.tar.bz2' - wget 'http://releases.qt-project.org/qt4/source/qt-everywhere-opensource-src-4.8.3.tar.gz' + wget 'ftp://ftp.simplesystems.org/pub/libpng/png/src/history/zlib/zlib-1.2.6.tar.gz' + wget 'ftp://ftp.simplesystems.org/pub/libpng/png/src/history/libpng15/libpng-1.5.9.tar.gz' + wget 'https://fukuchi.org/works/qrencode/qrencode-3.2.0.tar.bz2' + wget 'https://downloads.sourceforge.net/project/boost/boost/1.54.0/boost_1_54_0.tar.bz2' + wget 'https://svn.boost.org/trac/boost/raw-attachment/ticket/7262/boost-mingw.patch' -O \ + boost-mingw-gas-cross-compile-2013-03-03.patch + wget 'https://download.qt-project.org/archive/qt/4.8/4.8.3/qt-everywhere-opensource-src-4.8.3.tar.gz' + wget 'https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.bz2' cd .. ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/boost-win32.yml - mv build/out/boost-win32-1.50.0-gitian2.zip inputs/ - ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/qt-win32.yml - mv build/out/qt-win32-4.8.3-gitian-r1.zip inputs/ + mv build/out/boost-win32-*.zip inputs/ ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/deps-win32.yml - mv build/out/bitcoin-deps-0.0.5.zip inputs/ + mv build/out/bitcoin-deps-*.zip inputs/ + ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/qt-win32.yml + mv build/out/qt-win32-*.zip inputs/ + ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/protobuf-win32.yml + mv build/out/protobuf-win32-*.zip inputs/ Build bitcoind and bitcoin-qt on Linux32, Linux64, and Win32: @@ -58,13 +66,14 @@ Release Process ./bin/gsign --signer $SIGNER --release ${VERSION} --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian.yml pushd build/out zip -r bitcoin-${VERSION}-linux-gitian.zip * - mv bitcoin-${VERSION}-linux-gitian.zip ../../ + mv bitcoin-${VERSION}-linux-gitian.zip ../../../ popd ./bin/gbuild --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-win32.yml ./bin/gsign --signer $SIGNER --release ${VERSION}-win32 --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-win32.yml pushd build/out zip -r bitcoin-${VERSION}-win32-gitian.zip * - mv bitcoin-${VERSION}-win32-gitian.zip ../../ + mv bitcoin-${VERSION}-win32-gitian.zip ../../../ + popd popd Build output expected: diff --git a/doc/tor.md b/doc/tor.md new file mode 100644 index 0000000000..41dd71209f --- /dev/null +++ b/doc/tor.md @@ -0,0 +1,90 @@ +TOR SUPPORT IN BITCOIN +====================== + +It is possible to run Bitcoin as a Tor hidden service, and connect to such services. + +The following directions assume you have a Tor proxy running on port 9050. Many distributions default to having a SOCKS proxy listening on port 9050, but others may not. In particular, the Tor Browser Bundle defaults to listening on a random port. See [Tor Project FAQ:TBBSocksPort](https://www.torproject.org/docs/faq.html.en#TBBSocksPort) for how to properly +configure Tor. + + +1. Run bitcoin behind a Tor proxy +--------------------------------- + +The first step is running Bitcoin behind a Tor proxy. This will already make all +outgoing connections be anonimized, but more is possible. + + -socks=5 SOCKS5 supports connecting-to-hostname, which can be used instead + of doing a (leaking) local DNS lookup. SOCKS5 is the default, + but SOCKS4 does not support this. (SOCKS4a does, but isn't + implemented). + + -proxy=ip:port Set the proxy server. If SOCKS5 is selected (default), this proxy + server will be used to try to reach .onion addresses as well. + + -onion=ip:port Set the proxy server to use for tor hidden services. You do not + need to set this if it's the same as -proxy. You can use -noonion + to explicitly disable access to hidden service. + + -listen When using -proxy, listening is disabled by default. If you want + to run a hidden service (see next section), you'll need to enable + it explicitly. + + -connect=X When behind a Tor proxy, you can specify .onion addresses instead + -addnode=X of IP addresses or hostnames in these parameters. It requires + -seednode=X SOCKS5. In Tor mode, such addresses can also be exchanged with + other P2P nodes. + +In a typical situation, this suffices to run behind a Tor proxy: + + ./bitcoin -proxy=127.0.0.1:9050 + + +2. Run a bitcoin hidden server +------------------------------ + +If you configure your Tor system accordingly, it is possible to make your node also +reachable from the Tor network. Add these lines to your /etc/tor/torrc (or equivalent +config file): + + HiddenServiceDir /var/lib/tor/bitcoin-service/ + HiddenServicePort 8333 127.0.0.1:8333 + HiddenServicePort 18333 127.0.0.1:18333 + +The directory can be different of course, but (both) port numbers should be equal to +your bitcoind's P2P listen port (8333 by default). + + -externalip=X You can tell bitcoin about its publicly reachable address using + this option, and this can be a .onion address. Given the above + configuration, you can find your onion address in + /var/lib/tor/bitcoin-service/hostname. Onion addresses are given + preference for your node to advertize itself with, for connections + coming from unroutable addresses (such as 127.0.0.1, where the + Tor proxy typically runs). + + -listen You'll need to enable listening for incoming connections, as this + is off by default behind a proxy. + + -discover When -externalip is specified, no attempt is made to discover local + IPv4 or IPv6 addresses. If you want to run a dual stack, reachable + from both Tor and IPv4 (or IPv6), you'll need to either pass your + other addresses using -externalip, or explicitly enable -discover. + Note that both addresses of a dual-stack system may be easily + linkable using traffic analysis. + +In a typical situation, where you're only reachable via Tor, this should suffice: + + ./bitcoind -proxy=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -listen + +(obviously, replace the Onion address with your own). If you don't care too much +about hiding your node, and want to be reachable on IPv4 as well, additionally +specify: + + ./bitcoind ... -discover + +and open port 8333 on your firewall (or use -upnp). + +If you only want to use Tor to reach onion addresses, but not use it as a proxy +for normal IPv4/IPv6 communication, use: + + ./bitcoin -onion=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -discover + diff --git a/doc/translation_process.md b/doc/translation_process.md index 1724e95378..006726b953 100644 --- a/doc/translation_process.md +++ b/doc/translation_process.md @@ -32,14 +32,13 @@ This directory contains all translations. Filenames must adhere to this format: `src/qt/locale/bitcoin_en.ts` is treated in a special way. It is used as the source for all other translations. Whenever a string in the code is changed -this file must be updated to reflect those changes. This can be accomplished -by running `lupdate` (included in the Qt SDK). Also, a custom script is used +this file must be updated to reflect those changes. A custom script is used to extract strings from the non-Qt parts. This script makes use of `gettext`, so make sure that utility is installed (ie, `apt-get install gettext` on -Ubuntu/Debian): - - python share/qt/extract_strings_qt.py - lupdate bitcoin-qt.pro -no-obsolete -locations relative -ts src/qt/locale/bitcoin_en.ts +Ubuntu/Debian). Once this has been updated, lupdate (included in the Qt SDK) +is used to update bitcoin_en.ts. This process has been automated, from src/qt, +simply run: + make translate ##### Handling of plurals in the source file diff --git a/doc/unit-tests.md b/doc/unit-tests.md index d6fb2d8e2d..2c991eb03a 100644 --- a/doc/unit-tests.md +++ b/doc/unit-tests.md @@ -1,35 +1,18 @@ -Compiling/running bitcoind unit tests +Compiling/running unit tests ------------------------------------ -bitcoind unit tests are in the `src/test/` directory; they -use the Boost::Test unit-testing framework. +Unit tests will be automatically compiled if dependencies were met in configure +and tests weren't explicitly disabled. -To compile and run the tests: +After configuring, they can be run with 'make check'. - cd src - make -f makefile.unix test_bitcoin # Replace makefile.unix if you're not on unix - ./test_bitcoin # Runs the unit tests +To run the bitcoind tests manually, launch src/test/test_bitcoin . -If all tests succeed the last line of output will be: -`*** No errors detected` - -To add more tests, add `BOOST_AUTO_TEST_CASE` functions to the existing +To add more bitcoind tests, add `BOOST_AUTO_TEST_CASE` functions to the existing .cpp files in the test/ directory or add new .cpp files that -implement new BOOST_AUTO_TEST_SUITE sections (the makefiles are -set up to add test/*.cpp to test_bitcoin automatically). - - -Compiling/running Bitcoin-Qt unit tests ---------------------------------------- - -Bitcoin-Qt unit tests are in the src/qt/test/ directory; they -use the Qt unit-testing framework. - -To compile and run the tests: +implement new BOOST_AUTO_TEST_SUITE sections. - qmake bitcoin-qt.pro BITCOIN_QT_TEST=1 - make - ./bitcoin-qt_test +To run the bitcoin-qt tests manualy, launch src/qt/test/bitcoin-qt_test -To add more tests, add them to the `src/qt/test/` directory, -the `src/qt/test/test_main.cpp` file, and bitcoin-qt.pro. +To add more bitcoin-qt tests, add them to the `src/qt/test/` directory and +the `src/qt/test/test_main.cpp` file. |