Building on macOS

YGOPro macOS Compilation Guide

Note: macOS compilation support is still experimental, contributions to improve it are welcome.

1. Preparation

1.1 Required Software

• YGOPro distribution

  • Used to obtain card database and card images, the database is essential

• Git

• Homebrew

• Command Line Tools for Xcode

  • Usually installed automatically when installing Homebrew or Xcode
  • The project does not use the Xcode IDE

• Premake

  • The project supports both Premake and CMake build systems, but CMake has not been maintained recently, so Premake is recommended

1.2 Dependencies

Install the following dependencies via Homebrew:

brew install premake freetype libevent libx11 sqlite zlib

Dependencies that need to be manually downloaded (source code) and statically compiled:

• Irrlicht

  • This is a modified version of Irrlicht with added Chinese support and other features
  • The original Irrlicht is not supported

• Lua

  • Only versions 5.3.x and 5.4.x are supported
  • Needs to be compiled with C++ instead of the default C compiler, so static compilation is required

• miniaudio

  • Due to project specifics, it cannot be installed through Homebrew or other package managers, static compilation is required
  • Only version 0.11.22 is supported, and you need to use the miniaudio_split version from it

2. Getting the Source Code

2.1 Clone the Repository

Use Git to clone the repository, making sure to include all submodules:

# Complete clone of code and submodules (recommended)
git clone --recursive https://github.com/Fluorohydride/ygopro.git
cd ygopro

# Or step by step
git clone https://github.com/Fluorohydride/ygopro.git
cd ygopro
git submodule update --init

# Switch submodules to the correct branch
cd ocgcore
git checkout master 
cd ..
cd script
git checkout master 
cd ..

2.2 Install Dependencies

• Extract the downloaded Irrlicht to the project root directory and rename it to irrlicht
• Extract the downloaded Lua to the project root directory and rename it to lua
• Download miniaudio, and copy the c and h files from miniaudio/extras/miniaudio_split to the miniaudio folder in the project root directory (please create this folder manually)

2.3 Copy Description Files

Copy all subfolders in the premake folder to the project root directory. These folders contain the premake description files needed to compile each dependency library.

cp -r premake/* .

3. Generate Project and Compile

3.1 Generate Project Files

Use Premake to generate makefile:

premake5 gmake

If you are compiling on Apple Silicon, since Homebrew installs dependency libraries in a non-standard directory, you need to use the following command instead:

DYLD_LIBRARY_PATH=$(brew --prefix)/lib premake5 gmake

3.2 Directory Structure

After successful configuration, the project directory structure should look like this (some files omitted):

├── build
├── gframe
├── irrlicht
│   ├── include
│   └── source
│       └── Irrlicht
├── lua
│   └── src
├── miniaudio
├── ocgcore
├── script
├── sound
└── textures

3.3 Compile the Project

Go to the build directory and execute the make command:

cd build
make config=release # or make config=debug

After compilation, the generated executable will be located in the bin/release or bin/debug directory.

4. Running and Debugging

4.1 Basic Running

1. Copy the following files from the YGOPro distribution to the project root directory:

   • cards.cdb
   • pics folder
   • deck folder

2. Create a symbolic link for easier execution:

   ln -s bin/release/YGOPro.app ./ygopro
   # or ln -s bin/debug/YGOPro.app ./ygopro

3. Run ./ygopro

4.2 Using App Bundle

1. Generate the App bundle

   mkdir -p ygopro.app/Contents/MacOS
   cp ./bin/release/YGOPro.app ./ygopro.app/Contents/MacOS/ygopro

2. Run the program

   ./ygopro.app/Contents/MacOS/ygopro

   Or double-click ygopro.app from Finder to run it.

   The program will automatically determine its location and choose the correct working directory.

   Since the App bundle is unsigned, the first time you run it, you may get a warning saying "Cannot be opened because it is from an unidentified developer." You need to allow it in System Settings.

TODO: Currently, the program does not work like other macOS applications. Database, card images, and other resource files should be placed in the Contents/Resources directory, and configuration and deck files should be placed in the user's directory.

5. Common Issues

See FAQ for Building