Compiling Ember

Introduction

This document is meant as a guide to successfully compiling Ember.

For most people we recommend using the Hammer script to build all needed components. These instructions are meant to further help if there are any issues with Ember.

Steps

These steps needs to be taken in order to get a working Ember client compiled from scratch.

Note that these instructions currently only works on Linux. While Ember is available for Win32, we provide no build environment support for it. All development happens on Linux, and at release time it's "ported" to Win32. This involves using a custom minGW and mSYS build environment coupled with Code::Blocks, and the steps and processes needed just to get that working are to painful just to contemplate. If you however want to help out with a more robust Win32 build environment, please add to this document the steps you needed to take. See the compiling Ember on win32 page.

In order to properly compile Ember yourself we advice you follow these steps.

1. Get the Ember Source code
2. Install base support libs
   1. SigC++
   2. libCurl
3. Compile the Worldforge libraries
   1. Atlas
   2. WFMath
   3. Varconf
   4. Mercator
   5. Eris
   6. libWfut
4. Install Ogre support libs
   1. zzip
5. Compile Ogre
6. Install CEGUI support libs
   1. pcre
   2. lua
   3. FreeType2
7. Compile CEGUI
8. Install Ember support libs
   1. SDL
   2. OpenAL
9. Compile Ember
10. Install Ember media

Ember Source Code

In development Ember source code is available from GitHub.

For an anonymous checkout, just do:

git clone git://github.com/worldforge/ember.git

Base support libs

These libraries are used by core functionality in both Ember and other support libraries.

SigC++

SigC++ is used for signal passing. Much like SDL, this should be available for all Linux and BSD distributions. However, note the current versions of Worldforge source will require SigC++ 2.0, version 1.2 won't do.

Mac OSX Users

pkg-config is also necessary it seems, available from Free Desktop I installed this prior to installing SigC++ and things went smoothly.

libCurl

The libWfut library uses Curl for media transfer. This should be available prepackaged for all all Linux and BSD distributions.

Mac OSX Users Curl-7.16.3.tar.bz2 From Apple OSS is known to work in the dependency tree for libwfut. (As of libwfut-0.2.0)

Worldforge libraries

The first set of libraries needed are the Worldforge internal libraries. These are

1. Varconf, used for configuration handling.
2. Atlas, the common communication and data definition protocol.
3. WFMath, a comprehensive 3d math package.
4. Mercator, terrain generation and placement.
5. Eris, client side helper library.
6. libwfut, dynamic updates of content from the web.

Compile them in the order mentioned here. None of these libraries should pose any dependency problem if compiled in the correct order.

Additional libraries

Once the Worldforge libraries are compiled we'll move on to the other third party libraries. These can prove to be a little bit more difficult. Luckily many of the libraries listed below will come installed by default on some distributions, or are available as pre-built packages with their package management system for many others. It's a good idea to rely on them when available. Many of the dependent libraries make use of POSIX threads (Pthreads). If, for some reason, you have a platform that doesn't support pthreads, or at least an acceptable emulation like Windows, you might as well give up now. Good news is that outside of some bizarre embedded systems you might not want to even run Ember on, this is unlikely to happen - I'm just mentioning it for completeness.

Lua

Ember uses Lua for scripting the gui. Lua needs to be installed before we compile CEGUI in order for the bindings to be generated. Lua by default doesn't come with any .pc files used by the pkg-config system, but almost all distros that provide lua development packages provide such files themselves. You are therefore encouraged to use the lua packages provided by your distro, as you would have to craft your own lua.pc files else.

Either 5.1 is required; it won't work with earlier versions of Lua such as 5.0. Note however that CEGUI can be compiled with either 5.0 or 5.1, so you must make certain that it's compiled with 5.1. If CEGUI is compiled with 5.0 it cannot be used together with Ember.

Mac OSX Users

After building Lua 5.1.4 I had to perform the following in order for pkg-config to "see" that I'd installed lua in the system.

sudo cp etc/lua.pc /usr/local/lib/pkgconfig/lua.pc

pcre

