-
Notifications
You must be signed in to change notification settings - Fork 786
Building
This article is aimed at downloading Hercules and any dependencies required to run it. In this article, you are expected to know basic file and program management of the OS you are attempting to run Hercules on. (Or use Google to search for the answers)
Hercules runs on a variety of 32-bit and 64-bit operating systems, including Windows, Linux and Unix. Hardware requirements are ones of typical server environment, whether virtual or dedicated
Hercules primarily works on x86/x86_64 processors, but it may also work on ARM64 and Apple Silicon although not officially supported
To run Hercules, the following software must be installed on the machine that will run Hercules:
The following software is necessary to build Hercules
- cmake
- you preferred build tools like gmake, make or ninja
- python3
- python3 virtual environment plugin
- you preferred C++ compiler (gcc/g++ or clang/clang++).
on Debian based distros you may easily install all of the required packages using either of the following commands depends on which compiler you prefer
gcc
sudo apt install make python3 python3-venv cmake gcc g++
clang
sudo apt install make python3 python3-venv cmake clang
The following software is necessary to build Hercules
- Visual Studio 2022 with the following packages/options selected
- Desktop Development with C++
- MSVC v143 - VS 2022 C++ x64/x86 build tools
- Windows 11 SDK
- cmake
- ninja (strongly recommended)
- python3
you can easily install cmake, ninja and python3 on windows using the winget package manager on windows using the following command in an elevated powershell.
winget install Ninja-build.Ninja cmake python3
Before we start building we need to setup a virtual environment for python and install conan2 this is our package manager for our C/C++ dependencies, by default we will have it saved to .venv directory in our root directory of hercules, this directory is ignored by default.
Open a PowerShell window into the cloned Hercules repository's root directory and run the following command:
.\setup_env.ps1
For information and to see the available options, use:
get-help .\setup_env.ps1 -detailed
The same command can be used to re-enter the dev environment to rebuild at a later time.
Open a shell (zsh, bash, dash, etc.), cd into the cloned Hercules repository's root directory and run the following command:
. ./setup_env.sh
For information and to see the available options, use:
. ./setup_env.sh --help
The same command can be used to re-enter the dev environment to rebuild at a later time.
First run the following command in Hercules root directory
python3 -m venv .venv
then activate the environment
Unix-like
. .venv/bin/activate
Windows (Powershell)
.venv/Scripts/Activate.ps1
Windows (CMD)
".venv/Scripts/activate.bat"
Once your environment is activated, it's time to install conan.
pip install conan
Moving forward to compile on windows we need to use Visual Studio Native tools environment to run it search for x64 Native Tools Command Prompt for VS 2022 under VS directory in start menu or through search feature, this will be done for 64bit builds if you wish for a 32bit bit build open x86 Native Tools Command Prompt for VS 2022 instead then navigate to Hercules directory and enable python environment using the following command:
".venv/Scripts/activate.bat"
Usually you'd need to only run cmake once similar to how you used to run ./configure only once to configure the build system, cmake does the same pretty much, it also runs conan for us to download any packages we need to build Hercules.
with cmake we now expect to have a build directory and install directory for the build executables, plugins and dependencies the current default structure looks like the following:
- Hercules root directory
- build
- build directory and where we run build commands
- bin
- install directory where server executables, plugins and built dependencies are installed and ran from
our cmake scripts also come with the same options that were provided through ./configure to pass an option to cmake add a new argument starting with -D following by option name and value for example -DPACKETVER=20200101 to set PACKETVER option to 20200101.
The following table contains full options list for cmake:
| Option | Description | Default value |
|---|---|---|
| MEMORY_MANAGER | memory managers: none, builtin, memwatch, dmalloc, gcollect, bcheck
|
builtin |
| PACKETVER | Sets the PACKETVER define. (see src/common/mmo.h) |
|
| CASHSHOP_PREVIEW_PATCH | Enable Nemo patch ExtendCashShopPreview. | OFF |
| OLD_CASHSHOP_PREVIEW_PATCH | Enable Nemo patch ExtendOldCashShopPreview. | OFF |
| ENABLE_PACKETVER_RE | Sets or unsets the PACKETVER_RE define - see src/common/mmo.h
|
OFF |
| ENABLE_PACKETVER_ZERO | Sets or unsets the ENABLE_PACKETVER_ZERO define - see src/common/mmo.h
|
OFF |
| ENABLE_PACKETVER_AD | Sets or unsets the ENABLE_PACKETVER_AD define - see src/common/mmo.h
|
OFF |
| ENABLE_PACKETVER_SAK | Sets or unsets the ENABLE_PACKETVER_SAK define - see src/common/mmo.h
|
OFF |
| ENABLE_EPOLL | use epoll(4) on Linux | OFF |
| OBFUSCATIONKEY1 | Sets the first obfuscation key (ignored unless the other two are also specified) | |
| OBFUSCATIONKEY2 | Sets the second obfuscation key (ignored unless the other two are also specified) | |
| OBFUSCATIONKEY3 | Sets the third obfuscation key (ignored unless the other two are also specified) | |
| ENABLE_GDB | Compiles with gdb specific optimzations for better debugging. | OFF |
| ENABLE_LIBBACKTRACE | Compiles with libbacktrace. | OFF on non-linux ON on linux |
| ENABLE_BUILDBOT | Build bot specific code changes | OFF |
| ENABLE_RDTSC | Uses rdtsc as timing source | OFF |
| ENABLE_PROFILER | Profilers: none, gprof
|
none |
| ENABLE_RENEWAL | Enable renewal | ON |
| ENABLE_LTO | Enables or Disables Link-time Code Optimization | OFF |
| ENABLE_SANITIZE | Enables sanitizer. | OFF |
| ENABLE_WERROR | Enables warning as error | OFF |
| MAX_CONNECTIONS | optionally set the maximum connections the core can handle | Without epoll enabled, default: 1024. With epol enabled: 3072 |
| WITH_HTTP_PARSER | select http parser. Allowed values: http-parser, llhttp
|
http-parser |
| ENABLE_TESTING | Enables compiling and running of tests | OFF |
| ENABLE_CLASSIC_AUTOSPELL | Enables classic auto spell list | OFF |
| ENABLE_ASAN_LEAKREPORT | Uses AddressSanitizer to report memory leaks instead of the memory manager, requires memory manager to be disabled | OFF |
| BUILD_PLUGINS | Allows the build of plugins, if disabled plugins cmake files won't be loaded | ON |
| BUILD_HPMHOOKING | Allows the build of HPM Hooking plugins, if disabled their targets won't be added to build targets | OFF |
To configure cmake the first time with all default values you can run the following from Hercules root directory, you should pass -G option to define the preferred build tools in our case we will use ninja, and use the -DCMAKE_BUILD_TYPE option to decide if it's a Release, Debug or RelWithDebInfo build. generally speaking you want it RelWithDebInfo on production to aid a bit with debugging issues and Debug during development for best debugging capabilities.
On windows we will pass -G Ninja to use ninja build system which behaves pretty much like GNU Make
cmake -B build -S . -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=cmake_modules/conan_provider.cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -G Ninja
On other systems you can just use GNU Make or install ninja and use ninja
cmake -B build -S . -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=cmake_modules/conan_provider.cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo
First run may take a long while which is okay, conan will be pulling dependencies and compiling them for your system.
Once cmake is ran we now have our build files inside build directory, move to it and assuming you're using ninja build tools you may run ninja all or any specific targets like ninja plugins to build a specific part, you can know all the options from ninja help alternatively same commands would run with make if that's what you're using.
The following is a list of the most commonly used targets that can be used with any of the build systems.
| Target | Behavior |
|---|---|
all |
Builds all servers and plugins |
install |
Copies server executables, plugins and dependencies to installation path |
sql |
Builds all server |
hooks |
Build HPM Hooks definition and checks |
docs |
Builds doxygen documentation |
plugins |
Builds all plugins |
plugin.foo |
Builds a plugin named foo replace it with actual plugin name |
plugin.HPMHooking |
A special target that builds all HPMHooking plugins |
api-server |
Builds api-server |
login-server |
Builds login-server |
char-server |
Builds char-server |
map-server |
Builds map-server |
Once compilation is done we need to install our executables, plugins and conan dependencies to their expected path under bin directory to do that run ninja install
You may now go back to Hercules root directory and run any server as ./bin/login-server for example for login server, on windows you can run the bat scripts and on linux the athena-start and shell scripts are updated to run from this location