ThordekkCore/BOOST_SETUP_GUIDE.md

Boost Setup Guide for TrinityCore Playerbot

This guide explains how to set up Boost for compiling TrinityCore with the Playerbot module enabled.

Quick Start

The build system automatically detects Boost in multiple ways:

1. ✅ Environment Variable (Recommended): Set BOOST_ROOT to your Boost installation
2. ✅ Common Paths: Checks standard installation locations automatically
3. ✅ Standard CMake: Falls back to system-installed Boost if needed

Option 1: Using BOOST_ROOT Environment Variable (Recommended)

Windows

1. Download Boost 1.74+ (1.89 recommended for best compatibility)

   • Official prebuilt binaries: https://sourceforge.net/projects/boost/files/boost-binaries/
   • Choose the version matching your Visual Studio (e.g., boost_1_89_0-msvc-14.3-64.exe for VS2022)

2. Install Boost to a directory of your choice, e.g.:

   • C:\local\boost_1_89_0
   • C:\libs\boost_1_89_0
   • C:\Program Files\boost\boost_1_89_0

3. Set BOOST_ROOT Environment Variable:

   # Temporary (current session only)
   $env:BOOST_ROOT = "C:\local\boost_1_89_0"
   
   # Permanent (system-wide)
   [System.Environment]::SetEnvironmentVariable("BOOST_ROOT", "C:\local\boost_1_89_0", "User")
   

   Or via GUI:

   • Press Win+R, type sysdm.cpl, press Enter
   • Go to Advanced tab → Environment Variables
   • Under User variables, click New
   • Variable name: BOOST_ROOT
   • Variable value: C:\local\boost_1_89_0 (your path)
   • Click OK

4. Restart your terminal/IDE to pick up the new environment variable

5. Run CMake:

   mkdir build
   cd build
   cmake .. -DBUILD_PLAYERBOT=ON
   cmake --build . --config Release
   

Linux/Unix

1. Install Boost 1.74+ via package manager:

   # Ubuntu/Debian
   sudo apt-get install libboost-all-dev
   
   # Fedora/RHEL
   sudo dnf install boost-devel
   
   # Arch Linux
   sudo pacman -S boost
   

2. Or download from source:

   wget https://boostorg.jfrog.io/artifactory/main/release/1.89.0/source/boost_1_89_0.tar.gz
   tar -xzf boost_1_89_0.tar.gz
   cd boost_1_89_0
   ./bootstrap.sh --prefix=/usr/local/boost_1_89_0
   ./b2 install
   

3. Set BOOST_ROOT (if using custom location):

   export BOOST_ROOT=/usr/local/boost_1_89_0
   # Add to ~/.bashrc or ~/.zshrc for persistence
   echo 'export BOOST_ROOT=/usr/local/boost_1_89_0' >> ~/.bashrc
   

4. Run CMake:

   mkdir build
   cd build
   cmake .. -DBUILD_PLAYERBOT=ON
   cmake --build . --config Release -j$(nproc)
   

Option 2: Using Common Installation Paths (No BOOST_ROOT)

If you don't set BOOST_ROOT, the build system automatically searches these locations:

Windows

• C:/libs/boost_1_89_0-bin-msvc-all-32-64/boost_1_89_0
• C:/local/boost_1_89_0
• C:/Program Files/boost/boost_1_89_0

Linux/Unix

• /usr/local/boost_1_89_0
• /opt/boost_1_89_0
• System default paths (/usr/include, /usr/lib)

Just install Boost to one of these locations and CMake will find it automatically.

Option 3: Using vcpkg (Windows)

1. Install vcpkg:

   git clone https://github.com/microsoft/vcpkg.git
   cd vcpkg
   .\bootstrap-vcpkg.bat
   

2. Install Boost:

   .\vcpkg install boost:x64-windows
   

3. Run CMake with vcpkg toolchain:

   mkdir build
   cd build
   cmake .. -DBUILD_PLAYERBOT=ON -DCMAKE_TOOLCHAIN_FILE=C:/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
   cmake --build . --config Release
   

Troubleshooting

Error: "System Boost 1.89 not found at specified path"

Cause: Your BOOST_ROOT environment variable points to a non-existent path.

Solutions:

