jeirmeister/Cockatrice
1
0
Fork 0
mirror of https://github.com/Cockatrice/Cockatrice.git synced 2026-07-14 06:22:15 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions

Include compilation information in developer_reference.

Browse source 
Took 19 minutes

Took 2 minutes
This commit is contained in:
Lukas Brübach 2025-09-28 09:36:54 +02:00
parent 749afadf0f
commit d8e103466d
8 changed files with 836 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

1
doc/doxygen-extra-pages/building/index.md
View file

@ -1 +0,0 @@
\page building Building

79
doc/doxygen-extra-pages/developer_documentation/compilation/android.md Normal file
View file

@ -0,0 +1,79 @@
@page compilation_android Compiling for Android
[  ← Back to Compiling Overview](@ref compilation_index)
Hello everybody, this is probably the first thing I've ever contributed to the internet, so here goes.
Please excuse my lack of knowledge on how to format all this. (EDITed 9/25/21)
To start with you will need:
* A device running Android 7 or later. What matters is that you have ARMhf/x86/ARM64 (all I had to test on....)(update:def works on Samsung Galaxy Tab A also, Android 9)
* Active WiFi connection
* Between 1.5 - 3GB free space to play with; you're gonna need it. Plus space to save the images for your cards
* Patience....this will take the better part of 2 or 4 hours depending on your device CPU.
* The ability to copy commands without typos into a Linux terminal (JK)
Here's how this works!
Android is essentially Linux on an ARM device. So there's been plenty of development in the ARM space
for what we need, which isn't much really, just some repositories and a bit of code and we'll have you
running cockatrice on your smartphone in no time.
To start, download Termux, a terminal emulator or shell with which we will run our linux box on our device.
Then download your favorite VNC viewer of choice from the Play Store(UPDATE: Termux available through the F-Droid store, look it up. Dont get the one from the PLAY STORE)
***
There are multiple ways to do the next step;
Next, you need to get Linux on your device any way you like it; for me, I used AndroNix (free from the play store) to download Debian. This is where you have the freedom to choose what distro you are familiar with, but as a proof of concept, I used Debian. AndroNix basically copies the necessary text to a clipboard, which you then run inside Termux, thus downloading the basic Debian FileSystem (about 50MB). For me, at 1MB/s it took 2 mins or so. It then decompresses the .tar.xz file into a useable file system.
For me, the next step was to startup this Linux via './start-debian.sh'(EDIT: your name to startup linux may vary wildly. A simple LS command will show your startup scripts)
If all goes well, you are greeted with the bash prompt 'root@localhost:~#'
Now the nitty-gritty. We need a bunch of things to make this work, but a GUI would be nice so I used LXDE, again copying code from AndroNix. It downloads everything it needs (over 400 MB for LXDE) for a GUI and at 1MB/s it takes about 15 minutes.
Pay attention during your install. You do not want it to timeout on something simple like keyboard selection.
At some point you will be prompted to input your keyboard settings, this can be region specific. I put 1 for US default.
It will then "Get" a bunch of stuff downloaded and unpacked
Eventually you will get to this screen saying, you can run a vnc server. You put a password for the connection to the server, which we will use a VNC client for.
Before we see what we've done, we need to download the cockatrice source code so we can compile it on our device.
# Installs necessary packages, clones the repo, makes the build directory, cmakes, compiles, installs on Debian 10
# Run the following:
* sudo apt-get update
* sudo apt-get upgrade
* sudo apt-get install build-essential cmake git qt5-default qtbase5-dev qttools5-dev-tools qtmultimedia5-dev libqt5websockets5 libqt5websockets5-dev libqt5svg5-dev protobuf-compiler libprotoc17 libprotobuf17 libprotobuf-dev
You can leave out the lzma-dev bit since i tried that and it didnt add lzma support, but there is a way to get it I just cant remember how I got it. You will get an error message during compile but Cockatrice works for me without it. Search for lzma packages for your distro, and get the relevant -dev ones
<a href="https://app.photobucket.com/u/vindicate7/p/7752652b-37e3-4bc8-89e8-1485a7589127" target="_blank"> <img src="https://hosting.photobucket.com/images/ac357/vindicate7/0/2020-03-18%2001_12.png" border="0" alt="2020-03-18 01_12"/> </a>
Hold your breath. LOL not really cause this takes like 20 mins. But this next part, where we build Cockatrice from the ground up for our device, can take well over an hour; go ahead and start making dinner at this point.
* git clone git://github.com/Cockatrice/Cockatrice
* cd Cockatrice
* mkdir build
* cd build
* cmake -DWITH_SERVER=0 -DWITH_CLIENT=1 -DWITH_ORACLE=1 -DWITH_DBCONVERTER=1 ..
* make
<a href="https://app.photobucket.com/u/vindicate7/p/ea472184-21f8-4109-ac12-a1b2abc87113" target="_blank"> <img src="https://hosting.photobucket.com/images/ac357/vindicate7/0/2020-03-18%2002_04.png" border="0" alt="2020-03-18 02_04"/> </a>
* make install
Once you do that, it's all downhill from here bby. At the bash prompt type
* vncserver-start (if your vnc server isnt already up)
Now, you can switch to your VNC app you downloaded earlier. Use 127.0.0.1:5901 as your host or whatnot. Basically port 5901 is your connection to this Termux
***
<a href="https://app.photobucket.com/u/vindicate7/p/262ee328-239c-4bfe-88b9-5222b9d1ef7e" target="_blank"> <img src="https://hosting.photobucket.com/images/ac357/vindicate7/0/vnc.png" border="0" alt="vnc"/> </a>
<a href="https://app.photobucket.com/u/vindicate7/p/7db8493c-25d5-4438-9c27-219bb7f33b33" target="_blank"> <img src="https://hosting.photobucket.com/images/ac357/vindicate7/0/debian%20screen.png" border="0" alt="debian screen"/> </a>
***
When running Oracle for the first time, try the AllSets.json.xz like recommended. If your device can parse that file, good for you. On my device, I had to shorten the list to ModernPrintings.json myself since A)I don't play anything older than modern and B)My app would crash with the AllSets. Your mileage may vary. Essentially, checkout https://mtgjson.com/downloads/all-files/ and see what set you want to import into Oracle. Maybe you just want standard, or pioneer. There's a JSON for that. Oh I think here you may have to get the .zip version if you have no lzma support. At any rate it works so well.
In VNC Viewer for Android, a right click is with two fingers tap the screen. To click and drag, tap then tap-hold and drag.
Now that I've taken you this far, I think you should have no problem connecting to a server and playing; albeit it takes some getting used to.
You're welcome. Feel free to email me at dslman@gmail.com

