ccache: enable basedir, slopiness, add doc

ccache: enable basedir, slopiness, add doc

Pull Request resolved: #247

5 files changed, 114 insertions, 64 deletions

diff --git a/.github/actions/build/action.yml b/.github/actions/build/action.yml
index acbeb45f10..e7695bda5d 100644
--- a/.github/actions/build/action.yml
+++ b/.github/actions/build/action.yml
@@ -4,6 +4,9 @@ inputs:
   sanitizer:
     required: false
     type: string
+  ccache_remote_path:
+    required: false
+    description: "ccache remote storage definition"
 
 runs:
   using: "composite"
@@ -29,8 +32,9 @@ runs:
       mkdir -p ../build
       cd ../build
       rm -rf *
+      export CONAN_USER_HOME=`realpath .`
       cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
-        -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
+        -DCMAKE_C_COMPILER_LAUNCHER=/usr/local/bin/ccache -DCMAKE_CXX_COMPILER_LAUNCHER=/usr/local/bin/ccache \
         -DCMAKE_TOOLCHAIN_FILE=../ydb/clang.toolchain \
         -DCMAKE_CXX_FLAGS="-g" \
         -DCMAKE_C_FLAGS="-g" \
@@ -39,6 +43,10 @@ runs:
     shell: bash
     run: |
       ccache -z
+      export CCACHE_BASEDIR=`realpath ..`
+      export CCACHE_REMOTE_STORAGE="${{inputs.ccache_remote_path}}"
+      export CCACHE_SLOPPINESS=locale
+      export CCACHE_MAXSIZE=50G
       cd ../build
       ninja
       ccache -s
diff --git a/.github/workflows/build_and_test_ondemand.yml b/.github/workflows/build_and_test_ondemand.yml
index 984411f65e..48d7921e00 100644
--- a/.github/workflows/build_and_test_ondemand.yml
+++ b/.github/workflows/build_and_test_ondemand.yml
@@ -94,6 +94,7 @@ jobs:
       uses: ./.github/actions/build
       with: 
         sanitizer: ${{ inputs.sanitizer }}
+        ccache_remote_path: ${{ vars.REMOTE_CACHE_URL && format('http://{0}{1}', secrets.rc_auth, vars.REMOTE_CACHE_URL) || ''}}
     - name: Run tests
       uses: ./.github/actions/test
       with:
diff --git a/.github/workflows/build_and_test_provisioned.yml b/.github/workflows/build_and_test_provisioned.yml
index 6ef13f8a7b..5d044d1579 100644
--- a/.github/workflows/build_and_test_provisioned.yml
+++ b/.github/workflows/build_and_test_provisioned.yml
@@ -54,6 +54,7 @@ jobs:
       if: inputs.run_build
       with: 
         sanitizer: ${{ inputs.sanitizer }}
+        ccache_remote_path: ${{ vars.REMOTE_CACHE_URL && format('http://{0}{1}', secrets.rc_auth, vars.REMOTE_CACHE_URL) || ''}}
     - name: Run tests
       uses: ./.github/actions/test
       with: 
diff --git a/.github/workflows/prepare_vm_for_build.yml b/.github/workflows/prepare_vm_for_build.yml
index 778d03b1e3..24d8b3e5b7 100644
--- a/.github/workflows/prepare_vm_for_build.yml
+++ b/.github/workflows/prepare_vm_for_build.yml
@@ -35,21 +35,10 @@ jobs:
       run: |
         wget https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_386 -O ~/allurectl
         chmod +x ~/allurectl
-    - name: Checkout ccache
-      uses: actions/checkout@v3
-      with:
-        repository: ccache/ccache
-        path: ccache
-    - name: Build ccache
+    - name: install ccache
       shell: bash
       run: |
-        pwd
-        cd ccache
-        mkdir build && cd build
-        cmake -DCMAKE_BUILD_TYPE=Release ..
-        make -j32
-        make install
-        mkdir -p ~/.ccache
-        echo 'remote_storage = http://${{secrets.rc_auth}}${{vars.REMOTE_CACHE_URL}}' > /root/.ccache/ccache.conf
-        echo 'max_size = 50G' >> /root/.ccache/ccache.conf
-        ccache -p
+        export CCACHE_VERSION=4.8.1
+        curl -L https://github.com/ccache/ccache/releases/download/v${CCACHE_VERSION}/ccache-${CCACHE_VERSION}-linux-x86_64.tar.xz \
+          | tar -xJ -C /usr/local/bin/ --strip-components=1 --no-same-owner ccache-${CCACHE_VERSION}-linux-x86_64/ccache
+        ls -la /usr/local/bin/ccache
\ No newline at end of file
diff --git a/BUILD.md b/BUILD.md
index ee51b899c3..6cb6d2c2a0 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -1,6 +1,6 @@
-## Building YDB from sources
+# Building YDB from sources
 
-#### Build Requirements
+## Build Requirements
  We have tested YDB builds using Ubuntu 18.04 and Ubuntu 20.04. Other Linux distributions are likely to work, but additional effort may be needed. Only x86_64 Linux is currently supported.
 
  Below is a list of packages that need to be installed before building YDB. 'How to Build' section contains step by step instructions to obtain these packages.
@@ -19,71 +19,122 @@
 
  We run multiple clang instances in parallel to speed up the process by default. Each instance of clang may use up to 1GB of RAM, and linking the binary may use up to 16GB of RAM, please make sure your build host has enough resources.
 
-#### Runtime Requirements
+## Runtime Requirements
  The following packages are required to run ydbd server:
 
  - libidn11
  - libaio
 
-#### How to Build
+# How to Build
 
