ThordekkCore/BUILD_DOCUMENTATION.md

TrinityCore Build System Documentation

Overview

This document describes the complete build system for TrinityCore with Playerbot module support, including both Release and Debug configurations.

Build Configurations

Release Configuration

• Purpose: Production deployment, performance testing
• Optimization: Full compiler optimizations enabled (/O2)
• Debug Symbols: Limited (PDB with optimizations)
• Binary Size: ~25MB (worldserver.exe)
• Performance: Fastest execution speed
• Memory Usage: Lower runtime memory footprint
• Use Case: Production servers, performance benchmarking, final testing

Debug Configuration

• Purpose: Development, debugging, crash analysis
• Optimization: Disabled for easier debugging (/Od)
• Debug Symbols: Complete (full PDB information)
• Binary Size: ~76MB (worldserver.exe) + 488MB (worldserver.pdb)
• Performance: Slower execution (20-50% slower than Release)
• Memory Usage: Higher runtime memory footprint
• Use Case: Development, WinDbg debugging, Visual Studio debugging, crash analysis

Configuration Comparison

Aspect	Debug	Release	Difference
worldserver.exe size	76 MB	25 MB	3x smaller in Release
worldserver.pdb size	488 MB	50 MB	~10x smaller in Release
playerbot.lib size	512 MB	180 MB	~3x smaller in Release
Build time (full)	20-40 min	15-30 min	25% faster in Release
Runtime performance	Baseline	20-50% faster	Significant improvement
Memory usage	Higher	Lower	20-40% less in Release
Debugging capability	Full	Limited	Trade-off for performance

Prerequisites

Required Software

1. Visual Studio 2022 Enterprise

   • C++ Desktop Development workload
   • Windows 10 SDK
   • CMake integration tools

2. CMake 3.24+

   • Included with Visual Studio 2022

3. vcpkg Package Manager

   • Location: C:\libs\vcpkg
   • Toolchain file: C:\libs\vcpkg\scripts\buildsystems\vcpkg.cmake

4. MySQL 9.4

   • Required for database connectivity

Required Libraries

vcpkg Libraries

Install required libraries using vcpkg:

# Navigate to vcpkg directory
cd C:\libs\vcpkg

# Install libraries for x64-windows (includes both release and debug)
vcpkg.exe install tbb:x64-windows
vcpkg.exe install parallel-hashmap:x64-windows

# Verify installation
vcpkg.exe list

Installed Library Structure:

C:\libs\vcpkg\installed\x64-windows\
├── lib\                          # Release libraries
│   ├── tbb12.lib
│   ├── tbbmalloc.lib
│   └── tbbmalloc_proxy.lib
├── debug\
│   └── lib\                      # Debug libraries
│       ├── tbb12_debug.lib
│       ├── tbbmalloc_debug.lib
│       └── tbbmalloc_proxy_debug.lib
├── include\                      # Headers (shared)
└── bin\                          # DLLs (release and debug)

Boost 1.78 Libraries

IMPORTANT: TrinityCore uses a custom FindSystemBoost.cmake that automatically selects the correct Boost libraries based on build configuration.

Location: C:\libs\boost_1_78_0

Library Structure:

C:\libs\boost_1_78_0\
├── boost\                        # Header files
├── stage\
│   └── lib\                      # All compiled libraries
│       ├── libboost_*-vc143-mt-gd-x64-1_78.lib    # Debug libraries (with -gd-)
│       └── libboost_*-vc143-mt-x64-1_78.lib        # Release libraries (no -gd-)

Key Libraries Used:

• libboost_system - System utilities
• libboost_thread - Threading support
• libboost_filesystem - File system operations
• libboost_program_options - Command-line parsing
• libboost_regex - Regular expressions
• libboost_locale - Localization

Library Selection Logic (cmake/FindSystemBoost.cmake):

# Automatic configuration detection
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
    set(BOOST_LIB_SUFFIX "-vc143-mt-gd-x64-1_78")  # Debug suffix with -gd-
