diff --git a/contrib/init/README.md b/contrib/init/README.md index 1a949f3c07..8d3e57c526 100644 --- a/contrib/init/README.md +++ b/contrib/init/README.md @@ -1,12 +1,12 @@ Sample configuration files for: ``` SystemD: bitcoind.service Upstart: bitcoind.conf OpenRC: bitcoind.openrc bitcoind.openrcconf CentOS: bitcoind.init -OS X: org.bitcoin.bitcoind.plist +macOS: org.bitcoin.bitcoind.plist ``` have been made available to assist packagers in creating node packages here. See doc/init.md for more information. diff --git a/depends/README.md b/depends/README.md index c70acf5924..62b08f5acf 100644 --- a/depends/README.md +++ b/depends/README.md @@ -1,59 +1,59 @@ ### Usage To build dependencies for the current arch+OS: make To build for another arch/OS: make HOST=host-platform-triplet For example: make HOST=x86_64-w64-mingw32 -j4 A prefix will be generated that's suitable for plugging into Bitcoin's configure. In the above example, a dir named x86_64-w64-mingw32 will be created. To use it for bitcoin-abc: ./configure --prefix=`pwd`/depends/x86_64-w64-mingw32 Common `host-platform-triplets` for cross compilation are: - `i686-w64-mingw32` for Win32 - `x86_64-w64-mingw32` for Win64 -- `x86_64-apple-darwin11` for MacOSX +- `x86_64-apple-darwin11` for macOS - `arm-linux-gnueabihf` for Linux ARM 32 bit - `aarch64-linux-gnu` for Linux ARM 64 bit No other options are needed, the paths are automatically configured. Dependency Options: The following can be set when running make: make FOO=bar SOURCES_PATH: downloaded sources will be placed here BASE_CACHE: built packages will be placed here - SDK_PATH: Path where sdk's can be found (used by OSX) + SDK_PATH: Path where sdk's can be found (used by macOS) FALLBACK_DOWNLOAD_PATH: If a source file can't be fetched, try here before giving up NO_QT: Don't download/build/cache qt and its dependencies NO_WALLET: Don't download/build/cache libs needed to enable the wallet NO_UPNP: Don't download/build/cache packages needed for enabling upnp DEBUG: disable some optimizations and enable more runtime checking HOST_ID_SALT: Optional salt to use when generating host package ids BUILD_ID_SALT: Optional salt to use when generating build package ids If some packages are not built, for example `make NO_WALLET=1`, the appropriate options will be passed to bitcoin's configure. In this case, `--disable-wallet`. Additional targets: download: run 'make download' to fetch all sources without building them - download-osx: run 'make download-osx' to fetch all sources needed for osx builds + download-osx: run 'make download-osx' to fetch all sources needed for macOS builds download-win: run 'make download-win' to fetch all sources needed for win builds download-linux: run 'make download-linux' to fetch all sources needed for linux builds ### Other documentation - [description.md](description.md): General description of the depends system - [packages.md](packages.md): Steps for adding packages diff --git a/depends/description.md b/depends/description.md index 74f9ef3f20..9fc7093be4 100644 --- a/depends/description.md +++ b/depends/description.md @@ -1,53 +1,53 @@ This is a system of building and caching dependencies necessary for building Bitcoin. There are several features that make it different from most similar systems: ### It is designed to be builder and host agnostic In theory, binaries for any target OS/architecture can be created, from a builder running any OS/architecture. In practice, build-side tools must be specified when the defaults don't fit, and packages must be amended to work on new hosts. For now, a build architecture of x86_64 is assumed, either on -Linux or OSX. +Linux or macOS. ### No reliance on timestamps File presence is used to determine what needs to be built. This makes the results distributable and easily digestable by automated builders. ### Each build only has its specified dependencies available at build-time. For each build, the sysroot is wiped and the (recursive) dependencies are installed. This makes each build deterministic, since there will never be any unknown files available to cause side-effects. ### Each package is cached and only rebuilt as needed. Before building, a unique build-id is generated for each package. This id consists of a hash of all files used to build the package (Makefiles, packages, etc), and as well as a hash of the same data for each recursive dependency. If any portion of a package's build recipe changes, it will be rebuilt as well as any other package that depends on it. If any of the main makefiles (Makefile, funcs.mk, etc) are changed, all packages will be rebuilt. After building, the results are cached into a tarball that can be re-used and distributed. ### Package build results are (relatively) deterministic. Each package is configured and patched so that it will yield the same build-results with each consequent build, within a reasonable set of constraints. Some things like timestamp insertion are unavoidable, and are beyond the scope of this system. Additionally, the toolchain itself must be capable of deterministic results. When revisions are properly bumped, a cached build should represent an exact single payload. ### Sources are fetched and verified automatically Each package must define its source location and checksum. The build will fail if the fetched source does not match. Sources may be pre-seeded and/or cached as desired. ### Self-cleaning Build and staging dirs are wiped after use, and any previous version of a cached result is removed following a successful build. Automated builders should be able to build each revision and store the results with no further intervention. diff --git a/doc/README.md b/doc/README.md index e645be20c6..e4153ac640 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,74 +1,74 @@ Bitcoin ABC ===================== Setup --------------------- Bitcoin ABC is a fork of Bitcoin Core, which is the original Bitcoin client and builds the backbone of the network. It downloads and, by default, stores the entire history of Bitcoin transactions, which requires a few hundred gigabytes of disk space. 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. To download Bitcoin ABC, visit [bitcoinabc.org](https://download.bitcoinabc.org/). Running --------------------- The following are some helpful notes on how to run Bitcoin on your native platform. ### Unix Unpack the files into a directory and run: - `bin/bitcoin-qt` (GUI) or - `bin/bitcoind` (headless) ### Windows Unpack the files into a directory, and then run bitcoin-qt.exe. -### OS X +### macOS Drag bitcoin-abc to your applications folder, and then run bitcoin-abc. ### 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 the [Bitcoin ABC Subreddit](https://www.reddit.com/r/BitcoinABC/). 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) - [Gitian Building Guide](gitian-building.md) Development --------------------- The Bitcoin ABC repo's [root README](/README.md) contains relevant information on the development process and automated testing. - [Developer Notes](developer-notes.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) - [Translation Strings Policy](translation_strings_policy.md) - [Travis CI](travis-ci.md) - [Unauthenticated REST Interface](REST-interface.md) - [Shared Libraries](shared-libraries.md) - [BIPS](bips.md) - [Dnsseed Policy](dnsseed-policy.md) - [Benchmarking](benchmarking.md) ### Miscellaneous - [Assets Attribution](assets-attribution.md) - [Files](files.md) - [Fuzz-testing](fuzzing.md) - [Reduce Traffic](reduce-traffic.md) - [Tor Support](tor.md) - [Init Scripts (systemd/upstart/openrc)](init.md) - [ZMQ](zmq.md) License --------------------- Distribution is done under the [MIT software license](/COPYING). This product includes software developed by the OpenSSL Project for use in the [OpenSSL Toolkit](https://www.openssl.org/), 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.md b/doc/README_osx.md index 975be4be9e..739e22d634 100644 --- a/doc/README_osx.md +++ b/doc/README_osx.md @@ -1,97 +1,97 @@ -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 frameworks and sysroots, several other tools are needed as well such as install_name_tool, lipo, and nmedit. These do not build under linux, so they have been patched to do so. The work here was used as a starting point: [mingwandroid/toolchain4](https://github.com/mingwandroid/toolchain4). In order to build a working toolchain, the following source packages are needed from Apple: cctools, dyld, and ld64. These tools inject timestamps by default, which produce non-deterministic binaries. The ZERO_AR_DATE environment variable is used to disable that. This version of cctools has been patched to use the current version of clang's headers and its libLTO.so rather than those from llvmgcc, as it was 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 the [Xcode 7.3.1 dmg](https://developer.apple.com/devcenter/download.action?path=/Developer_Tools/Xcode_7.3.1/Xcode_7.3.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.11.sdk ``` 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 ``` Alternatively, you can use 7zip and SleuthKit to extract the files one by one. The script contrib/macdeploy/extract-osx-sdk.sh automates this. First ensure the dmg file is in the current directory, and then run the script. You may wish to delete the intermediate 5.hfs file and MacOSX10.11.sdk (the directory) when you've confirmed the extraction succeeded. ```bash apt-get install p7zip-full sleuthkit contrib/macdeploy/extract-osx-sdk.sh rm -rf 5.hfs MacOSX10.11.sdk ``` The Gitian descriptors build 2 sets of files: Linux tools, then Apple binaries which are created using these tools. The build process has been designed to avoid including the SDK's files in Gitian's outputs. All interim tarballs are fully deterministic and may be freely redistributed. genisoimage is used to create the initial DMG. It is not deterministic as-is, so it has been patched. A system genisoimage will work fine, but it will not be deterministic because the file-order will change between invocations. The patch can be seen here: [theuni/osx-cross-depends](https://raw.githubusercontent.com/theuni/osx-cross-depends/master/patches/cdrtools/genisoimage.diff). No effort was made to fix this cleanly, so it likely leaks memory badly. But it's only used for a single invocation, so that's no real concern. genisoimage cannot compress DMGs, so afterwards, the 'dmg' tool from the libdmg-hfsplus project is used to compress it. There are several bugs in this tool and its maintainer has seemingly abandoned the project. It has been forked and is available (with fixes) here: [theuni/libdmg-hfsplus](https://github.com/theuni/libdmg-hfsplus). The 'dmg' tool has the ability to create DMGs from scratch as well, but this functionality is broken. Only the compression feature is currently used. Ideally, the creation could be fixed and genisoimage would no longer be necessary. 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: - 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. Detached signatures are available from this [repository](https://github.com/bitcoin-core/bitcoin-detached-sigs). - 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/build-osx.md b/doc/build-osx.md index 9cc8d3ad55..fab8e9d057 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -1,93 +1,93 @@ -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 ----------- 1. Install Xcode from the app store if you don't have it already (it's a dependency for qt5) NOTE: Building with Qt4 is still supported, however, could result in a broken UI. Building with Qt5 is recommended. -2. Install the OS X command line tools: +2. Install the macOS command line tools: `xcode-select --install` When the popup appears, click `Install`. 3. Install [Homebrew](https://brew.sh). Dependencies ---------------------- Install dependencies: brew install automake berkeley-db libtool boost miniupnpc openssl pkg-config protobuf python qt libevent qrencode See [dependencies.md](dependencies.md) for a complete overview. If you want to build the disk image with `make deploy` (.dmg / optional), you need RSVG brew install librsvg Build Bitcoin ABC ----------------- Before you start building, please make sure that your compiler supports C++14. 1. Clone the Bitcoin ABC source code and cd into `bitcoin-abc` git clone https://github.com/Bitcoin-ABC/bitcoin-abc.git cd bitcoin-abc 2. Build bitcoin-abc: Configure and build the headless bitcoin binaries as well as the GUI (if Qt is found). You can disable the GUI build by passing `--without-gui` to configure. It is recommended to create a build directory to build out-of-tree. ./autogen.sh mkdir build cd build ../configure make 3. It is recommended to build and run the unit tests: make check 4. You can also create a .dmg that contains the .app bundle (optional): make deploy Running ------- Bitcoin ABC is now available at `./src/bitcoind` Before running, it's recommended you create an RPC configuration file. echo -e "rpcuser=bitcoinrpc\nrpcpassword=$(xxd -l 16 -p /dev/urandom)" > "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" chmod 600 "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" The first time you run bitcoind, it will start downloading the blockchain. This process could take several hours. You can monitor the download process by looking at the debug.log file: tail -f $HOME/Library/Application\ Support/Bitcoin/debug.log Other commands: ------- ./src/bitcoind -daemon # Starts the bitcoin daemon. ./src/bitcoin-cli --help # Outputs a list of command-line options. ./src/bitcoin-cli help # Outputs a list of RPC commands when the daemon is running. Notes ----- * 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/gitian-building.md b/doc/gitian-building.md index f4d1264082..30eeed24e8 100644 --- a/doc/gitian-building.md +++ b/doc/gitian-building.md @@ -1,112 +1,112 @@ Gitian building =============== *Setup instructions for a Gitian build of Bitcoin ABC using a VM or physical system.* Gitian is the deterministic build process that is used to build the Bitcoin ABC executables. It provides a way to be reasonably sure that the executables are really built from the source on GitHub. It also makes sure that the same, tested dependencies are used and statically built into the executable. Multiple developers build the source code by following a specific descriptor ("recipe"), cryptographically sign the result, and upload the resulting signature. These results are compared and only if they match, the build is accepted and uploaded to bitcoinabc.org. More independent Gitian builders are needed, which is why this guide exists. It is preferred you follow these steps yourself instead of using someone else's VM image to avoid 'contaminating' the build. Table of Contents ----------------- - [Preparing the Gitian builder host](#preparing-the-gitian-builder-host) - [Getting and building the inputs](#getting-and-building-the-inputs) - [Building Bitcoin Core](#building-bitcoin-core) - [Building an alternative repository](#building-an-alternative-repository) - [Signing externally](#signing-externally) - [Uploading signatures](#uploading-signatures) Preparing the Gitian builder host --------------------------------- The first step is to prepare the host environment that will be used to perform the Gitian builds. This guide explains how to set up the environment, and how to start the builds. Gitian builds are known to be working on recent versions of Debian, Ubuntu and Fedora. If your machine is already running one of those operating systems, you can perform Gitian builds on the actual hardware. Alternatively, you can install one of the supported operating systems in a virtual machine. You can create the virtual machine using [vagrant](./gitian-building/gitian-building-vagrant.md) or chose to setup the VM manually. Any kind of virtualization can be used, for example: - [VirtualBox](https://www.virtualbox.org/) (covered by this guide) - [KVM](http://www.linux-kvm.org/page/Main_Page) - [LXC](https://linuxcontainers.org/) Please refer to the following documents to set up the operating systems and Gitian. | | Debian | Fedora | |-----------------------------------|------------------------------------------------------------------------------------|------------------------------------------------------------------------------------| | Setup virtual machine (optional) | [Create Debian VirtualBox](./gitian-building/gitian-building-create-vm-debian.md) | [Create Fedora VirtualBox](./gitian-building/gitian-building-create-vm-fedora.md) | | Setup Gitian | [Setup Gitian on Debian](./gitian-building/gitian-building-setup-gitian-debian.md) | [Setup Gitian on Fedora](./gitian-building/gitian-building-setup-gitian-fedora.md) | Note that a version of `lxc-execute` higher or equal to 2.1.1 is required. You can check the version with `lxc-execute --version`. Non-Debian / Ubuntu, Manual and Offline Building ------------------------------------------------ The instructions below use the automated script [gitian-build.py](https://github.com/Bitcoin-ABC/bitcoin-abc/blob/master/contrib/gitian-build.py) which only works in Debian/Ubuntu. For manual steps and instructions for fully offline signing, see [this guide](./gitian-building/gitian-building-manual.md). MacOS code signing ------------------ In order to sign builds for MacOS, you need to download the free SDK and extract a file. The steps are described [here](./gitian-building/gitian-building-mac-os-sdk.md). It is possible to download the resulting archive directly for users that desire to do so: ```bash curl -LO https://storage.googleapis.com/f4936e83b2dcbca742be51fb9692b153/MacOSX10.11.sdk.tar.gz echo "4732b52b5ebe300c8c91cbeed6d19d59c1ff9c56c7a1dd6cfa518b9c2c72abde MacOSX10.11.sdk.tar.gz" | sha256sum -c ``` -Alternatively, you can skip the OSX build by adding `--os=lw` below. +Alternatively, you can skip the macOS build by adding `--os=lw` below. Initial Gitian Setup -------------------- The `gitian-build.py` script will checkout different release tags, so it's best to copy it: ```bash cp bitcoin-abc/contrib/gitian-build.py . ``` You only need to do this once: ```bash ./gitian-build.py --setup satoshi 0.18.5 ``` Where `satoshi` is your Github name and `0.18.5` is the most recent tag (without `v`). Build binaries -------------- -Windows and OSX have code signed binaries, but those won't be available until a few developers have gitian signed the non-codesigned binaries. +Windows and macOS have code signed binaries, but those won't be available until a few developers have gitian signed the non-codesigned binaries. To build the most recent tag: ```bash ./gitian-build.py --detach-sign --no-commit -b satoshi 0.18.5 ``` To speed up the build, use `-j 5 -m 5000` as the first arguments, where `5` is the number of CPU's you allocated to the VM plus one, and 5000 is a little bit less than then the MB's of RAM you allocated. If all went well, this produces a number of (uncommited) `.assert` files in the gitian.sigs repository. You need to copy these uncommited changes to your host machine, where you can sign them: ```bash export NAME=satoshi gpg --output $VERSION-linux/$NAME/bitcoin-abc-linux-0.18.5-build.assert.sig --detach-sign 0.18.5-linux/$NAME/bitcoin-abc-linux-0.18.5-build.assert gpg --output $VERSION-osx-unsigned/$NAME/bitcoin-abc-osx-0.18.5-build.assert.sig --detach-sign 0.18.5-osx-unsigned/$NAME/bitcoin-abc-osx-0.18.5-build.assert gpg --output $VERSION-win-unsigned/$NAME/bitcoin-abc-win-0.18.5-build.assert.sig --detach-sign 0.18.5-win-unsigned/$NAME/bitcoin-abc-win-0.18.5-build.assert ``` diff --git a/doc/gitian-building/gitian-building-create-vm-debian.md b/doc/gitian-building/gitian-building-create-vm-debian.md index 63054f0821..51435bd763 100644 --- a/doc/gitian-building/gitian-building-create-vm-debian.md +++ b/doc/gitian-building/gitian-building-create-vm-debian.md @@ -1,225 +1,225 @@ # Setup Debian virtual machine on VirtualBox Table of Contents ----------------- - [Create a new VirtualBox VM](#create-a-new-virtualbox-vm) - [Connecting to the VM](#connecting-to-the-vm) Create a new VirtualBox VM -------------------------- In the VirtualBox GUI click "New" and choose the following parameters in the wizard: ![](figs/create_new_vm_debian.png) - Type: Linux, Debian (64-bit) ![](figs/create_vm_memsize.png) - Memory Size: at least 3000MB, anything less and the build might not complete. ![](figs/create_vm_hard_disk.png) - Hard Disk: Create a virtual hard disk now ![](figs/create_vm_hard_disk_file_type.png) - Hard Disk file type: Use the default, VDI (VirtualBox Disk Image) ![](figs/create_vm_storage_physical_hard_disk.png) - Storage on physical hard disk: Dynamically Allocated ![](figs/create_vm_file_location_size.png) - File location and size: at least 40GB - Click `Create` After creating the VM, we need to configure it. - Click the `Settings` button, then go to `System` tab and `Processor` sub-tab. Increase the number of processors to the number of cores on your machine if you want builds to be faster. ![](figs/system_settings.png) - Go to the `Network` tab. Adapter 1 should be attached to `NAT`. ![](figs/network_settings.png) - Click `Advanced`, then `Port Forwarding`. We want to set up a port through which we can reach the VM to get files in and out. - Create a new rule by clicking the plus icon. ![](figs/port_forwarding_rules.png) - Set up the new rule the following way: - Name: `SSH` - Protocol: `TCP` - Leave Host IP empty - Host Port: `22222` - Leave Guest IP empty - Guest Port: `22` - Click `Ok` twice to save. Get the [Debian 9.x net installer](https://cdimage.debian.org/debian-cd/9.8.0/amd64/iso-cd/debian-9.8.0-amd64-netinst.iso) (a more recent minor version should also work, see also [Debian Network installation](https://www.debian.org/CD/netinst/)). This DVD image can be [validated](https://www.debian.org/CD/verify) using a SHA256 hashing tool, for example on Unixy OSes by entering the following in a terminal: ```bash echo "73bd56fb4548efa384bf32fd25808b99198f81c23cf19ab9e6507d898cd58dce debian-9.8.0-amd64-netinst.iso" | sha256sum -c # (must return OK) ``` -Replace `sha256sum` with `shasum` on OSX. +Replace `sha256sum` with `shasum` on macOS. Then start the VM. On the first launch you will be asked for a CD or DVD image. Choose the downloaded ISO. ![](figs/select_startup_disk_debian.png) Installing Debian ----------------- This section will explain how to install Debian on the newly created VM. - Choose the non-graphical installer. We do not need the graphical environment; it will only increase installation time and disk usage. ![](figs/debian_install_1_boot_menu.png) **Note**: Navigating in the Debian installer: To keep a setting at the default and proceed, just press `Enter`. To select a different button, press `Tab`. - Choose locale and keyboard settings (doesn't matter, you can just go with the defaults or select your own information) ![](figs/debian_install_2_select_a_language.png) ![](figs/debian_install_3_select_location.png) ![](figs/debian_install_4_configure_keyboard.png) - The VM will detect network settings using DHCP, this should all proceed automatically - Configure the network: - Hostname `debian`. - Leave domain name empty. ![](figs/debian_install_5_configure_the_network.png) ![](figs/debian_install_6_domain_name.png) - You can leave the root password empty. Otherwise, enter it twice and remember it for later. ![](figs/debian_install_6a_set_up_root_password.png) - Name the new user `gitianuser` (the full name doesn't matter, you can leave it empty) - Set the account username as `gitianuser` ![](figs/debian_install_7_set_up_user_fullname.png) ![](figs/debian_install_8_set_up_username.png) - Choose a user password and enter it twice (remember it for later) ![](figs/debian_install_9_user_password.png) - The installer will set up the clock using a time server; this process should be automatic - Set up the clock: choose a time zone (depends on the locale settings that you picked earlier; specifics don't matter) ![](figs/debian_install_10_configure_clock.png) - Disk setup - Partitioning method: Guided - Use the entire disk ![](figs/debian_install_11_partition_disks.png) - Select disk to partition: SCSI1 (0,0,0) ![](figs/debian_install_12_choose_disk.png) - Partition Disks -> *All files in one partition* ![](figs/all_files_in_one_partition.png) - Finish partitioning and write changes to disk -> *Yes* (`Tab`, `Enter` to select the `Yes` button) ![](figs/debian_install_14_finish.png) ![](figs/debian_install_15_write_changes.png) - The base system will be installed, this will take a minute or so - Scan another CD or DVD? -> *No* - Choose a mirror (any will do) ![](figs/debian_install_16_choose_a_mirror.png) - Enter proxy information (unless you are on an intranet, leave this empty) ![](figs/debian_install_18_proxy_settings.png) - Wait a bit while 'Select and install software' runs - Participate in popularity contest -> *No* - Choose software to install. We need just the base system. (`Tab` to highlight options, `Space` to select them) - Make sure only 'SSH server' and 'Standard System Utilities' are checked - Uncheck 'Debian Desktop Environment' and 'Print Server' ![](figs/debian_install_19_software_selection.png) - Install the GRUB boot loader to the master boot record? -> Yes ![](figs/debian_install_20_install_grub.png) - Device for boot loader installation -> ata-VBOX_HARDDISK ![](figs/debian_install_21_install_grub_bootloader.png) - Installation Complete -> *Continue* - After installation, the VM will reboot and you will have a working Debian VM. Congratulations! ![](figs/debian_install_22_finish_installation.png) Connecting to the VM -------------------- After the VM has booted you can connect to it using SSH, and files can be copied from and to the VM using a SFTP utility. Connect to `localhost`, port `22222` (or the port configured when installing the VM). On Windows you can use [putty](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) and [WinSCP](http://winscp.net/eng/index.php). For example, to connect as `gitianuser` from a Linux command prompt use $ ssh gitianuser@localhost -p 22222 The authenticity of host '[localhost]:22222 ([127.0.0.1]:22222)' can't be established. RSA key fingerprint is ae:f5:c8:9f:17:c6:c7:1b:c2:1b:12:31:1d:bb:d0:c7. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added '[localhost]:22222' (RSA) to the list of known hosts. gitianuser@localhost's password: (enter gitianuser password configured during install) The programs included with the Debian GNU/Linux system are free software; the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright. Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law. gitianuser@debian:~$ Use `sudo` to execute commands as root. Optional - Easier login to the VM --------------------------------- You'll need to generate an SSH key, e.g. by following the instructions under "Generating a new SSH key" [here](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). After that, login to the VM and enter: ```bash mkdir .ssh ``` On your machine edit or create `~/.ssh/config` and add: ```bash Host gitian HostName localhost Port 22222 User gitianuser ``` Open a new terminal tab and enter: ```bash scp ~/.ssh/id_rsa.pub gitian:.ssh/authorized_keys ``` Next time you need to login to the VM, just use: `ssh gitian` diff --git a/doc/gitian-building/gitian-building-create-vm-fedora.md b/doc/gitian-building/gitian-building-create-vm-fedora.md index 86bbff9d16..7d0fcb4e98 100644 --- a/doc/gitian-building/gitian-building-create-vm-fedora.md +++ b/doc/gitian-building/gitian-building-create-vm-fedora.md @@ -1,133 +1,133 @@ # Setup Fedora virtual machine on VirtualBox Table of Contents ------------------ - [Create a new VirtualBox VM](#create-a-new-virtualbox-vm) - [Connecting to the VM](#connecting-to-the-vm) Create a new VirtualBox VM --------------------------- In the VirtualBox GUI click "New" and choose the following parameters in the wizard: ![](figs/create_new_vm_fedora.png) - Type: Linux, Fedora (64-bit) ![](figs/create_vm_memsize.png) - Memory Size: at least 3000MB, anything less and the build might not complete. ![](figs/create_vm_hard_disk.png) - Hard Disk: Create a virtual hard disk now ![](figs/create_vm_hard_disk_file_type.png) - Hard Disk file type: Use the default, VDI (VirtualBox Disk Image) ![](figs/create_vm_storage_physical_hard_disk.png) - Storage on physical hard disk: Dynamically Allocated ![](figs/create_vm_file_location_size.png) - File location and size: at least 40GB - Click `Create` After creating the VM, we need to configure it. - Click the `Settings` button, then go to `System` tab and `Processor` sub-tab. Increase the number of processors to the number of cores on your machine if you want builds to be faster. ![](figs/system_settings.png) - Go to the `Network` tab. Adapter 1 should be attached to `NAT`. ![](figs/network_settings.png) - Click `Advanced`, then `Port Forwarding`. We want to set up a port through which we can reach the VM to get files in and out. - Create a new rule by clicking the plus icon. ![](figs/port_forwarding_rules.png) - Set up the new rule the following way: - Name: `SSH` - Protocol: `TCP` - Leave Host IP empty - Host Port: `22222` - Leave Guest IP empty - Guest Port: `22` - Click `Ok` twice to save. Get the [Fedora Netinstall Image](https://download.fedoraproject.org/pub/fedora/linux/releases/29/Workstation/x86_64/iso/Fedora-Workstation-netinst-x86_64-29-1.2.iso) (other resonably recent release should work as well, see [Fedora Workstation Download page](https://getfedora.org/en/workstation/download/)). This DVD image can be [validated](https://getfedora.org/verify) using a SHA256 hashing tool, for example on Unixy OSes by entering the following in a terminal: echo "6554404b66d38b89693232966d9290ed62156e32d1edde4074b1d25c97a7b10e Fedora-Workstation-netinst-x86_64-29-1.2.iso" | sha256sum -c # (must return OK) -Replace `sha256sum` with `shasum` on OSX. +Replace `sha256sum` with `shasum` on macOS. Then start the VM. On the first launch you will be asked for a CD or DVD image. Choose the downloaded ISO. ![](figs/select_startup_disk_fedora.png) Installing Fedora ------------------ This section will explain how to install Fedora on the newly created VM. - Choose the default option. This will start the graphical installer. ![](figs/fedora_install_1_boot_menu.png) - Pick the language, locale and keyboard settings of your choice. You can just go with the defaults or select your own information. - The VM will detect network settings using DHCP, this should all proceed automatically - Afterward, the installer will automatically pick an appropriate *Installation Source* (closest mirror) and starts fetching the package metadata. - Then, click the button for *Software Selection* and choose the *Minimal Install* from as the base environment and no addons for the selected environment. This will reduce installation time and disk usage. - Finally, open the settings for *Installation Destination* and click *Done*. The default settings are just fine. - The *Installation Summary* should look like this: ![](figs/fedora_install_2_summary.png) - Confirm by clicking on *Begin Installation*. - You can leave the root password empty. Otherwise, enter it twice and remember it for later. - Also, create a new user. Name the new user `gitianuser` (the full name doesn't matter, you can leave it empty) - Select *Make this user administrator* to add them to the wheel group. - Choose a user password and enter it twice (remember it for later) ![](figs/fedora_install_3_users.png) ![](figs/fedora_install_4_users.png) - Complete the installation by clicking *Finish configuration*. Then wait for it to complete and select *Reboot*. - If the greeter asks you to install fedora, make sure to remove the ISO: In the running VirtualBox instance, select *Devices* > *Optical Drives* > *Remove disk from virtual drive*. Then reboot again. - After reboot you will have a working Fedora VM. Congratulations! You'll be presented with a screen similar to this. ![](figs/fedora_root_login.png) Connecting to the VM ---------------------- After the VM has booted you can connect to it using SSH, and files can be copied from and to the VM using a SFTP utility. Connect to `localhost`, port `22222` (or the port configured when installing the VM). On Windows you can use [putty](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) and [WinSCP](http://winscp.net/eng/index.php). For example, to connect as `gitianuser` from a Linux command prompt use ``` $ ssh gitianuser@localhost -p 22222 The authenticity of host '[localhost]:22222 ([127.0.0.1]:22222)' can't be established. ECDSA key fingerprint is SHA256:Px5l4jnEItv44YnaESVlPMTu9gPYopIELKok99CjCvo. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added '[localhost]:22222' (ECDSA) to the list of known hosts. gitianuser@localhost's password: (enter gitianuser password configured during install) [gitianuser@localhost ~]$ ``` Use `sudo` to execute commands as root. diff --git a/doc/init.md b/doc/init.md index e3db5b05ef..e1796860e6 100644 --- a/doc/init.md +++ b/doc/init.md @@ -1,125 +1,125 @@ Sample init scripts and service configuration for bitcoind ========================================================== Sample scripts and configuration files for systemd, Upstart and OpenRC can be found in the contrib/init folder. contrib/init/bitcoind.service: systemd service unit configuration contrib/init/bitcoind.openrc: OpenRC compatible SysV style init script contrib/init/bitcoind.openrcconf: OpenRC conf.d file contrib/init/bitcoind.conf: Upstart service configuration file contrib/init/bitcoind.init: CentOS compatible SysV style init script 1. 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. 2. Configuration --------------------------------- At a bare minimum, bitcoind requires that the rpcpassword setting be set when running as a daemon. If the configuration file does not exist or this setting is not set, bitcoind will shutdown promptly after startup. This password does not have to be remembered or typed as it is mostly used as a fixed token that bitcoind and client programs read from the configuration file, however it is recommended that a strong and secure password be used as this password is security critical to securing the wallet should the wallet be enabled. If bitcoind is run with the "-server" flag (set by default), and no rpcpassword is set, it will use a special cookie file for authentication. The cookie is generated with random content when the daemon starts, and deleted when it exits. Read access to this file controls who can access it through RPC. By default the cookie is stored in the data directory, but it's location can be overridden with the option '-rpccookiefile'. This allows for running bitcoind without having to do any manual configuration. `conf`, `pid`, and `wallet` accept relative paths which are interpreted as relative to the data directory. `wallet` *only* supports relative paths. For an example configuration file that describes the configuration settings, see `contrib/debian/examples/bitcoin.conf`. 3. Paths --------------------------------- 3a) Linux All three configurations assume several paths that might need to be adjusted. Binary: `/usr/bin/bitcoind` Configuration file: `/etc/bitcoin/bitcoin.conf` Data directory: `/var/lib/bitcoind` PID file: `/var/run/bitcoind/bitcoind.pid` (OpenRC and Upstart) or `/var/lib/bitcoind/bitcoind.pid` (systemd) Lock file: `/var/lock/subsys/bitcoind` (CentOS) The configuration file, PID directory (if applicable) and data directory should all be owned by the bitcoin user and group. It is advised for security 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. -3b) Mac OS X +3b) macOS Binary: `/usr/local/bin/bitcoind` Configuration file: `~/Library/Application Support/Bitcoin/bitcoin.conf` Data directory: `~/Library/Application Support/Bitcoin` Lock file: `~/Library/Application Support/Bitcoin/.lock` 4. Installing Service Configuration ----------------------------------- 4a) systemd Installing this .service file consists of just copying it to /usr/lib/systemd/system directory, followed by the command `systemctl daemon-reload` in order to update running systemd configuration. To test, run `systemctl start bitcoind` and to enable for system startup run `systemctl enable bitcoind` 4b) OpenRC Rename bitcoind.openrc to bitcoind and drop it in /etc/init.d. Double check ownership and permissions and make it executable. Test it with `/etc/init.d/bitcoind start` and configure it to run on startup with `rc-update add bitcoind` 4c) Upstart (for Debian/Ubuntu based distributions) Drop bitcoind.conf in /etc/init. Test by running `service bitcoind start` it will automatically start on reboot. NOTE: This script is incompatible with CentOS 5 and Amazon Linux 2014 as they use old versions of Upstart and do not supply the start-stop-daemon utility. 4d) CentOS Copy bitcoind.init to /etc/init.d/bitcoind. Test by running `service bitcoind start`. 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. -4e) Mac OS X +4e) macOS Copy org.bitcoin.bitcoind.plist into ~/Library/LaunchAgents. Load the launch agent by running `launchctl load ~/Library/LaunchAgents/org.bitcoin.bitcoind.plist`. This Launch Agent will cause bitcoind to start whenever the user logs in. NOTE: This approach is intended for those wanting to run bitcoind as the current user. You will need to modify org.bitcoin.bitcoind.plist if you intend to use it as a Launch Daemon with a dedicated bitcoin user. 5. Auto-respawn ----------------------------------- Auto respawning is currently only configured for Upstart and systemd. Reasonable defaults have been chosen but YMMV. diff --git a/src/qt/README.md b/src/qt/README.md index 824055230d..554cc1eaf0 100644 --- a/src/qt/README.md +++ b/src/qt/README.md @@ -1,95 +1,95 @@ This directory contains the BitcoinQT graphical user interface (GUI). It uses the cross platform framework [QT](https://www1.qt.io/developers/). The current precise version for QT 5 is specified in [qt.mk](/depends/packages/qt.mk). ## Compile and run -See build instructions ([OSX](/doc/build-osx.md), [Windows](/doc/build-windows.md), [Unix](/doc/build-unix.md), etc). +See build instructions ([macOS](/doc/build-osx.md), [Windows](/doc/build-windows.md), [Unix](/doc/build-unix.md), etc). To run: ```sh ./src/qt/bitcoin-qt ``` ## Files and directories ### forms Contains [Designer UI](http://doc.qt.io/qt-5.9/designer-using-a-ui-file.html) files. They are created with [Qt Creator](#use-qt-Creator-as IDE), but can be edited using any text editor. ### locale Contains translations. They are periodically updated. The process is described [here](/doc/translation_process.md). ### res Resources such as the icon. ### test Tests. ### bitcoingui.(h/cpp) Represents the main window of the Bitcoin UI. ### \*model.(h/cpp) The model. When it has a corresponding controller, it generally inherits from [QAbstractTableModel](http://doc.qt.io/qt-5/qabstracttablemodel.html). Models that are used by controllers as helpers inherit from other QT classes like [QValidator](http://doc.qt.io/qt-5/qvalidator.html). ClientModel is used by the main application `bitcoingui` and several models like `peertablemodel`. ### \*page.(h/cpp) A controller. `:NAMEpage.cpp` generally includes `:NAMEmodel.h` and `forms/:NAME.page.ui` with a similar `:NAME`. ### \*dialog.(h/cpp) Various dialogs, e.g. to open a URL. Inherit from [QDialog](http://doc.qt.io/qt-5.5/qdialog.html). ### paymentserver.(h/cpp) Used to process BIP21 and BIP70 payment URI / requests. Also handles URI based application switching (e.g. when following a bitcoincash:... link from a browser). ### walletview.(h/cpp) Represents the view to a single wallet. ### Other .h/cpp files * UI elements like BitcoinAmountField, which inherit from QWidget. * `bitcoinstrings.cpp`: automatically generated * `bitcoinunits.(h/cpp)`: BCH / mBCH / etc handling * `callback.h` * `guiconstants.h`: UI colors, app name, etc * `guiutil.h`: several helper functions * `macdockiconhandler.(h/cpp)` -* `macdockiconhandler.(h/cpp)`: display notifications in OSX +* `macdockiconhandler.(h/cpp)`: display notifications in macOS ## Contribute See [CONTRIBUTING.md](/CONTRIBUTING.md) for general guidelines. Specifically for QT: * don't change `local/bitcoin_en.ts`; this happens [automatically](/doc/translation_process.md#writing-code-with-translations) ## Using Qt Creator as IDE You can use Qt Creator as an IDE. This is especially useful if you want to change the UI layout. Download and install the community edition of [Qt Creator](https://www.qt.io/download/). Uncheck everything except Qt Creator during the installation process. -Instructions for OSX: +Instructions for macOS: -1. Make sure you installed everything through Homebrew mentioned in the [OSX build instructions](/docs/build-osx.md) +1. Make sure you installed everything through Homebrew mentioned in the [macOS build instructions](/doc/build-osx.md) 2. Use `./configure` with the `--enable-debug` flag 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 installation) 10. Start debugging with Qt Creator (you might need to the executable to "bitcoin-qt" under "Run", which is where you can also add command line arguments)