Documentation Index
Fetch the complete documentation index at: https://mintlify.com/danielkrupinski/Osiris/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Osiris supports Linux distributions with modern kernel versions. The Linux build outputs libOsiris.so which must be injected into the CS2 game process using gdb or a custom injector.
Prerequisites
- CMake 3.24 or newer
- g++ 11 or newer OR clang++ 18 or newer
- Git (for cloning the repository)
- Standard build tools (make, binutils)
Supported Compilers
Supported versions:
- g++-11 (minimum)
- g++-12
- g++-13
- g++-14
- g++-15
Install on Ubuntu:sudo apt install g++-11 # or higher version
Supported versions:
- clang++-18 (minimum)
- clang++-19
- clang++-20
- clang++-21
Install on Ubuntu:# Download LLVM install script
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 18 # or higher version
Building from Source
# Release build
cmake -DCMAKE_BUILD_TYPE=Release -B build
# Debug build
cmake -DCMAKE_BUILD_TYPE=Debug -B build
# Specify Clang compiler
CXX=clang++-18 cmake -DCMAKE_BUILD_TYPE=Release -B build
cmake -DCMAKE_BUILD_TYPE=Release \
-DENABLE_TESTS="unit;functional" \
-B build
Build
cmake --build build -j $(nproc --all)
-j $(nproc --all) flag enables parallel compilation using all CPU cores.
Output File
The Linux build produces libOsiris.so, a shared object library.
File location:
build/Source/libOsiris.so
Injection Methods
GDB Injection (Standard)
The recommended injection method uses GDB to load the library:
cd build/Source/
sudo gdb -batch-silent -p $(pidof cs2) -ex "call (void*)dlopen(\"$PWD/libOsiris.so\", 2)"
VAC Detection RiskThis injection method might be detected by VAC because gdb is visible under TracerPid in /proc/$(pidof cs2)/status for the duration of the injection.Consider using alternative injection methods for reduced detection risk.
Entry Point
On Linux, Osiris initializes through a constructor function:
void __attribute__((constructor)) DllEntryPoint()
{
GlobalContext::initializeInstance();
}
dlopen().
Osiris uses custom Linux API wrappers located in Source/Platform/Linux/:
- LinuxPlatformApiImpl.h - Core platform API implementation
- LinuxDynamicLibrary.h - Dynamic library loading via dlopen/dlsym
- UserHomeFolderPath.h - Configuration file path resolution
- FileSystem/ - File I/O operations
- RTTI/ - Runtime type information parsing for virtual method tables
Configuration Storage
Configuration files are stored in:
$HOME/OsirisCS2/configs/default.cfg
HOME environment variable:
if (const auto home = LinuxPlatformApi::getenv("HOME"))
return ConstString{ home };
Technical Features
- No heap memory allocations
- No threads created
- Exception-free implementation
- Direct system calls for file operations
- ELF parsing for dynamic library introspection
- RTTI parsing for virtual method table location
Build Configurations
Release
Debug
Unity Build
Optimized build:cmake -DCMAKE_BUILD_TYPE=Release -B build
cmake --build build -j $(nproc --all)
- Full optimizations enabled
- Minimal binary size
- No debugging symbols
- Best performance
Development build:cmake -DCMAKE_BUILD_TYPE=Debug -B build
cmake --build build -j $(nproc --all)
- Debugging symbols included
- Runtime checks enabled
- Slower execution
- Easier to debug with GDB
Faster compilation:cmake -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_UNITY_BUILD=ON \
-DCMAKE_UNITY_BUILD_BATCH_SIZE=4 \
-B build
cmake --build build -j $(nproc --all)
Common Issues
CMake Version Too Old
If you see “CMake 3.24 or higher is required”:
# Add Kitware APT repository for latest CMake
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc | sudo apt-key add -
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ focal main'
sudo apt update
sudo apt install cmake
Compiler Not Found
If CMake can’t find your compiler:
# Explicitly specify compiler
CXX=/usr/bin/g++-11 cmake -DCMAKE_BUILD_TYPE=Release -B build
# Or for Clang
CXX=/usr/bin/clang++-18 cmake -DCMAKE_BUILD_TYPE=Release -B build
Injection Failed
If GDB injection fails:
# Ensure CS2 is running
pidof cs2
# Check if you have sufficient permissions
sudo -v
# Verify library path is correct
ls -lh $PWD/libOsiris.so
# Try with absolute path
sudo gdb -batch-silent -p $(pidof cs2) -ex "call (void*)dlopen(\"/absolute/path/to/libOsiris.so\", 2)"
Missing Dependencies
If build fails with missing headers:
# Install build essentials
sudo apt install build-essential cmake git
# For g++
sudo apt install g++-11
# For clang
sudo apt install clang-18
VAC Detection Considerations
VAC Risk on LinuxThe GDB injection method may be detectable because:
- GDB attaches as a debugger (visible in
/proc/[pid]/status)
- The
TracerPid field shows the debugger process
- VAC may scan for debugging indicators
For reduced risk, consider:
- Using manual mapping injectors
- Avoiding GDB-based injection in competitive matches
- Monitoring VAC ban reports from the community
Testing
Osiris includes comprehensive tests:
# Configure with tests enabled
cmake -DCMAKE_BUILD_TYPE=Release \
-DENABLE_TESTS="unit;functional" \
-B build
# Build tests
cmake --build build --target UnitTests -j $(nproc --all)
cmake --build build --target FunctionalTests -j $(nproc --all)
# Run tests
ctest -R ^Unit --test-dir build --output-on-failure -j $(nproc --all)
ctest -R ^Functional --test-dir build --output-on-failure -j $(nproc --all)
See Also