Merge pull request #2771 from super3/master

Docs Markdown Cleanup - Part 2
This commit is contained in:
Jeff Garzik 2013-06-24 06:55:46 -07:00
commit b0868eaf5f
8 changed files with 398 additions and 66 deletions

View File

@ -3,8 +3,7 @@ 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.
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.
@ -19,8 +18,13 @@ with each other, with the help of a P2P network to check for double-spending.
Setup
---------------------
[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; 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
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 +33,38 @@ 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.
### 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.
Building
---------------------
- [Bitcoin-Qt Readme](readme-qt.md)
- [OSX Build Notes](build-osx.md)
- [Unix Build Notes](build-unix.md)
- [Windows Build Notes](build-msw.md)
Development
---------------------
- [Coding Guidelines](coding.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)
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)
- [Assets Attribution](assets-attribution.md)
- [Files](files.md)
- [Tor Support](tor.md)

104
doc/assets-attribution.md Normal file
View File

@ -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

View File

@ -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.rst](readme-qt.rst) 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:

View File

@ -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.rst](readme-qt.rst) 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

View File

@ -1,12 +1,6 @@
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
---------------------

23
doc/files.md Normal file
View File

@ -0,0 +1,23 @@
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
* blocks/rev000??.dat; block undo data (custom); since 0.8.0 (format changed since pre-0.8)
* blocks/index/*; block index (LevelDB); since 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
---------------------
* 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
---------------------
* 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
---------------------
* addr.dat: peer IP address database (BDB); replaced by peers.dat in 0.7.0

128
doc/readme-qt.md Normal file
View File

@ -0,0 +1,128 @@
Bitcoin-Qt Readme
===============================
Contains build and configuration instructions for 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](http://qt-project.org/downloads/) and open the `bitcoin-qt.pro` file.
An executable named `bitcoin-qt` will be built.
### Mac OS X
* Download and install the [Qt Mac OS X SDK](https://qt-project.org/downloads). It is recommended to also install Apple's Xcode with UNIX tools.
* Download and install either [MacPorts](https://www.macports.org/) or [HomeBrew](http://mxcl.github.io/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)
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 [here](
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](http://fukuchi.org/works/qrencode/) may be used to generate QRCode images for payment requests. 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
Warnings
---------------------
### 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](http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=621425)).
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!
### 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](https://bugs.launchpad.net/ubuntu/+source/qt-at-spi/+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

89
doc/tor.md Normal file
View File

@ -0,0 +1,89 @@
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.
-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