Difference between revisions of "CompilingWesnothOnMacOSX"

From The Battle for Wesnoth Wiki
(Build using XCode: more work on updating Xcode build instructions)
(Build using XCode: update complete, if confusing)
Line 144: Line 144:
  
 
== Build using XCode ==
 
== Build using XCode ==
 
+
This method is currently rather disjointed as some required parts have not been integrated for a while. The most up to date versions of each of the components are listed here, but building versions of Wesnoth older than 1.9 will not work using these instructions.
This section is out of date.
 
  
 
The Xcode project can be found in the svn tree and is usually up to date. The forum contains a link to a copy of the headers and frameworks needed for early 1.9, but Boost is out of date and the included copy of SDL does not support full screen in Lion. You will need to install your own version of Boost, and get a recent snapshot of SDL from the hg repository to support Lion.
 
The Xcode project can be found in the svn tree and is usually up to date. The forum contains a link to a copy of the headers and frameworks needed for early 1.9, but Boost is out of date and the included copy of SDL does not support full screen in Lion. You will need to install your own version of Boost, and get a recent snapshot of SDL from the hg repository to support Lion.
Line 155: Line 154:
 
# Install XCode tools from the OS X install DVD.  You currently need XCode 3.0 or later to use the project file.
 
# Install XCode tools from the OS X install DVD.  You currently need XCode 3.0 or later to use the project file.
 
# Download and extract the source code to a folder; here we assume '''~/wesnoth'''
 
# Download and extract the source code to a folder; here we assume '''~/wesnoth'''
# Install the SDL frameworks from http://www.libsdl.org/
+
# Download additional compilation material from http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/
: -> You will need SDL, SDL-mixer, SDL-image, and SDL-net.
+
: -> Copy its contents into ~/wesnoth/projectfiles/Xcode/
 +
# Install Boost and replace the copy included with the Mac Compile Stuff download
 
# Download a recent official BFW OS X package
 
# Download a recent official BFW OS X package
 
: -> The more recent it is, the less likely you are to have problems with the build.
 
: -> The more recent it is, the less likely you are to have problems with the build.
# In the recent package, locate the folder called '''MacCompileStuff'''
+
# In the recent package, locate SDL.framework and replace the one included in the download
# Drag the '''MacCompileStuff''' folder into the '''~/wesnoth''' folder
 
: -> The '''MacCompileStuff''' folder should now be at the same level as the '''src''' folder.
 
 
# Open '''BattleForWesnoth.xcodeproj'''
 
# Open '''BattleForWesnoth.xcodeproj'''
 
# Make sure the target you want is selected in the pop-up menu (usually '''Battle For Wesnoth''')
 
# Make sure the target you want is selected in the pop-up menu (usually '''Battle For Wesnoth''')

Revision as of 19:06, 20 December 2011

[edit]Compiling Wesnoth

Platforms
Tools

Introduction: Compiling Wesnoth on Mac OS X

Other than the generic Unix information on how to build at CompilingWesnoth, there are some Mac OS X specific issues. These issues are dealt with here.

See also forum topics How To Compile On A Mac and Help with using BfW for Mac OS X with command-line arguments.

Compiling with the terminal

NOTE: Building with autotools has been removed as of 1.9.4. Even so, building with autotools is not recommended. See below for compiling with XCode.

It is possible to compile with scons instead. Follow the the Fink related instructions, but replace ./configure, and make with appropriate scons commands (same as for other platforms).

Basic Assumptions:

Basic Ideas

First, make sure you have installed the full XCode package, this includes the GCC compilers which do the actual compilation of wesnoth, and this is the easiest way to get them. XCode comes with all copies of OS X, though it's not installed by default (it's actually in a separate install program, and in 10.3/Panther, was on a separate CD). If you don't have it at all, you can get a cd image at http://www.apple.com/developer/ .

make and make install are traditional unix commands that compile a program for you from source. make compiles the program, make install puts all of the non-code and code parts in the correct places - on a Unix system, this means that it puts the code in your executable search path. When you type a command in the command line, the system looks in a certain set of directories/folders to find any executable file, that is, any file of machine code, which matches the name. make install takes care of doing that for you.

Many of the headaches that make, and other programs like automake alleviate are things like dependencies, which are the other programs and libraries that the programs you are attempting to compile build off of.

The process involves first setting a configuration file, which tells make where you want the files to end up (for example, where your executable search path is). You do this by entering the command ./configure with a bunch of options following it. If my name is John Doe, and that was also the name of my user account, I might enter the following:

./configure --bindir=/sw/bin --datadir=/Users/johndoe/wesnoth_data/ --with-libintl-prefix=/sw --with-libiconv-prefix=/sw

