diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Doxyfile | 2 | ||||
| -rw-r--r-- | doc/README.md | 9 | ||||
| -rw-r--r-- | doc/README_osx.txt | 32 | ||||
| -rw-r--r-- | doc/README_windows.txt | 12 | ||||
| -rw-r--r-- | doc/REST-interface.md | 27 | ||||
| -rw-r--r-- | doc/assets-attribution.md | 122 | ||||
| -rw-r--r-- | doc/bootstrap.md | 26 | ||||
| -rw-r--r-- | doc/build-osx.md | 39 | ||||
| -rw-r--r-- | doc/build-unix.md | 42 | ||||
| -rw-r--r-- | doc/developer-notes.md (renamed from doc/coding.md) | 64 | ||||
| -rw-r--r-- | doc/gitian-building.md | 38 | ||||
| -rw-r--r-- | doc/img/bootstrap3.png | bin | 56598 -> 0 bytes | |||
| -rw-r--r-- | doc/release-notes.md | 38 | ||||
| -rw-r--r-- | doc/release-notes/release-notes-0.9.3.md | 101 | ||||
| -rw-r--r-- | doc/release-process.md | 159 | ||||
| -rw-r--r-- | doc/translation_process.md | 136 |
16 files changed, 432 insertions, 415 deletions
diff --git a/doc/Doxyfile b/doc/Doxyfile index e0339e652e..8a11d1e8d0 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -34,7 +34,7 @@ PROJECT_NAME = Bitcoin # This could be handy for archiving the generated documentation or # if some version control system is used. -PROJECT_NUMBER = 0.9.99 +PROJECT_NUMBER = 0.10.99 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer diff --git a/doc/README.md b/doc/README.md index d5d61738e8..b2a0c2dcb7 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,9 +1,6 @@ -Bitcoin 0.9.99 BETA +Bitcoin Core 0.10.99 ===================== -Copyright (c) 2009-2014 Bitcoin Developers - - Setup --------------------- [Bitcoin Core](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. Thankfully you only have to do this once. If you would like the process to go faster you can [download the blockchain directly](bootstrap.md). @@ -51,7 +48,7 @@ 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) +- [Developer Notes](developer-notes.md) - [Multiwallet Qt Development](multiwallet-qt.md) - [Release Notes](release-notes.md) - [Release Process](release-process.md) @@ -71,6 +68,6 @@ The Bitcoin repo's [root README](https://github.com/bitcoin/bitcoin/blob/master/ License --------------------- -Distributed under the [MIT/X11 software license](http://www.opensource.org/licenses/mit-license.php). +Distributed under the [MIT 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](https://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. diff --git a/doc/README_osx.txt b/doc/README_osx.txt index 2be56c1592..6c0c21c190 100644 --- a/doc/README_osx.txt +++ b/doc/README_osx.txt @@ -20,14 +20,6 @@ https://github.com/mingwandroid/toolchain4 In order to build a working toolchain, the following source packages are needed from Apple: cctools, dyld, and ld64. -Beware. This part is ugly. Very very very ugly. In the future, this should be -broken out into a new repository and cleaned up. Additionally, the binaries -only work when built as x86 and not x86_64. This is an especially nasty -limitation because it must be linked with the toolchain's libLTO.so, meaning -that the entire toolchain must be x86. Gitian x86_64 should not be used until -this has been fixed, because it would mean that several native dependencies -(openssl, libuuid, etc) would need to be built as x86 first. - These tools inject timestamps by default, which produce non-deterministic binaries. The ZERO_AR_DATE environment variable is used to disable that. @@ -37,14 +29,15 @@ originally done in toolchain4. To complicate things further, all builds must target an Apple SDK. These SDKs are free to download, but not redistributable. -To obtain it, register for a developer account, then download xcode4630916281a.dmg: -https://developer.apple.com/downloads/download.action?path=Developer_Tools/xcode_4.6.3/xcode4630916281a.dmg +To obtain it, register for a developer account, then download the XCode 6.1.1 dmg: +https://developer.apple.com/downloads/download.action?path=Developer_Tools/xcode_6.1.1/xcode_6.1.1.dmg + This file is several gigabytes in size, but only a single directory inside is -needed: Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk +needed: Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk Unfortunately, the usual linux tools (7zip, hpmount, loopback mount) are incapable of opening this file. To create a tarball suitable for gitian input, mount the dmg in OSX, then create it with: - $ tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.7.sdk.tar.gz MacOSX10.7.sdk + $ tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.9.sdk.tar.gz MacOSX10.9.sdk The gitian descriptors build 2 sets of files: Linux tools, then Apple binaries @@ -73,3 +66,18 @@ Background images and other features can be added to DMG files by inserting a .DS_Store before creation. The easiest way to create this file is to build a DMG without one, move it to a device running OSX, customize the layout, then grab the .DS_Store file for later use. That is the approach taken here. + +As of OSX Mavericks (10.9), using an Apple-blessed key to sign binaries is a +requirement in order to satisfy the new Gatekeeper requirements. Because this +private key cannot be shared, we'll have to be a bit creative in order for the +build process to remain somewhat deterministic. Here's how it works: + +- Builders use gitian to create an unsigned release. This outputs an unsigned + dmg which users may choose to bless and run. It also outputs an unsigned app + structure in the form of a tarball, which also contains all of the tools + that have been previously (deterministically) built in order to create a + final dmg. +- The Apple keyholder uses this unsigned app to create a detached signature, + using the script that is also included there. +- Builders feed the unsigned app + detached signature back into gitian. It + uses the pre-built tools to recombine the pieces into a deterministic dmg. diff --git a/doc/README_windows.txt b/doc/README_windows.txt index 368f2b45e1..c582941696 100644 --- a/doc/README_windows.txt +++ b/doc/README_windows.txt @@ -1,13 +1,5 @@ -Bitcoin 0.9.99 BETA
-
-Copyright (c) 2009-2014 Bitcoin Core 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 (https://www.openssl.org/). This product includes
-cryptographic software written by Eric Young (eay@cryptsoft.com).
-
+Bitcoin Core 0.10.99
+=====================
Intro
-----
diff --git a/doc/REST-interface.md b/doc/REST-interface.md new file mode 100644 index 0000000000..0af650b4e8 --- /dev/null +++ b/doc/REST-interface.md @@ -0,0 +1,27 @@ +Unauthenticated REST Interface +============================== + +The REST API can be enabled with the `-rest` option. + +Supported API +------------- +`GET /rest/tx/TX-HASH.{bin|hex|json}` + +Given a transaction hash, +Returns a transaction, in binary, hex-encoded binary or JSON formats. + +`GET /rest/block/BLOCK-HASH.{bin|hex|json}` +`GET /rest/block/notxdetails/BLOCK-HASH.{bin|hex|json}` + +Given a block hash, +Returns a block, in binary, hex-encoded binary or JSON formats. + +The HTTP request and response are both handled entirely in-memory, thus making maximum memory usage at least 2.66MB (1 MB max block, plus hex encoding) per request. + +With the /notxdetails/ option JSON response will only contain the transaction hash instead of the complete transaction details. The option only affects the JSON response. + +For full TX query capability, one must enable the transaction index via "txindex=1" command line / configuration option. + +Risks +------------- +Running a webbrowser on the same node with a REST enabled bitcoind can be a risk. Accessing prepared XSS websites could read out tx/block data of your node by placing links like `<script src="http://127.0.0.1:1234/tx/json/1234567890">` which might break the nodes privacy.
\ No newline at end of file diff --git a/doc/assets-attribution.md b/doc/assets-attribution.md index cd864f254d..c860cdc534 100644 --- a/doc/assets-attribution.md +++ b/doc/assets-attribution.md @@ -1,103 +1,45 @@ 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](http://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 -* License: You are free to do with these icons as you wish, including selling, copying, modifying etc. -* License: MIT -* Site: [https://bitcointalk.org/index.php?topic=15276.0](https://bitcointalk.org/index.php?topic=15276.0) - -### Assets Used - src/qt/res/icons/transaction*.png - -[Everaldo.com](http://www.everaldo.com) +[Typicons/Stephen Hutchings](http://typicons.com) ----------------------- ### Info -* Icon Pack: Crystal SVG -* Designer: [http://www.everaldo.com](http://www.everaldo.com) -* 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/*.png - -[Vignoni David](http://techbase.kde.org/Projects/Oxygen) ------------------------ - -### Info -* Designer: Vignoni David -* 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. -* Site: [http://techbase.kde.org/Projects/Oxygen](http://techbase.kde.org/Projects/Oxygen) - -### Assets Used - src/qt/res/icons/debugwindow.png +* Icon Pack: Typicons (http://typicons.com) +* Designer: Stephen Hutchings (and more) +* License: CC BY-SA +* Site: [https://github.com/stephenhutchings/typicons.font](https://github.com/stephenhutchings/typicons.font) + +### Assets Used + src/qt/res/icons/add.png, src/qt/res/icons/address-book.png, + src/qt/res/icons/configure.png, src/qt/res/icons/connect4.png, + src/qt/res/icons/debugwindow.png, src/qt/res/icons/edit.png, + src/qt/res/icons/exitcopy.png, src/qt/res/icons/editpaste.png, + src/qt/res/icons/export.png, src/qt/res/icons/eye.png, + src/qt/res/icons/filesave.png, src/qt/res/icons/history.png, + src/qt/res/icons/info.png, src/qt/res/icons/key.png, + src/qt/res/icons/lock_*.png, src/qt/res/icons/open.png, + src/qt/res/icons/overview.png, src/qt/res/icons/quit.png, + src/qt/res/icons/receive.png, src/qt/res/icons/remove.png, + src/qt/res/icons/send.png, src/qt/res/icons/synced.png, + src/qt/res/icons/transaction*.png, src/qt/res/icons/tx_output.png, Jonas Schnelli ----------------------- ### Info -* Designer: Jonas Schnelli (based on the original bitcoin logo from Bitboy) +* Designer: Jonas Schnelli +* Bitcoin Icon: (based on the original bitcoin logo from Bitboy) +* Some icons are based on Stephan Hutchings Typicons (these are under CC BY-SA license) * 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/images/splash.png, src/qt/res/images/splash_testnet.png + src/qt/res/icons/about.png, src/qt/res/icons/about_qt.png, + src/qt/res/icons/bitcoin.icns, src/qt/res/icons/bitcoin.ico, + src/qt/res/icons/bitcoin.png, src/qt/res/icons/clock*.png, + src/qt/res/icons/connect[0-3].png, src/qt/res/icons/eye_minus.png, + src/qt/res/icons/eye_plus.png, src/qt/res/icons/verify.png, + src/qt/res/icons/tx_inout.png, src/qt/res/icons/tx_input.png, + src/qt/res/src/verify.svg, src/qt/res/src/bitcoin.svg, + src/qt/res/src/clock*.svg, src/qt/res/src/connect*.svg, + src/qt/res/src/mine.svg, src/qt/res/src/qt.svg, src/qt/res/src/tx*.svg, + src/qt/res/src/verify.svg, diff --git a/doc/bootstrap.md b/doc/bootstrap.md index 7ce71abaad..b84fd24b11 100644 --- a/doc/bootstrap.md +++ b/doc/bootstrap.md @@ -1,41 +1,31 @@ ### Bootstrap the Blockchain Synchronization -Normally the Bitcoin client will download the transaction and network information, called the blockchain, from the network by syncing with the other clients. This can be a process that can take multiple days as the [Bitcoin block chain](https://blockchain.info/charts/blocks-size) has grown to more than 15 gigabytes, and is growing almost a gigabyte every month. Luckily there is a safe and fast way to speed up this process. We’ll show you how to bootstrap your blockchain to bring your client up to speed in just a few simple steps. +Normally the Bitcoin client will download the transaction and network information, called the blockchain, from the network by syncing with the other clients. This process can take quite some time as the [Bitcoin blockchain](https://blockchain.info/charts/blocks-size) is growing bigger and bigger for each day. Luckily there is a safe and fast way to speed up this process. We'll show you how to bootstrap your blockchain to bring your client up to speed in just a few simple steps. ### Requirements - A fresh install of the Bitcoin client software. -### Download the blockchain via Bittorent +### Download the blockchain via BitTorrent -Jeff Garzik, Bitcoin core developer, offers an [torrent file](https://bitcointalk.org/index.php?topic=145386.0) for bootstrapping purposes that is updated often. Bittorrent is a protocol that speeds up the downloading of large files by using the other clients in the network. Examples of free and safe open-source clients are [Deluge](http://deluge-torrent.org/) or [QBittorent](http://www.qbittorrent.org/). A guide to installing and configuring the torrent clients can be found [here](http://dev.deluge-torrent.org/wiki/UserGuide) for Deluge and [here](http://qbforums.shiki.hu/) for QBittorent. A further in-depth tutorial on Bittorent can be found [here](http://www.howtogeek.com/howto/31846/bittorrent-for-beginners-how-get-started-downloading-torrents/). +Jeff Garzik, Bitcoin Core developer, offers an [torrent file](https://bitcointalk.org/index.php?topic=145386.0) for bootstrapping purposes that is updated often. BitTorrent is a protocol that speeds up the downloading of large files by using the other clients in the network. Examples of free and safe open source clients are [Deluge](http://deluge-torrent.org/) or [qBittorrent](http://www.qbittorrent.org/). A guide to installing and configuring the torrent clients can be found [here](http://dev.deluge-torrent.org/wiki/UserGuide) for Deluge and [here](http://qbforums.shiki.hu/) for qBittorrent. A further in-depth tutorial on BitTorrent can be found [here](http://www.howtogeek.com/howto/31846/bittorrent-for-beginners-how-get-started-downloading-torrents/). -With the client installed we’ll proceed to download the blockchain torrent file. Use the following magnet link: +With the client installed we'll proceed to download the blockchain torrent file. Use the following magnet link: magnet:?xt=urn:btih:2d4e6c1f96c5d5fb260dff92aea4e600227f1aea&dn=bootstrap.dat&tr=udp://tracker.openbittorrent.com:80&tr=udp://tracker.publicbt.com:80&tr=udp://tracker.ccc.de:80&tr=udp://tracker.istole.it:80 - or go to [Jeff Garzik's topic](https://bitcointalk.org/index.php?topic=145386.0) for a signed magnet link. Alternately you can use the [.torrent file](http://sourceforge.net/projects/bitcoin/files/Bitcoin/blockchain/bootstrap.dat.torrent/download) found on Sourceforge. + or go to [Jeff Garzik's topic](https://bitcointalk.org/index.php?topic=145386.0) for a signed magnet link. Alternatively you can use the [.torrent file](http://sourceforge.net/projects/bitcoin/files/Bitcoin/blockchain/bootstrap.dat.torrent/download) found on SourceForge.  The download page should look like this, with a countdown to the download. If it does not work click the direct download link. -The torrent client installed will recognize the download of the torrent file. Save the bootstrap.dat file to a folder you use for downloads. The image below shows the torrent download in QBittorent, with current speed and ETA highlighted. +The torrent client installed will recognize the download of the torrent file. Save the bootstrap.dat file to the folder you use for downloads. The image below shows the torrent download in qBittorrent, with current speed and ETA highlighted.  -### Download the block chain directly from official repositories -The Bittorent version, see above, of the block chain download is refreshed more often than the direct download available. If Bittorent is blocked on your network then you can use the direct download method. Be sure to only use official repositories as the link displayed below. This download will only update the client to March 2013. - -Click [here](http://sourceforge.net/projects/bitcoin/files/Bitcoin/blockchain/bitcoin_blockchain_170000.zip/download) to download or copy and paste the link below. - - http://sourceforge.net/projects/bitcoin/files/Bitcoin/blockchain/bitcoin_blockchain_170000.zip/download - -The download page should look like this, with a countdown to the download. If it does not work directly click the download. Save the file to a folder you use for downloads. - - ### Importing the blockchain -Exit the Bitcoin Client software if you have it running. Be sure not to have an actively used wallet in use. We are going to copy the download of the blockchain to the Bitcoin client data directory. You should run the client software at least once so it can generate the data directory. Copy the downloaded bootstrap.dat file into the Bitcoin data folder. +Exit the Bitcoin client software if you have it running. Be sure not to have an actively used wallet in use. We are going to copy the download of the blockchain to the Bitcoin client data directory. You should run the client software at least once so it can generate the data directory. Copy the downloaded bootstrap.dat file into the Bitcoin data folder. **For Windows users:** Open explorer, and type into the address bar: @@ -63,4 +53,4 @@ Wait until the import finishes. The client will download the last days not cover ### Is this safe? -Yes, the above method is safe. The download contains only raw block chain data and the client verifies this on import. Do not download the blockchain from unofficial sources, especially if they provide `*.rev` and `*.sst` files. These files are not verified and can contain malicious edits. +Yes, the above method is safe. The download contains only raw blockchain data and the client verifies this on import. Do not download the blockchain from unofficial sources, especially if they provide `*.rev` and `*.sst` files. These files are not verified and can contain malicious edits. diff --git a/doc/build-osx.md b/doc/build-osx.md index dc55f8259e..d6e93cb23d 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -5,8 +5,7 @@ This guide will show you how to build bitcoind(headless client) for OSX. Notes ----- -* Tested on OS X 10.6 through 10.9 on 64-bit Intel processors only. -Older OSX releases or 32-bit processors are no longer supported. +* Tested on OS X 10.7 through 10.10 on 64-bit Intel processors only. * All of the commands should be executed in a Terminal application. The built-in one is located in `/Applications/Utilities`. @@ -22,12 +21,6 @@ Xcode 4.3 or later, you'll need to install its command line tools. This can be done in `Xcode > Preferences > Downloads > Components` and generally must be re-done or updated every time Xcode is updated. -There's also an assumption that you already have `git` installed. If -not, it's the path of least resistance to install [Github for Mac](https://mac.github.com/) -(OS X 10.7+) or -[Git for OS X](https://code.google.com/p/git-osx-installer/). It is also -available via Homebrew. - You will also need to install [Homebrew](http://brew.sh) in order to install library dependencies. @@ -39,7 +32,9 @@ Instructions: Homebrew #### Install dependencies using Homebrew - brew install autoconf automake libtool boost miniupnpc openssl pkg-config protobuf qt + brew install autoconf automake libtool boost miniupnpc openssl pkg-config protobuf qt5 + +NOTE: Building with Qt4 is still supported, however, could result in a broken UI. As such, building with Qt5 is recommended. #### Installing berkeley-db4 using Homebrew @@ -47,7 +42,7 @@ The homebrew package for berkeley-db4 has been broken for some time. It will in Running this command takes you into brew's interactive mode, which allows you to configure, make, and install by hand: ``` -$ brew install https://raw.github.com/mxcl/homebrew/master/Library/Formula/berkeley-db4.rb -–without-java +$ brew install https://raw.github.com/homebrew/homebrew/master/Library/Formula/berkeley-db4.rb -–without-java ``` The rest of these commands are run inside brew interactive mode: @@ -74,7 +69,7 @@ After exiting, you'll get a warning that the install is keg-only, which means it 2. Build bitcoind: ./autogen.sh - ./configure + ./configure --with-gui=qt5 make 3. It is also a good idea to build and run the unit tests: @@ -85,6 +80,22 @@ After exiting, you'll get a warning that the install is keg-only, which means it make install +Use Qt Creator as IDE +------------------------ +You can use Qt Creator as IDE, for debugging and for manipulating forms, etc. +Download Qt Creator from http://www.qt.io/download/. Download the "community edition" and only install Qt Creator (uncheck the rest during the installation process). + +1. Make sure you installed everything through homebrew mentioned above +2. Do a proper ./configure --with-gui=qt5 --enable-debug +3. In Qt Creator do "New Project" -> Import Project -> Import Existing Project +4. Enter "bitcoin-qt" as project name, enter src/qt as location +5. Leave the file selection as it is +6. Confirm the "summary page" +7. In the "Projects" tab select "Manage Kits..." +8. Select the default "Desktop" kit and select "Clang (x86 64bit in /usr/bin)" as compiler +9. Select LLDB as debugger (you might need to set the path to your installtion) +10. Start debugging with Qt Creator + Creating a release build ------------------------ You can ignore this section if you are building `bitcoind` for your own use. @@ -96,11 +107,11 @@ as follows for maximum compatibility: All dependencies should be compiled with these flags: - -mmacosx-version-min=10.6 + -mmacosx-version-min=10.7 -arch x86_64 - -isysroot $(xcode-select --print-path)/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.6.sdk + -isysroot $(xcode-select --print-path)/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk -Once dependencies are compiled, see release-process.md for how the Bitcoin-Qt.app +Once dependencies are compiled, see [doc/release-process.md](release-process.md) for how the Bitcoin-Qt.app bundle is packaged and signed to create the .dmg disk image that is distributed. Running diff --git a/doc/build-unix.md b/doc/build-unix.md index fb5eaec431..8ddee3b757 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -27,31 +27,24 @@ This will build bitcoin-qt as well if the dependencies are met. Dependencies --------------------- +These dependencies are required: + Library | Purpose | Description ------------|------------------|---------------------- libssl | SSL Support | Secure communications - libdb4.8 | Berkeley DB | 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. See the configure options for upnp behavior desired: - --without-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 +Optional dependencies: -Licenses of statically linked libraries: - 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 + Library | Purpose | Description + ------------|------------------|---------------------- + miniupnpc | UPnP Support | Firewall-jumping support + libdb4.8 | Berkeley DB | Wallet storage (only needed when wallet enabled) + qt | GUI | GUI toolkit (only needed when GUI enabled) + protobuf | Payments in GUI | Data interchange format used for payment protocol (only needed when GUI enabled) + libqrencode | QR codes in GUI | Optional for generating QR codes (only needed when GUI enabled) -- For the versions used in the release, see doc/release-process.md under *Fetch and build inputs*. +For the versions used in the release, see [release-process.md](release-process.md) under *Fetch and build inputs*. System requirements -------------------- @@ -112,7 +105,7 @@ To build with Qt 4 you need the following: For Qt 5 you need the following: - sudo apt-get install libqt5gui5 libqt5core5 libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler + sudo apt-get install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler libqrencode (optional) can be installed with: @@ -129,6 +122,17 @@ symbols, which reduces the executable size by about 90%. miniupnpc --------- + +[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. See the configure options for upnp behavior desired: + + --without-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 + +To build: + tar -xzvf miniupnpc-1.6.tar.gz cd miniupnpc-1.6 make diff --git a/doc/coding.md b/doc/developer-notes.md index ceed8c18b4..eaeb90da1d 100644 --- a/doc/coding.md +++ b/doc/developer-notes.md @@ -12,20 +12,6 @@ gradually. - No indentation for public/protected/private or for namespaces. - No extra spaces inside parenthesis; don't do ( this ) - No space after function names; one space after if, for and while. -- Includes need to be ordered alphabetically, separate own and foreign headers with a new-line (example key.cpp): -```c++ -#include "key.h" - -#include "crypto/sha2.h" -#include "util.h" - -#include <openssl/foo.h> -``` -- Class or struct keywords in header files need to be ordered alphabetically: -```c++ -class CAlpha; -class CBeta; -``` Block style example: ```c++ @@ -103,6 +89,41 @@ Not OK (used plenty in the current source, but not picked up): A full list of comment syntaxes picked up by doxygen can be found at http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html, but if possible use one of the above styles. +Development tips and tricks +--------------------------- + +**compiling for debugging** + +Run configure with the --enable-debug option, then make. Or run configure with +CXXFLAGS="-g -ggdb -O0" or whatever debug flags you need. + +**debug.log** + +If the code is behaving strangely, take a look in the debug.log file in the data directory; +error and debugging messages are written there. + +The -debug=... command-line option controls debugging; running with just -debug will turn +on all categories (and give you a very large debug.log file). + +The Qt code routes qDebug() output to debug.log under category "qt": run with -debug=qt +to see it. + +**testnet and regtest modes** + +Run with the -testnet option to run with "play bitcoins" on the test network, if you +are testing multi-machine code that needs to operate across the internet. + +If you are testing something that can run on one machine, run with the -regtest option. +In regression test mode, blocks can be created on-demand; see qa/rpc-tests/ for tests +that run in -regtest mode. + +**DEBUG_LOCKORDER** + +Bitcoin Core is a multithreaded application, and deadlocks or other multithreading bugs +can be very difficult to track down. Compiling with -DDEBUG_LOCKORDER (configure +CXXFLAGS="-DDEBUG_LOCKORDER -g") inserts run-time checks to keep track of which locks +are held, and adds warnings to the debug.log file if inconsistencies are detected. + Locking/mutex usage notes ------------------------- @@ -129,8 +150,6 @@ Threads - StartNode : Starts other threads. -- ThreadGetMyExternalIP : Determines outside-the-firewall IP address, sends addr message to connected peers when it determines it. - - ThreadDNSAddressSeed : Loads addresses of peers from the DNS. - ThreadMapPort : Universal plug-and-play startup/shutdown @@ -152,3 +171,16 @@ Threads - BitcoinMiner : Generates bitcoins (if wallet is enabled). - Shutdown : Does an orderly shutdown of everything. + +Pull Request Terminology +------------------------ + +Concept ACK - Agree with the idea and overall direction, but haven't reviewed the code changes or tested them. + +utACK (untested ACK) - Reviewed and agree with the code changes but haven't actually tested them. + +Tested ACK - Reviewed the code changes and have verified the functionality or bug fix. + +ACK - A loose ACK can be confusing. It's best to avoid them unless it's a documentation/comment only change in which case there is nothing to test/verify; therefore the tested/untested distinction is not there. + +NACK - Disagree with the code changes/concept. Should be accompanied by an explanation. diff --git a/doc/gitian-building.md b/doc/gitian-building.md index b356a5d88d..1312979cac 100644 --- a/doc/gitian-building.md +++ b/doc/gitian-building.md @@ -83,7 +83,7 @@ Unixy OSes by entering the following in a terminal: After creating the VM, we need to configure it. -- Click the `Settings` button, then go to the `Network` tab. Adapter 1 should be attacked to `NAT`. +- Click the `Settings` button, then go to the `Network` tab. Adapter 1 should be attached to `NAT`.  @@ -291,7 +291,7 @@ Setting up gitian images ------------------------- Gitian needs virtual images of the operating system to build in. -Currently this is Ubuntu Precise for both x86 architectures. +Currently this is Ubuntu Precise for x86_64. These images will be copied and used every time that a build is started to make sure that the build is deterministic. Creating the images will take a while, but only has to be done once. @@ -300,7 +300,6 @@ Execute the following as user `debian`: ```bash cd gitian-builder -bin/make-base-vm --lxc --arch i386 --suite precise bin/make-base-vm --lxc --arch amd64 --suite precise ``` @@ -311,33 +310,25 @@ There will be a lot of warnings printed during build of the images. These can be Getting and building the inputs -------------------------------- -In [doc/release-process.md](release-process.md) in the bitcoin repository under 'Fetch and build inputs'. -you will find a list of `wget` commands that can be executed to get the dependencies. +Follow the instructions in [doc/release-process.md](release-process.md) in the bitcoin repository +under 'Fetch and build inputs' to install sources which require manual intervention. Also follow +the next step: 'Seed the Gitian sources cache', which will fetch all necessary source files allowing +for gitian to work offline. -I needed to add `--no-check-certificate` to the OpenSSL wget line to make it work. -Likely this is because the ca-certificates in Debian 7.4 is fairly old. This does not create a -security issue as the gitian descriptors check the integrity of the input archives and refuse to work -if any one is corrupted. +Building Bitcoin +---------------- -After downloading the archives, execute the `gbuild` commands to build the dependencies. -This can take a long time, but only has to be done when the dependencies change, for example -to upgrade the used version. +To build Bitcoin (for Linux, OSX and Windows) just follow the steps under 'perform +gitian builds' in [doc/release-process.md](release-process.md) in the bitcoin repository. -**Note**: Do not forget to copy the result from `build/out` to `inputs` after every gbuild command! This will save -you a lot of time. +This may take a long time as it also builds the dependencies needed for each descriptor. +These dependencies will be cached after a successful build to avoid rebuilding them when possible. At any time you can check the package installation and build progress with ```bash tail -f var/install.log tail -f var/build.log -``` - -Building Bitcoin ----------------- - -To build Bitcoin (for Linux, OSX and Windows) just follow the steps under 'perform -gitian builds' in [doc/release-process.md](release-process.md) in the bitcoin repository. Output from `gbuild` will look something like @@ -348,7 +339,7 @@ Output from `gbuild` will look something like Resolving deltas: 100% (25724/25724), done. From https://github.com/bitcoin/bitcoin ... (new tags, new branch etc) - --- Building for precise i386 --- + --- Building for precise x86_64 --- Stopping target if it is up Making a new image copy stdin: is not a tty @@ -363,9 +354,6 @@ Output from `gbuild` will look something like lxc-start: Connection refused - inotify event with no name (mask 32768) Running build script (log in var/build.log) -As when building the dependencies, the progress of package installation and building -can be inspected in `var/install.log` and `var/build.log`. - Building an alternative repository ----------------------------------- diff --git a/doc/img/bootstrap3.png b/doc/img/bootstrap3.png Binary files differdeleted file mode 100644 index 8a6754e3e0..0000000000 --- a/doc/img/bootstrap3.png +++ /dev/null diff --git a/doc/release-notes.md b/doc/release-notes.md index 967a39a0e7..1cb517e5c7 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -1,41 +1,3 @@ (note: this is a temporary file, to be added-to by anybody, and moved to release-notes at release time) -Transaction fee changes -======================= - -This release automatically estimates how high a transaction fee (or how -high a priority) transactions require to be confirmed quickly. The default -settings will create transactions that confirm quickly; see the new -'txconfirmtarget' setting to control the tradeoff between fees and -confirmation times. - -Prior releases used hard-coded fees (and priorities), and would -sometimes create transactions that took a very long time to confirm. - - -New Command Line Options -======================== - --txconfirmtarget=n : create transactions that have enough fees (or priority) -so they are likely to confirm within n blocks (default: 1). This setting -is over-ridden by the -paytxfee option. - -New RPC methods -=============== - -Fee/Priority estimation ------------------------ - -estimatefee nblocks : Returns approximate fee-per-1,000-bytes needed for -a transaction to be confirmed within nblocks. Returns -1 if not enough -transactions have been observed to compute a good estimate. - -estimatepriority nblocks : Returns approximate priority needed for -a zero-fee transaction to confirm within nblocks. Returns -1 if not -enough free transactions have been observed to compute a good -estimate. - -Statistics used to estimate fees and priorities are saved in the -data directory in the 'fee_estimates.dat' file just before -program shutdown, and are read in at startup. diff --git a/doc/release-notes/release-notes-0.9.3.md b/doc/release-notes/release-notes-0.9.3.md new file mode 100644 index 0000000000..0765a360b2 --- /dev/null +++ b/doc/release-notes/release-notes-0.9.3.md @@ -0,0 +1,101 @@ +Bitcoin Core version 0.9.3 is now available from: + + https://bitcoin.org/bin/0.9.3/ + +This is a new minor version release, bringing only bug fixes and updated +translations. Upgrading to this release is recommended. + +Please report bugs using the issue tracker at github: + + https://github.com/bitcoin/bitcoin/issues + +Upgrading and downgrading +========================== + +How to Upgrade +-------------- + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes for older versions), then run the +installer (on Windows) or just copy over /Applications/Bitcoin-Qt (on Mac) or +bitcoind/bitcoin-qt (on Linux). + +If you are upgrading from version 0.7.2 or earlier, the first time you run +0.9.3 your blockchain files will be re-indexed, which will take anywhere from +30 minutes to several hours, depending on the speed of your machine. + +Downgrading warnings +-------------------- + +The 'chainstate' for this release is not always compatible with previous +releases, so if you run 0.9.x and then decide to switch back to a +0.8.x release you might get a blockchain validation error when starting the +old release (due to 'pruned outputs' being omitted from the index of +unspent transaction outputs). + +Running the old release with the -reindex option will rebuild the chainstate +data structures and correct the problem. + +Also, the first time you run a 0.8.x release on a 0.9 wallet it will rescan +the blockchain for missing spent coins, which will take a long time (tens +of minutes on a typical machine). + +0.9.3 Release notes +======================= + +RPC: +- Avoid a segfault on getblock if it can't read a block from disk +- Add paranoid return value checks in base58 + +Protocol and network code: +- Don't poll showmyip.com, it doesn't exist anymore +- Add a way to limit deserialized string lengths and use it +- Add a new checkpoint at block 295,000 +- Increase IsStandard() scriptSig length +- Avoid querying DNS seeds, if we have open connections +- Remove a useless millisleep in socket handler +- Stricter memory limits on CNode +- Better orphan transaction handling +- Add `-maxorphantx=<n>` and `-maxorphanblocks=<n>` options for control over the maximum orphan transactions and blocks + +Wallet: +- Check redeemScript size does not exceed 520 byte limit +- Ignore (and warn about) too-long redeemScripts while loading wallet + +GUI: +- fix 'opens in testnet mode when presented with a BIP-72 link with no fallback' +- AvailableCoins: acquire cs_main mutex +- Fix unicode character display on MacOSX + +Miscellaneous: +- key.cpp: fail with a friendlier message on missing ssl EC support +- Remove bignum dependency for scripts +- Upgrade OpenSSL to 1.0.1i (see https://www.openssl.org/news/secadv_20140806.txt - just to be sure, no critical issues for Bitcoin Core) +- Upgrade miniupnpc to 1.9.20140701 +- Fix boost detection in build system on some platforms + +Credits +-------- + +Thanks to everyone who contributed to this release: + +- Andrew Poelstra +- Cory Fields +- Gavin Andresen +- Jeff Garzik +- Johnathan Corgan +- Julian Haight +- Michael Ford +- Pavel Vasin +- Peter Todd +- phantomcircuit +- Pieter Wuille +- Rose Toomey +- Ruben Dario Ponticelli +- shshshsh +- Trevin Hofmann +- Warren Togami +- Wladimir J. van der Laan +- Zak Wilcox + +As well as everyone that helped translating on [Transifex](https://www.transifex.com/projects/p/bitcoin/). diff --git a/doc/release-process.md b/doc/release-process.md index 7699af90bd..363465d827 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -23,6 +23,10 @@ Release Process * * * +###update gitian + + In order to take advantage of the new caching features in gitian, be sure to update to a recent version (e9741525c or higher is recommended) + ###perform gitian builds From a directory containing the bitcoin source, gitian-builder and gitian.sigs @@ -36,136 +40,75 @@ Release Process ###fetch and build inputs: (first time, or when dependency versions change) - mkdir -p inputs; cd inputs/ + mkdir -p inputs Register and download the Apple SDK: (see OSX Readme for details) - https://developer.apple.com/downloads/download.action?path=Developer_Tools/xcode_4.6.3/xcode4630916281a.dmg + https://developer.apple.com/downloads/download.action?path=Developer_Tools/xcode_6.1.1/xcode_6.1.1.dmg - Using a Mac, create a tarball for the 10.7 SDK and copy it to the inputs directory: + Using a Mac, create a tarball for the 10.9 SDK and copy it to the inputs directory: - tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.7.sdk.tar.gz MacOSX10.7.sdk + tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.9.sdk.tar.gz MacOSX10.9.sdk - Download remaining inputs, and build everything: - - wget 'http://miniupnp.free.fr/files/download.php?file=miniupnpc-1.9.tar.gz' -O miniupnpc-1.9.tar.gz - wget 'https://www.openssl.org/source/openssl-1.0.1h.tar.gz' - wget 'http://download.oracle.com/berkeley-db/db-4.8.30.NC.tar.gz' - wget 'http://zlib.net/zlib-1.2.8.tar.gz' - wget 'ftp://ftp.simplesystems.org/pub/png/src/history/libpng16/libpng-1.6.8.tar.gz' - wget 'https://fukuchi.org/works/qrencode/qrencode-3.4.3.tar.bz2' - wget 'https://downloads.sourceforge.net/project/boost/boost/1.55.0/boost_1_55_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/official_releases/qt/5.2/5.2.0/single/qt-everywhere-opensource-src-5.2.0.tar.gz' - wget 'https://download.qt-project.org/official_releases/qt/5.2/5.2.1/single/qt-everywhere-opensource-src-5.2.1.tar.gz' - wget 'https://download.qt-project.org/archive/qt/4.6/qt-everywhere-opensource-src-4.6.4.tar.gz' - wget 'https://protobuf.googlecode.com/files/protobuf-2.5.0.tar.bz2' - wget 'https://github.com/mingwandroid/toolchain4/archive/10cc648683617cca8bcbeae507888099b41b530c.tar.gz' - wget 'http://www.opensource.apple.com/tarballs/cctools/cctools-809.tar.gz' - wget 'http://www.opensource.apple.com/tarballs/dyld/dyld-195.5.tar.gz' - wget 'http://www.opensource.apple.com/tarballs/ld64/ld64-127.2.tar.gz' - wget 'http://pkgs.fedoraproject.org/repo/pkgs/cdrkit/cdrkit-1.1.11.tar.gz/efe08e2f3ca478486037b053acd512e9/cdrkit-1.1.11.tar.gz' - wget 'https://github.com/theuni/libdmg-hfsplus/archive/libdmg-hfsplus-v0.1.tar.gz' - wget 'http://llvm.org/releases/3.2/clang+llvm-3.2-x86-linux-ubuntu-12.04.tar.gz' -O clang-llvm-3.2-x86-linux-ubuntu-12.04.tar.gz - wget 'https://raw.githubusercontent.com/theuni/osx-cross-depends/master/patches/cdrtools/genisoimage.diff' -O cdrkit-deterministic.patch - cd .. - ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/boost-linux.yml - mv build/out/boost-*.zip inputs/ - ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/deps-linux.yml - mv build/out/bitcoin-deps-*.zip inputs/ - ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/qt-linux.yml - mv build/out/qt-*.tar.gz inputs/ - ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/boost-win.yml - mv build/out/boost-*.zip inputs/ - ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/deps-win.yml - mv build/out/bitcoin-deps-*.zip inputs/ - ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/qt-win.yml - mv build/out/qt-*.zip inputs/ - ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/protobuf-win.yml - mv build/out/protobuf-*.zip inputs/ - ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/gitian-osx-native.yml - mv build/out/osx-*.tar.gz inputs/ - ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/gitian-osx-depends.yml - mv build/out/osx-*.tar.gz inputs/ - ./bin/gbuild ../bitcoin/contrib/gitian-descriptors/gitian-osx-qt.yml - mv build/out/osx-*.tar.gz inputs/ - - The expected SHA256 hashes of the intermediate inputs are: - - f29b7d9577417333fb56e023c2977f5726a7c297f320b175a4108cf7cd4c2d29 boost-linux32-1.55.0-gitian-r1.zip - 88232451c4104f7eb16e469ac6474fd1231bd485687253f7b2bdf46c0781d535 boost-linux64-1.55.0-gitian-r1.zip - 46710f673467e367738d8806e45b4cb5931aaeea61f4b6b55a68eea56d5006c5 bitcoin-deps-linux32-gitian-r6.zip - f03be39fb26670243d3a659e64d18e19d03dec5c11e9912011107768390b5268 bitcoin-deps-linux64-gitian-r6.zip - 57e57dbdadc818cd270e7e00500a5e1085b3bcbdef69a885f0fb7573a8d987e1 qt-linux32-4.6.4-gitian-r1.tar.gz - 60eb4b9c5779580b7d66529efa5b2836ba1a70edde2a0f3f696d647906a826be qt-linux64-4.6.4-gitian-r1.tar.gz - 60dc2d3b61e9c7d5dbe2f90d5955772ad748a47918ff2d8b74e8db9b1b91c909 boost-win32-1.55.0-gitian-r6.zip - f65fcaf346bc7b73bc8db3a8614f4f6bee2f61fcbe495e9881133a7c2612a167 boost-win64-1.55.0-gitian-r6.zip - 70de248cd0dd7e7476194129e818402e974ca9c5751cbf591644dc9f332d3b59 bitcoin-deps-win32-gitian-r13.zip - 9eace4c76f639f4f3580a478eee4f50246e1bbb5ccdcf37a158261a5a3fa3e65 bitcoin-deps-win64-gitian-r13.zip - 963e3e5e85879010a91143c90a711a5d1d5aba992e38672cdf7b54e42c56b2f1 qt-win32-5.2.0-gitian-r3.zip - 751c579830d173ef3e6f194e83d18b92ebef6df03289db13ab77a52b6bc86ef0 qt-win64-5.2.0-gitian-r3.zip - e2e403e1a08869c7eed4d4293bce13d51ec6a63592918b90ae215a0eceb44cb4 protobuf-win32-2.5.0-gitian-r4.zip - a0999037e8b0ef9ade13efd88fee261ba401f5ca910068b7e0cd3262ba667db0 protobuf-win64-2.5.0-gitian-r4.zip - 512bc0622c883e2e0f4cbc3fedfd8c2402d06c004ce6fb32303cc2a6f405b6df osx-native-depends-r3.tar.gz - 927e4b222be6d590b4bc2fc185872a5d0ca5c322adb983764d3ed84be6bdbc81 osx-depends-r4.tar.gz - ec95abef1df2b096a970359787c01d8c45e2a4475b7ae34e12c022634fbdba8a osx-depends-qt-5.2.1-r4.tar.gz - - - Build Bitcoin Core for Linux, Windows, and OS X: +###Optional: Seed the Gitian sources cache + + By default, gitian will fetch source files as needed. For offline builds, they can be fetched ahead of time: + + make -C ../bitcoin/depends download SOURCES_PATH=`pwd`/cache/common + + Only missing files will be fetched, so this is safe to re-run for each build. + +###Build Bitcoin Core for Linux, Windows, and OS X: ./bin/gbuild --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml ./bin/gsign --signer $SIGNER --release ${VERSION}-linux --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml - pushd build/out - zip -r bitcoin-${VERSION}-linux-gitian.zip * - mv bitcoin-${VERSION}-linux-gitian.zip ../../../ - popd + mv build/out/bitcoin-*.tar.gz build/out/src/bitcoin-*.tar.gz ../ ./bin/gbuild --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-win.yml ./bin/gsign --signer $SIGNER --release ${VERSION}-win --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-win.yml - pushd build/out - zip -r bitcoin-${VERSION}-win-gitian.zip * - mv bitcoin-${VERSION}-win-gitian.zip ../../../ - popd - ./bin/gbuild --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx-bitcoin.yml - ./bin/gsign --signer $SIGNER --release ${VERSION}-osx --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx-bitcoin.yml - pushd build/out - mv Bitcoin-Qt.dmg ../../../ + mv build/out/bitcoin-*.zip build/out/bitcoin-*.exe ../ + ./bin/gbuild --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml + ./bin/gsign --signer $SIGNER --release ${VERSION}-osx-unsigned --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml + mv build/out/bitcoin-*-unsigned.tar.gz inputs/bitcoin-osx-unsigned.tar.gz + mv build/out/bitcoin-*.tar.gz build/out/bitcoin-*.dmg ../ popd - popd - Build output expected: - 1. linux 32-bit and 64-bit binaries + source (bitcoin-${VERSION}-linux-gitian.zip) - 2. windows 32-bit and 64-bit binaries + installer + source (bitcoin-${VERSION}-win-gitian.zip) - 3. OSX installer (Bitcoin-Qt.dmg) - 4. Gitian signatures (in gitian.sigs/${VERSION}-<linux|win|osx>/(your gitian key)/ + 1. source tarball (bitcoin-${VERSION}.tar.gz) + 2. linux 32-bit and 64-bit binaries dist tarballs (bitcoin-${VERSION}-linux[32|64].tar.gz) + 3. windows 32-bit and 64-bit installers and dist zips (bitcoin-${VERSION}-win[32|64]-setup.exe, bitcoin-${VERSION}-win[32|64].zip) + 4. OSX unsigned installer (bitcoin-${VERSION}-osx-unsigned.dmg) + 5. Gitian signatures (in gitian.sigs/${VERSION}-<linux|win|osx-unsigned>/(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 +###Next steps: -**Windows .zip and setup.exe:** +Commit your signature to gitian.sigs: - unzip bitcoin-${VERSION}-win-gitian.zip -d bitcoin-${VERSION}-win - mv bitcoin-${VERSION}-win/bitcoin-*-setup.exe . - zip -r bitcoin-${VERSION}-win.zip bitcoin-${VERSION}-win - rm -rf bitcoin-${VERSION}-win + pushd gitian.sigs + git add ${VERSION}-linux/${SIGNER} + git add ${VERSION}-win/${SIGNER} + git add ${VERSION}-osx-unsigned/${SIGNER} + git commit -a + git push # Assuming you can push to the gitian.sigs tree + popd -**Mac OS X .dmg:** + Wait for OSX detached signature: + Once the OSX build has 3 matching signatures, Gavin will sign it with the apple App-Store key. + He will then upload a detached signature to be combined with the unsigned app to create a signed binary. - mv Bitcoin-Qt.dmg bitcoin-${VERSION}-osx.dmg + Create the signed OSX binary: -###Next steps: + pushd ./gitian-builder + # Fetch the signature as instructed by Gavin + cp signature.tar.gz inputs/ + ./bin/gbuild -i ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml + ./bin/gsign --signer $SIGNER --release ${VERSION}-osx-signed --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml + mv build/out/bitcoin-osx-signed.dmg ../bitcoin-${VERSION}-osx.dmg + popd -Commit your signature to gitian.sigs: +Commit your signature for the signed OSX binary: pushd gitian.sigs - git add ${VERSION}-linux/${SIGNER} - git add ${VERSION}-win/${SIGNER} - git add ${VERSION}-osx/${SIGNER} + git add ${VERSION}-osx-signed/${SIGNER} git commit -a git push # Assuming you can push to the gitian.sigs tree popd @@ -178,8 +121,6 @@ Commit your signature to gitian.sigs: - Code-sign Windows -setup.exe (in a Windows virtual machine using signtool) - - Code-sign MacOSX .dmg - Note: only Gavin has the code-signing keys currently. - Create `SHA256SUMS.asc` for the builds, and GPG-sign it: diff --git a/doc/translation_process.md b/doc/translation_process.md index 9475b1dc72..eed467706e 100644 --- a/doc/translation_process.md +++ b/doc/translation_process.md @@ -1,89 +1,111 @@ Translations ============ -The Bitcoin Core GUI can be easily translated into other languages. Here's how we -handle those translations. +The Bitcoin-Core project has been designed to support multiple localisations. This makes adding new phrases, and completely new languages easily achievable. For managing all application translations, Bitcoin-Core makes use of the Transifex online translation management tool. -Files and Folders ------------------ +### Helping to translate (using Transifex) +Transifex is setup to monitor the Github repo for updates, and when code containing new translations is found, Transifex will process any changes. It may take several hours after a pull-request has been merged, to appear in the Transifex web interface. -### bitcoin-qt.pro +Multiple language support is critical in assisting Bitcoin’s global adoption, and growth. One of Bitcoin’s greatest strengths is cross-boarder money transfers, any help making that easier is greatly appreciated. -This file takes care of generating `.qm` files from `.ts` files. It is mostly -automated. +See the [Transifex Bitcoin project](https://www.transifex.com/projects/p/bitcoin/) to assist in translations. You should also join the translation mailing list for announcements - see details below. -### src/qt/bitcoin.qrc +### Writing code with translations +We use automated scripts to help extract translations in both Qt, and non-Qt source files. It is rarely necessary to manually edit the files in `src/qt/locale/`. The translation source files must adhere to the following format: +`bitcoin_xx_YY.ts or bitcoin_xx.ts` -This file must be updated whenever a new translation is added. Please note that -files must end with `.qm`, not `.ts`. +`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 source code is changed, 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). Once this has been updated, `lupdate` (included in the Qt SDK) is used to update `bitcoin_en.ts`. -```xml -<qresource prefix="/translations"> - <file alias="en">locale/bitcoin_en.qm</file> - ... -</qresource> +To automatically regenerate the `bitcoin_en.ts` file, run the following commands: +```sh +cd src/ +make translate ``` -### src/qt/locale/ +`contrib/bitcoin-qt.pro` takes care of generating `.qm` (binary compiled) files from `.ts` (source files) files. It’s mostly automated, and you shouldn’t need to worry about it. -This directory contains all translations. Filenames must adhere to this format: +**Example Qt translation** +```cpp +QToolBar *toolbar = addToolBar(tr("Tabs toolbar")); +``` - bitcoin_xx_YY.ts or bitcoin_xx.ts +### Creating a pull-request +For general PRs, you shouldn’t include any updates to the translation source files. They will be updated periodically, primarily around pre-releases, allowing time for any new phrases to be translated before public releases. This is also important in avoiding translation related merge conflicts. -#### bitcoin_en.ts (Source file) +When an updated source file is merged into the Github repo, Transifex will automatically detect it (although it can take several hours). Once processed, the new strings will show up as "Remaining" in the Transifex web interface and are ready for translators. -`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. 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). 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 +To create the pull-request, use the following commands: +``` +git add src/qt/bitcoinstrings.cpp src/qt/locale/bitcoin_en.ts +git commit +``` -When new plurals are added to the source file, it's important to do the following steps: +### Creating a Transifex account +Visit the [Transifex Signup](https://www.transifex.com/signup/) page to create an account. Take note of your username and password, as they will be required to configure the command-line tool. -1. Open bitcoin_en.ts in Qt Linguist (also included in the Qt SDK) -2. Search for `%n`, which will take you to the parts in the translation that use plurals -3. Look for empty `English Translation (Singular)` and `English Translation (Plural)` fields -4. Add the appropriate strings for the singular and plural form of the base string -5. Mark the item as done (via the green arrow symbol in the toolbar) -6. Repeat from step 2. until all singular and plural forms are in the source file -7. Save the source file +You can find the Bitcoin translation project at [https://www.transifex.com/projects/p/bitcoin/](https://www.transifex.com/projects/p/bitcoin/). -##### Creating the pull-request +### Installing the Transifex client command-line tool +The client it used to fetch updated translations. If you are having problems, or need more details, see [http://docs.transifex.com/developer/client/setup](http://docs.transifex.com/developer/client/setup) -An updated source file should be merged to github and Transifex will pick it -up from there (can take some hours). Afterwards the new strings show up as "Remaining" -in Transifex and can be translated. +**For Linux and Mac** -To create the pull-request you have to do: +`pip install transifex-client` - git add src/qt/bitcoinstrings.cpp src/qt/locale/bitcoin_en.ts - git commit +Setup your transifex client config as follows. Please *ignore the token field*. -Syncing with Transifex ----------------------- +```ini +nano ~/.transifexrc -We are using https://transifex.com as a frontend for translating the client. +[https://www.transifex.com] +hostname = https://www.transifex.com +password = PASSWORD +token = +username = USERNAME +``` -https://www.transifex.com/projects/p/bitcoin/resource/tx/ +**For Windows** -The "Transifex client" (see: http://support.transifex.com/customer/portal/topics/440187-transifex-client/articles) -is used to fetch new translations from Transifex. The configuration for this client (`.tx/config`) -is part of the repository. +Please see [http://docs.transifex.com/developer/client/setup#windows](http://docs.transifex.com/developer/client/setup#windows) for details on installation. -Do not directly download translations one by one from the Transifex website, as we do a few -postprocessing steps before committing the translations. +The Transifex Bitcoin project config file is included as part of the repo. It can be found at `.tx/config`, however you shouldn’t need change anything. -### Fetching new translations +### Synchronising translations +To assist in updating translations, we have created a script to help. 1. `python contrib/devtools/update-translations.py` -2. update `src/qt/bitcoin.qrc` manually or via +2. Update `src/qt/bitcoin.qrc` manually or via `ls src/qt/locale/*ts|xargs -n1 basename|sed 's/\(bitcoin_\(.*\)\).ts/<file alias="\2">locale\/\1.qm<\/file>/'` -3. update `src/qt/Makefile.am` manually or via +3. Update `src/qt/Makefile.am` manually or via `ls src/qt/locale/*ts|xargs -n1 basename|sed 's/\(bitcoin_\(.*\)\).ts/ locale\/\1.ts \\/'` 4. `git add` new translations from `src/qt/locale/` + +**Do not directly download translations** one by one from the Transifex website, as we do a few post-processing steps before committing the translations. + +### Handling Plurals (in source files) +When new plurals are added to the source file, it's important to do the following steps: + +1. Open `bitcoin_en.ts` in Qt Linguist (included in the Qt SDK) +2. Search for `%n`, which will take you to the parts in the translation that use plurals +3. Look for empty `English Translation (Singular)` and `English Translation (Plural)` fields +4. Add the appropriate strings for the singular and plural form of the base string +5. Mark the item as done (via the green arrow symbol in the toolbar) +6. Repeat from step 2, until all singular and plural forms are in the source file +7. Save the source file + +### Translating a new language +To create a new language template, you will need to edit the languages manifest file `src/qt/bitcoin.qrc` and add a new entry. Below is an example of the english language entry. + +```xml +<qresource prefix="/translations"> + <file alias="en">locale/bitcoin_en.qm</file> + ... +</qresource> +``` + +**Note:** that the language translation file **must end in `.qm`** (the compiled extension), and not `.ts`. + +### Questions and general assistance +The Bitcoin-Core translation maintainers include *tcatm, seone, Diapolo, wumpus and luke-jr*.You can find them, and others, in the Freenode IRC chatroom - `irc.freenode.net #bitcoin-dev`. + +If you are a translator, you should also subscribe to the mailing list, https://groups.google.com/forum/#!forum/bitcoin-translators. Announcements will be posted during application pre-releases to notify translators to check for updates.
\ No newline at end of file |