else()
    set(BOOST_LIB_SUFFIX "-vc143-mt-x64-1_78")     # Release suffix without -gd-
endif()

Build Scripts

Configuration Scripts

configure_debug.bat

Purpose: Configure CMake for Debug build

What it does:

1. Initializes Visual Studio 2022 environment
2. Cleans and recreates build/ directory
3. Runs CMake with Debug configuration
4. Points to correct vcpkg installation (C:\libs\vcpkg)
5. Enables Playerbot module (BUILD_PLAYERBOT=1)

Usage:

configure_debug.bat

CMake Parameters:

• -G "Visual Studio 17 2022" - Generate VS2022 solution
• -A x64 - Target x64 platform
• -DCMAKE_BUILD_TYPE=Debug - Debug configuration
• -DCMAKE_TOOLCHAIN_FILE="C:/libs/vcpkg/scripts/buildsystems/vcpkg.cmake" - vcpkg integration
• -DVCPKG_TARGET_TRIPLET=x64-windows - Target triplet
• -DBUILD_PLAYERBOT=1 - Enable Playerbot module

Output:

• build/TrinityCore.sln - Visual Studio solution
• build/CMakeCache.txt - CMake configuration cache
• Various .vcxproj files for each project

---

configure_release.bat

Purpose: Configure CMake for Release build

What it does:

1. Initializes Visual Studio 2022 environment
2. Cleans and recreates build/ directory
3. Runs CMake with Release configuration
4. Points to correct vcpkg installation
5. Enables Playerbot module

Usage:

configure_release.bat

CMake Parameters: (Same as debug, except -DCMAKE_BUILD_TYPE=Release)

---

Build Scripts

build_debug.bat

Purpose: Build entire TrinityCore solution in Debug configuration

What it does:

1. Verifies build directory exists (requires prior configuration)
2. Builds entire solution using MSBuild
3. Uses debug libraries from vcpkg automatically
4. Generates full debugging symbols (PDB files)

Usage:

# First time or after configuration changes:
configure_debug.bat
build_debug.bat

# Incremental builds:
build_debug.bat

Build Parameters:

• /p:Configuration=Debug - Debug configuration
• /p:Platform=x64 - x64 platform
• /maxcpucount:2 - Use 2 CPU cores (adjust based on system)
• /verbosity:minimal - Minimal console output
• /fileLogger - Enable file logging
• Log output: build_debug_output.txt

Output:

• build\src\server\worldserver\Debug\worldserver.exe
• build\src\server\worldserver\Debug\worldserver.pdb (debug symbols)
• build\src\server\bnetserver\Debug\bnetserver.exe
• build\src\server\bnetserver\Debug\bnetserver.pdb
• All module libraries in their respective Debug folders

Build Time: 20-40 minutes (full build)

---

build_release.bat

Purpose: Build entire TrinityCore solution in Release configuration

What it does:

1. Verifies build directory exists
2. Builds entire solution with optimizations
3. Uses release libraries from vcpkg automatically
4. Generates optimized binaries

Usage:

# First time or after configuration changes:
configure_release.bat
build_release.bat

# Incremental builds:
build_release.bat

Output:

• build\src\server\worldserver\Release\worldserver.exe
• build\src\server\bnetserver\Release\bnetserver.exe
• All module libraries in their respective Release folders

Build Time: 15-30 minutes (full build)

---

build_playerbot_debug.bat

Purpose: Fast incremental build of ONLY Playerbot module (Debug)

What it does:

1. Builds only the Playerbot module project
2. Skips building worldserver and other components
3. Useful for rapid development iterations

Usage:

# After making changes to Playerbot code:
build_playerbot_debug.bat

Note: After building the module, you must build worldserver to link the changes:

# Option 1: Build worldserver only
"C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe" ^
    "build\src\server\worldserver\worldserver.vcxproj" ^
    /p:Configuration=Debug /p:Platform=x64

# Option 2: Full rebuild
build_debug.bat

Output:

• build\src\server\modules\Playerbot\Debug\playerbot.lib

