How-to:Mac

From TrinityCore Wiki

Jump to: navigation, search

Introduction

TrinityCore is a rather complex and demanding software, and as such, it may seem quite daunting to install and maintain. This HOWTO is an attempt to help make this process less daunting and additionally, at the end of this process you would have learnt quite a few new things about your Mac.

This wiki page is divided in several parts:

Installing the prerequisites (starting from Requirements)
Compiling and installing TrinityCore (starting from Pulling the Source)
Manage the databases (starting from INSTALLING THE DATABASES)
Configure and run the server (starting from SETTING UP THE SERVER)

Important: As the TrinityCore project is highly active, portions of the guide may be outdated. In case something fails, please check the forum, which will usually have the answer already.

Notes

Don't be afraid. The majority of the tedious tasks in the wiki are one time ones and dont need to be repeated ever again.

Once you've completed the procedure, you'll only have to update the sources, create the XCode project file, compile and install, update the databases (literally 5 commands)

Credits

imbecile on TC Forums for initial guide
elegos for the libraries (compile and install) and compile procedures
all the contributors (see History)

Getting Started

Requirements

First a small intro. Software installation on MacOSX can be done in multiple ways. The most common method is to go to the software's site and download the package (usually in the form of a DMG or a cpkg) and install it. While this is easy and works for packages without dependencies, this method is not essy to work with in situations where multiple packages with dependencies are involved. The most well known example would be the packaging systems available on most of the Unix like systems, ranging from BSD derivatives to open solaris to linux. MacOSX is considered to be part of the BSD family and consequently a package management system like the ones used in other BSD derivaties has been developed for it. This is the MacPorts package management system. Thus, most of the packages listed below can be installed in multiple ways, either through a package from the software's home page or through the MacPorts system.

Xcode - You can install it from the Mac OS X installation DVD, or download it from the Apple website. During the installation you have to install the optional package "UNIX Development Support". Note that this is essential for installing macports
CMake - Cross-platform, open-source build system. You can both install directly downloading a .dmg file or installing via MacPorts (suggested, using a GUI like Porticus if you like)
MySQL Community Server - It can be installed via MacPorts or downloaded from the MySQL's website. To control MySQL from System Preferences, also install the MySQL.prefPane inside the disk image(only if DMG installation).
Git - Source Code Management Tool. You can get an installer from it's site or install it via MacPorts.
GNU Readline - Mac OS X comes with the editline library that tries to emulate readline, which is not good for trinity. You can either compile from sources or via MacPorts (see CMake)
ACE - ADAPTIVE Communication Environment. You can download the source files and compile it (see "Compiling the ACE library" for more details) or install it via MacPorts

Using MacPorts

MacPorts is a helpful tool which enables you to compile and install a lot of UNIX tools just in one command. It downloads the source files, the relative patches to make them compile under OSX (if any), it applies the patches, compiles the sources and install the resulting binary, library or whatever in a custom, safe directory (/opt/local). This means that if you want to restore your OSX installation, you only have to delete the /opt/local folder (brutal) or uninstall packages via port or Porticus (suggested). You can also download packages that are not BSD derived (like the GNU version of readline as opposed to the BSD editline bundled), and due to the custom path it will be completely harmless.

Updating and Upgrading

It's allways a good idea to keep libraries up-to-date. To do so, you have to run two easy commands

To update the ports list an eventually download a new version of the tool,

sudo port selfupdate

To compile the new versions of the files compiled under port.

sudo port upgrade outdated

Installing new libraries

You need some packages to build TrinityCore under OSX, you can use MacPorts to install them. To install these packages you only need to run(in Terminal): sudo port install cmake mysql5-server git-core readline libACE

Porticus

Porticus is a graphical front-end of Port. You can do all the things explained in the upper parts just clicking like a Windows user :- )

Compiling custom libraries in Mac OS X

The short story is that OSX has its own libraries and you should never mess around with them or (the worst thing you may do) override the OSX libraries with other versions (it may make the system unstable or even it could compromise its startup!). In order to avoid this kind of catastrophe, it's a good habit then to install custom libraries or binaries in a safe path. We're going to use /opt/local just like MacPorts does for this purpose.