1. Verify Boost is actually installed at that path
2. Check the path in BOOST_ROOT is correct (no typos)
3. Unset BOOST_ROOT to let CMake search automatically:

   # Windows
   [System.Environment]::SetEnvironmentVariable("BOOST_ROOT", $null, "User")
   
   # Linux
   unset BOOST_ROOT
   

4. Restart terminal/IDE after changing environment variables

Error: "Could not auto-detect Boost library directory"

Cause: Boost is installed but libraries are in an unexpected location.

Solutions:

1. Check your Boost installation has compiled libraries (not just headers)
2. Look for directories like:
   • lib64-msvc-14.3 (MSVC)
   • lib (standard)
   • stage/lib (custom build)
3. If using custom build, run ./b2 to compile Boost libraries

Error: "Boost not found. Please install Boost 1.74+"

Cause: No Boost installation detected anywhere.

Solutions:

1. Install Boost using one of the methods above
2. Set BOOST_ROOT environment variable
3. Verify Boost version is 1.74 or newer:

   # Check installed version
   cat $BOOST_ROOT/boost/version.hpp | grep "BOOST_VERSION"
   

CMake keeps using wrong Boost version

Solutions:

1. Delete CMake cache: rm -rf build/CMakeCache.txt build/CMakeFiles
2. Set BOOST_ROOT to force specific installation
3. Reconfigure from clean build directory:

   rm -rf build
   mkdir build
   cd build
   cmake .. -DBUILD_PLAYERBOT=ON
   

Verification

After successful CMake configuration, you should see:

-- Using system Boost 1.89 for Playerbot compatibility
-- Using BOOST_ROOT from environment: C:\local\boost_1_89_0
-- Attempting to use system Boost from: C:\local\boost_1_89_0
-- Detected Boost version: 1.89
-- ✅ Custom Boost found at: C:/local/boost_1_89_0
-- ✅ Boost Release libraries found: ...
-- ✅ Boost Debug libraries found: ...

Or for standard installation:

-- Using standard CMake Boost finding mechanism
-- ✅ Standard Boost 1.89.0 found at: /usr/include

Technical Details

How Boost Detection Works

When BUILD_PLAYERBOT=ON, the build system uses cmake/FindSystemBoost.cmake:

1. Phase 1: Search for Boost

   • Check BOOST_ROOT environment variable
   • Check common installation paths
   • Set USE_STANDARD_BOOST_SEARCH if not found

2. Phase 2: Locate Libraries

   • Auto-detect MSVC toolset version (e.g., 14.3)
   • Auto-detect architecture (x64/x32)
   • Auto-detect Boost version from version.hpp
   • Search for required libraries:
     • boost_thread
     • boost_filesystem
     • boost_program_options
     • boost_regex
     • boost_locale

3. Phase 3: Fallback

   • If custom search fails, use standard CMake find_package(Boost)
   • Requires Boost 1.74+ minimum
   • Uses system-installed packages

Required Boost Components

The Playerbot module requires these Boost libraries:

• filesystem - File and directory operations
• program_options - Configuration parsing
• regex - Regular expressions
• locale - Internationalization
• thread - Threading support (header-only in most versions)

Note: boost_system is header-only since Boost 1.69 and is not required as a separate library.

FAQ

Q: Do I need to rebuild Boost from source? A: No, prebuilt binaries work fine for Windows. Linux users can use package managers.

Q: What's the minimum Boost version? A: 1.74 minimum, 1.89 recommended for best compatibility.

Q: Can I use Boost installed by vcpkg? A: Yes! When BOOST_ROOT is not set, CMake will find vcpkg-installed Boost automatically.

Q: Why do I get "Debug libraries not found"? A: This is a warning, not an error. Release libraries will be used for both configurations. For full Debug support, install Boost debug binaries.

Q: Do I need different Boost versions for Debug/Release builds? A: No. The same Boost installation works for both. The build system automatically selects appropriate libraries.

Support

If you encounter issues not covered here:

1. Check CMake output for diagnostic messages
2. Verify your Boost installation is complete (headers + libraries)
3. Try deleting CMake cache and reconfiguring
4. Report build errors with full CMake output to project maintainers

---

Last Updated: 2025-11-03 Applies to: TrinityCore master branch with BUILD_PLAYERBOT=ON