diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.md | 4 | ||||
| -rw-r--r-- | doc/README_osx.md | 10 | ||||
| -rw-r--r-- | doc/build-freebsd.md | 46 | ||||
| -rw-r--r-- | doc/build-osx.md | 6 | ||||
| -rw-r--r-- | doc/build-unix.md | 33 | ||||
| -rw-r--r-- | doc/developer-notes.md | 40 | ||||
| -rw-r--r-- | doc/init.md | 6 | ||||
| -rw-r--r-- | doc/release-notes-pr10740.md | 11 | ||||
| -rw-r--r-- | doc/release-notes-pr12892.md | 2 | ||||
| -rw-r--r-- | doc/release-notes.md | 5 | ||||
| -rw-r--r-- | doc/release-process.md | 26 | ||||
| -rw-r--r-- | doc/translation_process.md | 8 |
12 files changed, 123 insertions, 74 deletions
diff --git a/doc/README.md b/doc/README.md index ddb239f60c..45762b2374 100644 --- a/doc/README.md +++ b/doc/README.md @@ -22,7 +22,7 @@ Unpack the files into a directory and run: Unpack the files into a directory, and then run bitcoin-qt.exe. -### OS X +### macOS Drag Bitcoin-Core to your applications folder, and then run Bitcoin-Core. @@ -38,7 +38,7 @@ Building The following are developer notes on how to build Bitcoin on your native platform. They are not complete guides, but include notes on the necessary libraries, compile flags, etc. - [Dependencies](dependencies.md) -- [OS X Build Notes](build-osx.md) +- [macOS Build Notes](build-osx.md) - [Unix Build Notes](build-unix.md) - [Windows Build Notes](build-windows.md) - [OpenBSD Build Notes](build-openbsd.md) diff --git a/doc/README_osx.md b/doc/README_osx.md index 975be4be9e..739e22d634 100644 --- a/doc/README_osx.md +++ b/doc/README_osx.md @@ -1,12 +1,12 @@ -Deterministic OS X DMG Notes. +Deterministic macOS DMG Notes. -Working OS X DMGs are created in Linux by combining a recent clang, +Working macOS DMGs are created in Linux by combining a recent clang, the Apple binutils (ld, ar, etc) and DMG authoring tools. Apple uses clang extensively for development and has upstreamed the necessary functionality so that a vanilla clang can take advantage. It supports the use of -F, -target, -mmacosx-version-min, and --sysroot, which are all necessary -when building for OS X. +when building for macOS. Apple's version of binutils (called cctools) contains lots of functionality missing in the FSF's binutils. In addition to extra linker options for @@ -38,7 +38,7 @@ Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.1 Unfortunately, the usual linux tools (7zip, hpmount, loopback mount) are incapable of opening this file. To create a tarball suitable for Gitian input, there are two options: -Using Mac OS X, you can mount the dmg, and then create it with: +Using macOS, you can mount the dmg, and then create it with: ``` $ hdiutil attach Xcode_7.3.1.dmg $ tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.11.sdk.tar.gz MacOSX10.11.sdk @@ -81,7 +81,7 @@ Background images and other features can be added to DMG files by inserting a .DS_Store before creation. This is generated by the script contrib/macdeploy/custom_dsstore.py. -As of OS X Mavericks (10.9), using an Apple-blessed key to sign binaries is a +As of OS X 10.9 Mavericks, 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: diff --git a/doc/build-freebsd.md b/doc/build-freebsd.md new file mode 100644 index 0000000000..c2e4e36dff --- /dev/null +++ b/doc/build-freebsd.md @@ -0,0 +1,46 @@ +FreeBSD build guide +====================== +(updated for FreeBSD 11.1) + +This guide describes how to build bitcoind and command-line utilities on FreeBSD. + +This guide does not contain instructions for building the GUI. + +## Preparation + +You will need the following dependencies, which can be installed as root via pkg: + +``` +pkg install autoconf automake boost-libs git gmake libevent libtool openssl pkgconf +``` + +For the wallet (optional): +``` +./contrib/install_db4.sh `pwd` +export BDB_PREFIX='$PWD/db4' +``` + +See [dependencies.md](dependencies.md) for a complete overview. + +Download the source code: +``` +git clone https://github.com/bitcoin/bitcoin +``` + +## Building Bitcoin Core + +**Important**: Use `gmake` (the non-GNU `make` will exit with an error). + +``` +./autogen.sh + +./configure # to build with wallet OR +./configure --disable-wallet # to build without wallet + +gmake +``` + +*Note on debugging*: The version of `gdb` installed by default is [ancient and considered harmful](https://wiki.freebsd.org/GdbRetirement). +It is not suitable for debugging a multi-threaded C++ program, not even for getting backtraces. Please install the package `gdb` and +use the versioned gdb command (e.g. `gdb7111`). + diff --git a/doc/build-osx.md b/doc/build-osx.md index e52a770ced..abd305cf9a 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -1,11 +1,11 @@ -Mac OS X Build Instructions and Notes +macOS Build Instructions and Notes ==================================== The commands in this guide should be executed in a Terminal application. The built-in one is located in `/Applications/Utilities/Terminal.app`. Preparation ----------- -Install the OS X command line tools: +Install the macOS command line tools: `xcode-select --install` @@ -93,6 +93,6 @@ Other commands: Notes ----- -* Tested on OS X 10.8 through 10.13 on 64-bit Intel processors only. +* Tested on OS X 10.8 Mountain Lion through macOS 10.13 High Sierra on 64-bit Intel processors only. * Building with downloaded Qt binaries is not officially supported. See the notes in [#7714](https://github.com/bitcoin/bitcoin/issues/7714) diff --git a/doc/build-unix.md b/doc/build-unix.md index 2d10484a65..60d888a297 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -2,8 +2,7 @@ UNIX BUILD NOTES ==================== Some notes on how to build Bitcoin Core in Unix. -(For BSD specific instructions, see [build-openbsd.md](build-openbsd.md) and/or -[build-netbsd.md](build-netbsd.md)) +(For BSD specific instructions, see `build-*bsd.md` in this directory.) Note --------------------- @@ -303,33 +302,3 @@ To build executables for ARM: For further documentation on the depends system see [README.md](../depends/README.md) in the depends directory. -Building on FreeBSD --------------------- - -(Updated as of FreeBSD 11.0) - -Clang is installed by default as `cc` compiler, this makes it easier to get -started than on [OpenBSD](build-openbsd.md). Installing dependencies: - - pkg install autoconf automake libtool pkgconf - pkg install boost-libs openssl libevent - pkg install gmake - -You need to use GNU make (`gmake`) instead of `make`. -(`libressl` instead of `openssl` will also work) - -For the wallet (optional): - - ./contrib/install_db4.sh `pwd` - setenv BDB_PREFIX $PWD/db4 - -Then build using: - - ./autogen.sh - ./configure --disable-wallet # OR - ./configure BDB_CFLAGS="-I${BDB_PREFIX}/include" BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx" - gmake - -*Note on debugging*: The version of `gdb` installed by default is [ancient and considered harmful](https://wiki.freebsd.org/GdbRetirement). -It is not suitable for debugging a multi-threaded C++ program, not even for getting backtraces. Please install the package `gdb` and -use the versioned gdb command e.g. `gdb7111`. diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 9081cab911..2fa91ecb02 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -499,7 +499,35 @@ Strings and formatting - Use `ParseInt32`, `ParseInt64`, `ParseUInt32`, `ParseUInt64`, `ParseDouble` from `utilstrencodings.h` for number parsing - - *Rationale*: These functions do overflow checking, and avoid pesky locale issues + - *Rationale*: These functions do overflow checking, and avoid pesky locale issues. + +- Avoid using locale dependent functions if possible. You can use the provided + [`lint-locale-dependence.sh`](/contrib/devtools/lint-locale-dependence.sh) + to check for accidental use of locale dependent functions. + + - *Rationale*: Unnecessary locale dependence can cause bugs that are very tricky to isolate and fix. + + - These functions are known to be locale dependent: + `alphasort`, `asctime`, `asprintf`, `atof`, `atoi`, `atol`, `atoll`, `atoq`, + `btowc`, `ctime`, `dprintf`, `fgetwc`, `fgetws`, `fprintf`, `fputwc`, + `fputws`, `fscanf`, `fwprintf`, `getdate`, `getwc`, `getwchar`, `isalnum`, + `isalpha`, `isblank`, `iscntrl`, `isdigit`, `isgraph`, `islower`, `isprint`, + `ispunct`, `isspace`, `isupper`, `iswalnum`, `iswalpha`, `iswblank`, + `iswcntrl`, `iswctype`, `iswdigit`, `iswgraph`, `iswlower`, `iswprint`, + `iswpunct`, `iswspace`, `iswupper`, `iswxdigit`, `isxdigit`, `mblen`, + `mbrlen`, `mbrtowc`, `mbsinit`, `mbsnrtowcs`, `mbsrtowcs`, `mbstowcs`, + `mbtowc`, `mktime`, `putwc`, `putwchar`, `scanf`, `snprintf`, `sprintf`, + `sscanf`, `stoi`, `stol`, `stoll`, `strcasecmp`, `strcasestr`, `strcoll`, + `strfmon`, `strftime`, `strncasecmp`, `strptime`, `strtod`, `strtof`, + `strtoimax`, `strtol`, `strtold`, `strtoll`, `strtoq`, `strtoul`, + `strtoull`, `strtoumax`, `strtouq`, `strxfrm`, `swprintf`, `tolower`, + `toupper`, `towctrans`, `towlower`, `towupper`, `ungetwc`, `vasprintf`, + `vdprintf`, `versionsort`, `vfprintf`, `vfscanf`, `vfwprintf`, `vprintf`, + `vscanf`, `vsnprintf`, `vsprintf`, `vsscanf`, `vswprintf`, `vwprintf`, + `wcrtomb`, `wcscasecmp`, `wcscoll`, `wcsftime`, `wcsncasecmp`, `wcsnrtombs`, + `wcsrtombs`, `wcstod`, `wcstof`, `wcstoimax`, `wcstol`, `wcstold`, + `wcstoll`, `wcstombs`, `wcstoul`, `wcstoull`, `wcstoumax`, `wcswidth`, + `wcsxfrm`, `wctob`, `wctomb`, `wctrans`, `wctype`, `wcwidth`, `wprintf` - For `strprintf`, `LogPrint`, `LogPrintf` formatting characters don't need size specifiers @@ -567,6 +595,12 @@ Source code organization - *Rationale*: Shorter and simpler header files are easier to read, and reduce compile time +- Use only the lowercase alphanumerics (`a-z0-9`), underscore (`_`) and hyphen (`-`) in source code filenames. + + - *Rationale*: `grep`:ing and auto-completing filenames is easier when using a consistent + naming pattern. Potential problems when building on case-insensitive filesystems are + avoided when using only lowercase characters in source code filenames. + - Every `.cpp` and `.h` file should `#include` every header file it directly uses classes, functions or other definitions from, even if those headers are already included indirectly through other headers. @@ -594,8 +628,8 @@ namespace { - *Rationale*: Avoids confusion about the namespace context -- Prefer `#include <primitives/transaction.h>` bracket syntax instead of - `#include "primitives/transactions.h"` quote syntax when possible. +- Use `#include <primitives/transaction.h>` bracket syntax instead of + `#include "primitives/transactions.h"` quote syntax. - *Rationale*: Bracket syntax is less ambiguous because the preprocessor searches a fixed list of include directories without taking location of the diff --git a/doc/init.md b/doc/init.md index ffd13ae1f9..d04f7d186a 100644 --- a/doc/init.md +++ b/doc/init.md @@ -15,7 +15,7 @@ Service User All three Linux startup configurations assume the existence of a "bitcoin" user and group. They must be created before attempting to use these scripts. -The OS X configuration assumes bitcoind will be set up for the current user. +The macOS configuration assumes bitcoind will be set up for the current user. Configuration --------------------------------- @@ -65,7 +65,7 @@ reasons to make the configuration file and data directory only readable by the bitcoin user and group. Access to bitcoin-cli and other bitcoind rpc clients can then be controlled by group membership. -### Mac OS X +### macOS Binary: `/usr/local/bin/bitcoind` Configuration file: `~/Library/Application Support/Bitcoin/bitcoin.conf` @@ -111,7 +111,7 @@ Using this script, you can adjust the path and flags to the bitcoind program by setting the BITCOIND and FLAGS environment variables in the file /etc/sysconfig/bitcoind. You can also use the DAEMONOPTS environment variable here. -### Mac OS X +### macOS Copy org.bitcoin.bitcoind.plist into ~/Library/LaunchAgents. Load the launch agent by running `launchctl load ~/Library/LaunchAgents/org.bitcoin.bitcoind.plist`. diff --git a/doc/release-notes-pr10740.md b/doc/release-notes-pr10740.md index f286216b6e..c81ea6a4db 100644 --- a/doc/release-notes-pr10740.md +++ b/doc/release-notes-pr10740.md @@ -1,8 +1,9 @@ -Dynamic loading of wallets --------------------------- +Dynamic loading and creation of wallets +--------------------------------------- -Previously, wallets could only be loaded at startup, by specifying `-wallet` parameters on the command line or in the bitcoin.conf file. It is now possible to load wallets dynamically at runtime by calling the `loadwallet` RPC. +Previously, wallets could only be loaded or created at startup, by specifying `-wallet` parameters on the command line or in the bitcoin.conf file. It is now possible to load and create wallets dynamically at runtime: -The wallet can be specified as file/directory basename (which must be located in the `walletdir` directory), or as an absolute path to a file/directory. +- Existing wallets can be loaded by calling the `loadwallet` RPC. The wallet can be specified as file/directory basename (which must be located in the `walletdir` directory), or as an absolute path to a file/directory. +- New wallets can be created (and loaded) by calling the `createwallet` RPC. The provided name must not match a wallet file in the `walletdir` directory or the name of a wallet that is currently loaded. -This feature is currently only available through the RPC interface. Wallets loaded in this way will display in the bitcoin-qt GUI. +This feature is currently only available through the RPC interface. diff --git a/doc/release-notes-pr12892.md b/doc/release-notes-pr12892.md index 8105eca5c0..f4a95bd40f 100644 --- a/doc/release-notes-pr12892.md +++ b/doc/release-notes-pr12892.md @@ -18,7 +18,7 @@ Here are the changes to RPC methods: | Deprecated Method | New Method | Notes | | :---------------------- | :-------------------- | :-----------| | `getaccount` | `getaddressinfo` | `getaddressinfo` returns a json object with address information instead of just the name of the account as a string. | -| `getaccountaddress` | `getlabeladdress` | `getlabeladdress` throws an error by default if the label does not already exist, but provides a `force` option for compatibility with existing applications. | +| `getaccountaddress` | n/a | There is no replacement for `getaccountaddress` since labels do not have an associated receive address. | | `getaddressesbyaccount` | `getaddressesbylabel` | `getaddressesbylabel` returns a json object with the addresses as keys, instead of a list of strings. | | `getreceivedbyaccount` | `getreceivedbylabel` | _no change in behavior_ | | `listaccounts` | `listlabels` | `listlabels` does not return a balance or accept `minconf` and `watchonly` arguments. | diff --git a/doc/release-notes.md b/doc/release-notes.md index 7a9a98bfec..e1bb84cca9 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -56,6 +56,11 @@ frequently tested on them. Notable changes =============== +GUI changes +----------- + +- Block storage can be limited under Preferences, in the Main tab. Undoing this setting requires downloading the full blockchain again. This mode is incompatible with -txindex and -rescan. + RPC changes ------------ diff --git a/doc/release-process.md b/doc/release-process.md index a988c74ba5..912b620794 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -89,7 +89,7 @@ Ensure gitian-builder is up-to-date: wget -P inputs http://downloads.sourceforge.net/project/osslsigncode/osslsigncode/osslsigncode-1.7.1.tar.gz popd -Create the OS X SDK tarball, see the [OS X readme](README_osx.md) for details, and copy it into the inputs directory. +Create the macOS SDK tarball, see the [macOS readme](README_osx.md) for details, and copy it into the inputs directory. ### Optional: Seed the Gitian sources cache and offline git repositories @@ -111,7 +111,7 @@ NOTE: Offline builds must use the --url flag to ensure Gitian fetches only from The gbuild invocations below <b>DO NOT DO THIS</b> by default. -### Build and sign Bitcoin Core for Linux, Windows, and OS X: +### Build and sign Bitcoin Core for Linux, Windows, and macOS: pushd ./gitian-builder ./bin/gbuild --num-make 2 --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml @@ -134,7 +134,7 @@ Build output expected: 1. source tarball (`bitcoin-${VERSION}.tar.gz`) 2. linux 32-bit and 64-bit dist tarballs (`bitcoin-${VERSION}-linux[32|64].tar.gz`) 3. windows 32-bit and 64-bit unsigned installers and dist zips (`bitcoin-${VERSION}-win[32|64]-setup-unsigned.exe`, `bitcoin-${VERSION}-win[32|64].zip`) - 4. OS X unsigned installer and dist tarball (`bitcoin-${VERSION}-osx-unsigned.dmg`, `bitcoin-${VERSION}-osx64.tar.gz`) + 4. macOS unsigned installer and dist tarball (`bitcoin-${VERSION}-osx-unsigned.dmg`, `bitcoin-${VERSION}-osx64.tar.gz`) 5. Gitian signatures (in `gitian.sigs/${VERSION}-<linux|{win,osx}-unsigned>/(your Gitian key)/`) ### Verify other gitian builders signatures to your own. (Optional) @@ -161,13 +161,13 @@ Commit your signature to gitian.sigs: git push # Assuming you can push to the gitian.sigs tree popd -Codesigner only: Create Windows/OS X detached signatures: +Codesigner only: Create Windows/macOS detached signatures: - Only one person handles codesigning. Everyone else should skip to the next step. -- Only once the Windows/OS X builds each have 3 matching signatures may they be signed with their respective release keys. +- Only once the Windows/macOS builds each have 3 matching signatures may they be signed with their respective release keys. -Codesigner only: Sign the osx binary: +Codesigner only: Sign the macOS binary: - transfer bitcoin-osx-unsigned.tar.gz to osx for signing + transfer bitcoin-osx-unsigned.tar.gz to macOS for signing tar xf bitcoin-osx-unsigned.tar.gz ./detached-sig-create.sh -s "Key ID" Enter the keychain password and authorize the signature @@ -192,12 +192,12 @@ Codesigner only: Commit the detached codesign payloads: git tag -s v${VERSION} HEAD git push the current branch and new tag -Non-codesigners: wait for Windows/OS X detached signatures: +Non-codesigners: wait for Windows/macOS detached signatures: -- Once the Windows/OS X builds each have 3 matching signatures, they will be signed with their respective release keys. +- Once the Windows/macOS builds each have 3 matching signatures, they will be signed with their respective release keys. - Detached signatures will then be committed to the [bitcoin-detached-sigs](https://github.com/bitcoin-core/bitcoin-detached-sigs) repository, which can be combined with the unsigned apps to create signed binaries. -Create (and optionally verify) the signed OS X binary: +Create (and optionally verify) the signed macOS binary: pushd ./gitian-builder ./bin/gbuild -i --commit signature=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml @@ -216,7 +216,7 @@ Create (and optionally verify) the signed Windows binaries: mv build/out/bitcoin-*win32-setup.exe ../bitcoin-${VERSION}-win32-setup.exe popd -Commit your signature for the signed OS X/Windows binaries: +Commit your signature for the signed macOS/Windows binaries: pushd gitian.sigs git add ${VERSION}-osx-signed/"${SIGNER}" @@ -276,14 +276,14 @@ bitcoin.org (see below for bitcoin.org update instructions). - Update bitcoin.org version - First, check to see if the Bitcoin.org maintainers have prepared a - release: https://github.com/bitcoin-dot-org/bitcoin.org/labels/Releases + release: https://github.com/bitcoin-dot-org/bitcoin.org/labels/Core - If they have, it will have previously failed their Travis CI checks because the final release files weren't uploaded. Trigger a Travis CI rebuild---if it passes, merge. - If they have not prepared a release, follow the Bitcoin.org release - instructions: https://github.com/bitcoin-dot-org/bitcoin.org#release-notes + instructions: https://github.com/bitcoin-dot-org/bitcoin.org/blob/master/docs/adding-events-release-notes-and-alerts.md#release-notes - After the pull request is merged, the website will automatically show the newest version within 15 minutes, as well as update the OS download links. Ping @saivann/@harding (saivann/harding on Freenode) in case anything goes wrong diff --git a/doc/translation_process.md b/doc/translation_process.md index 5a9c59914e..022d7bb00b 100644 --- a/doc/translation_process.md +++ b/doc/translation_process.md @@ -46,9 +46,7 @@ Visit the [Transifex Signup](https://www.transifex.com/signup/) page to create a You can find the Bitcoin translation project at [https://www.transifex.com/projects/p/bitcoin/](https://www.transifex.com/projects/p/bitcoin/). ### 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) - -**For Linux and Mac** +The client is used to fetch updated translations. If you are having problems, or need more details, see [https://docs.transifex.com/client/installing-the-client](https://docs.transifex.com/client/installing-the-client) `pip install transifex-client` @@ -64,10 +62,6 @@ token = username = USERNAME ``` -**For Windows** - -Please see [http://docs.transifex.com/developer/client/setup#windows](http://docs.transifex.com/developer/client/setup#windows) for details on installation. - 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. ### Synchronising translations |