From 2341e9b533fedf9bade5b55d676b2c0cf5ed8604 Mon Sep 17 00:00:00 2001 From: super3 Date: Mon, 20 May 2013 00:30:00 -0400 Subject: [PATCH] Docs Markdown Cleanup --- doc/README | 33 ---- doc/README.md | 46 +++++ doc/{build-msw.txt => build-msw.md} | 66 +++---- doc/{build-unix.txt => build-unix.md} | 118 +++++++------ doc/coding.md | 94 ++++++++++ doc/coding.txt | 96 ---------- doc/{multiwallet-qt.txt => multiwallet-qt.md} | 11 +- doc/{release-notes.txt => release-notes.md} | 46 ++--- doc/release-process.md | 164 ++++++++++++++++++ doc/release-process.txt | 144 --------------- doc/{unit-tests.txt => unit-tests.md} | 24 +-- 11 files changed, 443 insertions(+), 399 deletions(-) delete mode 100644 doc/README create mode 100644 doc/README.md rename doc/{build-msw.txt => build-msw.md} (55%) rename doc/{build-unix.txt => build-unix.md} (64%) create mode 100644 doc/coding.md delete mode 100644 doc/coding.txt rename doc/{multiwallet-qt.txt => multiwallet-qt.md} (89%) rename doc/{release-notes.txt => release-notes.md} (55%) create mode 100644 doc/release-process.md delete mode 100644 doc/release-process.txt rename doc/{unit-tests.txt => unit-tests.md} (55%) diff --git a/doc/README b/doc/README deleted file mode 100644 index ecd9c603..00000000 --- a/doc/README +++ /dev/null @@ -1,33 +0,0 @@ -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. -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). - - -Intro ------ -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. - - -Setup ------ -You need the Qt4 run-time libraries to run Bitcoin-Qt. On Debian or Ubuntu: - sudo apt-get install libqtgui4 - -Unpack the files into a directory and run: - bin/32/bitcoin-qt (GUI, 32-bit) - bin/32/bitcoind (headless, 32-bit) - 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. diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 00000000..cdd31057 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,46 @@ +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. +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 +--------------------- +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. + + +Setup +--------------------- +You need the Qt4 run-time libraries to run Bitcoin-Qt. On Debian or Ubuntu: + `sudo apt-get install libqtgui4` + +Unpack the files into a directory and run: + +- bin/32/bitcoin-qt (GUI, 32-bit) +- bin/32/bitcoind (headless, 32-bit) +- 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 +--------------------- +- [Unix Build Notes](build-unix.md) +- [OSX Build Notes](build-osx.md) +- [Windows Build Notes](build-msw.md) +- [Coding Guidelines](coding.md) +- [Release Process](release-process.md) +- [Release Notes](release-notes.md) +- [Multiwallet Qt Development](multiwallet-qt.md) +- [Unit Tests](unit-tests.md) +- [Translation Process](translation_process.md) \ No newline at end of file diff --git a/doc/build-msw.txt b/doc/build-msw.md similarity index 55% rename from doc/build-msw.txt rename to doc/build-msw.md index 3e64813b..b7abe288 100644 --- a/doc/build-msw.txt +++ b/doc/build-msw.md @@ -1,10 +1,9 @@ -Copyright (c) 2009-2012 Bitcoin Developers +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) and UPnP -software written by Thomas Bernard. +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 @@ -30,55 +29,62 @@ Boost \boost-1.50.0-mgw http://www.boost.org/users/download/ miniupnpc \miniupnpc-1.6-mgw http://miniupnp.tuxfamily.org/files/ Their licenses: -OpenSSL Old BSD license with the problematic advertising requirement -Berkeley DB New BSD license with additional requirement that linked software must be free open source -Boost MIT-like license -miniupnpc New (3-clause) BSD license + + OpenSSL Old BSD license with the problematic advertising requirement + Berkeley DB New BSD license with additional requirement that linked software must be free open source + Boost MIT-like license + miniupnpc New (3-clause) BSD license Versions used in this release: -OpenSSL 1.0.1c -Berkeley DB 4.8.30.NC -Boost 1.50.0 -miniupnpc 1.6 + + OpenSSL 1.0.1c + Berkeley DB 4.8.30.NC + Boost 1.50.0 + miniupnpc 1.6 OpenSSL ------- MSYS shell: + un-tar sources with MSYS 'tar xfz' to avoid issue with symlinks (OpenSSL ticket 2377) change 'MAKE' env. variable from 'C:\MinGW32\bin\mingw32-make.exe' to '/c/MinGW32/bin/mingw32-make.exe' -cd /c/openssl-1.0.1c-mgw -./config -make + cd /c/openssl-1.0.1c-mgw + ./config + make Berkeley DB ----------- MSYS shell: -cd /c/db-4.8.30.NC-mgw/build_unix -sh ../dist/configure --enable-mingw --enable-cxx -make + + cd /c/db-4.8.30.NC-mgw/build_unix + sh ../dist/configure --enable-mingw --enable-cxx + make Boost ----- DOS prompt: -downloaded boost jam 3.1.18 -cd \boost-1.50.0-mgw -bjam toolset=gcc --build-type=complete stage + + downloaded boost jam 3.1.18 + cd \boost-1.50.0-mgw + bjam toolset=gcc --build-type=complete stage MiniUPnPc --------- -UPnP support is optional, make with USE_UPNP= to disable it. +UPnP support is optional, make with `USE_UPNP=` to disable it. MSYS shell: -cd /c/miniupnpc-1.6-mgw -make -f Makefile.mingw -mkdir miniupnpc -cp *.h miniupnpc/ + + cd /c/miniupnpc-1.6-mgw + make -f Makefile.mingw + mkdir miniupnpc + cp *.h miniupnpc/ Bitcoin ------- DOS prompt: -cd \bitcoin\src -mingw32-make -f makefile.mingw -strip bitcoind.exe + + cd \bitcoin\src + mingw32-make -f makefile.mingw + strip bitcoind.exe diff --git a/doc/build-unix.txt b/doc/build-unix.md similarity index 64% rename from doc/build-unix.txt rename to doc/build-unix.md index a1e24ff5..6181bb25 100644 --- a/doc/build-unix.txt +++ b/doc/build-unix.md @@ -1,26 +1,23 @@ -Copyright (c) 2009-2012 Bitcoin Developers +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) and UPnP -software written by Thomas Bernard. - +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 -================ +==================== To Build --------- +--------------------- -cd src/ -make -f makefile.unix # Headless bitcoin + cd src/ + make -f makefile.unix # Headless bitcoin -See readme-qt.rst for instructions on building Bitcoin-Qt, -the graphical user interface. +See readme-qt.rst for instructions on building Bitcoin-Qt, the graphical user interface. Dependencies ------------- +--------------------- Library Purpose Description ------- ------- ----------- @@ -29,15 +26,17 @@ Dependencies libboost Boost C++ Library miniupnpc UPnP Support Optional firewall-jumping support -miniupnpc may be used for UPnP port mapping. It can be downloaded from -http://miniupnp.tuxfamily.org/files/. UPnP support is compiled in and +[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: - 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 + + 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 IPv6 support may be disabled by setting: - USE_IPV6=0 Disable IPv6 support + + USE_IPV6=0 Disable IPv6 support Licenses of statically linked libraries: Berkeley DB New BSD license with additional requirement that linked @@ -45,51 +44,54 @@ Licenses of statically linked libraries: Boost MIT-like license miniupnpc New (3-clause) BSD license -Versions used in this release: - GCC 4.3.3 - OpenSSL 1.0.1c - Berkeley DB 4.8.30.NC - Boost 1.37 - miniupnpc 1.6 +- Versions used in this release: +- GCC 4.3.3 +- OpenSSL 1.0.1c +- Berkeley DB 4.8.30.NC +- Boost 1.37 +- miniupnpc 1.6 Dependency Build Instructions: Ubuntu & Debian ---------------------------------------------- Build requirements: - sudo apt-get install build-essential - sudo apt-get install libssl-dev + + sudo apt-get install build-essential + sudo apt-get install libssl-dev for Ubuntu 12.04: - sudo apt-get install libboost-all-dev - db4.8 packages are available at: - https://launchpad.net/~bitcoin/+archive/bitcoin + 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, but using these will break binary wallet compatibility, and is not recommended. for other Ubuntu & Debian: - sudo apt-get install libdb4.8-dev - sudo apt-get install libdb4.8++-dev - sudo apt-get install libboost1.37-dev + + sudo apt-get install libdb4.8-dev + sudo apt-get install libdb4.8++-dev + sudo apt-get install libboost1.37-dev (If using Boost 1.37, append -mt to the boost libraries in the makefile) Optional: - sudo apt-get install libminiupnpc-dev (see USE_UPNP compile flag) + + sudo apt-get install libminiupnpc-dev (see USE_UPNP compile flag) Dependency Build Instructions: Gentoo ------------------------------------- -Note: If you just want to install bitcoind on Gentoo, you can add the Bitcoin - overlay and use your package manager: - layman -a bitcoin && emerge bitcoind +Note: If you just want to install bitcoind on Gentoo, you can add the Bitcoin overlay and use your package manager: -emerge -av1 --noreplace boost glib openssl sys-libs/db:4.8 + layman -a bitcoin && emerge bitcoind + emerge -av1 --noreplace boost glib openssl sys-libs/db:4.8 Take the following steps to build (no UPnP support): - cd ${BITCOIN_DIR}/src - make -f makefile.unix USE_UPNP= USE_IPV6=1 BDB_INCLUDE_PATH='/usr/include/db4.8' - strip bitcoind + + cd ${BITCOIN_DIR}/src + make -f makefile.unix USE_UPNP= USE_IPV6=1 BDB_INCLUDE_PATH='/usr/include/db4.8' + strip bitcoind Notes @@ -100,26 +102,28 @@ symbols, which reduces the executable size by about 90%. miniupnpc --------- -tar -xzvf miniupnpc-1.6.tar.gz -cd miniupnpc-1.6 -make -sudo su -make install + tar -xzvf miniupnpc-1.6.tar.gz + cd miniupnpc-1.6 + make + sudo su + make install Berkeley DB ----------- You need Berkeley DB 4.8. If you have to build Berkeley DB yourself: -../dist/configure --enable-cxx -make + + ../dist/configure --enable-cxx + make Boost ----- If you need to build Boost yourself: -sudo su -./bootstrap.sh -./bjam install + + sudo su + ./bootstrap.sh + ./bjam install Security @@ -138,10 +142,12 @@ exploit even if a vulnerability is found, you can take the following measures: 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 + + 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 + + scanelf -e ./bitcoin The output should contain: TYPE @@ -155,10 +161,10 @@ exploit even if a vulnerability is found, you can take the following measures: executable without the non-executable stack protection. To verify that the stack is non-executable after compiling use: - scanelf -e ./bitcoin + `scanelf -e ./bitcoin` the output should contain: - STK/REL/PTL - RW- R-- RW- + STK/REL/PTL + RW- R-- RW- The STK RW- means that the stack is readable and writeable but not executable. diff --git a/doc/coding.md b/doc/coding.md new file mode 100644 index 00000000..3581d7de --- /dev/null +++ b/doc/coding.md @@ -0,0 +1,94 @@ +Coding +==================== + +Please be consistent with the existing coding style. + +Block style: + + bool Function(char* psz, int n) + { + // Comment summarising what this section of code does + for (int i = 0; i < n; i++) + { + // When something fails, return early + if (!Something()) + return false; + ... + } + + // Success return is usually at the end + return true; + } + +- ANSI/Allman block style +- 4 space indenting, no tabs +- No extra spaces inside parenthesis; please don't do ( this ) +- No space after function names, one space after if, for and while + +Variable names begin with the type in lowercase, like nSomeVariable. +Please don't put the first word of the variable name in lowercase like +someVariable. + +Common types: + + n integer number: short, unsigned short, int, unsigned int, int64, uint64, sometimes char if used as a number + d double, float + f flag + hash uint256 + p pointer or array, one p for each level of indirection + psz pointer to null terminated string + str string object + v vector or similar list objects + map map or multimap + set set or multiset + bn CBigNum + +------------------------- +Locking/mutex usage notes + +The code is multi-threaded, and uses mutexes and the +LOCK/TRY_LOCK macros to protect data structures. + +Deadlocks due to inconsistent lock ordering (thread 1 locks cs_main +and then cs_wallet, while thread 2 locks them in the opposite order: +result, deadlock as each waits for the other to release its lock) are +a problem. Compile with -DDEBUG_LOCKORDER to get lock order +inconsistencies reported in the debug.log file. + +Re-architecting the core code so there are better-defined interfaces +between the various components is a goal, with any necessary locking +done by the components (e.g. see the self-contained CKeyStore class +and its cs_KeyStore lock for example). + +------- +Threads + +- StartNode : Starts other threads. + +- ThreadGetMyExternalIP : Determines outside-the-firewall IP address, sends addr message to connected peers when it determines it. + +- ThreadSocketHandler : Sends/Receives data from peers on port 8333. + +- ThreadMessageHandler : Higher-level message handling (sending and receiving). + +- ThreadOpenConnections : Initiates new connections to peers. + +- ThreadTopUpKeyPool : replenishes the keystore's keypool. + +- ThreadCleanWalletPassphrase : re-locks an encrypted wallet after user has unlocked it for a period of time. + +- SendingDialogStartTransfer : used by pay-via-ip-address code (obsolete) + +- ThreadDelayedRepaint : repaint the gui + +- ThreadFlushWalletDB : Close the wallet.dat file if it hasn't been used in 500ms. + +- ThreadRPCServer : Remote procedure call handler, listens on port 8332 for connections and services them. + +- ThreadBitcoinMiner : Generates bitcoins + +- ThreadMapPort : Universal plug-and-play startup/shutdown + +- Shutdown : Does an orderly shutdown of everything + +- ExitTimeout : Windows-only, sleeps 5 seconds then exits application diff --git a/doc/coding.txt b/doc/coding.txt deleted file mode 100644 index 427e388c..00000000 --- a/doc/coding.txt +++ /dev/null @@ -1,96 +0,0 @@ -Please be consistent with the existing coding style. - -Block style: - -bool Function(char* psz, int n) -{ - // Comment summarising what this section of code does - for (int i = 0; i < n; i++) - { - // When something fails, return early - if (!Something()) - return false; - ... - } - - // Success return is usually at the end - return true; -} - -- ANSI/Allman block style -- 4 space indenting, no tabs -- No extra spaces inside parenthesis; please don't do ( this ) -- No space after function names, one space after if, for and while - -Variable names begin with the type in lowercase, like nSomeVariable. -Please don't put the first word of the variable name in lowercase like -someVariable. - -Common types: -n integer number: short, unsigned short, int, unsigned int, - int64, uint64, sometimes char if used as a number -d double, float -f flag -hash uint256 -p pointer or array, one p for each level of indirection -psz pointer to null terminated string -str string object -v vector or similar list objects -map map or multimap -set set or multiset -bn CBigNum - -------------------------- -Locking/mutex usage notes - -The code is multi-threaded, and uses mutexes and the -LOCK/TRY_LOCK macros to protect data structures. - -Deadlocks due to inconsistent lock ordering (thread 1 locks cs_main -and then cs_wallet, while thread 2 locks them in the opposite order: -result, deadlock as each waits for the other to release its lock) are -a problem. Compile with -DDEBUG_LOCKORDER to get lock order -inconsistencies reported in the debug.log file. - -Re-architecting the core code so there are better-defined interfaces -between the various components is a goal, with any necessary locking -done by the components (e.g. see the self-contained CKeyStore class -and its cs_KeyStore lock for example). - -------- -Threads - -StartNode : Starts other threads. - -ThreadGetMyExternalIP : Determines outside-the-firewall IP address, -sends addr message to connected peers when it determines it. - -ThreadSocketHandler : Sends/Receives data from peers on port 8333. - -ThreadMessageHandler : Higher-level message handling (sending and -receiving). - -ThreadOpenConnections : Initiates new connections to peers. - -ThreadTopUpKeyPool : replenishes the keystore's keypool. - -ThreadCleanWalletPassphrase : re-locks an encrypted wallet after user -has unlocked it for a period of time. - -SendingDialogStartTransfer : used by pay-via-ip-address code (obsolete) - -ThreadDelayedRepaint : repaint the gui - -ThreadFlushWalletDB : Close the wallet.dat file if it hasn't been used -in 500ms. - -ThreadRPCServer : Remote procedure call handler, listens on port 8332 -for connections and services them. - -ThreadBitcoinMiner : Generates bitcoins - -ThreadMapPort : Universal plug-and-play startup/shutdown - -Shutdown : Does an orderly shutdown of everything - -ExitTimeout : Windows-only, sleeps 5 seconds then exits application diff --git a/doc/multiwallet-qt.txt b/doc/multiwallet-qt.md similarity index 89% rename from doc/multiwallet-qt.txt rename to doc/multiwallet-qt.md index 8394080d..8d695552 100644 --- a/doc/multiwallet-qt.txt +++ b/doc/multiwallet-qt.md @@ -39,15 +39,14 @@ Changes to bitcoin.cpp bitcoin.cpp is the entry point into bitcoin-qt, and as such, will require some minor modifications to provide hooks for multiple wallet support. Most importantly will be the way it instantiates WalletModels and passes them to the singleton BitcoinGUI instance called window. Formerly, BitcoinGUI kept a pointer to a single instance of a WalletModel. -The initial change required is very simple: rather than calling window.setWalletModel(&walletModel); we perform the +The initial change required is very simple: rather than calling `window.setWalletModel(&walletModel);` we perform the following two steps: -window.addWallet("~Default", &walletModel); -window.setCurrentWallet("~Default"); + window.addWallet("~Default", &walletModel); + window.setCurrentWallet("~Default"); -The string parameter is just an arbitrary name given to the default wallet. It's been prepended with a tilde to avoid name -collisions in the future with additional wallets. +The string parameter is just an arbitrary name given to the default wallet. It's been prepended with a tilde to avoid name collisions in the future with additional wallets. -The shutdown call window.setWalletModel(0) has also been removed. In its place is now: +The shutdown call `window.setWalletModel(0)` has also been removed. In its place is now: window.removeAllWallets(); diff --git a/doc/release-notes.txt b/doc/release-notes.md similarity index 55% rename from doc/release-notes.txt rename to doc/release-notes.md index 36b2f753..0e0b04bc 100644 --- a/doc/release-notes.txt +++ b/doc/release-notes.md @@ -26,41 +26,41 @@ the rest of the network your transactions may never confirm. Bitcoin-Qt changes ------------------ -* New icon and splash screen -* Improve reporting of synchronization process -* Remove hardcoded fee recommendations -* Improve metadata of executable on MacOSX and Windows -* Move export button to individual tabs instead of toolbar -* Add "send coins" command to context menu in address book -* Add "copy txid" command to copy transaction IDs from transaction overview -* Save & restore window size and position when showing & hiding window -* New translations: Arabic (ar), Bosnian (bs), Catalan (ca), Welsh (cy), - Esperanto (eo), Interlingua (la), Latvian (lv) and many improvements - to current translations +- New icon and splash screen +- Improve reporting of synchronization process +- Remove hardcoded fee recommendations +- Improve metadata of executable on MacOSX and Windows +- Move export button to individual tabs instead of toolbar +- Add "send coins" command to context menu in address book +- Add "copy txid" command to copy transaction IDs from transaction overview +- Save & restore window size and position when showing & hiding window +- New translations: Arabic (ar), Bosnian (bs), Catalan (ca), Welsh (cy), Esperanto (eo), Interlingua (la), Latvian (lv) and many improvements to current translations MacOSX: -* OSX support for click-to-pay (bitcoin:) links -* Fix GUI disappearing problem on MacOSX (issue #1522) + +- OSX support for click-to-pay (bitcoin:) links +- Fix GUI disappearing problem on MacOSX (issue #1522) Linux/Unix: -* Copy addresses to middle-mouse-button clipboard + +- Copy addresses to middle-mouse-button clipboard Command-line options -------------------- -* -walletnotify will call a command on receiving transactions that affect the wallet. -* -alertnotify will call a command on receiving an alert from the network. -* -par now takes a negative number, to leave a certain amount of cores free. +* `-walletnotify` will call a command on receiving transactions that affect the wallet. +* `-alertnotify` will call a command on receiving an alert from the network. +* `-par` now takes a negative number, to leave a certain amount of cores free. JSON-RPC API changes -------------------- -* listunspent now lists account and address infromation. -* getinfo now also returns the time adjustment estimated from your peers. -* getpeerinfo now returns bytessent, bytesrecv and syncnode. -* gettxoutsetinfo returns statistics about the unspent transaction output database. -* gettxout returns information about a specific unspent transaction output. +* `listunspent` now lists account and address infromation. +* `getinfo` now also returns the time adjustment estimated from your peers. +* `getpeerinfo` now returns bytessent, bytesrecv and syncnode. +* `gettxoutsetinfo` returns statistics about the unspent transaction output database. +* `gettxout` returns information about a specific unspent transaction output. Networking changes @@ -76,5 +76,5 @@ Wallet compatibility/rescuing ----------------------------- * Cases where wallets cannot be opened in another version/installation should be reduced. -* -salvagewallet now works for encrypted wallets. +* `-salvagewallet` now works for encrypted wallets. diff --git a/doc/release-process.md b/doc/release-process.md new file mode 100644 index 00000000..17d6a089 --- /dev/null +++ b/doc/release-process.md @@ -0,0 +1,164 @@ +Release Process +==================== + +* update translations (ping wumpus, Diapolo or tcatm on IRC) +* see https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#syncing-with-transifex + +* * * + +###update (commit) version in sources + + + bitcoin-qt.pro + contrib/verifysfbinaries/verify.sh + doc/README* + share/setup.nsi + src/clientversion.h (change CLIENT_VERSION_IS_RELEASE to true) + +###tag version in git + + git tag -a v0.8.0 + +###write release notes. git shortlog helps a lot, for example: + + git shortlog --no-merges v0.7.2..v0.8.0 + +* * * + +##perform gitian builds + + From a directory containing the bitcoin source, gitian-builder and gitian.sigs + + export SIGNER=(your gitian key, ie bluematt, sipa, etc) + export VERSION=0.8.0 + cd ./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 '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' + 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/ + ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/deps-win32.yml + mv build/out/bitcoin-deps-0.0.5.zip inputs/ + + Build bitcoind and bitcoin-qt on Linux32, Linux64, and Win32: + + ./bin/gbuild --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian.yml + ./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 ../../ + 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 ../../ + popd + + Build output expected: + + 1. linux 32-bit and 64-bit binaries + source (bitcoin-${VERSION}-linux-gitian.zip) + 2. windows 32-bit binary, installer + source (bitcoin-${VERSION}-win32-gitian.zip) + 3. Gitian signatures (in gitian.sigs/${VERSION}[-win32]/(your gitian key)/ + +repackage gitian builds for release as stand-alone zip/tar/installer exe + +**Linux .tar.gz:** + + unzip bitcoin-${VERSION}-linux-gitian.zip -d bitcoin-${VERSION}-linux + tar czvf bitcoin-${VERSION}-linux.tar.gz bitcoin-${VERSION}-linux + rm -rf bitcoin-${VERSION}-linux + +**Windows .zip and setup.exe:** + + unzip bitcoin-${VERSION}-win32-gitian.zip -d bitcoin-${VERSION}-win32 + mv bitcoin-${VERSION}-win32/bitcoin-*-setup.exe . + zip -r bitcoin-${VERSION}-win32.zip bitcoin-${VERSION}-win32 + rm -rf bitcoin-${VERSION}-win32 + +**Perform Mac build:** + + OSX binaries are created by Gavin Andresen on a 32-bit, OSX 10.6 machine. + + qmake RELEASE=1 USE_UPNP=1 USE_QRCODE=1 bitcoin-qt.pro + make + export QTDIR=/opt/local/share/qt4 # needed to find translations/qt_*.qm files + T=$(contrib/qt_translations.py $QTDIR/translations src/qt/locale) + python2.7 share/qt/clean_mac_info_plist.py + python2.7 contrib/macdeploy/macdeployqtplus Bitcoin-Qt.app -add-qt-tr $T -dmg -fancy contrib/macdeploy/fancy.plist + + Build output expected: Bitcoin-Qt.dmg + +###Next steps: + +* Code-sign Windows -setup.exe (in a Windows virtual machine) and + OSX Bitcoin-Qt.app (Note: only Gavin has the code-signing keys currently) + +* upload builds to SourceForge + +* create SHA256SUMS for builds, and PGP-sign it + +* update bitcoin.org version + make sure all OS download links go to the right versions + +* update forum version + +* update wiki download links + +* update wiki changelog: [https://en.bitcoin.it/wiki/Changelog](https://en.bitcoin.it/wiki/Changelog) + +Commit your signature to gitian.sigs: + + pushd gitian.sigs + git add ${VERSION}/${SIGNER} + git add ${VERSION}-win32/${SIGNER} + git commit -a + git push # Assuming you can push to the gitian.sigs tree + popd + +------------------------------------------------------------------------- + +### After 3 or more people have gitian-built, repackage gitian-signed zips: + +From a directory containing bitcoin source, gitian.sigs and gitian zips + + export VERSION=0.5.1 + mkdir bitcoin-${VERSION}-linux-gitian + pushd bitcoin-${VERSION}-linux-gitian + unzip ../bitcoin-${VERSION}-linux-gitian.zip + mkdir gitian + cp ../bitcoin/contrib/gitian-downloader/*.pgp ./gitian/ + for signer in $(ls ../gitian.sigs/${VERSION}/); do + cp ../gitian.sigs/${VERSION}/${signer}/bitcoin-build.assert ./gitian/${signer}-build.assert + cp ../gitian.sigs/${VERSION}/${signer}/bitcoin-build.assert.sig ./gitian/${signer}-build.assert.sig + done + zip -r bitcoin-${VERSION}-linux-gitian.zip * + cp bitcoin-${VERSION}-linux-gitian.zip ../ + popd + mkdir bitcoin-${VERSION}-win32-gitian + pushd bitcoin-${VERSION}-win32-gitian + unzip ../bitcoin-${VERSION}-win32-gitian.zip + mkdir gitian + cp ../bitcoin/contrib/gitian-downloader/*.pgp ./gitian/ + for signer in $(ls ../gitian.sigs/${VERSION}-win32/); do + cp ../gitian.sigs/${VERSION}-win32/${signer}/bitcoin-build.assert ./gitian/${signer}-build.assert + cp ../gitian.sigs/${VERSION}-win32/${signer}/bitcoin-build.assert.sig ./gitian/${signer}-build.assert.sig + done + zip -r bitcoin-${VERSION}-win32-gitian.zip * + cp bitcoin-${VERSION}-win32-gitian.zip ../ + popd + +- Upload gitian zips to SourceForge +- Celebrate \ No newline at end of file diff --git a/doc/release-process.txt b/doc/release-process.txt deleted file mode 100644 index ce661433..00000000 --- a/doc/release-process.txt +++ /dev/null @@ -1,144 +0,0 @@ -* update translations (ping wumpus, Diapolo or tcatm on IRC) - * see https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#syncing-with-transifex - -* update (commit) version in sources - bitcoin-qt.pro - contrib/verifysfbinaries/verify.sh - doc/README* - share/setup.nsi - src/clientversion.h (change CLIENT_VERSION_IS_RELEASE to true) - -* tag version in git - - git tag -a v0.8.0 - -* write release notes. git shortlog helps a lot, for example: - - git shortlog --no-merges v0.7.2..v0.8.0 - -* perform gitian builds - - * From a directory containing the bitcoin source, gitian-builder and gitian.sigs - export SIGNER=(your gitian key, ie bluematt, sipa, etc) - export VERSION=0.8.0 - cd ./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 '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' - 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/ - ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/deps-win32.yml - mv build/out/bitcoin-deps-0.0.5.zip inputs/ - - * Build bitcoind and bitcoin-qt on Linux32, Linux64, and Win32: - ./bin/gbuild --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian.yml - ./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 ../../ - 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 ../../ - popd - - Build output expected: - 1. linux 32-bit and 64-bit binaries + source (bitcoin-${VERSION}-linux-gitian.zip) - 2. windows 32-bit binary, installer + source (bitcoin-${VERSION}-win32-gitian.zip) - 3. Gitian signatures (in gitian.sigs/${VERSION}[-win32]/(your gitian key)/ - -* repackage gitian builds for release as stand-alone zip/tar/installer exe - - * Linux .tar.gz: - unzip bitcoin-${VERSION}-linux-gitian.zip -d bitcoin-${VERSION}-linux - tar czvf bitcoin-${VERSION}-linux.tar.gz bitcoin-${VERSION}-linux - rm -rf bitcoin-${VERSION}-linux - - * Windows .zip and setup.exe: - unzip bitcoin-${VERSION}-win32-gitian.zip -d bitcoin-${VERSION}-win32 - mv bitcoin-${VERSION}-win32/bitcoin-*-setup.exe . - zip -r bitcoin-${VERSION}-win32.zip bitcoin-${VERSION}-win32 - rm -rf bitcoin-${VERSION}-win32 - -* perform Mac build - OSX binaries are created by Gavin Andresen on a 32-bit, OSX 10.6 machine. - - qmake RELEASE=1 USE_UPNP=1 USE_QRCODE=1 bitcoin-qt.pro - make - export QTDIR=/opt/local/share/qt4 # needed to find translations/qt_*.qm files - T=$(contrib/qt_translations.py $QTDIR/translations src/qt/locale) - python2.7 share/qt/clean_mac_info_plist.py - python2.7 contrib/macdeploy/macdeployqtplus Bitcoin-Qt.app -add-qt-tr $T -dmg -fancy contrib/macdeploy/fancy.plist - - Build output expected: - Bitcoin-Qt.dmg - -* Code-sign Windows -setup.exe (in a Windows virtual machine) and - OSX Bitcoin-Qt.app (Note: only Gavin has the code-signing keys currently) - -* upload builds to SourceForge - -* create SHA256SUMS for builds, and PGP-sign it - -* update bitcoin.org version - make sure all OS download links go to the right versions - -* update forum version - -* update wiki download links - -* update wiki changelog: https://en.bitcoin.it/wiki/Changelog - -* Commit your signature to gitian.sigs: - pushd gitian.sigs - git add ${VERSION}/${SIGNER} - git add ${VERSION}-win32/${SIGNER} - git commit -a - git push # Assuming you can push to the gitian.sigs tree - popd - -------------------------------------------------------------------------- - -* After 3 or more people have gitian-built, repackage gitian-signed zips: - - * From a directory containing bitcoin source, gitian.sigs and gitian zips - export VERSION=0.5.1 - mkdir bitcoin-${VERSION}-linux-gitian - pushd bitcoin-${VERSION}-linux-gitian - unzip ../bitcoin-${VERSION}-linux-gitian.zip - mkdir gitian - cp ../bitcoin/contrib/gitian-downloader/*.pgp ./gitian/ - for signer in $(ls ../gitian.sigs/${VERSION}/); do - cp ../gitian.sigs/${VERSION}/${signer}/bitcoin-build.assert ./gitian/${signer}-build.assert - cp ../gitian.sigs/${VERSION}/${signer}/bitcoin-build.assert.sig ./gitian/${signer}-build.assert.sig - done - zip -r bitcoin-${VERSION}-linux-gitian.zip * - cp bitcoin-${VERSION}-linux-gitian.zip ../ - popd - mkdir bitcoin-${VERSION}-win32-gitian - pushd bitcoin-${VERSION}-win32-gitian - unzip ../bitcoin-${VERSION}-win32-gitian.zip - mkdir gitian - cp ../bitcoin/contrib/gitian-downloader/*.pgp ./gitian/ - for signer in $(ls ../gitian.sigs/${VERSION}-win32/); do - cp ../gitian.sigs/${VERSION}-win32/${signer}/bitcoin-build.assert ./gitian/${signer}-build.assert - cp ../gitian.sigs/${VERSION}-win32/${signer}/bitcoin-build.assert.sig ./gitian/${signer}-build.assert.sig - done - zip -r bitcoin-${VERSION}-win32-gitian.zip * - cp bitcoin-${VERSION}-win32-gitian.zip ../ - popd - - * Upload gitian zips to SourceForge diff --git a/doc/unit-tests.txt b/doc/unit-tests.md similarity index 55% rename from doc/unit-tests.txt rename to doc/unit-tests.md index a1278651..d6fb2d8e 100644 --- a/doc/unit-tests.txt +++ b/doc/unit-tests.md @@ -1,18 +1,19 @@ Compiling/running bitcoind unit tests ------------------------------------ -bitcoind unit tests are in the src/test/ directory; they +bitcoind unit tests are in the `src/test/` directory; they use the Boost::Test unit-testing framework. To compile and run the tests: -cd src -make -f makefile.unix test_bitcoin # Replace makefile.unix if you're not on unix -./test_bitcoin # Runs the unit tests + + cd src + make -f makefile.unix test_bitcoin # Replace makefile.unix if you're not on unix + ./test_bitcoin # Runs the unit tests If all tests succeed the last line of output will be: -*** No errors detected +`*** No errors detected` -To add more tests, add BOOST_AUTO_TEST_CASE functions to the existing +To add more 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). @@ -25,9 +26,10 @@ Bitcoin-Qt unit tests are in the src/qt/test/ directory; they use the Qt unit-testing framework. To compile and run the tests: -qmake bitcoin-qt.pro BITCOIN_QT_TEST=1 -make -./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. + qmake bitcoin-qt.pro BITCOIN_QT_TEST=1 + make + ./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.