Build Time: 2-5 minutes (incremental)

---

build_playerbot_and_worldserver_debug.bat

Purpose: Fast incremental build of Playerbot AND worldserver (Debug)

What it does:

1. Builds the Playerbot module first
2. Automatically rebuilds worldserver to link the changes
3. Optimal for Playerbot development workflow

Usage:

# After making changes to Playerbot code:
build_playerbot_and_worldserver_debug.bat

Output:

• build\src\server\modules\Playerbot\Debug\playerbot.lib
• build\bin\Debug\worldserver.exe

Build Time: 5-10 minutes (incremental)

---

build_playerbot_and_worldserver_release.bat

Purpose: Fast incremental build of Playerbot AND worldserver (Release)

What it does:

1. Builds the Playerbot module in Release mode
2. Automatically rebuilds worldserver with optimizations
3. For testing release performance

Usage:

# For performance testing:
build_playerbot_and_worldserver_release.bat

Output:

• build\src\server\modules\Playerbot\Release\playerbot.lib
• build\bin\Release\worldserver.exe

Build Time: 5-8 minutes (incremental)

---

Typical Workflows

Initial Setup (First Time)

# 1. Install vcpkg libraries
cd C:\libs\vcpkg
vcpkg.exe install tbb:x64-windows parallel-hashmap:x64-windows

# 2. Configure for Debug
cd C:\TrinityBots\TrinityCore
configure_debug.bat

# 3. Build entire project
build_debug.bat

Daily Development (Playerbot Module)

# 1. Edit code in src/modules/Playerbot/

# 2. Quick module rebuild
build_playerbot_debug.bat

# 3. Rebuild worldserver to link changes
"C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe" ^
    "build\src\server\worldserver\worldserver.vcxproj" ^
    /p:Configuration=Debug /p:Platform=x64

Switching Between Debug and Release

# Switch to Debug
configure_debug.bat
build_debug.bat

# Switch to Release
configure_release.bat
build_release.bat

Note: Each configuration requires reconfiguration because CMake generates different project files.

Full Clean Rebuild

# Delete build directory
rmdir /s /q build

# Reconfigure
configure_debug.bat

# Rebuild
build_debug.bat

---

Debugging

Visual Studio Debugging

1. Open Solution:

   start build\TrinityCore.sln
   

2. Set Startup Project:

   • Right-click worldserver in Solution Explorer
   • Select "Set as Startup Project"

3. Configure Command Arguments:

   • Right-click worldserver → Properties
   • Configuration Properties → Debugging
   • Command Arguments: -c worldserver.conf
   • Working Directory: $(OutDir) or absolute path to server directory

4. Start Debugging:

   • Press F5 to start with debugging
   • Press Ctrl+F5 to start without debugging

WinDbg Debugging

# Launch with WinDbg
windbg.exe -o build\src\server\worldserver\Debug\worldserver.exe -c worldserver.conf

# WinDbg commands for debugging
# Break on exception:
sxe av

# Load symbols:
.sympath+ C:\TrinityBots\TrinityCore\build\src\server\worldserver\Debug

# Analyze crash dump:
!analyze -v

---

Library Linking (Debug vs Release)

How vcpkg Integration Works

When you use CMAKE_TOOLCHAIN_FILE, vcpkg automatically:

1. Debug Configuration:

   • Links to C:\libs\vcpkg\installed\x64-windows\debug\lib\*.lib
   • Copies debug DLLs to output directory
   • Uses debug version of libraries (e.g., tbb12_debug.lib)

2. Release Configuration:

   • Links to C:\libs\vcpkg\installed\x64-windows\lib\*.lib
   • Copies release DLLs to output directory
   • Uses release version of libraries (e.g., tbb12.lib)

Verifying Library Linkage

Check CMake configuration:

# View CMake cache
type build\CMakeCache.txt | findstr /I "vcpkg"

# Expected output:
# CMAKE_TOOLCHAIN_FILE:FILEPATH=C:/libs/vcpkg/scripts/buildsystems/vcpkg.cmake
# VCPKG_TARGET_TRIPLET:STRING=x64-windows

