Skip to content

[Cron] Sync and update documentation #388

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
infinityCurator merged 1 commit into from
Mar 26, 2026
Merged

[Cron] Sync and update documentation #388

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions website/versioned_docs/version-v0.7.0-dev4/getstarted/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"label": "Get started",
"position": 0,
"link": {
"type": "generated-index",
"description": "quickstart and more"
}
}
368 changes: 368 additions & 0 deletions website/versioned_docs/version-v0.7.0-dev4/getstarted/build_from_source.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,368 @@
---
sidebar_position: 2
slug: /build_from_source
---

# Build from Source
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Build Infinity from source, build and run unit/functional tests.

---

This document provides instructions for building Infinity from source, as well as building and running unit and functional tests.

:::tip NOTE
Infinity can be natively compiled on Linux only. For non-Linux operating systems, build it using Docker.
:::

- [Prerequisites](#prerequisites)
- [Build from source](#build-the-source-code)
- [Build and run unit tests](#build-and-run-unit-tests)
- [Build and run functional tests](#build-and-run-functional-tests)

## Prerequisites

### 1. Replace the native Out-Of-Memory killer

Building the entire project, particularly during the link stage, requires considerable RAM, which can cause the host machine to become unresponsive due to the sluggishness of the kernel's Out-Of-Memory (OOM) killer. To mitigate this, we recommend installing [earlyoom](https://github.com/rfjakob/earlyoom) to improve the host's responsiveness.

### 2. Limit the number of concurrent link processes

Configure `cmake` to limit the number of concurrent link processes. For example:

`-DCMAKE_JOB_POOLS:STRING='link=4'`

:::tip NOTE
Recommended link pool size settings are as follows:

- `1`: 6 GB of RAM
- `2`: 16 GB of RAM
- `3`: 32 GB of RAM
:::

### 3. Set the `cmake` build type

The `cmake` build type (`CMAKE_BUILD_TYPE`) can be one of the following:

- `Debug`: Suitable for daily development.
No inline; with symbol info; with address sanitizer.
Typically ~10x slower than `RelWithDebInfo` or `Release`.
- `RelWithDebInfo`: Suitable for performance analysis.
Optimizes with `-O2`; with symbol information.
- `Release`: Suitable for [project releases](https://github.com/infiniflow/infinity/releases).
Optimizes with `-O3`; without symbol information.
The built executables are significantly smaller than those of `RelWithDebInfo`.

:::tip NOTE
The following procedures set `CMAKE_BUILD_TYPE` to `Debug`. Change it as you see necessary.
:::

## Build the source code

<Tabs
defaultValue="linuxdocker"
values={[
{label: 'On Linux using Docker', value: 'linuxdocker'},
{label: 'On Ubuntu', value: 'ubuntu'},
]}>
<TabItem value="linuxdocker">

This section provides instructions for building Infinity from source on Linux using Docker.

1. Download the source code:

```shell
git clone https://github.com/infiniflow/infinity.git
```

2. Build the source code using Docker:

```shell
cd infinity && mkdir cmake-build-debug
TZ=$(readlink -f /etc/localtime | awk -F '/zoneinfo/' '{print $2}')
docker run -d --name infinity_build -e TZ=$TZ -v $PWD:/infinity -v /boot:/boot infiniflow/infinity_builder:ubuntu22_clang20
docker exec infinity_build bash -c "cd /infinity/cmake-build-debug && cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_VERBOSE_MAKEFILE=ON .. && cmake --build . -t infinity"
```

3. Start up the Infinity server:

```shell
sudo mkdir -p /var/infinity && sudo chown -R $USER /var/infinity
ulimit -n 500000
./cmake-build-debug/src/infinity
```

</TabItem>
<TabItem value="ubuntu">

This section provides instructions for building Infinity from source on Ubuntu.

1. Install necessary dependencies:

<Tabs
defaultValue="ubuntu2204"
values={[
{label: 'Ubuntu 22.04', value: 'ubuntu2204'},
{label: 'Ubuntu 24.04', value: 'ubuntu2404'},
]}>
<TabItem value="ubuntu2204">

```shell
sudo apt update && sudo apt install git wget unzip software-properties-common pkg-config bison autoconf-archive libtool
wget https://github.com/Kitware/CMake/releases/download/v4.0.3/cmake-4.0.3-linux-x86_64.tar.gz
tar zxvf cmake-4.0.3-linux-x86_64.tar.gz
sudo cp -rf cmake-4.0.3-linux-x86_64/bin/* /usr/local/bin && sudo cp -rf cmake-4.0.3-linux-x86_64/share/* /usr/local/share && rm -rf cmake-4.0.3-linux-x86_64
wget https://github.com/ninja-build/ninja/archive/refs/tags/v1.13.1.zip
unzip v1.13.1.zip && cd ninja-1.13.1 && cmake -Bbuild-cmake -DBUILD_TESTING=OFF && cmake --build build-cmake --parallel $(nproc) && cd build-cmake && sudo cp ninja /usr/local/bin
cd ../.. && rm -rf v1.13.1.zip ninja-1.13.1
wget https://github.com/rui314/mold/archive/refs/tags/v2.40.3.zip
./install-build-deps.sh
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=g++-15 -B build
cmake --build build -j$(nproc)
sudo cmake --build build --target install
# compile gcc-15 and install it
cd ~/Downloads # Of course, you can specify a different path.
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg && ./bootstrap-vcpkg.sh -disableMetrics
sh -c 'cat <<EOF >> ~/.bashrc
export VCPKG_ROOT=${PWD}
export PATH=${VCPKG_ROOT}:${PATH}
EOF'
source ~/.bashrc
wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh && sudo ./llvm.sh 20 && rm llvm.sh
sudo add-apt-repository -P ppa:ubuntu-toolchain-r/test
sudo apt update && sudo apt install clang-tools-20 flex zlib1g-dev python3-dev autoconf autoconf-archive libtool
wget https://github.com/jemalloc/jemalloc/archive/refs/tags/5.3.0.tar.gz
tar zxvf 5.3.0.tar.gz && cd jemalloc-5.3.0 && ./autogen.sh && CFLAGS="-fPIC" CXXFLAGS="-fPIC" ./configure --enable-static --disable-libdl --enable-prof --enable-prof-libunwind --disable-initial-exec-tls && sudo make -j install && cd ..
sudo ldconfig && sudo rm -rf jemalloc-5.3.0 5.3.0.tar.gz
sudo ln -s /usr/lib/llvm-20/bin/clang-scan-deps /usr/bin/clang-scan-deps
sudo ln -s /usr/bin/clang-format-20 /usr/bin/clang-format
sudo ln -s /usr/bin/clang-tidy-20 /usr/bin/clang-tidy
sudo ln -s /usr/bin/llvm-symbolizer-20 /usr/bin/llvm-symbolizer
sudo ln -s /usr/lib/llvm-20/include/x86_64-pc-linux-gnu/c++/v1/__config_site /usr/lib/llvm-20/include/c++/v1/__config_site
```

</TabItem>
<TabItem value="ubuntu2404">

```shell
sudo apt update && sudo apt install -y git wget lsb-release software-properties-common pkg-config bison mold autoconf-archive libtool
wget https://github.com/Kitware/CMake/releases/download/v4.2.3/cmake-4.2.3-linux-x86_64.tar.gz
tar zxvf cmake-4.2.3-linux-x86_64.tar.gz
sudo cp -rf cmake-4.2.3-linux-x86_64/bin/* /usr/local/bin && sudo cp -rf cmake-4.2.3-linux-x86_64/share/* /usr/local/share && rm -rf cmake-4.2.3-linux-x86_64
wget https://github.com/ninja-build/ninja/archive/refs/tags/v1.13.1.zip
unzip v1.13.1.zip && cd ninja-1.13.1 && cmake -Bbuild-cmake -DBUILD_TESTING=OFF && cmake --build build-cmake --parallel $(nproc) && cd build-cmake && sudo cp ninja /usr/local/bin
cd ../.. && rm -rf v1.13.1.zip ninja-1.13.1
sudo add-apt-repository ppa:puni070/gcc-noble
sudo apt update
sudo apt install gcc-15 g++-15
# Ensure that no other gcc&g++ versions have a priority set, or that if they do, their priority is below 100.
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-15 100
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-15 100
cd ~/Downloads # Of course, you can specify a different path.
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg && ./bootstrap-vcpkg.sh -disableMetrics
sh -c 'cat <<EOF >> ~/.bashrc
export VCPKG_ROOT=${PWD}
export PATH=${VCPKG_ROOT}:${PATH}
EOF'
source ~/.bashrc
wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh && sudo ./llvm.sh 20 && rm llvm.sh
sudo apt install -y clang-tools-20 flex zlib1g-dev python3-dev autoconf libjemalloc-dev
# Ensure that no other Clang versions have a priority set, or that if they do, their priority is below 100.
sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-20 100
sudo ln -s /usr/lib/llvm-20/bin/clang-scan-deps /usr/bin/clang-scan-deps
sudo ln -s /usr/bin/clang-format-20 /usr/bin/clang-format
sudo ln -s /usr/bin/clang-tidy-20 /usr/bin/clang-tidy
sudo ln -s /usr/bin/llvm-symbolizer-20 /usr/bin/llvm-symbolizer
sudo ln -s /usr/lib/llvm-20/include/x86_64-pc-linux-gnu/c++/v1/__config_site /usr/lib/llvm-20/include/c++/v1/__config_site
```

</TabItem>
</Tabs>

2. Download the source code:

```shell
git clone https://github.com/infiniflow/infinity.git
```

3. Build the source code:

:::tip NOTE
You must *also* install `simde` v0.7.4+ if using Ubuntu 22.04 on an ARM architecture.

```shell
sudo apt install libsimde-dev
```

If your installed version is below v0.7.4, download the include files directly from github and replace them.
:::

```shell
git config --global --add safe.directory infinity
cd infinity && mkdir cmake-build-debug && cd cmake-build-debug
export CC=/usr/bin/clang-20
export CXX=/usr/bin/clang++-20
cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_VERBOSE_MAKEFILE=ON ..
cmake --build . -t infinity
```

4. Start up the Infinity server:

```shell
sudo mkdir -p /var/infinity && sudo chown -R $USER /var/infinity
ulimit -n 500000
./cmake-build-debug/src/infinity
```

</TabItem>
</Tabs>

## Build and run unit tests

<Tabs
defaultValue="dockerlinux"
values={[
{label: 'Using Docker on Linux', value: 'dockerlinux'},
{label: 'on Ubuntu', value: 'ubuntu'},
{label: 'With code coverage enabled', value: 'codecoverage'},
]}>
<TabItem value="dockerlinux">

```shell
docker exec infinity_build bash -c "cd /infinity/cmake-build-debug && cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_VERBOSE_MAKEFILE=ON .. && cmake --build . -t test_main"
./cmake-build-debug/src/test_main
```

</TabItem>
<TabItem value="ubuntu">

```shell
cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_VERBOSE_MAKEFILE=ON ..
cmake --build . -t test_main
./cmake-build-debug/src/test_main
```

</TabItem>
<TabItem value="codecoverage">

1. Install the `llvm-20` dependency:

```shell
sudo apt install llvm-20
```

2. Build and run the unit tests with code coverage enabled:

```shell
cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_VERBOSE_MAKEFILE=ON -DCODE_COVERAGE=ON ..
cmake --build . -t test_main
find . -name "infinity*.profraw" | xargs rm -f
export LLVM_PROFILE_FILE="infinity-%p.profraw"
./cmake-build-debug/src/test_main
```

3. Use llvm-cov-20 to generate summarized code coverage results:

```shell
llvm-profdata-20 merge -sparse infinity-*.profraw -o coverage.profdata
llvm-cov-20 export cmake-build-debug/src/test_main -instr-profile=coverage.profdata -format=lcov -ignore-filename-regex='.*unit_test.*|.*third_party.*|.*cmake-build-debug.*|.*cppm.*' > coverage.lcov
```

</TabItem>
</Tabs>

## Build and run functional tests

<Tabs
defaultValue="dockerlinux"
values={[
{label: 'Using Docker on Linux', value: 'dockerlinux'},
{label: 'on Ubuntu', value: 'ubuntu'},
{label: 'With code coverage enabled', value: 'codecoverage'},
]}>
<TabItem value="dockerlinux">

1. Build and start up the Infinity server:

```shell
docker exec infinity_build bash -c "cd /infinity/cmake-build-debug && cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_VERBOSE_MAKEFILE=ON .. && cmake --build . -t infinity"
./cmake-build-debug/src/infinity
```

2. Install Python sdk of infinity:
```bash
pip install infinity-sdk==0.7.0.dev4
```

3. Run the functional tests:

```shell
python3 tools/run_pytest_parallel.py
```

</TabItem>
<TabItem value="ubuntu">

1. Build and start up the Infinity server:

```shell
cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_VERBOSE_MAKEFILE=ON ..
cmake --build . -t infinity
./cmake-build-debug/src/infinity
```

2. Install Python sdk of infinity:
```bash
pip install infinity-sdk==0.7.0.dev4
```

3. Run the functional tests:

```shell
python3 tools/run_pytest_parallel.py
```

</TabItem>
<TabItem value="codecoverage">

1. Build and start up the Infinity server with code coverage enabled:

```shell
cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_VERBOSE_MAKEFILE=ON -DCODE_COVERAGE=ON ..
cmake --build . -t infinity
find . -name "infinity*.profraw" | xargs rm -f
export LLVM_PROFILE_FILE="infinity-%p.profraw"
export LLVM_PROFILE_DUMP_ON_EXIT=1
./cmake-build-debug/src/infinity
```

2. Install Python sdk of infinity:
```bash
pip install infinity-sdk==0.7.0.dev4
```

3. Run the functional tests:

```shell
python3 tools/run_pytest_parallel.py
```

4. Shut down the Infinity server:

```shell
kill `pidof infinity`
```

5. Use llvm-cov-20 to generate summarized code coverage results:

```shell
llvm-profdata-20 merge -sparse infinity-*.profraw -o coverage.profdata
llvm-cov-20 export cmake-build-debug/src/infinity -instr-profile=coverage.profdata -format=lcov -ignore-filename-regex='.*third_party.*|.*cmake-build-debug.*|.*cppm.*' > coverage.lcov
```

</TabItem>
</Tabs>
Loading
Loading