Skip to content

Commit

Permalink
Minimal refactoring to README.md, formatted the builds table to be mo…
Browse files Browse the repository at this point in the history 
…re compact.
  • Loading branch information
cbnolok committed Aug 26, 2024
1 parent 6194606 commit 1f43026
Showing 1 changed file with 80 additions and 88 deletions.
168 changes: 80 additions & 88 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,9 @@ If you're new to the Sphere server and want to setup your first shard, [this is
| :--- | :--- |
| [![GitHub last commit on Master branch](https://img.shields.io/github/last-commit/Sphereserver/Source-X/master.svg)](https://github.com/Sphereserver/Source-X/) &nbsp; <a href="https://github.com/Sphereserver/Source-X/blob/master/Changelog.txt">Changelog</a> | [![GitHub last commit on Dev branch](https://img.shields.io/github/last-commit/Sphereserver/Source-X/dev.svg)](https://github.com/Sphereserver/Source-X/tree/dev) &nbsp; <a href="https://github.com/Sphereserver/Source-X/blob/dev/Changelog.txt">Changelog</a> |
| **Nightly builds:** | **Nightly builds:** |
| [![Build status: Windows x86_64](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86_64.yml/badge.svg?branch=master)](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86_64.yml) | [![Build status: Windows x86_64](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86_64.yml/badge.svg?branch=dev)](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86_64.yml) |
| [![Build status: Windows x86](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86.yml/badge.svg?branch=master)](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86.yml) | [![Build status: Windows x86](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86.yml/badge.svg?branch=dev)](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86.yml) |
| [![Build status: Linux x86_64](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86_64.yml/badge.svg?branch=master)](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86_64.yml) | [![Build status: Linux x86_64](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86_64.yml/badge.svg?branch=dev)](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86_64.yml) |
| [![Build status: Linux x86](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86.yml/badge.svg?branch=master)](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86.yml) | [![Build status: Linux x86](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86.yml/badge.svg?branch=dev)](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86.yml) |
| [![Build status: MacOS x86_64](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_x86_64.yml/badge.svg?branch=master)](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_x86_64.yml) | [![Build status: MacOS x86_64](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_x86_64.yml/badge.svg?branch=dev)](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_x86_64.yml) |
| [![Build status: MacOS ARM](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_arm.yml/badge.svg?branch=master)](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_arm.yml) | [![Build status: MacOS ARM](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_arm.yml/badge.svg?branch=dev)](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_arm.yml) |
| [![Build status: Windows x86_64](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86_64.yml/badge.svg?branch=master)](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86_64.yml) [![Build status: Windows x86](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86.yml/badge.svg?branch=master)](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86.yml) | [![Build status: Windows x86_64](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86_64.yml/badge.svg?branch=dev)](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86_64.yml) [![Build status: Windows x86](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86.yml/badge.svg?branch=dev)](https://github.com/Sphereserver/Source-X/actions/workflows/build_win_x86.yml)|
| [![Build status: Linux x86_64](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86_64.yml/badge.svg?branch=master)](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86_64.yml) [![Build status: Linux x86](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86.yml/badge.svg?branch=master)](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86.yml) | [![Build status: Linux x86_64](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86_64.yml/badge.svg?branch=dev)](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86_64.yml) [![Build status: Linux x86](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86.yml/badge.svg?branch=dev)](https://github.com/Sphereserver/Source-X/actions/workflows/build_linux_x86.yml) |
| [![Build status: MacOS x86_64](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_x86_64.yml/badge.svg?branch=master)](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_x86_64.yml) [![Build status: MacOS ARM](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_arm.yml/badge.svg?branch=master)](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_arm.yml) | [![Build status: MacOS x86_64](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_x86_64.yml/badge.svg?branch=dev)](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_x86_64.yml) [![Build status: MacOS ARM](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_arm.yml/badge.svg?branch=dev)](https://github.com/Sphereserver/Source-X/actions/workflows/build_osx_arm.yml) |

**Click the badges or follow the links:**

Expand Down Expand Up @@ -74,67 +71,63 @@ Most notable changes (right now) are:

### Required libraries (Windows)

+ `libmariadb.dll` (MariaDB Client v10.*package), found in lib/bin/*cpu_architecture*/mariadb/libmariadb.dll
+ `libmariadb.dll` (MariaDB Client v10.*package), found in `lib/bin/*cpu_architecture*/mariadb/libmariadb.dll`
<br>

### Required libraries (Linux)

+ MariaDB Client library. Get it from the following sources.
<br>

#### From MariaDB website

See <https://mariadb.com/docs/skysql/connect/clients/mariadb-client/>

#### Ubuntu and Debian repositories

Ubuntu: Enable "universe" repository: `sudo add-apt-repository universe`
Install MariaDB client: `sudo apt-get install mariadb-client` or `sudo apt-get install libmariadb3` (depends on the OS version)

#### CentOS - Red Hat Enterprise Linux - Fedora repositories

Then install MariaDB client via yum (CentOS or RH) or dnf (Fedora): `mariadb-connector-c`
<br>
+ From MariaDB website
See <https://mariadb.com/docs/skysql/connect/clients/mariadb-client/>
+ Ubuntu and Debian repositories
Ubuntu: Enable "universe" repository: `sudo add-apt-repository universe`
Install MariaDB client: `sudo apt-get install mariadb-client` or `sudo apt-get install libmariadb3` (depends on the OS version)
+ CentOS - Red Hat Enterprise Linux - Fedora repositories
Then install MariaDB client via yum (CentOS or RH) or dnf (Fedora): `mariadb-connector-c`

### Required libraries (MacOS)

+ Install MariaDB Client library via `brew install mariadb-connector-c`

## Building
## Building the server from the source

### Generating the project files

The compilation of the code is possible only using recent compilers, since C++20 features are used: the newer the compiler, the better. Oldest compiler versions supporting C++20: Visual Studio 2019 version 16.11, GCC 8, MinGW distributions using GCC 8, Clang version 10.<br>
You need to build Makefiles or Ninja files (and project files if you wish) with CMake for both Linux (GCC) and Windows (MSVC and MinGW).<br>
Both 32 and 64 bits compilation are supported.<br>
No pre-built project files included.<br>
Does CMake give you an error? Ensure that you have Git installed, and if you are on Windows ensure also that the Git executable was added to the PATH environmental variable
Only recent compilers are supported, since Sphere uses C++20 features: the newer the compiler, the better. Oldest compiler versions supporting C++20: Visual Studio 2019 version 16.11, GCC 8, MinGW distributions using GCC 8, Clang version 10.
No pre-built project files are included. You need to build Visual Studio solution (.sln), Makefiles or Ninja Build files (or project files for other IDE or build systems) with CMake.
Below there's is a small guide.
You can use CMake GUI (graphical interface) or its CLI (command line interface).
To pass a flag to using the CLI, just prepend `-D` to the name of the variable, then assign the value with the equal sign, eg: `-DFOO=TRUE`.

Before starting: does CMake give you an error? Ensure that you have Git installed, and if you are on Windows ensure also that the Git executable was added to the PATH environmental variable
(you'll need to add it manually if you are using Git Desktop,
<a href="https://stackoverflow.com/questions/26620312/installing-git-in-path-with-github-client-for-windows?answertab=votes#tab-top">here's a quick guide</a>).<br>

#### Toolchains and custom CMake variables

When generating project files, if you don't specify a toolchain, the CMake script will pick the native one as default.<br>
How to set a toolchain:

+ Via CMake GUI: when configuring for the first time the project, choose "Specify toolchain file for cross-compiling", then on the next step you'll be allowed to select the toolchain file
+ Via CMake CLI (command line interface): pass the parameter `-DCMAKE_TOOLCHAIN_FILE="..."`
When using Makefiles or Ninja, you can specify a build type by setting (also this via GUI or CLI) `CMAKE_BUILD_TYPE="build"`, where build is **Nightly**, **Debug** or **Release**. If the build type
was not set, by default the makefiles for all of the three build types are generated.<br>
<br />

You can also add other compiler flags, like optimization flags, with the custom variables C_FLAGS_EXTRA and CXX_FLAGS_EXTRA.<br>

Example of CMake CLI additional parameters:<br>

```bash
-DC_FLAGS_EXTRA="-mtune=native" -DCXX_FLAGS_EXTRA="-mtune=native"
```

(Use the -mtune=native flag only if you are compiling on the same machine on which you will execute Sphere!)

Example to build makefiles on Linux for a 64 bits Nightly version, inside the "build" directory (run it inside the project's root folder):<br>

<a href="https://stackoverflow.com/questions/26620312/installing-git-in-path-with-github-client-for-windows?answertab=votes#tab-top">here's a quick guide</a>).

+ Select a **Generator**
Tells CMake which kind of project file to generate (Visual Studio, makefile, ninja build file...)
+ GUI: it's the first thing CMake will ask you (well, after Sphere source directory)
+ CLI: use -G flag, example: `-G "Visual Studio 17 2022"` or `-G Ninja`.

+ Select a **Toolchain**
When generating project files, the easiest way is to use the provided OS-specific CMake toolchain file to automatically pass the right options to the selected compiler.
You can find them in the `cmake/toolchains/` folder.
If you don't specify a toolchain, CMake will pick the native one as default.
How to set a toolchain:
+ Via CMake GUI: when configuring for the first time the project, choose "Specify toolchain file for cross-compiling", then on the next step you'll be allowed to select the toolchain file.
+ Via CMake CLI (command line interface): pass the parameter `-DCMAKE_TOOLCHAIN_FILE="..."`

+ Build **Configuration** (type)
When using Makefiles or Ninja, you can specify a build type by setting (also this via GUI or CLI) `CMAKE_BUILD_TYPE="build"`, where build is **Nightly**, **Debug** or **Release**. If the build type was not set, by default the makefiles for all of the three build types are generated.
**Debug** build is expected to be slow and it's to be used, you guessed it, for debugging purposes (best coupled with a debugger or with sanitizers enabled, more on them right below), so don't use it for a live shard!

<br>
Other useful CMake flags:

+ You can add other compiler flags with the custom variables `C_FLAGS_EXTRA` and `CXX_FLAGS_EXTRA`.
+ Enable Sanitizers: `USE_ASAN[=ON]`, `USE_UBSAN`, `USE_LSAN`, etc.
+ `CROSSCOMPILING_ARCH`: set this to TRUE to tell the compiler you are building binary files for a different architecture (not from x86_64 to x86, but for example from x86 to ARM).

Example to build makefiles on Linux for a 64 bits Nightly version, inside the "build" directory (run the command inside the project's root folder):
```bash
mkdir build
cmake -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/Linux-GNU-x86_64.cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE="Nightly" -B ./build -S ./
Expand All @@ -146,32 +139,29 @@ cmake -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/Linux-GNU-x86_64.cmake -G "Unix Ma

Building will require more packages than the ones needed to run Sphere.

##### Ubuntu and Debian

+ Ubuntu and Debian
Install these additional packages:
+ Build tools (other than the compiler): `sudo apt-get install git cmake`.
+ MariaDB client: `sudo apt-get install libmariadb-dev` and `libmariadb3` or `mariadb-client` (depends on the OS version)
If you are on a 64 bits architecture but you want to compile (or execute) a 32 bits binary, you will need to
install MariaDB packages adding the postfix `:i386` to each package name.

+ `sudo apt-get install git cmake`
+ MariaDB client: `sudo apt-get install libmariadb-dev` and `libmariadb3` or `mariadb-client` (depends on the OS version)

If you are on a 64 bits architecture but you want to compile (or execute) a 32 bits binary, you will need to
install MariaDB packages adding the postfix `:i386` to each package name.

##### CentOS - Red Hat Enterprise Linux - Fedora

Then install these additional packages via yum (CentOS or RH) or dnf (Fedora): `git gcc-c++ glibc-devel mariadb-connector-c mariadb-connector-c-devel`<br>
<br>If you are on a 64 bits architecture but you want to compile (or execute) a 32 bits binary, you will need to install the appropriate gcc package
and to install the MySQL packages adding the postfix `.i686` to each package name.
+ CentOS - Red Hat Enterprise Linux - Fedora
Install these additional packages via yum (CentOS or RH) or dnf (Fedora).
+ Build tools (other than the compiler): `git cmake glibc-devel`
+ MariaDB client: `mariadb-connector-c mariadb-connector-c-devel`
If you are on a 64 bits architecture but you want to compile (or execute) a 32 bits binary, you will need to install MariaDB packages adding the postfix `.i686` to each package name.

#### Compiling on Linux

Just run the `make` command inside the `build` folder. You can pass the -jX argument (`make -jX`, where X is a number) to speed up the compilation and split the work between X threads.

#### Address Sanitizer and Undefined Behaviour Sanitizer

You can enable Address Sanitizer (ASan) and Undefined Behaviour Sanitizer (UBSan) with the ENABLE_SANITIZERS checkbox via the GUI, or via the CLI flag `-DENABLE_SANITIZERS=true`.<br>
This is easier with GCC and Clang on Linux.<br>
You can enable Address Sanitizer (ASan) and Undefined Behaviour Sanitizer (UBSan) with the ENABLE_SANITIZERS checkbox via the GUI, or via the CLI flag `-DENABLE_SANITIZERS=true`.
This is easier with GCC and Clang on Linux.
Since ASan redirects the error output to stderr, you can retrieve its output by launching sphere from cmd (Command Prompt) or shell with the following command:
`SphereSvrX64_nightly > Sphere_ASan_log.txt 2>&1`
`SphereSvrX64_nightly > Sphere_ASan_log.txt 2>&1`, or simply use the precise flag to redirect the errors to a log file.

## Coding Notes (add as you wish to standardize the coding for new contributors)

Expand All @@ -186,9 +176,9 @@ Since ASan redirects the error output to stderr, you can retrieve its output by
to be printed to or retrieved by scripts should always be signed.
+ Don't use "long" except if you know why do you actually need it. Always prefer "int" or "llong".
Use fixed width variables only for values that need to fit a limited range.
+ For strings, use pointers:<br>
to "char" for strings that should always have ASCII encoding;<br>
to "tchar" for strings that may be ASCII or Unicode, depending from compilation settings (more info in "datatypes.h");<br>
+ For strings, use pointers:
to "char" for strings that should always have ASCII encoding;
to "tchar" for strings that may be ASCII or Unicode, depending from compilation settings (more info in "datatypes.h");
to "wchar" for string that should always have Unicode encoding.

### Naming Conventions
Expand All @@ -212,12 +202,14 @@ These are meant to be applied to new code and, if there's some old code not foll
**Variables meant to hold characters (also strings):**

+ For char, wchar, tchar use respectively the prefixes "c", "wc", "tc".
+ When handling strings, "lpstr", "lpcstr", "lpwstr", "lpcwstr", "lptstr", "lpctstr" data types are preferred aliases.<br>
You'll find a lot of "psz" prefixes for strings: the reason is that in the past Sphere coders wanted to be consistent with Microsoft's Hungarian Notation.<br>
+ When handling strings, "lpstr", "lpcstr", "lpwstr", "lpcwstr", "lptstr", "lpctstr" data types are preferred aliases.
You'll find a lot of "psz" prefixes for strings: the reason is that in the past Sphere coders wanted to be consistent with Microsoft's Hungarian Notation.
The correct and up to date notation is "pc" for lpstr/lpcstr (which are respectively char*and const char*), "pwc" (wchar*and const wchar*),
"ptc" for lptstr/lpctstr (tchar*and const tchar*).<br>
Use the "s" or "ps" (if pointer) when using CString or std::string. Always prefer CString over std::string, unless in your case there are obvious advantages for using the latter.<br />
"ptc" for lptstr/lpctstr (tchar*and const tchar*).
Use the "s" or "ps" (if pointer) when using CString or std::string. Always prefer CString over std::string, unless in your case there are obvious advantages for using the latter.

Examples:

+ Class or Struct: "CChar".
+ Class internal variable, signed integer: "_iAmount".
+ Tchar pointer: "ptcName".
Expand All @@ -226,24 +218,24 @@ Examples:
### Coding Style Conventions

+ Indent with **spaces** of size 4.
+ Use the Allman indentation style:<br>
while (x == y)<br>
{<br>
&nbsp;&nbsp;&nbsp;&nbsp;something();<br>
&nbsp;&nbsp;&nbsp;&nbsp;somethingelse();<br>
+ Use the Allman indentation style:
while (x == y)
{
&nbsp;&nbsp;&nbsp;&nbsp;something();
&nbsp;&nbsp;&nbsp;&nbsp;somethingelse();
}

+ Even if a single statement follows the if/else/while... clauses, use the brackets:<br>
if (fTrue)<br>
{<br>
&nbsp;&nbsp;&nbsp;&nbsp;g_Log.EventWarn("True!\n");<br>
+ Even if a single statement follows the if/else/while... clauses, use the brackets:
if (fTrue)
{
&nbsp;&nbsp;&nbsp;&nbsp;g_Log.EventWarn("True!\n");
}

## Licensing

Copyright 2024 SphereServer development team.<br>
Copyright 2024 SphereServer development team.

Licensed under the Apache License, Version 2.0 (the "License").<br>
You may not use any file of this project except in compliance with the License.<br>
Licensed under the Apache License, Version 2.0 (the "License").
You may not use any file of this project except in compliance with the License.
You may obtain a copy of the License at <http://www.apache.org/licenses/LICENSE-2.0>

0 comments on commit 1f43026

Please sign in to comment.