Check library paths in Visual Studio project:

# View library directories in project file
type build\src\server\worldserver\worldserver.vcxproj | findstr /I "AdditionalLibraryDirectories"

---

Troubleshooting

Linking Errors (LNK2019, LNK2001)

Problem: Undefined symbols or missing library references

Solution:

1. Verify vcpkg libraries are installed:

   C:\libs\vcpkg\vcpkg.exe list
   

2. Check debug libraries exist:

   dir C:\libs\vcpkg\installed\x64-windows\debug\lib
   

3. Reconfigure with correct vcpkg path:

   configure_debug.bat
   

Boost Library Conflicts (LNK2038)

Problem: Runtime library mismatch error:

error LNK2038: mismatch detected for 'RuntimeLibrary':
value 'MD_DynamicRelease' doesn't match value 'MDd_DynamicDebug'

Root Cause: Mixing Debug and Release Boost libraries

Solution:

1. Verify correct Boost libraries are being used:

   # Check CMake cache for Boost libraries
   type build\CMakeCache.txt | findstr "Boost_.*_LIBRARY"
   
   # Debug should have -gd- in the library names
   # Release should NOT have -gd- in the library names
   

2. Check FindSystemBoost.cmake is present:

   dir cmake\FindSystemBoost.cmake
   

3. Clean and reconfigure:

   rmdir /s /q build
   configure_debug.bat  # or configure_release.bat
   

4. Verify Boost library directory has both Debug and Release libraries:

   # Should see both types of libraries
   dir C:\libs\boost_1_78_0\stage\lib\libboost_system*.lib
   
   # Expected output:
   # libboost_system-vc143-mt-gd-x64-1_78.lib    (Debug)
   # libboost_system-vc143-mt-x64-1_78.lib        (Release)
   

Wrong Library Version Linked

Problem: Debug build tries to link release libraries (or vice versa)

Solution:

1. Clean build directory:

   rmdir /s /q build
   

2. Reconfigure:

   configure_debug.bat
   

3. Rebuild:

   build_debug.bat
   

CMake Configuration Fails

Problem: CMake cannot find vcpkg or libraries

Solution:

1. Verify vcpkg path:

   dir C:\libs\vcpkg\vcpkg.exe
   

2. Verify libraries installed:

   C:\libs\vcpkg\vcpkg.exe list
   

3. Install missing libraries:

   C:\libs\vcpkg\vcpkg.exe install tbb:x64-windows parallel-hashmap:x64-windows
   

Build Hangs or Freezes

Problem: MSBuild appears to hang during compilation

Solution:

1. Reduce CPU cores used:

   # Edit build script and change /maxcpucount:2 to /maxcpucount:1
   

2. Check for antivirus interference:

   • Add build directory to antivirus exclusions

3. Check for disk space:

   • Debug builds require ~15-20 GB free space

Out of Memory Errors

Problem: Compiler runs out of memory (C1060, C1076)

Solution:

1. Reduce parallel build jobs:

   # Edit build script: /maxcpucount:1
   

2. Close other applications

3. Increase virtual memory (page file size)

---

Performance Considerations

Build Times

Configuration	Full Build	Incremental	Playerbot Only
Debug	20-40 min	2-10 min	2-5 min
Release	15-30 min	2-8 min	2-5 min

Disk Space Requirements

Configuration	Build Directory	Total Size
Debug	~10-12 GB	~15-18 GB
Release	~4-6 GB	~8-10 GB

Memory Requirements

• Minimum: 8 GB RAM
• Recommended: 16 GB RAM
• Optimal: 32 GB RAM (for parallel builds)

---

Advanced Usage

Building Specific Projects

# Build only worldserver (Debug)
"C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe" ^
    "build\src\server\worldserver\worldserver.vcxproj" ^
    /p:Configuration=Debug /p:Platform=x64

# Build only Playerbot module (Debug)
"C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe" ^
    "build\src\server\modules\Playerbot\playerbot.vcxproj" ^
    /p:Configuration=Debug /p:Platform=x64