Compile GNU Readline (no MacPorts)

Extract the source files somewhere in your computer (for example in (home dir)/Resources) and open the Terminal application.
In the Terminal, use these commands

cd WHERE/YOU/EXTRACTED/THE/FILES/readline-6.1
mkdir build
cd build
../configure --prefix=/opt/local
make -j2
sudo make install

Your library will be /opt/local/lib/libreadline.dylib and the header files will be present in /opt/local/include

Compile ACE

ACE is a little bit harder to compile, but you're fortunate, as I found the easy way just for you :- )

After trying several configurations, I found out that you need to compile it statically and not dynamically due to the Apple's different ld options. That's not a problem, as it works like a charm.

Notes: if you're compiling for Leopard, substitute 10.6 with 10.5, and snowleopard with leopard.

Download the ACE library from the download page (under the section Latest Release, the package with ACE only), in my case ACE-5.8.0.zip
Extract the files somewhere
In Terminal (this will create a bash profile to compile the library):

cd WHERE/YOU/EXTRACTED/ACE/ACE_wrappers
export ACE_ROOT=$(pwd)
echo "export ACE_ROOT=$ACE_ROOT" >> bash_profile
echo "export LD_LIBRARY_PATH=$ACE_ROOT/ace:$ACE_ROOT/lib" >> bash_profile
echo "export DYLD_LIBRARY_PATH=$ACE_ROOT/ace:$ACE_ROOT/lib" >> bash_profile
echo "export MACOSX_DEPLOYMENT_TARGET=10.6" >> bash_profile

Create the file ACE_wrappers/ace/config.h with this text:

#include "ace/config-macosx-snowleopard.h"

Create the file ACE_wrappers/include/makeinclude/platform_macros.GNU with this text:

debug = 1
shared_libs = 0
static_libs = 1
include ${ACE_ROOT}/include/makeinclude/platform_macosx_snowleopard.GNU
INSTALL_PREFIX = /opt/local

In Terminal (this will actually compile and install the library):

source bash_profile
cd ace
make -j2
sudo su
cd ..
source bash_profile
cd ace
make install
exit

Note: if you get the "/bin/sh^M: bad interpreter" error, it's due to the Windows new line style. You have to open that file and save with UNIX format (hint: use a text processor like TextWrangler and save as -> New line stile: UNIX).

Pulling the Source

Use Terminal:


git clone https://github.com/TrinityCore/TrinityCore.git

Git must be installed.

Make TrinityCore Mac OS X compilable

