Building

Getting started > [Building] > Installing > Tutorial

---

First, clone the repo:

git clone --recursive https://github.com/VowpalWabbit/vowpal_wabbit.git
cd vowpal_wabbit

Then, pick one of several ways to configure the project:

1. Using vcpkg and CMake Presets (CMake 3.20+)
2. Using vcpkg
3. Using system dependencies

Option 1: Using vcpkg and CMake Presets (CMake 3.20+)

Prerequisites

• CMake 3.20+
• Ninja

cmake --preset=vcpkg-release -DBUILD_TESTING=OFF
cmake --build --preset=vcpkg-release

Next step: Installing

Option 2: Using vcpkg

cmake -S . -B build -G Ninja \
    -DCMAKE_BUILD_TYPE:STRING="Release" \
    -DCMAKE_TOOLCHAIN_FILE:FILEPATH="./ext_libs/vcpkg/scripts/buildsystems/vcpkg.cmake" \
    -DFMT_SYS_DEP:BOOL="ON" \
    -DRAPIDJSON_SYS_DEP:BOOL="ON" \
    -DSPDLOG_SYS_DEP:BOOL="ON" \
    -DVW_BOOST_MATH_SYS_DEP:BOOL="ON" \
    -DVW_GTEST_SYS_DEP:BOOL="ON" \
    -DVW_ZLIB_SYS_DEP:BOOL="ON" \
    -DBUILD_TESTING:BOOL="OFF"
cmake --build build

Next step: Installing

Option 3: Using system dependencies

1. Install dependencies

MacOS Homebrew

brew install cmake ninja rapidjson spdlog fmt boost zlib flatbuffers

# Test dependencies
brew install googletest

Ubuntu

apt update
apt install cmake ninja-build g++ libfmt-dev libspdlog-dev libflatbuffers-dev rapidjson-dev zlib1g-dev libboost-math-dev libflatbuffers-dev flatbuffers-compiler-dev

# Test dependencies
apt install libboost-test-dev libgtest-dev libgmock-dev

Conda

conda install cmake ninja rapidjson spdlog fmt boost zlib flatbuffers

# Test dependencies
conda install gtest gmock

2. Build

cmake -S . -B build -G Ninja \
    -DCMAKE_BUILD_TYPE:STRING="Release" \
    -DFMT_SYS_DEP:BOOL="ON" \
    -DRAPIDJSON_SYS_DEP:BOOL="ON" \
    -DSPDLOG_SYS_DEP:BOOL="ON" \
    -DVW_BOOST_MATH_SYS_DEP:BOOL="ON" \
    -DVW_GTEST_SYS_DEP:BOOL="ON" \
    -DVW_ZLIB_SYS_DEP:BOOL="ON" \
    -DBUILD_TESTING:BOOL="OFF"
cmake --build build

Next step: Installing

Notes

Windows specific info

• 10.0.16299.0 or newer Windows 10 SDK must be installed
• The default triplet on Windows is 32 bit. Therefore -DVCPKG_TARGET_TRIPLET=x64-windows should be added to the first CMake command to use 64 bit.
• To generate a Windows solution -A x64 -G "Visual Studio 17 2022" should also be added to the CMake command. It will generate a solution in the build directory that can be opened.
  • Alternatively, you can use Visual Studio's open folder feature to open the repo directly without needing to run any CMake commands

WSL

• If using WSL ensure you clone the repo in WSL and not in Windows to prevent broken line endings.
• If building on WSL on an NTFS drive, also be sure that the drive is mounted with the "metadata" option, or CMake will not complete successfully. (See: here)

Compiling a static executable

A statically linked vw executable that is not sensitive to boost version upgrades and can be safely copied between different Linux versions (e.g. even from Ubuntu to Red-Hat) can be built by including -DSTATIC_LINK_VW=ON in the CMake command and building the vw_cli_bin target.

cmake --build build --target vw_cli_bin

Running tests

Unit tests:

ctest --test-dir build --label-regex VWTestList

Integration tests:

python test/run_tests.py --epsilon 0.01 --fuzzy_compare

If you see:

Diff OK, Minor float difference ignored

That's ok. Floating point arithmetic does not round exactly the same way on all platforms.