# Build only game library (Debug)
"C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe" ^
    "build\src\server\game\game.vcxproj" ^
    /p:Configuration=Debug /p:Platform=x64

Parallel Builds with Higher CPU Count

# Use all CPU cores (faster but more memory intensive)
"C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe" ^
    "build\TrinityCore.sln" ^
    /p:Configuration=Debug /p:Platform=x64 ^
    /maxcpucount ^
    /verbosity:minimal

Clean Build (Delete Intermediate Files)

# Clean Debug build
"C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe" ^
    "build\TrinityCore.sln" ^
    /t:Clean /p:Configuration=Debug /p:Platform=x64

# Clean Release build
"C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe" ^
    "build\TrinityCore.sln" ^
    /t:Clean /p:Configuration=Release /p:Platform=x64

---

File Structure Reference

C:\TrinityBots\TrinityCore\
├── configure_debug.bat              # Configure CMake for Debug
├── configure_release.bat            # Configure CMake for Release
├── build_debug.bat                  # Build full solution (Debug)
├── build_release.bat                # Build full solution (Release)
├── build_playerbot_debug.bat        # Build Playerbot only (Debug)
├── BUILD_DOCUMENTATION.md           # This file
├── build/                           # CMake build directory (generated)
│   ├── TrinityCore.sln             # Visual Studio solution
│   ├── CMakeCache.txt              # CMake configuration cache
│   ├── src/
│   │   └── server/
│   │       ├── worldserver/
│   │       │   ├── Debug/          # Debug binaries
│   │       │   └── Release/        # Release binaries
│   │       ├── bnetserver/
│   │       │   ├── Debug/
│   │       │   └── Release/
│   │       └── modules/
│   │           └── Playerbot/
│   │               ├── Debug/
│   │               └── Release/
├── src/
│   └── modules/
│       └── Playerbot/              # Playerbot source code
└── build_debug_output.txt          # Build log (generated)

---

Quick Reference

Configure Commands

configure_debug.bat      # Configure for Debug
configure_release.bat    # Configure for Release

Build Commands

build_debug.bat          # Build all (Debug)
build_release.bat        # Build all (Release)
build_playerbot_debug.bat # Build Playerbot only (Debug)

vcpkg Commands

# Install libraries
C:\libs\vcpkg\vcpkg.exe install tbb:x64-windows
C:\libs\vcpkg\vcpkg.exe install parallel-hashmap:x64-windows

# List installed libraries
C:\libs\vcpkg\vcpkg.exe list

# Update libraries
C:\libs\vcpkg\vcpkg.exe upgrade --no-dry-run

# Remove library
C:\libs\vcpkg\vcpkg.exe remove tbb:x64-windows

CMake Commands (Manual)

# Configure Debug
cmake .. -G "Visual Studio 17 2022" -A x64 ^
    -DCMAKE_BUILD_TYPE=Debug ^
    -DCMAKE_TOOLCHAIN_FILE="C:/libs/vcpkg/scripts/buildsystems/vcpkg.cmake" ^
    -DVCPKG_TARGET_TRIPLET=x64-windows ^
    -DBUILD_PLAYERBOT=1

# Configure Release
cmake .. -G "Visual Studio 17 2022" -A x64 ^
    -DCMAKE_BUILD_TYPE=Release ^
    -DCMAKE_TOOLCHAIN_FILE="C:/libs/vcpkg/scripts/buildsystems/vcpkg.cmake" ^
    -DVCPKG_TARGET_TRIPLET=x64-windows ^
    -DBUILD_PLAYERBOT=1

---

Support

For build issues:

1. Check build_debug_output.txt or build_release_output.txt
2. Verify vcpkg libraries are installed correctly
3. Ensure Visual Studio 2022 Enterprise is properly installed
4. Check disk space and memory availability

For TrinityCore-specific issues:

• TrinityCore Documentation: https://trinitycore.info/
• TrinityCore GitHub: https://github.com/TrinityCore/TrinityCore