CEGUI uses the Perl Compatible Regular Expressions C library. This base library should be available prepackaged for all major BSD and Linux distributions.

FreeType2

CEGUI and Ogre will also require FreeType2 Font Engine. I can't imagine any good reason this wouldn't be provided by your distribution already, but in case of emergency, grab the source-code from the download link, build and install.

Zzip

OGRE will require Zzip compression library. It's a bit obscure, but odds are your distribution provides a prebuilt package for it. If not, grab the sources and build it yourself.

Might be: This ZZipLib

Cg

For the full OGRE build, you are going to need nVidia Cg toolkit. There is no source, but pre-built packages for all platforms are provided. Make sure to get at least version 2.1, as earlier versions has had a couple of bugs and memory leaks. Cg is fully optional and if it's not available Ember will still work, albeit with a little less amazing and wonderful look.

OGRE

The 3d view in Ember is provided by the Ogre library. Ember uses version 1.10.11 or later. It's absolutely imperative that you have FreeImage installed and it is being used by Ogre. Do not use DevIL, as that's not thread safe. Ogre can also be built without any image library at all, which will make Ember not run.

CEGUI

For our GUI system we use CEGUI. Download the latest version of the 0.7 series and compile it. Worth noting is that CEGUI support a couple of different xml parsing engines. By default the Xerces library will be used, and if that's not available it will fall back to any other of the four backends. If you don't have any of the required development files needed installed it will default to the built in TinyXML parser. If you run into any trouble with building any xml parser, you can disable it through the --disable-* configure directives. For example "--disable-xerces-c". Otherwise it should make no difference what xml parser is used.

On Ubuntu and perhaps other dpkg based systems CEGUI does not detect the system lua packages as they embed the version in the pkgconfig filenames. It looks for lua.pc rather than for example lua51.pc. It may be necessary to tweak CEGUI so that it detects lua, and modify the Makefile in ScriptingModules/CEGUILua/LuaScriptModule to add the necessary include directories for the lua headers, as Ubuntu appears to put them in a subdirectory which is ignored by CEGUI's configure script.

There are a couple of subparts of CEGUI which might pose problems (for example the samples might not build if you have stray Ogre includes files laying around). The following configure directive is thus recommended:

./configure --disable-samples --disable-opengl-renderer --disable-irrlicht-renderer --disable-directfb-renderer

It's absolutely crucial that CEGUI picks up the Lua dependency and builds the Lua scripting module. After running configure make sure it says

Building Lua scripting module:                yes

SDL

We use SDL mainly for input handling. SDL should be available for almost all Linux and BSD distributions in prepackaged format. If you're building for win32 you might need to compile SDL yourself, since the SDL library needs to be of the same type as the rest of Ember ("multi-threaded, non-debug" for example).

OpenAL

We use OpenAL for sounds and music. If you have a fairly recent major distribution you can probably install correct prepackaged versions of both OpenAL and FreeAlut (sometimes just "alut"). If not, download and compile the latest version of both OpenAL and FreeAlut from the aforementioned site. OpenAL 0.0.8 has a broken pkgconfig file, if this causes you problems (likely) you should edit ${prefix}/lib/pkgconfig/openal.pc with your favorite plain text editor and remove the Requires: @requirements@ line.

Compiling Ember

If you've followed the steps you should now have all the support libs needed to compile Ember. The compilation is pretty straightforward: do a ./configure and then make and make install.

Installing media

After you've compiled and installed Ember you will also need to download and install the media. Without that Ember won't run. There are a couple of different ways of installing the media. If you have rsync installed on your system (which you really should have) you can use the helpful make targets. Depending on whether you're compiling a stable release or a development release you can do:

make devmedia

or

make releasemediarsync

This will fire up rsync to connect to the media rsync service at amber.worldforge.org and install all needed media automatically. If this doesn't work you can however install the media manually instead. The media can be obtained from the Sourceforge repository. The media needs to be installed to

PREFIX/share/ember/media 

so that you get

PREFIX/share/ember/media/shared 

and

PREFIX/share/ember/media/user

Errors

For a list of Commonly encountered errors and how to fix them please visit the Troubleshooting page.