Some of these names, like wesnoth_data are whatever you choose them to be. Namely, the --bindir and --datadir choose where your executable file goes, and where the images and game data files for Wesnoth go (don't confuse these with the preference files - these get created by Wesnoth when it runs, and go in a hidden folder called .wesnoth in your home directory).


However, you probably don't have any of these programs like make on your computer right now. What you will do is use a program known as Fink to download and install these Unix programs. Unix command-line programs are made portable by being distributed as the source code they were made from - anyone can (theoretically) compile them on their own computer platform, and make them work, for free. Unfortunately, this is generally a very difficult process that is prone to esoteric and difficult problems. Fortunately, you don't have to solve them, because someone else already has - Fink is a master list of Unix programs for which all the headaches of getting them to compile on the Mac have been sorted out in advance. All you do is type a command (or click a button), and they will be downloaded, compiled, and installed into the correct spots on your machine! FinkCommander, by the way, is the gui program that you use to drive the rest of what makes Fink work - as far as you're concerned, it's Fink, and it's all you have to download to run Fink.

Once you have Fink, you will download make and some other files needed to compile Wesnoth. One of the most important of these is a set of libraries called SDL (Simple Direct media Layer), which allow programmers to write graphics (and other) code that will run on any platform SDL runs on (which is almost anything, these days).

With all of these downloaded, you will then run make and make install. After that, you can start Wesnoth from the command line by typing in the command wesnoth. Some of the advantages of doing this are that you can see debug information, such as missing images, being dumped to the terminal window from which you typed the wesnoth command, and you can also specify certain command line options, like what bit depth the game graphics should run in. There is a way to get a double-clickable application (see below), but this really isn't anything remotely like Sithrandel's builds, and you may as well stick to the command line if you are, like most, using these builds to help create graphics or code for the game.

Outline of Steps

  • Get OS X 10.3 or 10.4
  • Install XCode
  • Download Fink
  • Download a copy of the SVN repository

Use Fink to install the latest versions of the following:

  • Automake
  • SDL
  • SDL-mixer
  • SDL-image
  • SDL-net
  • freetype2
  • freetype2-dev

Then, these are the steps you repeat every time you want to compile wesnoth:

  • Get an up-to-date copy of the game source and resources - usually by running svn update.
  • change the working directory (using the cd command) to the bottom/"root" folder of those game files
  • execute the command ./autogen.sh
  • execute the command ./configure --bindir=/sw/bin --datadir=datadir --with-libintl-prefix=/sw --with-libiconv-prefix=/sw
    • add --enable-editor to the end of this line to compile the map editor
  • execute the command make
  • execute the command sudo make install

At this point, you can run wesnoth by typing wesnoth in the command line.

  • wesnoth_editor will run the map editor

Advanced/Specific Instructions for each step

Since 0.8.11+cvs the code compiles just fine on Mac OS X with gcc-3.3 (as shipped with Xcode 1.2 and 1.5) and gcc-4 (as shipped with Xcode 2.0), using the normal GNU autotools ./configure; make; make install build process.

You do need a set of SDL libraries that have sdl-config installed -- the ones from Fink's unstable tree work well. The .pkg files from http://www.libsdl.org/ do not include sdl-config and are not designed for command-line building, so they are best avoided for now.

Fink is a program available from the Fink homepage that automates the installation of common Unix/Linux software. The SDL, SDL-mixer, and SDL-image files are available as normal Fink packages. SDL-net is unstable, so Fink does not list it by default (for your protection, presumably). This page describes how to activate unstable packages, after which you can install SDL-net normally.

fink install SDL SDL-mixer SDL-image SDL-net

Also note that you need gettext-dev and libiconv-dev or equivalent, for instance, from Fink. If you use Fink, you probably want libgettext3-dev and not gettext-dev, since the latter is currently based on an ancient 0.10 version of gettext and may result in warnings like

 ld: Undefined symbols:
 _libintl_bind_textdomain_codeset
 _libintl_dgettext
 _libintl_gettext
 _libintl_bindtextdomain

when trying to link.

If you still have problems, you may need to change the normal config command to look like this:

./configure --with-libintl-prefix=/sw --with-libiconv-prefix=/sw

This is because fink installs everything into your /sw directory. In fact, it is possible to have multiple copies of a single program on your system in various locations: one where you installed it and another in /sw.

ALSO note that fink installs freetype1 by default, but the game wants you to have freetype2. Using the same fink installation process, install freetype2. I uninstalled freetype1 to avoid confusing 'make', but that may have been unnecessary. The commands are:

fink install freetype2 freetype2-dev
fink remove freetype freetype-dev

Building using the autotools configure/make process creates an application that has to be started from the commandline, but otherwise functions the same as on every other platform. Since 0.9.2, you can also do

 make wesnoth_bundle
 make wesnoth_editor_bundle

to create application bundles for the game and the map editor. These are at present quite minimalist, with no icon or Finder information, but they can at least be launched from the Finder. Note that these apps both look for the game data in ${prefix}/share/wesnoth/ which is usually /usr/local/share/wesnoth/ unless you specified a different --prefix argument to configure when you built it.

Summary:

  1. Install Apple developer tools from the OS X install DVD (so you have gcc)
  2. Install Fink
  3. Activate unstable packages in Fink
  4. Install the SDL libraries using Fink
  5. Install libgettext3-dev using Fink
  6. Install freetype2 using Fink
  7. Run the ./configure; make; make install sequence (either as-is or modified as described above or elsewhere)


Tuning the build

One of the reason you may want to compile the game by yourself is to build an optimized version for your computer. For this, you just have to know which CPU you have (G3, G4, G5; etc.) By default, Wesnoth will compile with level 2 optimzation (-O2); to enable level 3 (the highest) on a G4 CPU (for example), run the following command instead of the usual ./configure:

 CXXFLAGS="-mtune=G4 -O3" ./configure

For csh-like shell, such as tcsh, the syntax is

 setenv CXXFLAGS "-mtune=G4 -O3" 
 ./configure

If you already built a Wesnoth binary with the current sources, clean your build with

 make clean

then type

 make && sudo make install

Note that -O3 is not recomanded for all programs and hosts, as it may require more memory to run the program. On some host, you may try -Os which will optimize for size and may use less memory.

You may also get a bit more optimization using -mcpu=G4 instead of -mtune=G4. This will cause the compiler to use instructions only available to the specified CPU, which could make it not work on any other CPU. Use with care.

This optimizations are only about the game by itself. You may also want to build optimized versions of required libraries (SDL, gettext, etc.). If you built them yourself, rebuild them with the optimization arguments you want. For tools written in C, as most are, use CFLAGS instead of CXXFLAGS for C++. If the tool uses a configure script, just type

 CFLAGS="-mcpu=G4 -O3" ./configure ...

This should work with Fink too (CFLAGS="..." fink ...) Don't forget to read the install documentation and requirements of each tool.

Note that, if you used Fink, the compiler will look for tools in /sw/bin before /usr/local/bin.

Build using XCode

This method is currently rather disjointed as some required parts have not been integrated for a while. The most up to date versions of each of the components are listed here, but building versions of Wesnoth older than 1.9 will not work using these instructions.

The Xcode project can be found in the svn tree and is usually up to date. The forum contains a link to a copy of the headers and frameworks needed for early 1.9, but Boost is out of date and the included copy of SDL does not support full screen in Lion. You will need to install your own version of Boost, and get a recent snapshot of SDL from the hg repository to support Lion.

Here are some basic steps to compile with XCode, most of which are taken from the thread discussion on the same topic.

Summary:

  1. Install XCode tools from the OS X install DVD. You currently need XCode 3.0 or later to use the project file.
  2. Download and extract the source code to a folder; here we assume ~/wesnoth
  3. Download additional compilation material from http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/
-> Copy its contents into ~/wesnoth/projectfiles/Xcode/
  1. Install Boost and replace the copy included with the Mac Compile Stuff download
  2. Download a recent official BFW OS X package
-> The more recent it is, the less likely you are to have problems with the build.
  1. In the recent package, locate SDL.framework and replace the one included in the download
  2. Open BattleForWesnoth.xcodeproj
  3. Make sure the target you want is selected in the pop-up menu (usually Battle For Wesnoth)
  4. Click Build

Troubleshooting the Build Step

At this point, you may run into an error that causes the build to fail. Here are ways to deal with some of them:

Can't find SDL.h (or similar)

This is usually the first error of many. The XCode project file assumes you installed the SDL frameworks in /Library/Frameworks. If you decide to install them somewhere else (for example, ~/Library/Frameworks), you need to tell the project file where to look.

  1. Expand Targets in the project window, and double-click on Battle for Wesnoth.
  2. Click the Build tab, and make sure Collection is set to Customized Settings .
  3. Click Header Search Paths, and then click Edit.
  4. Click the + to add a new search path, and type in the path to the Headers directory inside the SDL framework.
  5. Repeat the previous step for each of the other SDL frameworks, then click OK and close the Info window.
  6. Locate SDL.framework in the right-hand pane of the project window (it should appear in red), click on it, and then click Info.
  7. Click Choose..., locate SDL.framework on your system, and close the Info window.
  8. Repeat the previous two steps for each of the other SDL frameworks.

Undefined symbols

The project file contains a list of the files in the src folder. If new files were added to the src folder since the last release, your old XCode project file won't know about them. This is less likely to happen when the project file is from the latest release.

  1. Expand the Wesnoth group in the project window.
  2. In the Finder, select any files in the src folder that are not listed in the project window.
  3. Drag them into the src group, and click OK.

Warnings

Warnings tend to be very likely to occur when building any large project. They will not cause the build to fail, and can generally be ignored, unless they seem particularly ominous.

More About XCode Builds

This build uses a more "Mac-like" set of defaults, for instance putting all the information that is usually in the ~/.wesnoth/ directory into the ~/Library/Application Support/Wesnoth 1.x/ folder, and placing the system-wide game files (which are usually in /usr/local/share/wesnoth/) inside the Battle For Wesnoth.app folder of the application itself. If you want to use both, just make a symbolic link between the directories:

ln -s Library/Preferences/Wesnoth ~/.wesnoth

Before running this command, make sure ~/.wesnoth does not exist. If necessary, merge the information within it and delete it.

The commandline and Cocoa-app approaches are hopefully going to be merged at some stage in the future, but some additional scripts still need to be written to keep the project file in sync.

See Also