TrinityCore should be Mac OS X compilable, but actually it's not. There's an open ticket with the patch elegos made to make it fully compatible (download it here: tc_osx_diff_g3d_included.diff. You can find all the differences in comment 6. If the ticket is signed as "Fixed" just ignore this section.

Once you've downloaded the diff file, put it somewhere (I suggest to put it in the parent folder of the trinitycore one). To patch the source files, in Terminal (# are comments):

cd ~/Resources/trinitycore # my TrinityCore source directoroy
patch -p1 < ../tc_osx_diff_g3d_included.diff # my diff file

Compile TrinityCore

To create an XCode solution, in Terminal:

cd ~/my/trinitycore/source/dir
mkdir build
cd build
cmake ../ -GXcode \
-DMYSQL_ADD_INCLUDE_PATH=/usr/local/mysql \
-DREADLINE_INCLUDE_DIR=/opt/local/include \
-DREADLINE_LIBRARY=/opt/local/lib/libreadline.dylib \
-DACE_INCLUDE_DIR=/opt/local/include \
-DACE_LIBRARY=/opt/local/lib/libACE.a \
-DPREFIX=/opt/trinitycore \
-DWARNINGS=0

- -GXcode: generate an XCode solution
- -DMYSQL_ADD_INCLUDE_PATH: where to search for MySQL header files
- -DREADLINE_INCLUDE_DIR: where to search for the GNU readline headers
- -DREADLINE_LIBRARY: the dylib the GNU readline headers point to
- -DACE_INCLUDE_DIR: where to search for the ACE headers
- -DACE_LIBRARY: the static ACE library
- -DPREFIX: where to install the compiled things ($PREFIX/bin $PREFIX/etc $PREFIX/log etc.)
- -DWARNINGS: disable the output of warnings (BOOL)
Now open the TrinityCore.xcodeproj file found under the build subfolder of the trinitycore sources directory, select the target "ALL_BUILD", Build->Build (CMD+B)
In Terminal, from the build subdir (sudo is used if you're gonna install tirnitycore in a folder in which you have no permissions, like /opt as default (you can edit its group to access it with XRW permissions)):

sudo xcodebuild -target install

NOTE: the files within $PREFIX/etc have a suffix ".dist", you have to remove it, or copy the dist files to the same without the suffix in order to make the server run.

sudo cp /opt/trinitycore/etc/authserver.conf.dist /opt/trinitycore/etc/authserver.conf
sudo cp /opt/trinitycore/etc/worldserver.conf.dist /opt/trinitycore/etc/worldserver.conf

Keeping the code up to date

TrinityCore Developers are always at work fixing and adding new features to the core. You can always check them [1].

To update the core files, go into the trinitycore sources directory and revert all your patches (to avoid conflicts) via git revert (this will revert the OSX compatibility patch too!), retrieve the updates via git pull:

cd YOUR/TRINITY/SOURCES/DIR
git revert 
git pull

Or you can use git stash (see more info when using git help stash)

Then continue this guide from Make TrinityCore Mac OS X compilable

INSTALLING THE DATABASES

About once per month all of the updates made from all previous months are combined into a few bulk .sql files to easily import them into your databases. These updates are similar to how Service Packs are released for Windows. Furthermore, smaller, individual .sql updates are occasionally added as the core is fixed by the developers (these can be seen in Git Extensions while selecting individual commits in the commit view with the Diff tab selected). This offers two options:

(Beginner) It is highly recommended to keep your current revision (the commit in bold text in Git Extensions) on a commit with a description similar to "DB: TrinityDB revision XX: move SQL updates to the old directory" (example). These commit descriptions mark each monthly compilation, and are also useful for knowing when a new compilation is released and can be downloaded/imported. Doing this will keep your databases 100% up-to-date each month.
(Advanced) If you decide to update your revision outside of a commit with the above description, you must also import all of the smaller .sql updates (C:\Trinity\sql\updates folder) that have been done with EACH commit up to yours, if there are any. Not importing these additional updates cause a majority of user errors. This will ensure that your databases are 100% up-to-date.

This is described in more detail in the following instructions.

Downloading the Database

Download the latest database compilation from TrinityCore Github Downloads.
- The Download Packages at the top are the ones you want. Find the package with the latest date and download it.
  - For example, a file such as TDB_full_335.11.42_2011_08_27.rar tells us three things:
    - TDB: Trinity Database
    - 335.11.42: The version of the database and the client it belongs to. 335 = WoW version 3.3.5, 42 = the 42nd full revision.
    - 2011_08_27: The date - Aug 27th, 2011
- The file is in .rar format, so you will need an archive program like 7zip to unpack it.

Note: There are multiple .sql files to choose from in the .rar archive. If this is your first time installing TrinityCore, you will want to import the file with "TDB_full" at the beginning. The other files are for updating existing world and characters databases from a previous compilation. This makes it easy to update your databases from one compilation to the next as explained in the section above.

Installing The Trinity Databases

Trinity needs three databases to run - Auth, Characters, and World:

auth - holds account data - usernames, passwords, GM access, realm information, etc.
characters - holds character data - created characters, inventory, bank items, auction house, tickets, etc.
world - holds game-experience content such as NPCs, quests, objects, etc.

Note: The auth database was previously named "realmd". If you are having trouble and searching the forum for solutions, try searching for realmd instead of auth.

The following steps are done using the database management program you installed in Step #5 of Software Required (ex. HeidiSQL or SQLYog):

In HeidiSQL, click on the database you want to use in order to "select" it, then click Tools > Load SQL File... > (select the file) > Run file(s) directly
In SQLYog, click on the database you want to use in order to "select" it, then click Database > Import > Execute SQL Script

Create the three databases by importing C:\Trinity\sql\create\create_mysql.sql. You now have three databases - auth, characters, and world. You may need to refresh your program in order to see the new databases.
Click on the "auth" database and import the auth database structure by importing C:\Trinity\sql\base\auth_database.sql.
Click on the "characters" database and import the characters database structure by importing C:\Trinity\sql\base\character_database.sql.
Click on the "world" database and import the world database structure by extracting and importing the "TDB_full" .sql file you downloaded from the Downloading the Database section.

Note: If this is your first time installing TrinityCore, continue with SETTING UP THE SERVER

Keeping the DB up to date

Both core and DB fixes will be committed to the TrinityCore repository, which you may also view in Git Extensions by following the "Fetch" instructions in Keeping the Source Up-to-Date. Pending fixes can be found on our tracker with data from the developers and contributors.

As mentioned earlier, it is recommended to stay on the same revision as the TDB_full database (Beginner). If you choose to brave the wilds beyond the current monthly revision, use the (Advanced) instructions below.

Note: You can run the following query on the World database to see your current DB and core revision:

SELECT * FROM `version`;

This instruction assumes that you have already completed the (Beginner) Keeping the Source Up-to-Date, which means you now have a newly downloaded revision archive from the TrinityCore Downloads. This instruction also assumes that you have completed the initial Downloading the Database which had you import the TDB_FULL.sql, and it is now approximately one month later - a new revision has been released.

Note: If you have made any custom changes to your database, you may wish to backup (export) all three of them (world, characters, and auth) before performing the next few steps.

(Beginner)
1. Extract the TDB_FULL.sql file from the archive and import it into your world database.
2. If they exist, also import the characters_ and auth_ .sql files into their respective databases.
3. Once this is finished and you have already compiled your source, you may run the worldserver.exe to load your server. The revision update is complete.

Note: It is at this point that most user errors occur. If your worldserver.exe closes abruptly, make sure that your core's version matches your database version. Check that the `version` table in your world database matches the commit hash listed beside the archive you downloaded at TrinityCore Downloads.

(Advanced)

If you update your source beyond a monthly revision, you will likely have additional updates in the C:\Trinity\sql\updates folder. The folders within show which database they need to be imported to. For example, the "world" folder has all of the files that need to be imported to your world DB.

File naming conventions follow simple and consistent rules:

yyyy_mm_dd_id_world_tablename.sql -> World DB    
yyyy_mm_dd_id_character_tablename.sql -> Characters DB    
yyyy_mm_dd_id_auth_tablename.sql -> Auth DB
(yyyy - the year; mm - month; dd - day; id - incremental daily id

Note: The incremental daily id starts at 00, with 00 needing to be imported first, then 01, then 02, etc.

It is imperative to know the date of your previous revision when updating in order to import all of the updates from that revision to your current one. Then, simply follow these steps:

Browse into your C:\Trinity\sql\updates\world folder and import all *_world_*.sql files into your world DB that have a date later than your previous revision.
Do the same above step for the characters and auth folders, if they exist. If these folders don't exist, there have not been any characters or auth database updates.

Note: If you are comfortable with executing batch files, you are welcome to use the batch file located on the Combine SQL Updates thread in the TrinityCore forum to make the importing process easier. Also note that doing this will also gather up .sql files you may have already imported. In most cases this is safe, but you should use this batch file at your own risk.

Pro Tip: If your world database is ever corrupted (ex. creatures or objects are accidentally deleted), it is easy to revert it back to its original state by re-importing the TDB_FULL.sql into your world database. If you updated your core using the (Advanced) instructions, make sure you also re-import all of the necessary C:\Trinity\sql\updates as explained above.

SETTING UP THE SERVER

Now that you have the Source compiled and the Databases installed, you need to set up the server.

Extracting dbc, maps and vmaps files

In order to run Trinity needs dbc and maps files. In addition, if you want to enable vmaps (mobs not seeing through walls, etc) you will need to extract them as well. Warning: use Trinity's extractors. If you use extractors from other projects it is almost certain that your Trinity Core will not recognize the extracted data!

dbc and maps files

Compile map and DBC extractor. In the trinitycore source directory, run

 cd contrib/extractor && mkdir build && cd build && cmake ../ && make

Extract the maps and DBCs. In the build directory for the extractor

 ln -s "/Applications/World of Warcraft/Data"
 ./ad

Move the two newly created folders (maps, dbc) to the trinity installation directory

 mkdir /opt/trinitycore/data
 mv maps dbc /opt/trinitycore/data

Alternatively, you can run the extractor on Windows and copy the dbc's to your Mac.

vmaps (optional)

You can also extract vmaps which will take quite a while depending on your machine (1-2 hours). Note: This part must be done on a Windows machine. At the moment, there is no Mac guide for that. EDIT: It is possible to do the extraction on MacOSX, but will require a bit more work before it can be documented here.

Copy all files from /home/trinity/trinitycore/contrib/vmap_extract_assembler_bin/ to where all your binaries, dbc dir and maps dir are. Run makevmaps_SIMPLE.bat. It will take a long time. It will first create a directory called 'buildings'. Then it will start extracting files to the directory 'vmaps'.

You will not see any progress in the application's window or anything else. You will just notice files being created in the 'vmaps' folder as it is proceeding. Do not stop the process. It will ask to "press any key" to terminate the program when it is finished.

Configuring the Server

First of all you need to create 2 files worldserver.conf and auth.conf in your /opt/trinitycore/etc/ folder. There should be 2 files named worldserver.conf.dist and auth.conf.dist. Open the worldserver.conf.dist file and copy its complete contents into the worldserver.conf file. Same for the auth file.

worldserver.conf

Edit MySQL account username and password (instead of trinity;trinity).

LoginDatabaseInfo     = "YOUR_IP;YOUR_PORT;MYSQL_USERNAME;MYSQL_PASSWORD;REALM_DB_NAME"
WorldDatabaseInfo     = "YOUR_IP;YOUR_PORT;MYSQL_USERNAME;MYSQL_PASSWORD;WORLD_DB_NAME"
CharacterDatabaseInfo = "YOUR_IP;YOUR_PORT;MYSQL_USERNAME;MYSQL_PASSWORD;CHARACTERS_DB_NAME"

Standard Values:

LoginDatabaseInfo     = "127.0.0.1;3306;trinity;trinity;auth"
WorldDatabaseInfo     = "127.0.0.1;3306;trinity;trinity;world"
CharacterDatabaseInfo = "127.0.0.1;3306;trinity;trinity;characters"

If you haven't extracted vmaps then edit the following:

vmap.enableLOS = 1 -- set this to 0
vmap.enableHeight = 1 -- set this to 0
vmap.petLOS = 1 -- set this to 0
vmap.enableIndoorCheck = 1 -- set this to 0

auth.conf

Edit MySQL account username and password (instead of trinity;trinity).

LoginDatabaseInfo     = "127.0.0.1;3306;trinity;trinity;auth"

Realmlist table

You need to make sure that trinityrealm binary directs incoming connections to your realm. In the auth DB there is a table called realmlist. You need to edit the field address according to your needs:

127.0.0.1 -- Leave default localhost if you are connecting alone from the same machine Trinity runs on.
LAN ip -- Use the machine's LAN ip if you want other computers from the same network as Trinity's to connect to your server.
Public ip -- Use your public ip if you have friends and testers which need to connect your server from the internet.

Warning: The TrinityCore Development Team and Owners and the TrinityDB Team and Owners DO NOT in any case sponsor nor support illegal public servers. If you use these projects to run an illegal public server and not for testing and learning it is your own personal choice.

SUPPORT & CONCLUSION

This guide is for beginners and states what to do and what to edit, assuming you left everything else with default values. Visit the following threads and post questions if you still need special support:

TortoiseGIT