forked from pingcap/tiflash
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update build section in README (pingcap#4006)
- Loading branch information
1 parent
982f3c3
commit c30afc6
Showing
1 changed file
with
147 additions
and
79 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -7,85 +7,71 @@ TiFlash stores data in columnar format and synchronizes data updates in real-tim | |
|
|
||
| TiFlash repository is based on the early version of [ClickHouse](https://github.com/ClickHouse/ClickHouse/tree/30fcaeb2a3fff1bf894aae9c776bed7fd83f783f). We appreciate the excellent work of ClickHouse team. | ||
|
|
||
| ## Building TiFlash | ||
| ## Build TiFlash | ||
|
|
||
| ### Prerequisites | ||
| TiFlash supports building on the following hardware architectures: | ||
| * x86-64/amd64 | ||
| * aarch64 | ||
|
|
||
| - CMake 3.13.2+ | ||
| - clang-format 12.0.0+ | ||
| - Python 3.0+ | ||
| - Rust | ||
| - `curl https://sh.rustup.rs -sSf | sh -s -- -y --profile minimal --default-toolchain nightly` | ||
| - `source $HOME/.cargo/env` | ||
| - Apple Clang 12.0.0 for MacOS | ||
| - Clang 13.0.0 for Linux | ||
| And the following operating systems: | ||
| * Linux | ||
| * MacOS | ||
|
|
||
| ### Checkout Source Code | ||
|
|
||
| ``` | ||
| # WORKSPACE | ||
| $ git clone --recursive https://github.com/pingcap/tics.git | ||
| ``` | ||
| Assume `$WORKSPACE` to be the directory under which the TiFlash repo is placed. | ||
|
|
||
| ### Build Options [Optional] | ||
| ```bash | ||
| cd $WORKSPACE | ||
| git clone --recursive https://github.com/pingcap/tics.git | ||
| ``` | ||
|
|
||
| TiFlash has several build options to tweak the build for different purposes. | ||
| **Basically all these options have proper default values so you shouldn't experience troubles if you skip all this paragraph.** | ||
| ### Prerequisites | ||
|
|
||
| - `CMAKE_BUILD_TYPE`: `DEBUG` / `RELWITHDEBINFO` (default) / `RELEASE` | ||
| - `ENABLE_TESTS`: `ON` / `OFF` (default) | ||
| - `USE_INTERNAL_GRPC_LIBRARY` / `USE_INTERNAL_PROTOBUF_LIBRARY`: `TRUE` (default) / `FALSE` | ||
| - One may want to use prebuilt/system-wide gRPC or Protobuf, set them to `FALSE` so CMake will try to find prebuilt gRPC and Protobuf instead of build the ones from the submodules. | ||
| - Option `PREBUILT_LIBS_ROOT` can be used to guide CMake's searching for them. | ||
| - Note that though these two options can be set individually, it is recommended to set them both because we won't guarantee the compatibility between gRPC and Protobuf in arbitrary versions. | ||
| - `USE_INTERNAL_TIFLASH_PROXY`: `TRUE` (default) / `FALSE` | ||
| - One may want to use external TiFlash proxy, e.g., if he is developing TiFlash proxy (https://github.com/pingcap/tidb-engine-ext) together with TiFlash. | ||
| - Usually need to be combined with `PREBUILT_LIBS_ROOT="<PATH_TO_YOUR_OWN_TIFLASH_PROXY_REPO>..."`. | ||
| - It assumes the `<PATH_TO_YOUR_OWN_TIFLASH_PROXY_REPO>` has the same directory structure as the TiFlash proxy submodule in TiFlash, i.e.: | ||
| - Header files are under directory `<PATH_TO_YOUR_OWN_TIFLASH_PROXY_REPO>/raftstore-proxy/ffi/src`. | ||
| - Built library is under directory `<PATH_TO_YOUR_OWN_TIFLASH_PROXY_REPO>/target/release`. | ||
| - `PREBUILT_LIBS_ROOT`: Paths for CMake to search for prebuilt/system-wide libraries | ||
| - Can be specified with multiple values, seperated by `;`. | ||
| The following packages are needed for all platforms: | ||
| - CMake 3.13.2+ | ||
| - Rust | ||
| ```bash | ||
| curl https://sh.rustup.rs -sSf | sh -s -- -y --profile minimal --default-toolchain nightly | ||
| source $HOME/.cargo/env | ||
| ``` | ||
| - Python 3.0+ | ||
| - Ninja or GNU Make | ||
|
|
||
| These options apply to all the following platforms, take them as needed, and at your own risk. | ||
| The following are platform-specific prerequisites. | ||
|
|
||
| ### Build TiFlash on MacOS | ||
| #### Linux | ||
|
|
||
| ``` | ||
| # WORKSPACE/tics | ||
| $ rm -rf build | ||
| $ mkdir -p build | ||
| $ pushd build | ||
| $ cmake .. | ||
| $ make tiflash | ||
| $ popd | ||
| ``` | ||
| Now you will get TiFlash binary under `WORKSPACE/tics/build/dbms/src/Server/tiflash`. | ||
| TiFlash can be built using either LLVM or GCC toolchain on Linux. LLVM toolchain is our official one for releasing. | ||
| > But for GCC, only GCC 7.x is supported as far, and is not planned to be a long term support. So it may get broken some day, silently. | ||
| ### Build TiFlash on Linux | ||
| ##### LLVM 13.0.0+ | ||
|
|
||
| TiFlash compiles in full LLVM environment (libc++/libc++abi/libunwind/compiler-rt) by default. To quickly setup a LLVM environment, you can use TiFlash Development Environment (see `release-centos7-llvm/env`). Or you can also use system-wise toolchain if you can install `clang/compiler-rt/libc++/libc++abi` (with development headers, version 13+) in your environment. | ||
| TiFlash compiles using full LLVM toolchain (`clang/compiler-rt/libc++/libc++abi`) by default. | ||
| To quickly set up a LLVM environment, you can use TiFlash Development Environment (short as TiFlash Env, see `release-centos7-llvm/env`). | ||
| Or you can also use system-wise toolchain if you can install `clang/compiler-rt/libc++/libc++abi` in your environment. | ||
|
|
||
| #### Option 1: TiFlash Env | ||
| ###### TiFlash Env | ||
|
|
||
| > for faster access of precompiled package in internal network, you can use [this link](http://fileserver.pingcap.net/download/development/tiflash-env/v1.0.0/tfilash-env-x86_64.tar.xz) | ||
| > For faster access to precompiled package in internal network, you can use [this link](http://fileserver.pingcap.net/download/development/tiflash-env/v1.0.0/tiflash-env-x86_64.tar.xz). | ||
| The development environment can be easily created with following commands (`docker` and `tar xz` are needed): | ||
| TiFlash Env can be created with the following commands (`docker` and `tar xz` are needed): | ||
|
|
||
| ``` | ||
| cd release-centos7-llvm/env | ||
| ```bash | ||
| cd $WORKSPACE/tics/release-centos7-llvm/env | ||
| make tiflash-env-$(uname -m).tar.xz | ||
| ``` | ||
| Then copy and uncompress `tiflash-env-$(uname -m).tar.xz` to a suitable place. | ||
|
|
||
| Then copy and uncompress `tiflash-env-$(uname -m).tar.xz` to a suitable place, assuming `$TIFLASH_ENV`. | ||
|
|
||
| To enter the env (before compiling TiFlash): | ||
|
|
||
| ``` | ||
| cd /path/to/tiflash-env | ||
| ```bash | ||
| cd $TIFLASH_ENV | ||
| ./loader | ||
| ``` | ||
|
|
||
| #### Option 2: System-wise Toolchain | ||
| ###### System-wise Toolchain | ||
|
|
||
| - Debian/Ubuntu users: | ||
|
|
||
|
|
@@ -113,31 +99,114 @@ cd /path/to/tiflash-env | |
| curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh | ||
| ``` | ||
|
|
||
| #### Compile TiFlash | ||
| ##### GCC 7.x | ||
|
|
||
| > **WARNING**: This support may not be maintained in the future. | ||
| You can now build tiflash using the following commands: | ||
| TiFlash compiles on GCC 7.x (no older, nor newer) only because it hasn't been broken. If you have GCC 7.x, you are probably fine, for now. | ||
|
|
||
| #### MacOS | ||
|
|
||
| - Apple Clang 12.0.0+ | ||
| - OpenSSL 1.1 | ||
| ```bash | ||
| brew install [email protected] | ||
| ``` | ||
|
|
||
| ### Build | ||
|
|
||
| Assume `$BUILD` to be the directory under which you want to build TiFlash. | ||
|
|
||
| For Ninja: | ||
|
|
||
| ```bash | ||
| cd $BUILD | ||
| cmake $WORKSPACE/tics -Gninja | ||
| ninja tiflash | ||
| ``` | ||
|
|
||
| For GNU Make: | ||
|
|
||
| ```bash | ||
| cd $BUILD | ||
| cmake $WORKSPACE/tics | ||
| make tiflash -j | ||
| ``` | ||
| cd /your/build/dir | ||
| cmake /path/to/tiflash/src/dir -GNinja | ||
| ninja | ||
|
|
||
| After building, you cat get TiFlash binary under `$BUILD/dbms/src/Server/tiflash`. | ||
|
|
||
| ### Build Options | ||
|
|
||
| TiFlash has several build options to tweak the build, mostly for development purposes. | ||
|
|
||
| > **WARNING**: These options SHOULD NOT be tuned for production usage, as they may introduce unexpected build errors and unpredictable runtime behaviors. | ||
| They are all CMake options thus are specified using `-D...=...`s in CMake command line. | ||
|
|
||
| #### Build Types | ||
|
|
||
| - `CMAKE_BUILD_TYPE`: `DEBUG` / `RELWITHDEBINFO` (default) / `RELEASE` | ||
|
|
||
| #### Build with Unit Tests | ||
|
|
||
| - `ENABLE_TESTS`: `ON` / `OFF` (default) | ||
|
|
||
| #### Build with System Libraries | ||
|
|
||
| For local development, it is sometimes handy to use pre-installed third-party libraries in the system, rather than to compile them from sources of the bundled (internal) submodules. | ||
|
|
||
| Options are supplied to control whether to use internal third-party libraries (bundled in TiFlash) or to try using the pre-installed system ones. | ||
|
|
||
| > **WARNING**: It is NOT guaranteed that TiFlash would still build if any of the system libraries are used. | ||
| > Build errors are very likely to happen, almost all the time. | ||
| You can view these options along with their descriptions by running: | ||
|
|
||
| ```bash | ||
| cd $BUILD | ||
| cmake -LH | grep "USE_INTERNAL" -A3 | ||
| ``` | ||
|
|
||
| Now you will get TiFlash binary under `WORKSPACE/tics/build/dbms/src/Server/tiflash`. | ||
| All of these options are default as `ON`, as the names tell, using the internal libraries and build from sources. | ||
|
|
||
| There is another option to append extra paths for CMake to find system libraries: | ||
|
|
||
| - `PREBUILT_LIBS_ROOT`: Default as empty, can be specified with multiple values, seperated by `;` | ||
|
|
||
| Specifically, for [TiFlash proxy](https://github.com/pingcap/tidb-engine-ext): | ||
|
|
||
| - `USE_INTERNAL_TIFLASH_PROXY`: `TRUE` (default) / `FALSE` | ||
| - One may want to use external TiFlash proxy, e.g., if he is developing TiFlash proxy together with TiFlash, assume `$TIFLASH_PROXY_REPO` to be the path to the external TiFlash proxy repo | ||
| - Usually need to be combined with `PREBUILT_LIBS_ROOT=$TIFLASH_PROXY_REPO`, and `$TIFLASH_PROXY_REPO` should have the following directory structure: | ||
| - Header files are under directory `$TIFLASH_PROXY_REPO/raftstore-proxy/ffi/src` | ||
| - Built library is under directory `$TIFLASH_PROXY_REPO/target/release` | ||
|
|
||
| ### IDE Support | ||
|
|
||
| Normally a CMake-based IDE, e.g., Clion and VSCode, should be able to open TiFlash project with no pain as long as the toolchains are properly configured. | ||
|
|
||
| If your toolchain is set up using [TiFlash Env](#tiflash-env), and you may not want to add those libs to your system loader config, you can pass the following CMake options to your IDE: | ||
|
|
||
| #### IDE Support | ||
| Because all shared libs are shipped with `tiflash-env` and you may not add those libs to your system loader config, you may experience difficulties running executables compiled by `tiflash-env` with an IDE like CLion or VSCode. To make life easier, we provide an option `TIFLASH_ENABLE_LLVM_DEVELOPMENT`, which helps you to setup rpaths automatically so that you can run them without entering the env. To do so, you can use the following commands (or setup your IDE toolchain with the flags): | ||
| ``` | ||
| cmake /path/to/tiflash/src/dir \ | ||
| -GNinja \ | ||
| -DENABLE_TESTS=ON \ | ||
| -DTIFLASH_ENABLE_LLVM_DEVELOPMENT=ON \ | ||
| -DCMAKE_PREFIX_PATH=/path/to/tiflash-env/sysroot | ||
| -DTIFLASH_ENABLE_LLVM_DEVELOPMENT=ON -DCMAKE_PREFIX_PATH=$TIFLASH_ENV | ||
| ``` | ||
| Then, you can compile and run tifalsh or tests as normal in your IDE. | ||
|
|
||
| #### Generate LLVM Coverage Report | ||
| Remember that `$TIFLASH_ENV` is a placeholder mentioned in [TiFlash Env](#tiflash-env). | ||
|
|
||
| ## Run Unit Tests | ||
|
|
||
| TBD. | ||
|
|
||
| ## Run Integration Tests | ||
|
|
||
| TBD. | ||
|
|
||
| ## Generate LLVM Coverage Report | ||
|
|
||
| [//]: <> (TODO: This section is not proper for developers outside PingCAP, as it uses docker image only available on internal network.) | ||
| [//]: <> (TODO: Should refine to use local commands rather than docker.) | ||
| To get a coverage report of unit tests, we recommend using the docker image and our scripts. | ||
|
|
||
| ``` | ||
| docker run --rm -it -v /path/to/tiflash/src:/build/tiflash hub.pingcap.net/tiflash/tiflash-llvm-base:amd64 /bin/bash # or aarch64 | ||
| cd /build/tiflash/release-centos7-llvm | ||
|
|
@@ -162,18 +231,17 @@ mkdir -p /build/tiflash/report | |
| genhtml /tiflash/profile/lcov.info -o /build/tiflash/report | ||
| ``` | ||
|
|
||
| ### Notice | ||
| ## Contributing | ||
|
|
||
| Before submitting pull request, please use [format-diff.py](format-diff.py) to format source code, otherwise ci-build may raise error. | ||
| ``` | ||
| # WORKSPACE/tics | ||
| $ python3 format-diff.py --diff_from `git merge-base ${TARGET_REMOTE_BRANCH} HEAD` | ||
| ``` | ||
| Here is the overview of TiFlash architecture [The architecture of TiFlash's distributed storage engine and transaction layer](/docs/design/0000-00-00-architecture-of-distributed-storage-and-transaction.md). | ||
|
|
||
| You can download the `clang-format` from [muttleyxd/clang-tools-static-binaries](https://github.com/muttleyxd/clang-tools-static-binaries/releases). clang-format 12.0.0+ is required. | ||
| See [TiFlash Development Guide](/docs/DEVELOPMENT.md) and [TiFlash Design documents](/docs/design). | ||
|
|
||
| ## Development | ||
| Before submitting a pull request, please use [format-diff.py](format-diff.py) to format source code, otherwise CI build may raise error. | ||
|
|
||
| To start developing TiFlash, see [TiFlash Development Guide](/docs/DEVELOPMENT.md) and [TiFlash Design documents](/docs/design). | ||
| > **NOTE**: It is required to use clang-format 12.0.0+. | ||
| - [The architecture of TiFlash's distributed storage engine and transaction layer](/docs/design/0000-00-00-architecture-of-distributed-storage-and-transaction.md) | ||
| ``` | ||
| cd $WORKSPACE/tics | ||
| python3 format-diff.py --diff_from `git merge-base ${TARGET_REMOTE_BRANCH} HEAD` | ||
| ``` | ||