From 53b5347a3b92edb783687a8e37e886f7eadbf0f5 Mon Sep 17 00:00:00 2001 From: Mike Ellery Date: Fri, 19 Jan 2018 09:05:02 -0800 Subject: [PATCH 1/2] Update macos build instructions: Added workaround for include path order anomaly with Xcode (discovered while testing the xcode build instructions) --- Builds/CMake/CMakeFuncs.cmake | 7 +- Builds/XCode/README.md | 183 ------------------------------ Builds/macos/README.md | 206 ++++++++++++++++++++++++++++++++++ 3 files changed, 212 insertions(+), 184 deletions(-) delete mode 100644 Builds/XCode/README.md create mode 100644 Builds/macos/README.md diff --git a/Builds/CMake/CMakeFuncs.cmake b/Builds/CMake/CMakeFuncs.cmake index 0fc1b0c62c2..e013736557e 100644 --- a/Builds/CMake/CMakeFuncs.cmake +++ b/Builds/CMake/CMakeFuncs.cmake @@ -354,7 +354,12 @@ macro(use_boost) if(NOT Boost_FOUND) message(WARNING "Boost directory found, but not all components. May not be able to build.") endif() - include_directories(SYSTEM ${Boost_INCLUDE_DIRS}) + if (is_xcode) + include_directories(BEFORE ${Boost_INCLUDE_DIRS}) + append_flags(CMAKE_CXX_FLAGS --system-header-prefix="boost/") + else() + include_directories(SYSTEM ${Boost_INCLUDE_DIRS}) + endif() link_directories(${Boost_LIBRARY_DIRS}) else() message(FATAL_ERROR "Boost not found") diff --git a/Builds/XCode/README.md b/Builds/XCode/README.md deleted file mode 100644 index 698fe2187cb..00000000000 --- a/Builds/XCode/README.md +++ /dev/null @@ -1,183 +0,0 @@ -# macos Build Instructions - -## Important - -We don't recommend macos for rippled production use at this time. Currently, the -Ubuntu platform has received the highest level of quality assurance and -testing. That said, macos is suitable for many development/test tasks. - -## Prerequisites - -You'll need macos 10.8 or later - -To clone the source code repository, create branches for inspection or -modification, build rippled using clang, and run the system tests you will need -these software components: - -* [XCode](https://developer.apple.com/xcode/) -* [Homebrew](http://brew.sh/) -* [Git](http://git-scm.com/) -* [CMake](http://cmake.org/) - -## Install Software - -### Install XCode - -If not already installed on your system, download and install XCode using the -appstore or by using [this link](https://developer.apple.com/xcode/). - -For more info, see "Step 1: Download and Install the Command Line Tools" -[here](http://www.moncefbelyamani.com/how-to-install-xcode-homebrew-git-rvm-ruby-on-mac) - -The command line tools can be installed through the terminal with the command: - -``` -xcode-select --install -``` - -### Install Homebrew - -> "[Homebrew](http://brew.sh/) installs the stuff you need that Apple didn’t." - -Open a terminal and type: - -``` -ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -``` - -For more info, see "Step 3: Install Homebrew" -[here](http://www.moncefbelyamani.com/how-to-install-xcode-homebrew-git-rvm-ruby-on-mac) - -### Install Git - -``` -brew update brew install git -``` - -For more info, see "Step 4: Install Git" -[here](http://www.moncefbelyamani.com/how-to-install-xcode-homebrew-git-rvm-ruby-on-mac) - -**NOTE**: To gain full featured access to the -[git-subtree](http://blogs.atlassian.com/2013/05/alternatives-to-git-submodule-git-subtree/) -functionality used in the rippled repository, we suggest Git version 1.8.3.2 or -later. - -### Install Scons - -Requires version 3.6.0 or later - -``` -brew install cmake -``` - -`brew` will generally install the latest stable version of any package, which -should satisfy the cmake minimum version requirement for rippled. - -### Install Package Config - -``` -brew install pkg-config -``` - -## Install/Build/Configure Dependencies - -### Build Google Protocol Buffers Compiler - -Building rippled on osx requires `protoc` version 2.5.x or 2.6.x (later versions -do not work with rippled at this time). - -Download [this](https://github.com/google/protobuf/releases/download/v2.6.1/protobuf-2.6.1.tar.bz2) - -We want to compile protocol buffers with clang/libc++: - -``` -tar xfvj protobuf-2.6.1.tar.bz2 -cd protobuf-2.6.1 -./configure CC=clang CXX=clang++ CXXFLAGS='-std=c++11 -stdlib=libc++ -O3 -g' LDFLAGS='-stdlib=libc++' LIBS="-lc++ -lc++abi" -make -j 4 -sudo make install -``` - -If you have installed `protobuf` via brew - either directly or indirectly as a -dependency of some other package - this is likely to conflict with our specific -version requirements. The simplest way to avoid conflicts is to uninstall it. -`brew ls --versions protobuf` will list any versions of protobuf -you currently have installed. - -### Install OpenSSL - -``` -brew install openssl -``` - -### Build Boost - -We want to compile boost with clang/libc++ - -Download [a release](https://sourceforge.net/projects/boost/files/boost/1.61.0/boost_1_61_0.tar.bz2) - -Extract it to a folder, making note of where, open a terminal, then: - -``` -./bootstrap.sh ./b2 toolset=clang threading=multi runtime-link=static link=static cxxflags="-stdlib=libc++" linkflags="-stdlib=libc++" address-model=64 -``` - -Create an environment variable `BOOST_ROOT` in one of your `rc` files, pointing -to the root of the extracted directory. - -### Clone the rippled repository - -From the terminal - -``` -git clone git@github.com:ripple/rippled.git -cd rippled -``` - -Choose the master branch or one of the tagged releases listed on -[GitHub](https://github.com/ripple/rippled/releases GitHub). - -``` -git checkout master -``` - -or to test the latest release candidate, choose the `release` branch. - -``` -git checkout release -``` - -### Configure Library Paths - -If you didn't persistently set the `BOOST_ROOT` environment variable to the -root of the extracted directory above, then you should set it temporarily. - -For example, assuming your username were `Abigail` and you extracted Boost -1.61.0 in `/Users/Abigail/Downloads/boost_1_61_0`, you would do for any -shell in which you want to build: - -``` -export BOOST_ROOT=/Users/Abigail/Downloads/boost_1_61_0 -``` - -## Build - -``` -mkdir xcode_build && cd xcode_build -cmake -GXcode .. -``` - -There are a number of variables/options that our CMake files support and they -can be added to the above command as needed (e.g. `-Dassert=ON` to enable -asserts) - -After generation succeeds, the xcode project file can be opened and used to -build and debug. - -## Unit Tests (Recommended) - -rippled builds a set of unit tests into the server executable. To run these unit -tests after building, pass the `--unittest` option to the compiled `rippled` -executable. The executable will exit after running the unit tests. - - diff --git a/Builds/macos/README.md b/Builds/macos/README.md new file mode 100644 index 00000000000..bf6bb50141c --- /dev/null +++ b/Builds/macos/README.md @@ -0,0 +1,206 @@ +# macos Build Instructions + +## Important + +We don't recommend macos for rippled production use at this time. Currently, the +Ubuntu platform has received the highest level of quality assurance and +testing. That said, macos is suitable for many development/test tasks. + +## Prerequisites + +You'll need macos 10.8 or later. + +To clone the source code repository, create branches for inspection or +modification, build rippled using clang, and run the system tests you will need +these software components: + +* [XCode](https://developer.apple.com/xcode/) +* [Homebrew](http://brew.sh/) +* [Boost](http://boost.org/) +* other misc utilities and libraries installed via homebrew + +## Install Software + +### Install XCode + +If not already installed on your system, download and install XCode using the +appstore or by using [this link](https://developer.apple.com/xcode/). + +For more info, see "Step 1: Download and Install the Command Line Tools" +[here](http://www.moncefbelyamani.com/how-to-install-xcode-homebrew-git-rvm-ruby-on-mac) + +The command line tools can be installed through the terminal with the command: + +``` +xcode-select --install +``` + +### Install Homebrew + +> "[Homebrew](http://brew.sh/) installs the stuff you need that Apple didn’t." + +Open a terminal and type: + +``` +ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" +``` + +For more info, see "Step 3: Install Homebrew" +[here](http://www.moncefbelyamani.com/how-to-install-xcode-homebrew-git-rvm-ruby-on-mac) + +### Install Dependencies Using Homebrew + +`brew` will generally install the latest stable version of any package, which +should satisfy the the minimum version requirements for rippled. + +``` +brew update +brew install git cmake pkg-config protobuf openssl ninja +``` + +### Build Boost + +We want to compile boost with clang/libc++ + +Download [a release](https://sourceforge.net/projects/boost/files/boost/1.65.1/boost_1_65_1.tar.bz2) + +Extract it to a folder, making note of where, open a terminal, then: + +``` +./bootstrap.sh +./b2 cxxflags="-std=c++14" +``` + +Create an environment variable `BOOST_ROOT` in one of your `rc` files, pointing +to the root of the extracted directory. + +### Dependencies for Building Source Documentation + +Source code documentation is not required for running/debugging rippled. That +said, the documentation contains some helpful information about specific +components of the application. For more information on how to install and run +the necessary components, see [this document](../../docs/README.md) + +## Build + +### Clone the rippled repository + +From a shell: + +``` +git clone git@github.com:ripple/rippled.git +cd rippled +``` + +For a stable release, choose the `master` branch or one of the tagged releases +listed on [GitHub](https://github.com/ripple/rippled/releases GitHub). + +``` +git checkout master +``` + +or to test the latest release candidate, choose the `release` branch. + +``` +git checkout release +``` + +If you are doing development work and want the latest set of untested +features, you can consider using the `develop` branch instead. + +``` +git checkout develop +``` + +### Configure Library Paths + +If you didn't persistently set the `BOOST_ROOT` environment variable to the +root of the extracted directory above, then you should set it temporarily. + +For example, assuming your username were `Abigail` and you extracted Boost +1.65.1 in `/Users/Abigail/Downloads/boost_1_65_1`, you would do for any +shell in which you want to build: + +``` +export BOOST_ROOT=/Users/Abigail/Downloads/boost_1_65_1 +``` + +### Generate and Build + +For simple command line building we recommend using the *Unix Makefile* or +*Ninja* generator with cmake. All builds should be done in a separate directory +from the source tree root (a subdirectory is fine). For example, from the root +of the ripple source tree: + +``` +mkdir my_build +cd my_build +``` + +followed by: + +``` +cmake -G "Unix Makefiles" -Dtarget=clang.debug.unity .. +``` + +or + +``` +cmake -G "Ninja" -Dtarget=clang.debug.unity .. +``` + +The target variable can be adjusted as needed for `debug` vs. `release` and +`unity` vs. `nounity` builds. `unity` builds are typically faster to compile +but run the risk of ODR violations given that multiple compilation units are +merged together at compile time. `nounity` builds will take longer to compile +but align more closely with language standards. + +Once you have generated the build system, you can run the build via cmake: + +``` +cmake --build . -- -j 4 +``` + +the `-j` parameter in this example tells the build tool to compile several +files in parallel. This value should be chosen roughly based on the number of +cores you have available and/or want to use for building. + +When the build completes succesfully, you will have a `rippled` executable in +the current directory, which can be used to connect to the network (when +properly configured) or to run unit tests. + +If you prefer to have an XCode project to use for building, ask CMake to +generate that instead: + +``` +cmake -GXcode .. +``` + +After generation succeeds, the xcode project file can be opened and used to +build/debug. However, just as with other generators, cmake knows how to build +using the xcode project as well: + +``` +cmake --build . -- -jobs 4 +``` + +This will invoke the `xcodebuild` utility to compile the project. See `xcodebuild +--help` for details about build options. + +#### Options During Configuration: + +There are a number of config variables that our CMake files support. These +can be added to the cmake generation command as needed: + +* `-Dassert=ON` to enable asserts +* `-Djemalloc=ON` to enable jemalloc support for heap checking +* `-Dsan=thread` to enable the thread sanitizer with clang +* `-Dsan=address` to enable the address sanitizer with clang + +## Unit Tests (Recommended) + +`rippled` builds a set of unit tests into the server executable. To run these unit +tests after building, pass the `--unittest` option to the compiled `rippled` +executable. The executable will exit with summary info after running the unit tests. + + From cd6d841e211a31d045b4f3b54f99b35dd3bdfbe9 Mon Sep 17 00:00:00 2001 From: Mike Ellery Date: Tue, 23 Jan 2018 16:01:15 -0800 Subject: [PATCH 2/2] [FOLD] Fix link and title for external homebrew info --- Builds/macos/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Builds/macos/README.md b/Builds/macos/README.md index bf6bb50141c..ec68ccdaafd 100644 --- a/Builds/macos/README.md +++ b/Builds/macos/README.md @@ -45,8 +45,8 @@ Open a terminal and type: ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" ``` -For more info, see "Step 3: Install Homebrew" -[here](http://www.moncefbelyamani.com/how-to-install-xcode-homebrew-git-rvm-ruby-on-mac) +For more info, see "Step 2: Install Homebrew" +[here](http://www.moncefbelyamani.com/how-to-install-xcode-homebrew-git-rvm-ruby-on-mac#step-2) ### Install Dependencies Using Homebrew