# Building YDB from sources

From this repository you can build YDB Server and YDB CLI (Command Line Interface utility) executables. You can build using either Yatool or CMake:

- [Yatool](https://github.com/yandex/yatool) is the primary multilanguage build/test system being used to [build and test YDB](https://ydb.tech/docs/en/development/build-ya). You need to use Yatool and follow the [YDB development process](https://ydb.tech/docs/en/development/suggest-change) to make contributions to the YDB project.
- [CMake](https://en.wikipedia.org/wiki/CMake) is a secondary build system available, with CMakelists.txt automatically pregenerated by Yatool. You can build any binary artifact of YDB using CMake.

## 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.

```bash
mkdir ~/ydbwork && cd ~/ydbwork
```

## Clone the ydb repository

```bash
git clone https://github.com/ydb-platform/ydb.git
```

Change the current working directory to the cloned repository root to perform further commands:

```
cd ydb
```

## Checkout a branch for build

There are two branches for the latest development update in the YDB repository:

- `main` - the primary development branch for **Yatool** build
- `cmakebuild` - the follower branch for **CMake** build, synced from `main` every hour, with generated CMakelists.txt files

Build from the development mainline branches may sometimes be broken for short periods of time, and also some tests may fail. So, you may prefer to build the latest stable versions of YDB Server and CLI. As stable versions of the YDB Server and CLI belong to different commits, it is not possible to get both server and CLI stable executables with a single checkout/build. Checkout and build server first, then CLI, or vice versa.

Stable versions can be built by both **Yatool** and **CMake**.

### Checkout the latest development update for Yatool build

By default, the `main` branch is checked out, so you can run Yatool build without executing a checkout command.

### Checkout the latest development update for CMake build

To checkout the latest development update for CMake build, run the following command:

```bash
git checkout cmakebuild
```

### Check out the latest stable YDB Server version

To build the latest stable version of a YDB Server, check out the latest stable Server tag from the repository. To do so, visit the https://github.com/ydb-platform/ydb/releases/latest page and use the provided 'tag' value in the `git checkout <tag>` command.

For example, at the time of writing the latest stable release was [YDB Server 23.2.12](https://github.com/ydb-platform/ydb/releases/tag/23.2.12) with a tag `23.2.12`, so the checkout command looks like this:

```bash
git checkout 23.2.12
```

### Check out the latest stable YDB CLI version

To build a latest stable version of a YDB CLI, check out the latest stable CLI tag from the repository. To do so, visit the https://github.com/ydb-platform/ydb/releases page, scroll down to the top-most 'YDB CLI' release, and use the provided 'tag' value in the `git checkout <tag>` command.

For example, at the time of writing the latest YDB CLI release was [YDB CLI 2.5.0](https://github.com/ydb-platform/ydb/releases/tag/CLI_2.5.0) with a tag `CLI_2.5.0`, so the checkout command looks like this:

```bash
git checkout CLI_2.5.0
```

## Build using Yatool

You can use the native Yatool build for x86_64 under Ubuntu Linux 18+.

Run `ya make` from the repository root, followed by an optional relative path to the build target. By default, `ya make` compiles a `debug` configuration, while you can choose to have `release` or `relwithdebinfo`. The latter is recommended for faster builds, as is leverages the YDB remote build cache.

To build a binary, Yatool downloads and caches relevant toolchains from the YDB S3 storage, so you do not need to install anything on the build machine.

To build YDB server run:

```
./ya make ydb/apps/ydbd --build relwithdebinfo
```

To build YDB CLI run:

```
./ya make ydb/apps/ydb --build relwithdebinfo
```

Upon completion, you will have the `ydbd`/`ydb` executables in the `ydb/apps/ydbd`/`ydb/apps/ydb` directories, respectively.

You can read more about Yatool options in the [YDB documentation](https://ydb.tech/docs/development/build-ya).

## Build using CMake

You can use CMake to build YDB for various architectures and operating systems.

YDB server can be built for Ubuntu 18.04, 20.04 and 22.04. Other Linux distributions are likely to work, but additional effort may be required.

YDB CLI can be built for Ubuntu 18+, Windows, and MacOS. Instructions below are provided for Ubuntu only, other options are to be described later.

### For Ubuntu versions earlier than 22.04

It is recommended to build YDB on Ubuntu 22.04. Follow these additional instructions if you don't have access to it and need to use an earlier version.

<details>
   <summary>For Ubuntu 18.04, install Python 3.8, create and activate a new virtual environment, and install the latest PIP.</summary>

   ```bash
   apt-get install python3.8 python3.8-venv python3-venv
   python3.8 -m venv ~/ydbwork/ve
   source ~/ydbwork/ve/bin/activate
   pip install -U pip
   ```
</details>

<details>
   <summary>For Ubuntu 18.04 and Ubuntu 20.04, add CMake and LLVM APT repositories.</summary>

   ```bash
   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
   
   wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
   echo "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs)-14 main" | sudo tee /etc/apt/sources.list.d/llvm.list >/dev/null
   
   sudo apt-get update
   
   ```

</details>

### Install dependencies

```bash
sudo apt-get -y install git cmake python3-pip ninja-build antlr3 m4 clang-14 lld-14 libidn11-dev libaio1 libaio-dev llvm-14
sudo pip3 install conan==1.59 grpcio-tools==1.57.0

```

### Create the build directory. 

```bash
cd ~/ydbwork
mkdir build
```

### Install ccache

1. Install `ccache` into `/usr/local/bin/`. The recommended version is `4.8.1` or above, the minimum required version is `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)
    ```

2. To speed up the first build time, you may configure `ccache` to use remote storage of YDB build artifacts:
    ```bash
    ccache -o remote_storage="http://cachesrv.ydb.tech:8080|read-only|layout=bazel"
    ccache -o sloppiness=locale 
    ccache -o base_dir=~/ydbwork/
    ```
   If you use a non-default work directory, adjust the `base_dir` ccache option to match it.


### Configure

1. Change Conan's home folder to the build folder for better remote cache hit 
    ```bash
    export CONAN_USER_HOME=~/ydbwork/build
    ```

2. Generate build configuration using `ccache`
    ```bash
    cd build
    cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
    -DCCACHE_PATH=/usr/local/bin/ccache \
    -DCMAKE_TOOLCHAIN_FILE=../ydb/clang.toolchain \
    ../ydb  
    ```

### Build

To build YDB Server run:
```bash
ninja ydb/apps/ydbd/all
```

A YDB server binary can be found at:
```
ydb/apps/ydbd/ydbd
```

To build YDB CLI (Command Line Interface utility) run:
```bash
ninja ydb/apps/ydb/all
```

A YDB CLI binary can be found at:
```
ydb/apps/ydb/ydb
```