From ce8f1b0845fe69fef05ff44777c0d11eab3faf3d Mon Sep 17 00:00:00 2001 From: Nathaniel Chin <22572406+nathanielcwm@users.noreply.github.com> Date: Thu, 3 Jun 2021 15:45:06 +0800 Subject: [PATCH] doc: Port newer build documentation from Bitcoin Co-authored-by: Cy Rossignol Port newer commits --- doc/build-freebsd.md | 62 ++++++++++++++++ doc/build-macos.md | 171 +++++++++++++++++++++++++++++++------------ doc/build-openbsd.md | 167 +++++++++++++----------------------------- doc/build-unix.md | 89 ++++++---------------- doc/build-windows.md | 87 +++++++++++----------- 5 files changed, 302 insertions(+), 274 deletions(-) create mode 100644 doc/build-freebsd.md diff --git a/doc/build-freebsd.md b/doc/build-freebsd.md new file mode 100644 index 0000000000..1bf3edd131 --- /dev/null +++ b/doc/build-freebsd.md @@ -0,0 +1,62 @@ +Building on FreeBSD +-------------------- + +**Updated for FreeBSD [12.2](https://www.freebsd.org/releases/12.2R/announce.html)** + +This guide describes how to build gridcoinresearchd, command-line utilities, and GUI on FreeBSD. + +Preparing the Build +-------------------- + +Install the required dependencies the usual way you [install software on FreeBSD](https://www.freebsd.org/doc/en/books/handbook/ports.html) - either with `pkg` or via the Ports collection. The example commands below use `pkg` which is usually run as `root` or via `sudo`. If you want to use `sudo`, and you haven't set it up: [use this guide](http://www.freebsdwiki.net/index.php/Sudo%2C_configuring) to setup `sudo` access on FreeBSD. +#### General Dependencies +```bash +pkg install autoconf automake boost-libs git gmake libevent libtool pkgconf db5 openssl libzip + +``` +--- +#### GUI Dependencies +```bash +pkg install qt5 libqrencode +``` + +--- +#### Test Suite Dependencies +There is an included test suite that is useful for testing code changes when developing. +To run the test suite (recommended), you will need to have Python 3 installed: + +```bash +pkg install python3 +``` + +Clone the repository and cd into it: + +``` bash +git clone https://github.com/gridcoin-community/Gridcoin-Research +cd Gridcoin-Research +git checkout master +``` + +To Build +--------------------- +### 1. Configuration + +There are many ways to configure Gridcoin, here are a few common examples: +##### Wallet Support, No GUI: +This explicitly enables wallet support and disables the GUI. +```bash +./autogen.sh +./configure --with-gui=no --with-incompatible-bdb \ + BDB_LIBS="-ldb_cxx-5" \ + BDB_CFLAGS="-I/usr/local/include/db5" \ + MAKE=gmake +``` + + +### 2. Compile +**Important**: Use `gmake` (the non-GNU `make` will exit with an error). + +```bash +gmake # use "-j N" for N parallel jobs +gmake check # Run tests if Python 3 is available +``` diff --git a/doc/build-macos.md b/doc/build-macos.md index c7a631e449..91cc94408e 100644 --- a/doc/build-macos.md +++ b/doc/build-macos.md @@ -1,67 +1,146 @@ # macOS Build Instructions and Notes +**Updated for MacOS [11.2](https://www.apple.com/macos/big-sur/)** + +This guide describes how to build gridcoinresearchd, command-line utilities, and GUI on macOS + +**Note:** The following is for Intel Macs only! + +## Preparation The commands in this guide should be executed in a Terminal application. -The built-in one is located at: +macOS comes with a built-in Terminal located in: + ``` /Applications/Utilities/Terminal.app ``` +### 1. Xcode Command Line Tools +The Xcode Command Line Tools are a collection of build tools for macOS. +These tools must be installed in order to build Gridcoin from source. -## Preparation -Install the macOS command line tools: +To install, run the following command from your terminal: ```shell xcode-select --install ``` -When the popup appears, click `Install`. +Upon running the command, you should see a popup appear. +Click on `Install` to continue the installation process. + +### 2. Homebrew Package Manager +Homebrew is a package manager for macOS that allows one to install packages from the command line easily. +While several package managers are available for macOS, this guide will focus on Homebrew as it is the most popular. +Since the examples in this guide which walk through the installation of a package will use Homebrew, it is recommended that you install it to follow along. +Otherwise, you can adapt the commands to your package manager of choice. + +To install the Homebrew package manager, see: https://brew.sh -Then install [Homebrew](https://brew.sh). +Note: If you run into issues while installing Homebrew or pulling packages, refer to [Homebrew's troubleshooting page](https://docs.brew.sh/Troubleshooting). +### 3. Install Required Dependencies +The first step is to download the required dependencies. +These dependencies represent the packages required to get a barebones installation up and running. +To install, run the following from your terminal: -## Dependencies ```shell -brew install automake libtool boost miniupnpc openssl@1.1 pkg-config python qt@5 qrencode libzip +brew install automake libtool boost openssl pkg-config libzip ``` -If you run into issues, check [Homebrew's troubleshooting page](https://docs.brew.sh/Troubleshooting). +### 4. Clone Gridcoin repository -If you want to build the disk image with `make deploy` (.dmg / optional), you need RSVG: -```shell -brew install librsvg +`git` should already be installed by default on your system. +Now that all the required dependencies are installed, let's clone the Gridcoin repository to a directory. +All build scripts and commands will run from this directory. + +``` bash +git clone https://github.com/gridcoin-community/Gridcoin-Research +cd Gridcoin-Research +git checkout master ``` -...as well as [`macdeployqtplus`](../contrib/macdeploy/README.md) dependencies: -```shell -pip3 install ds_store mac_alias +### 5. Install Optional Dependencies + +#### Wallet Dependencies +Enabling wallet support requires bdb 4.8 +``` bash +brew install berkeley-db@4 ``` -#### Berkeley DB +--- -It is recommended to use Berkeley DB 4.8. If you have to build it yourself, -you can use [this](/contrib/install_db4.sh) script to install it -like so: +#### GUI Dependencies -```shell -./contrib/install_db4.sh . +###### Qt + +Gridcoin includes a GUI built with the cross-platform Qt Framework. +To compile the GUI, we need to install `qt@5`. +Skip if you don't intend to use the GUI. + +``` bash +brew install qt@5 ``` -from the root of the repository. +Ensure that the `qt@5` package is installed, not the `qt` package. +If 'qt' is installed, the build process will fail. +if installed, remove the `qt` package with the following command: -Also, the Homebrew package could be installed: +``` bash +brew uninstall qt +``` -```shell -brew install berkeley-db4 +Note: Building with Qt binaries downloaded from the Qt website is not officially supported. +See the notes in [Bitcoin#7714](https://github.com/bitcoin/bitcoin/issues/7714). + +###### qrencode + +The GUI can encode addresses in a QR Code. To build in QR support for the GUI, install `qrencode`. +Skip if not using the GUI or don't want QR code functionality. + +``` bash +brew install qrencode ``` +--- -## Build Gridcoin +#### Port Mapping Dependencies -1. Clone the Gridcoin source code: - ```shell - git clone https://github.com/gridcoin-community/Gridcoin-Research - cd Gridcoin-Research - git checkout master - ``` +###### miniupnpc + +miniupnpc may be used for UPnP port mapping. +Skip if you do not need this functionality. + +``` bash +brew install miniupnpc +``` + +--- + +#### Test Suite Dependencies -2. Build Gridcoin: +There is an included test suite that is useful for testing code changes when developing. +To run the test suite (recommended), you will need to have Python 3 installed: + +``` bash +brew install python +``` + +--- + +#### Deploy Dependencies + +You can deploy a `.dmg` containing the Gridcoin application using `make deploy`. +This command depends on a couple of python packages, so it is required that you have `python` installed. + +Ensuring that `python` is installed, you can install the deploy dependencies by running the following commands in your terminal: + +``` bash +brew install librsvg +``` + +``` bash +pip3 install ds_store mac_alias +``` + +## Build Gridcoin + +1. Build Gridcoin: Prepare the assembly code (requires Perl): ```shell @@ -78,34 +157,38 @@ brew install berkeley-db4 ``` You can disable the GUI build by passing `--without-gui` to configure. -3. It is recommended to build and run the unit tests: +2. It is recommended to build and run the unit tests: ```shell make check ``` -4. You can also create a `.dmg` that contains the `.app` bundle (optional): +3. You can also create a `.dmg` that contains the `.app` bundle (optional): ```shell make deploy ``` -5. Testnet participation info is found at [Using Testnet](https://wiki.gridcoin.us/OS_X_Guide#Using_Testnet). - - To open the app in testnet mode: - ```shell - open -a /your/path/to/gridcoinresearch.app --args -testnet - ``` - ## Running The daemon binary is placed in _src/_ and the GUI client is found in _src/qt/_. For example, to run the GUI client for production or testnet: +**Important:** [Please read this before using testnet.](https://gridcoin.us/wiki/testnet) + ```shell ./src/qt/gridcoinresearch ./src/qt/gridcoinresearch -testnet ./src/qt/gridcoinresearch -printtoconsole -debug -testnet ``` +The first time you run Gridcoin, it will start downloading the blockchain. This process could +take several hours. + +By default, blockchain and wallet data files will be stored in: + +``` bash +/Users/${USER}/Library/Application Support/GridcoinResearch +``` + Before running, you may create an empty configuration file: ```shell mkdir -p "/Users/${USER}/Library/Application Support/GridcoinResearch" @@ -115,13 +198,7 @@ touch "/Users/${USER}/Library/Application Support/GridcoinResearch/gridcoinresea chmod 600 "/Users/${USER}/Library/Application Support/GridcoinResearch/gridcoinresearch.conf" ``` -The first time you run Gridcoin, 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: ```shell tail -f $HOME/Library/Application\ Support/GridcoinResearch/debug.log ``` - -## 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/build-openbsd.md b/doc/build-openbsd.md index ef8fcebee8..cd616af48d 100644 --- a/doc/build-openbsd.md +++ b/doc/build-openbsd.md @@ -1,10 +1,8 @@ OpenBSD build guide ====================== -(updated for OpenBSD 6.0) +(updated for OpenBSD 6.9) -This guide describes how to build gridcoinresearchd and command-line utilities on OpenBSD. - -As OpenBSD is most common as a server OS, we will not bother with the GUI. +This guide describes how to build gridcoinresearchd, command-line utilities, and GUI on OpenBSD. Preparation ------------- @@ -12,94 +10,48 @@ Preparation Run the following as root to install the base dependencies for building: ```bash -pkg_add gmake libtool libevent -pkg_add autoconf # (select highest version, e.g. 2.69) -pkg_add automake # (select highest version, e.g. 1.15) -pkg_add python # (select highest version, e.g. 3.6) +pkg_add git gmake libtool libevent boost libzip +pkg_add qt5 libqrencode # (optional for enabling the GUI) +pkg_add autoconf # (select highest version, e.g. 2.71) +pkg_add automake # (select highest version, e.g. 1.16) +pkg_add python # (select highest version, e.g. 3.9) ``` -The default C++ compiler that comes with OpenBSD 5.9 is g++ 4.2. This version is old (from 2007), and is not able to compile the current version of Bitcoin Core, primarily as it has no C++11 support, but even before there were issues. So here we will be installing a newer compiler. +**Important**: From OpenBSD 6.2 onwards a C++11-supporting clang compiler is +part of the base image, and while building it is necessary to make sure that +this compiler is used and not ancient g++ 4.2.1. This is done by appending +`CC=cc CC_FOR_BUILD=cc CXX=c++` to configuration commands. Mixing different +compilers within the same executable will result in errors. -GCC -------- +### Building BerkeleyDB -You can install a newer version of gcc with: +It is recommended to use Berkeley DB 4.8. You cannot use the BerkeleyDB library +from ports, for the same reason as boost above (g++/libstd++ incompatibility). +If you have to build it yourself, you can use [the installation script included +in contrib/](/contrib/install_db4.sh) like so: ```bash -pkg_add g++ # (select newest 4.x version, e.g. 4.9.3) -``` - -This compiler will not overwrite the system compiler, it will be installed as `egcc` and `eg++` in `/usr/local/bin`. - -### Building boost - -Do not use `pkg_add boost`! The boost version installed thus is compiled using the `g++` compiler not `eg++`, which will result in a conflict between `/usr/local/lib/libestdc++.so.XX.0` and `/usr/lib/libstdc++.so.XX.0`, resulting in a test crash: - - test_bitcoin:/usr/lib/libstdc++.so.57.0: /usr/local/lib/libestdc++.so.17.0 : WARNING: symbol(_ZN11__gnu_debug17_S_debug_me ssagesE) size mismatch, relink your program - ... - Segmentation fault (core dumped) - -This makes it necessary to build boost, or at least the parts used by Gridcoin, manually: - +./contrib/install_db4.sh `pwd` CC=cc CXX=c++ ``` -# Pick some path to install boost to, here we create a directory within the bitcoin directory -BITCOIN_ROOT=$(pwd) -BOOST_PREFIX="${BITCOIN_ROOT}/boost" -mkdir -p $BOOST_PREFIX - -# Fetch the source and verify that it is not tampered with -curl -o boost_1_61_0.tar.bz2 http://heanet.dl.sourceforge.net/project/boost/boost/1.61.0/boost_1_61_0.tar.bz2 -echo 'a547bd06c2fd9a71ba1d169d9cf0339da7ebf4753849a8f7d6fdb8feee99b640 boost_1_61_0.tar.bz2' | sha256 -c -# MUST output: (SHA256) boost_1_61_0.tar.bz2: OK -tar -xjf boost_1_61_0.tar.bz2 - -# Boost 1.61 needs one small patch for OpenBSD -cd boost_1_61_0 -# Also here: https://gist.githubusercontent.com/laanwj/bf359281dc319b8ff2e1/raw/92250de8404b97bb99d72ab898f4a8cb35ae1ea3/patch-boost_test_impl_execution_monitor_ipp.patch -patch -p0 < /usr/ports/devel/boost/patches/patch-boost_test_impl_execution_monitor_ipp - -# Build w/ minimum configuration necessary for bitcoin -echo 'using gcc : : eg++ : "-fvisibility=hidden -fPIC" "" "ar" "strip" "ranlib" "" : ;' > user-config.jam -config_opts="runtime-link=shared threadapi=pthread threading=multi link=static variant=release --layout=tagged --build-type=complete --user-config=user-config.jam -sNO_BZIP2=1" -./bootstrap.sh --without-icu --with-libraries=filesystem,system,thread,test -./b2 -d2 -j2 -d1 ${config_opts} --prefix=${BOOST_PREFIX} stage -./b2 -d0 -j4 ${config_opts} --prefix=${BOOST_PREFIX} install -``` - -### Building BerkeleyDB -BerkeleyDB is only necessary for the wallet functionality. To skip this, pass `--disable-wallet` to `./configure`. - -See "Berkeley DB" in [build-unix.md](build-unix.md) for instructions on how to build BerkeleyDB 4.8. -You cannot use the BerkeleyDB library from ports, for the same reason as boost above (g++/libstd++ incompatibility). +from the root of the repository. Then set `BDB_PREFIX` for the next section: ```bash -# Pick some path to install BDB to, here we create a directory within the bitcoin directory -BITCOIN_ROOT=$(pwd) -BDB_PREFIX="${BITCOIN_ROOT}/db4" -mkdir -p $BDB_PREFIX - -# Fetch the source and verify that it is not tampered with -curl -o db-4.8.30.NC.tar.gz 'http://download.oracle.com/berkeley-db/db-4.8.30.NC.tar.gz' -echo '12edc0df75bf9abd7f82f821795bcee50f42cb2e5f76a6a281b85732798364ef db-4.8.30.NC.tar.gz' | sha256 -c -# MUST output: (SHA256) db-4.8.30.NC.tar.gz: OK -tar -xzf db-4.8.30.NC.tar.gz - -# Build the library and install to specified prefix -cd db-4.8.30.NC/build_unix/ -# Note: Do a static build so that it can be embedded into the executable, instead of having to find a .so at runtime -../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX CC=egcc CXX=eg++ CPP=ecpp -make install # do NOT use -jX, this is broken +export BDB_PREFIX="$PWD/db4" ``` -### Resource limits +Resource limits +------------------- + +If the build runs into out-of-memory errors, the instructions in this section +might help. The standard ulimit restrictions in OpenBSD are very strict: data(kbytes) 1572864 -This is, unfortunately, no longer enough to compile some `.cpp` files in the project, -at least with gcc 4.9.3 (see issue https://github.com/bitcoin/bitcoin/issues/6658). +This is, unfortunately, in some cases not enough to compile some `.cpp` files in the project, +(see [Bitcoin#6658](https://github.com/bitcoin/bitcoin/issues/6658)). If your user is in the `staff` group the limit can be raised with: ulimit -d 3000000 @@ -114,57 +66,38 @@ make the change system-wide, change `datasize-cur` and `datasize-max` in Preparation: ```bash -export AUTOCONF_VERSION=2.69 # replace this with the autoconf version that you installed -export AUTOMAKE_VERSION=1.15 # replace this with the automake version that you installed -./autogen.sh -``` -Make sure `BDB_PREFIX` and `BOOST_PREFIX` are set to the appropriate paths from the above steps. +# Replace this with the autoconf version that you installed. Include only +# the major and minor parts of the version: use "2.69" for "autoconf-2.69p2". +export AUTOCONF_VERSION=2.69 -To configure without wallet: -```bash -./configure --disable-wallet --with-gui=no --with-boost=$BOOST_PREFIX \ - CC=egcc CXX=eg++ CPP=ecpp -``` +# Replace this with the automake version that you installed. Include only +# the major and minor parts of the version: use "1.16" for "automake-1.16.1". +export AUTOMAKE_VERSION=1.16 -Build and run the tests: -```bash -gmake # can use -jX here for parallelism -gmake check +./autogen.sh ``` -Clang (not currently working) ------------------------------- - -WARNING: This is outdated, needs to be updated for OpenBSD 6.0 and re-tried. - -Using a newer g++ results in linking the new code to a new libstdc++. -Libraries built with the old g++, will still import the old library. -This gives conflicts, necessitating rebuild of all C++ dependencies of the application. - -With clang this can - at least theoretically - be avoided because it uses the -base system's libstdc++. +Make sure `BDB_PREFIX` and `BOOST_PREFIX` are set to the appropriate paths from the above steps. +To configure with wallet: ```bash -pkg_add llvm boost +./configure --with-gui=no CC=cc CXX=c++ \ + BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \ + BDB_CFLAGS="-I${BDB_PREFIX}/include" \ + MAKE=gmake ``` +To configure with GUI: ```bash -./configure --disable-wallet --with-gui=no CC=clang CXX=clang++ -gmake +./configure --with-gui=yes CC=cc CXX=c++ \ + BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \ + BDB_CFLAGS="-I${BDB_PREFIX}/include" \ + MAKE=gmake ``` -However, this does not appear to work. Compilation succeeds, but link fails -with many 'local symbol discarded' errors: - - local symbol 150: discarded in section `.text._ZN10tinyformat6detail14FormatIterator6finishEv' from libbitcoin_util.a(libbitcoin_util_a-random.o) - local symbol 151: discarded in section `.text._ZN10tinyformat6detail14FormatIterator21streamStateFromFormatERSoRjPKcii' from libbitcoin_util.a(libbitcoin_util_a-random.o) - local symbol 152: discarded in section `.text._ZN10tinyformat6detail12convertToIntIA13_cLb0EE6invokeERA13_Kc' from libbitcoin_util.a(libbitcoin_util_a-random.o) - -According to similar reported errors this is a binutils (ld) issue in 2.15, the -version installed by OpenBSD 5.7: - -- http://openbsd-archive.7691.n7.nabble.com/UPDATE-cppcheck-1-65-td248900.html -- https://llvm.org/bugs/show_bug.cgi?id=9758 - -There is no known workaround for this. +Build and run the tests: +```bash +gmake # use "-j N" here for N parallel jobs +gmake check +``` diff --git a/doc/build-unix.md b/doc/build-unix.md index eb2403a67b..bdac0dbc9c 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -2,7 +2,7 @@ UNIX BUILD NOTES ==================== Some notes on how to build Gridcoin in Unix. -(for OpenBSD specific instructions, see [build-openbsd.md](build-openbsd.md)) +(For BSD specific instructions, see build-*bsd.md in this directory.) Note --------------------- @@ -24,8 +24,8 @@ Clone the repository and cd into it: ```bash git clone https://github.com/gridcoin-community/Gridcoin-Research -git checkout master cd Gridcoin-Research +git checkout master ``` Go to platform specific instructions for the required dependencies below. @@ -35,7 +35,7 @@ To Build ```bash ./autogen.sh ./configure -make -j$(nproc --all) # core count by default, could be changed to the desired amount of threads +make # use "-j N" for N parallel jobs make install # optional ``` @@ -45,7 +45,7 @@ Or, to keep the source directory clean: mkdir build cd build ../configure -make -j$(nproc --all) # core count by default, could be changed to the desired amount of threads +make # use "-j N" for N parallel jobs ``` This will build gridcoinresearch (Qt client) as well if the dependencies are met. @@ -78,31 +78,33 @@ tuned to conserve memory with additional CXXFLAGS: ./configure CXXFLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768" +Alternatively, clang (often less resource hungry) can be used instead of gcc, which is used by default: + + ./configure CXX=clang++ CC=clang + + Dependency Build Instructions: Ubuntu & Debian ---------------------------------------------- Build requirements: sudo apt-get install build-essential libtool autotools-dev automake pkg-config libssl-dev libevent-dev bsdmainutils libzip-dev libfreetype-dev -Options when installing required Boost library files: - -1. On at least Ubuntu 14.04+ and Debian 7+ there are generic names for the -individual boost development packages, so the following can be used to only -install necessary parts of boost: +Now, you can either build from self-compiled [depends](/depends/README.md) or install the required dependencies: sudo apt-get install libboost-system-dev libboost-filesystem-dev libboost-test-dev libboost-thread-dev libboost-iostreams-dev libcurl4-gnutls-dev -2. If that doesn't work, you can install all boost development packages with: - - sudo apt-get install libboost-all-dev - BerkeleyDB is required for the wallet. +Ubuntu and Debian have their own `libdb-dev` and `libdb++-dev` packages, but these will install +Berkeley DB 5.1 or later. This will break binary wallet compatibility with the distributed executables, which +are based on BerkeleyDB 4.8. If you do not care about wallet compatibility, +pass `--with-incompatible-bdb` to configure. + **For Ubuntu only:** db4.8 packages are available [here](https://launchpad.net/~bitcoin/+archive/bitcoin). You can add the repository and install using the following commands: -**For Ubuntu 18.04 and earlier versions** +**For Ubuntu 18.04** sudo apt-get install software-properties-common sudo add-apt-repository ppa:bitcoin/bitcoin @@ -111,7 +113,7 @@ You can add the repository and install using the following commands: **For Ubuntu 20.04+ or Debian 10/Raspberry Pi** - For Ubuntu 20.04+ users the db4.8 is not available on the official PPA. Use the script in contrib/install_db4.sh + For Ubuntu 20.04+ users the db4.8 is not available on the Bitcoin PPA. Use the script in contrib/install_db4.sh to compile and install db4.8. You can use the script in your build location. For example if your build location is Gridcoin-Research/ then `./contrib/install_db4.sh $PWD`. Once complete, when running `./configure`, you must tell it about the location of the compiled db4.8 which you can do with the export line given when install_db4.sh @@ -120,12 +122,6 @@ You can add the repository and install using the following commands: followed by whatever other flags you want such as --without-gui. -Ubuntu and Debian have their own libdb-dev and libdb++-dev packages, but these will install -BerkeleyDB 5.1 or later, which break binary wallet compatibility with the distributed executables which -are based on BerkeleyDB 4.8. If you do not care about wallet compatibility, -pass `--with-incompatible-bdb` to configure. - -See the section "Disable-wallet mode" to build Gridcoin without wallet. Optional (see --with-miniupnpc and --enable-upnp-default): @@ -134,11 +130,11 @@ Optional (see --with-miniupnpc and --enable-upnp-default): Dependencies for the GUI: Ubuntu & Debian ----------------------------------------- -If you want to build gridcoinresearch, make sure that the required packages for Qt development +If you want to build Gridcoin with UI, make sure that the required packages for Qt development are installed. Qt 5 is necessary to build the GUI. To build without GUI pass `--without-gui` to configure. -To build with Qt 5 (recommended) you need the following: +To build with Qt 5 you need the following: sudo apt-get install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler @@ -156,12 +152,6 @@ Build requirements: sudo zypper install -t pattern devel_basis sudo zypper install libtool automake autoconf pkg-config libopenssl-devel libevent-devel -Options when installing required Boost library files: - -1. On at least openSUSE Leap there are generic names for the -individual boost development packages, so the following can be used to only -install necessary parts of boost: - Tumbleweed: sudo zypper install libboost_system1_*_0-devel libboost_filesystem1_*_0-devel libboost_test1_*_0-devel libboost_thread1_*_0-devel @@ -170,15 +160,15 @@ Leap: sudo zypper install libboost_system1_61_0-devel libboost_filesystem1_61_0-devel libboost_test1_61_0-devel libboost_thread1_61_0-devel -2. If that doesn't work, you can install all boost development packages with: +If that doesn't work, you can install all boost development packages with: Leap: - sudo zypper install boost_1_61-devel + sudo zypper install boost_1_61-devel BerkeleyDB is required for the wallet. - sudo zypper install libdb-4_8-devel + sudo zypper install libdb-4_8-devel Optional (see --with-miniupnpc and --enable-upnp-default): @@ -191,7 +181,7 @@ If you want to build gridcoinresearch, make sure that the required packages for are installed. Qt 5 is necessary to build the GUI. To build without GUI pass `--without-gui` to configure. -To build with Qt 5 (recommended) you need the following: +To build with Qt 5 you need the following: sudo zypper install libQt5Gui5 libQt5Core5 libQt5DBus5 libQt5Network-devel libqt5-qttools-devel libqt5-qttools @@ -275,36 +265,3 @@ For 32 bit configure with: 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): - - pkg install db5 - -This will give a warning "configure: WARNING: Found Berkeley DB other -than 4.8; wallets opened by this build will not be portable!", but as FreeBSD never -had a binary release, this may not matter. If backwards compatibility -with 4.8-built Gridcoin is needed follow the steps under "Berkeley DB" above. - -Then build using: - - ./autogen.sh - ./configure --with-incompatible-bdb BDB_CFLAGS="-I/usr/local/include/db5" BDB_LIBS="-L/usr/local/lib -ldb_cxx-5" - 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-windows.md b/doc/build-windows.md index c0cbf9d727..041b387df8 100644 --- a/doc/build-windows.md +++ b/doc/build-windows.md @@ -5,10 +5,10 @@ Below are some notes on how to build Gridcoin for Windows. The options known to work for building Gridcoin on Windows are: -* On Linux, using the [Mingw-w64](https://mingw-w64.org/doku.php) cross compiler tool chain. Ubuntu Bionic 18.04 is required +* On Linux, using the [Mingw-w64](https://mingw-w64.org/doku.php) cross compiler tool chain. and is the platform used to build the Gridcoin Windows release binaries. -* On Windows, using [Windows -Subsystem for Linux (WSL)](https://docs.microsoft.com/windows/wsl/about) and the Mingw-w64 cross compiler tool chain. + +* On Windows, using [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/windows/wsl/about) and Mingw-w64. * On Windows, using a native compiler tool chain such as [Visual Studio](https://www.visualstudio.com). Other options which may work, but which have not been extensively tested are (please contribute instructions): @@ -18,40 +18,15 @@ Other options which may work, but which have not been extensively tested are (pl Installing Windows Subsystem for Linux --------------------------------------- -With Windows 10, Microsoft has released a new feature named the [Windows -Subsystem for Linux (WSL)](https://docs.microsoft.com/windows/wsl/about). This -feature allows you to run a bash shell directly on Windows in an Ubuntu-based -environment. Within this environment you can cross compile for Windows without -the need for a separate Linux VM or server. Note that while WSL can be installed with -other Linux variants, such as OpenSUSE, the following instructions have only been -tested with Ubuntu. - -This feature is not supported in versions of Windows prior to Windows 10 or on -Windows Server SKUs. In addition, it is available [only for 64-bit versions of -Windows](https://docs.microsoft.com/windows/wsl/install-win10). - -Full instructions to install WSL are available on the above link. -To install WSL on Windows 10 with Fall Creators Update installed (version >= 16215.0) do the following: - -1. Enable the Windows Subsystem for Linux feature - * Open the Windows Features dialog (`OptionalFeatures.exe`) - * Enable 'Windows Subsystem for Linux' - * Click 'OK' and restart if necessary -2. Install Ubuntu - * Open Microsoft Store and search for "Ubuntu 18.04" or use [this link](https://www.microsoft.com/store/productId/9N9TNGVNDL3Q) - * Click Install -3. Complete Installation - * Open a cmd prompt and type "Ubuntu1804" - * Create a new UNIX user account (this is a separate account from your Windows account) - -After the bash shell is active, you can follow the instructions below, starting -with the "Cross-compilation" section. Compiling the 64-bit version is -recommended, but it is possible to compile the 32-bit version. +Note that while WSL can be installed with +other Linux variants, such as OpenSUSE, the following instructions have only been tested with Ubuntu. + +[Follow the upstream installation instructions, available here](https://docs.microsoft.com/windows/wsl/install-win10). Cross-compilation for Ubuntu and Windows Subsystem for Linux ------------------------------------------------------------ -The steps below can be performed on Ubuntu (including in a VM) or WSL. The depends system +The steps below can be performed on Ubuntu or WSL. The depends system will also work on other Linux distributions, however the commands for installing the toolchain will be different. @@ -61,6 +36,14 @@ First, install the general dependencies: sudo apt upgrade sudo apt install build-essential libtool autotools-dev automake pkg-config bsdmainutils curl git +Then install the mingw-w64 cross-compilation tool chain: + + sudo apt install g++-mingw-w64-x86-64 + +Or the following to build for 32-bit + + sudo apt-get install g++-mingw-w64-i686 mingw-w64-i686-dev + A host toolchain (`build-essential`) is necessary because some dependency packages need to build host utilities that are used in the build process. @@ -71,18 +54,29 @@ If you want to build the windows installer with `make deploy` you need [NSIS](ht Acquire the source in the usual way: git clone https://github.com/gridcoin-community/Gridcoin-Research.git - git checkout master cd Gridcoin-Research + git checkout master ## Building for 64-bit Windows -The first step is to install the mingw-w64 cross-compilation tool chain: +If on Ubuntu set the default `mingw32 g++` compiler option to POSIX[1](#footnote1): - sudo apt install g++-mingw-w64-x86-64 + sudo update-alternatives --config x86_64-w64-mingw32-g++ + +After running the above command, you should see output similar to that below. +Choose the option that ends with `posix`. -Ubuntu Bionic 18.04: +``` +There are 2 choices for the alternative x86_64-w64-mingw32-g++ (providing /usr/bin/x86_64-w64-mingw32-g++). + + Selection Path Priority Status +------------------------------------------------------------ + 0 /usr/bin/x86_64-w64-mingw32-g++-win32 60 auto mode +* 1 /usr/bin/x86_64-w64-mingw32-g++-posix 30 manual mode + 2 /usr/bin/x86_64-w64-mingw32-g++-win32 60 manual mode - sudo update-alternatives --config x86_64-w64-mingw32-g++ # Set the default mingw32 g++ compiler option to posix. +Press to keep the current choice[*], or type selection number: +``` Once the toolchain is installed the build steps are common: @@ -109,13 +103,9 @@ Build using: ## Building for 32-bit Windows -To build executables for Windows 32-bit, install the following dependencies: +If on Ubuntu set the default `mingw32 g++` compiler option to POSIX[1](#footnote1): - sudo apt-get install g++-mingw-w64-i686 mingw-w64-i686-dev - -For Ubuntu Xenial 16.04, Ubuntu Zesty 17.04 and Windows Subsystem for Linux: - - sudo update-alternatives --config i686-w64-mingw32-g++ # Set the default mingw32 g++ compiler option to posix. + sudo update-alternatives --config i686-w64-mingw32-g++ For WSL use: @@ -152,3 +142,12 @@ way. This will install to `c:\workspace\Gridcoin-Research`, for example: You can also create an installer using: make deploy + +Footnotes +--------- +1: Starting from Ubuntu Xenial 16.04, both the 32 and 64 bit Mingw-w64 packages install two different +compiler options to allow a choice between either posix or win32 threads. The default option is win32 threads which is the more +efficient since it will result in binary code that links directly with the Windows kernel32.lib. Unfortunately, the headers +required to support win32 threads conflict with some of the classes in the C++11 standard library, in particular std::mutex. +It's not possible to build the Gridcoin code using the win32 version of the Mingw-w64 cross compilers (at least not without +modifying headers in the Gridcoin source code).