84
doc/doxygen-extra-pages/developer_documentation/compilation/chromebooks.md Normal file
View file

@ -0,0 +1,84 @@
@page compilation_chromebooks Compiling for Chromebooks
[&nbsp; &larr; Back to Compiling Overview](@ref compilation_index)
## Installing Cockatrice
There are many ways to install Cockatrice on a Chromebook: via Flatpak, via pre-compiled .deb, and directly from source. No matter which method you choose, **you must first Enable Linux Apps** in order to have a Linux environment available to work in.
Please note that Cockatrice is not officially supported on ChromeOS and may behave unexpectedly or run poorly as a result. We are happy to help with issues to the best of our ability, but cannot guarantee solutions to all problems.
### Enabling Linux Apps
These steps may change! If they do not work for you, you can find the official instructions [here](https://support.google.com/chromebook/answer/9145439).
1. On your Chromebook, at the bottom right, select the time.
2. Select `Settings` > `About ChromeOS` >`Developers`.
3. Next to "Linux development environment," select `Set up`.
4. Follow the on-screen instructions. This can take some time.
### Installing via Flatpak
#### Setting up Flatpak
1. Open the Launcher, and select Terminal
2. Update your Linux environment:
- `sudo apt update && sudo apt upgrade`
3. Install Flatpak
- `sudo apt install flatpak`
4. Enable the Flathub repository
- `flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo`
5. Fetch updated repo information
- `flatpak update`
#### Installing and Launching Cockatrice
1. Install the Cockatrice flatpak
- `flatpak --user install io.github.Cockatrice.cockatrice`
2. Open the Launcher, and select Cockatrice
#### Updating Cockatrice
A flatpak install of Cockatrice can be updated by running `flatpak update` in Terminal.
### Installing via deb Package
#### Note on Compatibility
As of this writing, the Linux environment used by ChromeOS is either Debian 11 (Bullseye) or Debian 12 (Bookworm). You can check which version of Debian your environment is by running `cat /etc/os-release` in Terminal. It should be listed in the VERSION field. If you have a higher version of Debian, you can still use these instructions, simply use our package for the higher version, if available. If you have a lower version of Debian, try to update to at least 11 using the instructions under "Fix Problems with Linux" [here](https://support.google.com/chromebook/answer/9145439?hl=en). If you are unable to find the right package for your system or unable to upgrade past Debian 10, please use the Flatpak instructions above or the Compile from Source instructions below.
#### Installation Instructions
1. Download the .deb file for the [latest release](https://github.com/Cockatrice/Cockatrice/releases/latest) that matches your version of Debian.
2. Open the Launcher, and select Terminal
3. Install Cockatrice
- `sudo apt install {the full path to the downloaded file}`.
- A common path is `MyFiles/Downloads/[name of the installation file]`, but please ascertain where the downloaded file ended up on your system and use the appropriate file path with `apt install`.
3. Open the Launcher, and select Cockatrice to open the program.
4. When a new version of Cockatrice is released, you will have to repeat these instructions to upgrade to the newer version. This **will not** delete any deck file, custom sets, or other local files.
### Installing from Source
To install Cockatrice from source, follow the steps to enable Linux apps, and then follow our [Linux compilation guide](@ref compilation_linux) using the [dependencies for Qt5 on Debian based systems](@ref compilation_linux_qt5).
## Updating your Cards List
Regardless of how you install Cockatrice, you will need to update your cards list regularly in order to have the most current cards and tokens to play with. The most straight forward way to update the list of cards available in Cockatrice is via `Help -> Check for card updates...`. This runs Oracle, which will download and parse the official list of cards and tokens. However, parsing the cards file takes a fair about of RAM (about 2.5 GB at the time of this writing), which is often too strenuous for Chromebooks or other computers with low amounts of RAM. If you run a check for card updates and your updater crashes, it is likely due to low RAM. There are a few things you can do to work around this issue (listed in the order that you should try them):
**Method 1: Free Up RAM.** Close every other program running on your computer (especially things like Chrome, Firefox, or Discord that can use a lot of RAM) and then try to run the check again.
**Method 2 Get a copy of the cards list manually from a friend.** You will need to get the files `cards.xml` and `tokens.xml` from a friend who is also using Cockatrice. Where these files should be located on each computer can be found by going to `Cockatrice > Settings` and looking for the `Card Database:` path in the `Paths` section. Copy `cards.xml` and `tokens.xml` from the appropriate folder on a friend's computer and place them in the corresponding folder on your computer (If there is a `.` before any of the folder names in the path, you may need to Show Hidden Files to be able to navigate there in a file explorer). This method avoids checking for card updates entirely and so avoids the problem of low RAM; however, the downside to this method is that you will need to repeat this process with each new set that comes out.
**Method 3 Get a copy of the cards list manually from a different download source.** This method requires Cockatrice version 2.10.0 or later (see `Help > About Cockatrice` if you are unsure of your version). You can configure Oracle to fetch the final, parsed version of cards.xml instead of needing to parse it locally on your computer and therefore use significantly less RAM. **Currently, this version of cards.xml is UNOFFICIAL and is not affiliated with the maintainers of Cockatrice. It is a copy of cards.xml from a personal installation of Cockatrice that is maintained by one person and may not be completely up to date. It is intended as a fallback measure if other methods fail.**
To use this version, run `Help > Check for card updates...` as normal and stop when you get to this screen:
![Screenshot from 2023-10-10 13-40-35](https://github.com/Cockatrice/Cockatrice/assets/71394296/ba4647e4-1157-4966-8380-35635c34b061)
Delete the URL in `Download URL:` and replace it with `https://github.com/SlightlyCircuitous/image-storage/raw/main/cards.zip` to point it to a zip file containing cards.xml:
![Screenshot from 2023-10-10 13-02-20](https://github.com/Cockatrice/Cockatrice/assets/71394296/656c861a-607c-43b8-82a7-d1681b8ccbc7)
Click `Next>` as normal and Oracle should fetch the files without crashing. It will move on to getting the tokens file, which should not need much RAM and so proceed normally. Once you have set this up, you can simply run `Help > Check for Card Updates` periodically to get cards from new sets. However, as stated, this version of the file is updated manually and may not update as frequently as the official version. If you want to go back to the official card source URL at any point, you can click `Restore default URL` in the updater dialogue.
If, for some reason, Oracle still will not update your cards when given the link to the zip file, you can follow the link in your browser, download and unzip the zip file yourself, and place it in the correct folder as detailed in Method 2 above. You can get [an official copy of the tokens file here](https://github.com/Cockatrice/Magic-Token) and place it in the same spot.

24
doc/doxygen-extra-pages/developer_documentation/compilation/index.md Normal file
View file

@ -0,0 +1,24 @@
@page compilation_index Building
# Compiling Cockatrice
OS-Specific instructions are available at their respective pages:
- **@subpage compilation_linux**
- **@subpage compilation_macos**
- **@subpage compilation_windows**
<br>
We also have installation instructions for some unsupported operating systems:
- @subpage compilation_android
- @subpage compilation_chromebooks
<br>
**Official** ready-to-install binaries are hosted on [GitHub Releases](https://github.com/Cockatrice/Cockatrice/releases), both [stable](https://github.com/Cockatrice/Cockatrice/releases/latest) and [beta](https://github.com/Cockatrice/Cockatrice/releases) versions are available here.<br>
These are provided for several big operating systems, make sure the package matches the version of your operating system.<br>
Please check the [release notes](https://github.com/Cockatrice/Cockatrice/releases/latest) and our [official website](https://cockatrice.github.io) for more information.
**Unofficial** installation sources as an alternative to our packages are listed on our [[Unofficial Developer Builds]] page.

401
doc/doxygen-extra-pages/developer_documentation/compilation/linux.md Normal file
View file

@ -0,0 +1,401 @@
@page compilation_linux Compiling for Linux
[&nbsp; &larr; Back to Compiling Overview](@ref compilation_index)
- [Precompiled Packages](#Packages)
- [Installing Dependencies](#Dependencies)
- [Compiling](#Compiling)
- [Installation](#Installing)
- [Troubleshooting](#Troubleshooting)
<br>
> ### Note
> All command lines indicated by `$` are to be run as a normal user, while `#` requires root privilege, for example by prefacing it with `sudo` or executing through `sudo sh -c 'command'` or `su -c 'command'`.
## Packages
We provide packages for some distros on our [release page](https://github.com/Cockatrice/Cockatrice/releases). You can install these packages with your package manager or a tool like Eddy. Make sure the package name matches the specific version of your operating system.
> to install a downloaded package on a debian based system for example you can open a terminal at the location that you downloaded the package to and use `sudo apt install ./Cockatrice*.deb`
Some distros already include packages for cockatrice in their repositories, see [[Unofficial Developer Builds]].
<br>
## Dependencies
In order to compile Cockatrice we recommend to install the following tools. Instructions are split up for different package sources:
### Qt6
Newer distros will have both Qt6 and Qt5 available, we recommend using Qt6 if available. Alternatively check our requirements using [Qt5](#Qt5).
#### Arch Linux based systems using pacman
(Manjaro and EndeavourOS are based on Arch Linux)
```
# pacman --sync --needed \
cmake \
git \
mariadb-libs \
protobuf \
qt6-base \
qt6-multimedia \
qt6-svg \
qt6-tools \
qt6-translations \
qt6-websockets \
zlib
```
#### Debian based systems using apt
(Ubuntu, Linux Mint, PopOS and KDE Neon are based on Debian)
Ubuntu 22.04 and 22.10, and their derivative distros
(Note that this DOES NOT work for Debian 11 or lower; use Qt5 or see note below.)
```
# apt install \
build-essential \
ccache \
clang-format \
cmake \
file \
g++ \
git \
libgl-dev \
liblzma-dev \
libmariadb-dev-compat \
libprotobuf-dev \
libqt6multimedia6 \
libqt6sql6-mysql \
libqt6svg6-dev \
libqt6websockets6-dev \
protobuf-compiler \
qt6-l10n-tools \
qt6-multimedia-dev \
qt6-tools-dev \
qt6-tools-dev-tools
```
Debian 12 and newer, Ubuntu 23.04 and newer, and their derivative distros
(Note that this _should_ also work for Debian 11 if you [enable Backports](https://backports.debian.org/Instructions/). Otherwise, use Qt5.)
```
# apt install \
build-essential \
ccache \
clang-format \
cmake \
file \
g++ \
git \
libgl-dev \
liblzma-dev \
libmariadb-dev-compat \
libprotobuf-dev \
libqt6multimedia6 \
libqt6sql6-mysql \
protobuf-compiler \
qt6-l10n-tools \
qt6-multimedia-dev \
qt6-svg-dev \
qt6-tools-dev \
qt6-tools-dev-tools \
qt6-websockets-dev
```
#### Fedora
(Fedora 36 and newer)
```
# dnf install \
@development-tools \
cmake \
desktop-file-utils \
gcc-c++ \
hicolor-icon-theme \
libappstream-glib \
mariadb-devel \
protobuf-devel \
qt6-{qttools,qtsvg,qtmultimedia,qtwebsockets}-devel \
wget \
xz-devel \
zlib-devel
```
#### Gentoo
```
# emerge -av \
protobuf \
qt{base,tools,svg,multimedia,websockets}:6
```
#### Qt6 Minimum Dependencies
- C++ compiler w/ C++17 support (eg. GCC 8 or Newer)
- CMake 3.16 or Newer
- Protobuf 3.0 or Newer
- Qt 6.2.3 or Newer with components `qtmultimedia` and `qtwebsockets`
@anchor compilation_linux_qt5
### Qt5
Qt5 is available on most distros and can be relied upon if the newer version isn't available.
#### Arch Linux based systems using pacman
(Manjaro and EndeavourOS are based on Arch Linux)
```
# pacman --sync --needed \
cmake \
git \
mariadb-libs \
protobuf \
qt5-base \
qt5-multimedia \
qt5-svg \
qt5-tools \
qt5-websockets \
zlib
```
#### Debian based systems using apt
(Ubuntu, Linux Mint, PopOS and KDE Neon are based on Debian)
```
# apt install \
build-essential \
cmake \
g++ \
git \
liblzma-dev \
libmysqlclient-dev \
libprotobuf-dev \
libqt5multimedia5-plugins \
libqt5sql5-mysql \
libqt5svg5-dev \
libqt5websockets5-dev \
protobuf-compiler \
qt5-qmake \
qtbase5-dev \
qtbase5-dev-tools \
qtchooser \
qtmultimedia5-dev \
qttools5-dev \
qttools5-dev-tools
```
#### Fedora
```
# dnf install \
@development-tools \
cmake \
desktop-file-utils \
gcc-c++ \
hicolor-icon-theme \
libappstream-glib \
protobuf-devel \
qt5-{qttools,qtsvg,qtmultimedia,qtwebsockets}-devel \
wget \
{zlib,sqlite}-devel
```
#### FreeBSD
```
# pkg install \
cmake \
protobuf \
qt5-buildtools \
qt5-concurrent \
qt5-network \
qt5-qmake \
qt5-websockets \
qt5-widgets \
qt5-gui \
qt5-multimedia \
qt5-printsupport \
qt5-svg \
qt5-linguisttools \
qt5-sql \
qt5-sqldrivers-mysql
```
#### Gentoo
```
# emerge -av \
protobuf \
qt{svg,multimedia,websockets,sql}:5
```
#### Sabayon
```
# equo i -av \
dev-libs/protobuf \
dev-qt/qt{core,multimedia,websockets,sql}:5 \
dev-util/cmake \
sys-devel/gcc
```
#### Void Linux
```
# xbps-install \
cmake \
liblzma \
liblzma-devel \
protobuf \
protobuf-devel \
qt5 \
qt5-devel \
qt5-multimedia \
qt5-multimedia-devel \
qt5-svg \
qt5-svg-devel \
qt5-tools \
qt5-tools-devel \
qt5-websockets \
qt5-websockets-devel
```
#### Qt5 Minimum Dependencies
- C++ compiler w/ C++17 support (eg. GCC 8 or Newer)
- CMake 3.10 or Newer
- Protobuf 3.0 or Newer
- Qt 5.8.0 or Newer with components `websockets` and `multimedia`
Conditional requirements:
- mysql or mariadb (only for running a server database)
- if using mysql the qt sql connector for C++ is required
- liblzma (recommended for oracle)
> In case your os is not listed you can try to find these components yourself.
> Make sure the packages you install meet our version requirements.
> You might have to compile these components from their sources if no suitable
> packages are available, please refer to their respective documentation for
> information on how to do so.
<br>
## Compiling
Get a copy of Cockatrice's source code:
```
$ git clone https://github.com/Cockatrice/Cockatrice
$ cd Cockatrice
```
Create a directory to host the build process:
```
$ mkdir build
$ cd build
```
Run cmake to configure the build:
```
$ cmake ..
```
### CMake options
When configuring you can select multiple options, by default Cockatrice will only select the tools needed to run the client, in order to compile the server you should add the following option to the cmake command:
```
$ cmake .. -DWITH_SERVER=1
```
Alternatively, if you want to create a debug build as a developer or to troubleshoot issues:
```
$ cmake .. -DWITH_SERVER=1 -DCMAKE_BUILD_TYPE=Debug -DTEST=1
```
> We use googletest in our tests, if you enable them the components will be downloaded to your build dir, alternatively you can install googletest separately
In order to compile only the server you can exclude the client components:
```
cmake .. -DWITH_SERVER=1 -DWITH_CLIENT=0 -DWITH_ORACLE=0 -DWITH_DBCONVERTER=0
```
If you have a version of Qt6 installed but would rather use Qt5 you can use this flag:
```
cmake .. -DFORCE_USE_QT5=1
```
### Compiling
You can now start compiling, you can configure the amount of cpu cores used, the recommended amount is the total amount of threads available to the system minus one.
```
$ cmake --build . --parallel7
```
Alternatively you can use nice to have the compiler be nicer to your system resources:
```
$ nice make -j
```
## Installing
### Using Cpack
On debian or fedora based systems you can create a .deb or .rpm package like this:
```
$ make package
```
At last, install the package:
```
# dpkg -i ./Cockatrice*.deb # for debian packages
# dnf --install ./Cockatrice*.rpm # for rpm packages
```
### Other systems
Alternatively, you can install Cockatrice directly:
```
# make install
```
> Cockatrice does not provide an uninstall target, when running install cmake will create a file named `install_manifest.txt`, in order to completely uninstall you'll want to remove all files listed there [(issue ticket)](/Cockatrice/Cockatrice/issues/430)
<br>
## Troubleshooting
### Warnings in debug builds
If you're using an older version of protobuf you might have warnings in protobuf be caught as errors in your debug build, add this flag to cmake to prevent this from stopping the build: ` -DWARNING_AS_ERROR=0 `
### Error with shared libraries on Ubuntu
If you get the following error: `/usr/lib/qt5/bin/lrelease: error while loading shared libraries: libQt5Core.so.5: cannot open shared object file: No such file or directory`, you'll want to refer to [these instructions](https://github.com/dnschneid/crouton/wiki/Fix-error-while-loading-shared-libraries:-libQt5Core.so.5). The tl;dr version is to run the following command, replacing the file path with whatever path contains your libQt5Core.so.5 file:
```
sudo strip --remove-section=.note.ABI-tag /usr/lib64/libQt5Core.so.5
```
### Debug logging on Fedora
Some of the debug logging functionality (`qDebug()` output) of the Debug builds (`-DCMAKE_BUILD_TYPE=Debug`) may not work immediately with Fedora. Qt logging is turned off system-wide, but can be enabled by creating a `qtlogging.ini` file at `~/.config/QtProject/qtlogging.ini`, and adding the following rules into it:
```
[Rules]
*.debug=true
qt.*.debug=false
```
[https://brendanwhitfield.wordpress.com/2016/06/08/enabling-qdebug-on-fedora/](https://brendanwhitfield.wordpress.com/2016/06/08/enabling-qdebug-on-fedora/)
[https://ask.fedoraproject.org/en/question/87522/qt-56-qdebug-and-qlog-no-longer-work/](https://ask.fedoraproject.org/en/question/87522/qt-56-qdebug-and-qlog-no-longer-work/)
### Memory shortages on Raspberry Pi
Due to the amount of memory that is required in order to compile the application you will also need to make sure you have at least 2GB of swap space configured. If you are unfamiliar with how to increase your swap file size on the Raspberry Pi one decent article available is located at http://raspberrypimaker.com/adding-swap-to-the-raspberrypi.
The cards database has grown lately and Oracle might need more memory. So to be sure to correctly update your database, you need more swap on your Raspberry. Follow the following steps to use a dynamic swapfile that will grow when needed:
1- Edit the /etc/dphys-swapfile
```
$ sudo nano /etc/dphys-swapfile
```
2- Uncomment the **CONF_SWAPFILE=/var/swap** line.<br>
3- Uncomment the **CONF_SWAPFACTOR=2** line.<br>
4- Check that the **CONF_SWAPSIZE=100** line stays commented.<br>
5- Restart the swap process.
```
$ sudo /etc/init.d/dphys-swapfile restart
```
Once installation has completed, it is recommended to restart your Raspberry Pi. This will allow for the X Windows manager to shutdown properly and upon restart add the Cockatrice application shortcut to the Games menu.
### Using Windows Subsystem for Linux
One final note: If you're building for Linux using WSL (Windows Subsystem for Linux) you'll need to install an X Server to be able to actually run the program. One option is [Xming](https://sourceforge.net/projects/xming/). Since Windows 11 this might not be necessary anymore.
<br>
> TODO:
> - trim down package requirements to minimum
> - should we provide instructions for centos?
> - instructions on how to make appimages?
<br>

65
doc/doxygen-extra-pages/developer_documentation/compilation/macos.md Normal file
View file

@ -0,0 +1,65 @@
@page compilation_macos Compiling for MacOS
[&nbsp; &larr; Back to Compiling Overview](@ref compilation_index)
# Newbie Intro
Hi! If you're new to Terminal and perhaps here just to get a version of Cockatrice you can run on an older macOS, let me explain a few things quickly.
* **Terminal** is an application pre-installed on all Macs that allows deeper control of your operating system (OS) through the use of written commands. It can be dangerous to use if you don't know what you're doing, but all the commands here are safe and do not involve any deleting of data so don't worry. You can copy and paste the commands from this page and press enter to use them, or type them very carefully.
* **Homebrew** is a package manager. Basically, Cockatrice needs a few different packages or "dependencies" in order to function (e.g. one called "Qt" for you to actually be able have menus and click around). Homebrew is a easy way to collect all these packages so you can shove them all together at the end. By installing Homebrew, you will have access to more commands in Terminal; it won't appear in Applications or be openable like other apps you may have installed in the past.
* In this case and in a grossly simplified way, **Compiling** just means taking our packages and source code, shoving it together (with a compiler), then getting our Cockatrice apps at the end. Apps can also be referred to as "executables/exes" or "binaries".
> **Disclaimer and requirements**: There is no guarantee the instructions below will work for older OS versions, you may get errors and get stuck. You should try to install the newest version of macOS that your computer is compatible with incase of errors. You may need a bit of free hard drive space to install all the packages and tools, but the packages won't add up to much at the end (2gb including Xcode?). If you're worried about clogging your computer with all these packages don't worry, they will be only accessible through Terminal or hidden folders and won't effect performance. If you're looking to compile a version quickly, unfortunately it can take several hours to a day to install everything and compile if you're on an old OS, have no packages installed beforehand, and maybe run into some errors on the way. If at some point you decide to uninstall the dependencies and/or homebrew, there are uninstall guides on Google and your built version of Cockatrice shouldn't be affected.
## Compiling
1) To compile Cockatrice on macOS you need to first **install the dependencies manager**, [Homebrew](http://brew.sh/).
2) Install the dependencies, this may take a long time.
- Just Cockatrice: **`brew install cmake protobuf qt@5 git`**
- _User Comment_: If you are compiling on a version of macOS that is older than what Cockatrice currently supports, you will likely run into errors installing these packages as Homebrew won't support it either. For High Sierra at least, I used the command Homebrew recommends i.e. **`brew install --build-from-source [the package you want]`** and used it for protobuf, qt5, git, and their respective dependency packages you'll be told about when trying to install them. Also, if you're not able to automatically download Xcode Command Line Tools when prompted, go [here](https://developer.apple.com/download/more/) (you will need an Apple account) and download the newest version that supports your OS. For High Sierra, "Command Line Tools (macOS 10.13) for Xcode 10.1" worked fine for me. Expect all these packages to take several hours to install in total and an 1hr+ build time in step 5.
- Cockatrice & Servatrice: **`brew install cmake protobuf qt@5 git libgcrypt --with-mysql`**
- Note that this requires compiling mysql, which can take a long time. It may be easier to use the servatrice docker container instead.
3) Download the Cockatrice source code:
```bash
cd ~
git clone https://github.com/Cockatrice/Cockatrice
cd Cockatrice
```
4) Determine the location of Qt on your system.
- **`ls /usr/local/Cellar/qt@5/`** will give you a number (5.9.2, 5.12.2, etc.)
5) Make the installer and open it
```bash
mkdir build
cd build
QT5_DIR="/usr/local/Cellar/qt@5/NUMBER_FOUND_IN_STEP_4"
cmake .. -DWITH_SERVER=0 -DCMAKE_PREFIX_PATH=$QT5_DIR/ # Use -DWITH_SERVER=1 to include servatrice.
make -j
make package
open Cockatrice *.dmg
```
You can then install the application from the dmg as normal. If you want to share the dmg around, you can find it in ~/Users/username/Cockatrice/build/.
- Note: The created dmg and it's binaries should be compatible with all versions of MacOS higher than the minimum supported OS of the version of cmake you used.
# Advanced
## About using Qt's official packages
If you plan to use Qt's official packages from https://www.qt.io/download-open-source/ to build servatrice, you'll get an error when building the package. This is due to the fact that the Qt's Mysql plugin is built with an hardcoded path that needs to be fixed depending on where MySql / MariaDB has been installed on your box.
Example: if you installed MariaDB using Homebrew, you can fix the plugin running this command:
```bash
install_name_tool -change \
/opt/local/lib/mysql55/mysql/libmysqlclient.18.dylib \
/usr/local/lib/libmysqlclient.18.dylib \
/Users/foo/Qt/5.5/clang_64/plugins/sqldrivers/libqsqlmysql.dylib
```
This command will fix the `qsqlmysql` plugin pointing it from the old, hardcoded path in `/opt/` to the correct path in `/usr/local/`.

182
doc/doxygen-extra-pages/developer_documentation/compilation/windows.md Normal file
View file

@ -0,0 +1,182 @@
@page compilation_windows Compiling for Windows
[&nbsp; &larr; Back to Compiling Overview](@ref compilation_index)
## Zach's New Guide (January 2023)
Looking to get setup on Windows? This guide should help you start with CLion! Windows is finicky and this guide should hopefully help you recreate whatever mess I ended up with that is fully functional.
### Software
- [Visual Studio 2022 Community Edition](https://visualstudio.microsoft.com/free-developer-offers/)
- Select "Desktop Development with C++" and then tick all boxes in the Installation Details section (Windows 10/11 SDKs optional)
- [Jetbrains CLion 2022.3 (or newer)](https://www.jetbrains.com/clion/)
- This is a paid software, but you can do this completely in Visual Studio, if necessary
- [Python 3.11 (or newer)](https://www.python.org/downloads/)
- Download the installer
- Tick `Add python.exe to PATH`
- Custom Installation > Next
- Tick all boxes
- Install
- Qt and CMake via Python
- ```
python3 -m pip install aqtinstall cmake
aqt install-qt windows desktop 6.6.3 msvc2019_64 -m all
aqt install-tool windows desktop tools_opensslv3_x64
```
- [Git Bash 2.39.0 (or newer)](https://git-scm.com/download/win)
- It's a good piece of software to have, regardless
- [Nullsoft Scriptable Install System (NSIS) 3.08 (or newer)](https://sourceforge.net/projects/nsis/files/latest/download)
- This is how we can package our software for distribution, if necessary
### Development Environment Configurations
- Add Qt6 to your PATH Environment Variable
- `Windows Start > Edit System Environment Variables > Environment variables... > PATH > Edit...`
- Add the absolute path of your Qt6 binary directory
- Ex: `C:\Users\Zach\Documents\Development\Qt\6.6.3\msvc2019_64\bin`
- Establish VCPKG repository
- `Windows Start > Git Bash`
- ```
git clone https://github.com/Cockatrice/Cockatrice.git ~/Desktop/Cockatrice
cd ~/Desktop/Cockatrice
git submodule update --init
```
- Setup CLion with the proper Toolchain and CMake profile
- Open Cockatrice project in CLion
- Set up the VS2022 Toolchain Configuration
- `File > Settings > Build, Execution, Deployment > Toolchains > +`
- Name: `Visual Studio 17 2022`
- Toolset: `C:\Program Files\Microsoft Visual Studio\2022\Community`
- Set up a CMake profile
- `File > Settings > Build, Execution, Deployment > CMake > +`
- Build type: `Release`
- Toolchain: `Visual Studio 17 2022`
- Generator: `Visual Studio 17 2022`
- CMake options: `-DCMAKE_GENERATOR_PLATFORM="x64" -DWITH_SERVER=1`
- Build options: `--parallel 8 -- -p:CL_MPcount=8 -p:UseMultiToolTask=true`
- Modify CMake Application to build All Targets
- `Run > Edit Configurations... > CMake Application > cockatrice > Target > All targets`
### Building and Testing
- Just run it in CLion now, it should (hopefully) work!
## Old Guide
The windows compiling instructions have been tested successfully using a Windows 7 SP1 and Windows 10 computer when using Visual Studio 2017 community editions.
The following instructions refers to building a 64-bit package using 64-bit libraries (the most common configuration on new pcs). If you want to build a 32-bit package instead, ensure to install the 32-bit libraries.
As an additional reference, you can check out the `build-windows` section of the script we use to build the official packages on GitHub Actions: [desktop-build.yml](https://github.com/Cockatrice/Cockatrice/blob/master/.github/workflows/desktop-build.yml)
## Required Software
1. [Visual Studio 2017 Community Edition](https://go.microsoft.com/?linkid=9832280)
> Workloads
> &rarr; Desktop development with C++ &rarr; Check all boxes under summary section (right side of window)
2. [Qt libraries](https://download.qt.io/official_releases/online_installers/)
> Download the Windows installer, usually named qt-unified-windows-x86-online.exe
> You only need to install **Qt &rarr; Qt5.x &rarr; msvc2017 64-bit**
> Set an environmental variable of QTDIR to the path of your qt library e. g. C:\Qt\5.12.11\msvc2017_64
3. [CMake](https://cmake.org/download/)
> Download the Windows win32-x86 Installer, usually named cmake-3.x.x-win64-x64.msi
> Choose to add CMake to the System path for all users.
4. [Git for Windows](https://github.com/git-for-windows/git/releases/)
> Download the Windows installer, usually named Git-2.x.x-64-bit.exe
> During installation select the defaults except for<br>
> **Use Git from Git Bash only &rarr; Use Git from the Windows Command Prompt**<br>
> **Use MinTTY &rarr; Use Windows default console window**
5.[Nullsoft Scriptable Install System (NSIS)](https://sourceforge.net/projects/nsis/files/latest/download)
> Download the latest installer version, usually named nsis-3.x-setup.exe
6. [Vcpkg](https://github.com/Microsoft/vcpkg)
> Vcpkg it's a library manager and is the easiest way to install all the other needed dependencies; to install it, follow the official instructions, here reported for brevity; from a command prompt, run:
```bat
$ cd \
$ git clone https://github.com/Microsoft/vcpkg.git c:\vcpkg
$ cd vcpkg
```
> Then open a powershell prompt, enter the C:\vcpkg folder and run:
```ps
PS> .\bootstrap-vcpkg.bat
```
> Once vcpkg is installed while still in powershell, you can then run it to fetch and install the needed development libraries:
```bat
$ vcpkg install openssl protobuf liblzma zlib
```
> Note that in most cases, vcpkg defaults to installing x86 versions for packages. If you are intending to compile for x64, run the following command instead: (for any other architecture, call "vcpkg --triplet help")
```bat
$ vcpkg --triplet x64-windows install openssl protobuf liblzma zlib
```
7. [MySql Database Connector](https://dev.mysql.com/downloads/installer/)
> The Mysql Database connector is only needed by servatrice to support storing the configuration on a database.
## Compiling Cockatrice
01. Open Git CMD
02. Execute the following commands from inside the shell window:
```bat
$ git clone --recurse-submodules https://github.com/Cockatrice/Cockatrice C:\Cockatrice
$ mkdir C:\Cockatrice\build
$ cd C:\Cockatrice\build
$ cmake .. \
```
3. This will fail. Do not be alarmed. Open up the CMakeCache.txt file inside your git clone. change: these variables
```bat
WITH_SERVER:BOOL=OFF to ON
```
4. in CMD go in to the vcpkg folder of cockatrice and run this code to enter powershell
```bat
$powershell
.\bootstrap-vcpkg.bat
```
5. In PS run this line to install the libraries needed for this project.
```bat
PS vcpkg --triplet x64-windows install openssl protobuf liblzma zlib
```
Exit PowerShell using exit.
6. On CMD run cmake .. \ This will fail again if you have activated the server, but you will now have the server variables loaded in to the cache. Now change the MYSQLCLIENT_LIBRARIES:FILEPATH= in the cache to the directory of your MYSQL Connector C++ libraries. Example Below
```bat
MYSQLCLIENT_LIBRARIES:FILEPATH=C:\Program Files\MySQL\Connector C++ 8.0\lib64
```
If you get an error about missing libraries, make sure the paths those libraries are installed in match with the libraries in the above command. For example, you will probably have to replace `"C:/Qt/5.x/..."` with your actual version number.
07. Open VS2017 and open the Cockatrice.sln project (C:\Cockatrice\build)
08. Choose "Release" in the Solutions Configurations drop down along the top toolbar.
09. Right click and choose build for the following projects in the solutions explorer along the right.
PACKAGE
If all goes well, each should compile successfully. Once completed there will be an executable installer file located under the `C:\Cockatrice\build` directory.
## Configuring Build Environment to run application from with-in Visual Studios
01. Open VS2017 and open the Cockatrice.sln project (C:\Cockatrice\build)
02. Choose "Release" in the Solutions Configurations drop down along the top toolbar.
> Note: Compiling in Debug will require updating the vcpkg cmake path to point to the debug folder instead. Example: `C:\vcpkg\installed\x64-windows\debug\bin`
03. Right click and choose build for the following projects in the solutions explorer along the right.
INSTALL
If all goes well, each should compile successfully. Once completed there will be a folder under `C:\Cockatrice\build` directory named `Release` that contains all the files needed to execute the application.
04. Open Windows file explorer and select all the files under the `Release` folder described in step 03.
05. Copy the selected files to `C:\Cockatrice\build\cockatrice\Release` folder choose to "skip" any files that are trying to be overwritten.
06. Copy the selected files to `C:\Cockatrice\build\oracle\Release` folder choose to "skip" any files that are trying to be overwritten.
07. Copy the selected files to `C:\Cockatrice\build\servatrice\Release` folder choose to "skip" any files that are trying to be overwritten.
You should now be able to open the Cockatrice project in Visual Studio, right click on any of the 3 project solutions (cockatrice, oracle, or servatrice) and choose Debug &rarr; Start new instance and the application will now start from with-in Visual Studio allowing you to see various statistics and outputs.

2
doc/doxygen-extra-pages/developer_documentation/index.md
View file

@ -1,4 +1,4 @@
\page developer_reference Developer Reference \page developer_reference Developer Reference
- [Building](@subpage building) - [Building](@subpage compilation_index)
- [Contributing](@subpage contributing) - [Contributing](@subpage contributing)