-1. Add repositories for dependencies
+## Add repositories for dependencies
 
-    Note: the following repositories are required for **Ubuntu 18.04 and Ubuntu 20.04**. You may skip this step if your GNU/Linux distribution has all required packages in their default repository.
-    For more information please read your distribution documentation and https://apt.llvm.org as well as https://apt.kitware.com/
-     ```
-    wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
-    wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc | sudo apt-key add -
-    echo "deb http://apt.kitware.com/ubuntu/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/kitware.list >/dev/null
-    echo "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/llvm.list >/dev/null
+Note: the following repositories are required for **Ubuntu 18.04 and Ubuntu 20.04**. You may skip this step if your GNU/Linux distribution has all required packages in their default repository.
+For more information please read your distribution documentation and https://apt.llvm.org as well as https://apt.kitware.com/
+```bash
+wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
+wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc | sudo apt-key add -
+echo "deb http://apt.kitware.com/ubuntu/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/kitware.list >/dev/null
+echo "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/llvm.list >/dev/null
 
-    sudo apt-get update
-     ```
+sudo apt-get update
+```
 
-   For Ubuntu 18, use `llvm-toolchain-$(lsb_release -cs)-12` in the command above.
+For Ubuntu 18, use `llvm-toolchain-$(lsb_release -cs)-12` in the command above.
 
-1. Install dependencies
+## Install dependencies
 
-    ```
-    sudo apt-get -y install git cmake python3-pip ninja-build antlr3 m4 clang-12 lld-12 libidn11-dev libaio1 libaio-dev
-    sudo pip3 install conan==1.59
-     ```
+```bash
+sudo apt-get -y install git cmake python3-pip ninja-build antlr3 m4 clang-12 lld-12 libidn11-dev libaio1 libaio-dev
+sudo pip3 install conan==1.59
+```
 
- 1. Create the work directory. Please make sure you have at least 80Gb of free space. We also recommend placing this directory on SSD to reduce build times.
-    ```
-    mkdir ~/ydbwork && cd ~/ydbwork
-    mkdir build
-    ```
+## Create the work directory. 
+> :warning: Please make sure you have at least 80Gb of free space. We also recommend placing this directory on SSD to reduce build times.
 
- 1. Clone the ydb repository.
-    ```
-    git clone https://github.com/ydb-platform/ydb.git
-    ```
+```bash
+mkdir ~/ydbwork && cd ~/ydbwork
+mkdir build
+```
 
- 1. Build ydb
+## Clone the ydb repository.
 
-    Run cmake to generate build configuration:
+```bash
+git clone https://github.com/ydb-platform/ydb.git
+```
 
-    ```
-    cd build
-    cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=../ydb/clang.toolchain ../ydb
-    ```
+## Configure
 
-    To build both YDB server (ydbd) and YDB CLI (ydb) run:
-    ```
-    ninja
-    ```
 
-    To build only YDB CLI (ydb) run:
-    ```
-    ninja ydb/apps/ydb/all
-    ```
 
-    A YDB server binary can be found at:
+### Configure without Ccache
+
+Run cmake to generate build configuration:
+
+```bash
+cd build
+cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=../ydb/clang.toolchain ../ydb
+```
+
+
+### (optionally) Configure with Ccache
+
+With enabled Ccache, you can finish the compilation of all targets on supported Linux distributions in a few minutes. 
+  Or just `ydbd` or `ydb` binary in a couple of seconds. To optionally enable `Ccache` and enhance the compilation speed, follow these steps:
+
+1. Install `Ccache` into `/usr/local/bin/` (We are using version `4.8.1`, you can use any version greater than `4.7`)
+    ```bash
+    (V=4.8.1; curl -L https://github.com/ccache/ccache/releases/download/v${V}/ccache-${V}-linux-x86_64.tar.xz | \
+     sudo tar -xJ -C /usr/local/bin/ --strip-components=1 --no-same-owner ccache-${V}-linux-x86_64/ccache)
     ```
-    ydb/apps/ydbd/ydbd
+
+2. Configure `Ccache` to use remote storage using environment variables
+    ```bash
+    export CCACHE_REMOTE_STORAGE="http://158.160.20.102:8080|layout=bazel"
+    export CCACHE_SLOPPINESS=locale
+    export CCACHE_BASEDIR=~/ydbwork/
     ```
-    A YDB CLI binary can be found at:
+    <details>
+    <summary>or using Ccache config file</summary>
+
+    ```bash
+    ccache -o remote_storage="http://158.160.20.102:8080|layout=bazel"
+    ccache -o sloppiness=locale 
+    ccache -o basedir=~/ydbwork/
     ```
-    ydb/apps/ydb/ydb
+    </details>
+3. Also, you should change Conan's home folder to the build folder for better cache hit 
+   ```bash
+   export CONAN_USER_HOME=~/ydbwork/build
+   ```
+
+4. Genreate build configuration using `ccache`
+    ```bash
+    cd build
+    cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
+    -DCMAKE_C_COMPILER_LAUNCHER=/usr/local/bin/ccache -DCMAKE_CXX_COMPILER_LAUNCHER=/usr/local/bin/ccache \
+    -DCMAKE_TOOLCHAIN_FILE=../ydb/clang.toolchain \
+    ../ydb
     ```
+
+## Build
+
+To build both YDB server (ydbd) and YDB CLI (ydb) run:
+```bash
+ninja
+```
+
+To build only YDB CLI (ydb) run:
+```bash
+ninja ydb/apps/ydb/all
+```
+
+A YDB server binary can be found at:
+```
+ydb/apps/ydbd/ydbd
+```
+A YDB CLI binary can be found at:
+```
+ydb/apps/ydb/ydb
+```
+