Build (Mac)
From Emergent
- Getting the source
- Installing from packages
- Building from packages (recommended!)
- OSX
- Fedora
- Ubuntu
- Ubuntu (64 bit)
- Gentoo (unsupported)
The Mac build of Emergent depends on several other toolkits, which in turn have other more standard dependencies and are described in About Emergent. If you've never developed code on OSX before, you will need to download the Mac Developer Tools in addition to our prerequisites. Go through each item in the following tables and install any that you do not already have. Detailed instructions are included below for a full build from source.
However, by far the easiest way to build is to download and install the pre-built package for Mac OSX, and then follow these directions:
- Build From Package OSX -- how to build from source after downloading binary package.
Configuring Mac for Building Software
- Build Tools OSX -- has detailed instructions for getting your Mac ready to compile software.
Overview of Emergent-specific packages you need
(Note: follow specific instructions below for installing these items)
| Package | Min Version | Web Link File Link | Description |
|---|---|---|---|
| OpenGL | (platform dependent) | OpenGL | Low-level 3d graphics toolkit (hardware accelerated); this is usually provided by the graphics card driver, or the OS. |
| Qt4 (open source edition) | Qt-4.2.3 or Qt-4.3.1 | http://www.trolltech.com/ | Main GUI Toolkit |
| sndfile | 1.0.17 | http://www.mega-nerd.com/libsndfile/ | sound reading library (except mp3); is also used by simage (below) |
| Coin3D | 2.4.6 | http://www.coin3d.org/ | Open Inventor providing higher-level 3d toolkit |
| SoQt | 1.4.1 | http://www.coin3d.org/ | Qt interface to Coin3d |
| simage | 1.6.1 | http://www.coin3d.org/ | library for loading textures (and doing media i/o) |
| GSL | 1.9 | http://www.gnu.org/software/gsl/ | Gnu Scientific Library: for matrix math and other math functions |
| ODE | 0.8 or 0.7 | http://ode.org/ | Open Dynamics Engine: for virtual environment simulations |
Step-by-Step Instructions
You need to be logged in as 'root' to install the prerequisites (or else use a 'sudo -s' shell or precede all your commands with "sudo " to mimic the root user).
You also need to have an OpenGL compatible library, such as mesa, installed. This is normally installed by default, but make sure the development package (mesa-devel) is also installed, otherwise Qt won't get compiled with OpenGL support. NOTE: we are 99% sure this is installed by default on Mac if you have installed XCode -- ignore this comment and let us know if you have troubles or if all goes ok, and we'll remove this comment.
The command examples assume the Bash shell -- if you don't use bash, it is suggested to enter "bash" to get the Bash shell prior to running the commands, since some, such as setting environment variables, are different in other shells.
Environment Setup
- do *not* define a QTDIR variable -- we will use the pre-built dmg install of Qt, which goes in /Library/Frameworks and does not use a QTDIR. In addition to being simpler, the pre-built install saves you ~2.3 GB of disk space because it omits the sources, etc.
Download pre-built Qt4 dmg file
- NOTE: Emergent 4.0.7 reverted Mac packages to Qt 4.2.3 to avoid serious drag-and-drop and other layout bugs with 4.3.1.
- This link should have the current release: http://trolltech.com/developer/downloads/qt/mac -- the 'dmg' (disk image) pre-built versions are (currently) at the bottom of the page:
- ftp://ftp.trolltech.com/qt/source/qt-mac-opensource-4.2.3.dmg
- ftp://ftp.trolltech.com/qt/source/qt-mac-opensource-4.2.3-debug-libs.dmg (extra debug symbols -- not needed but maybe useful)
These are standard mac install things -- Safari or whatever should mount the disk images and you'll get an installer package that you click on to install. This saves hours of compiling relative to the Build (Linux) instructions (which you could follow if you really wanted to..)
- If you do decide to compile from source, use this configure command:
./configure -debug-and-release -no-exceptions -framework -no-iconv
(the -no-iconv is required on Leopard (10.5) to avoid errors in src/corelib/codecs/qiconvcodec.cpp, which could otherwise be easily fixed by changing the const char* to a char* or vice-versa..)
Configure/build/install Coin3d and SoQt
- IMPORTANT: you must apply this patch Media:soqt-accum-20070319.txt to SoQt prior to compiling -- click on the above link and save in the same place as your Coin and SoQt downloads.
- The following assumes Coin 2.4.6 and SoQt 1.4.1 and that you downloaded the files to /tmp
- NOTE: you may use the -j N multi cpu switch if you have multi cores or cpus
> mkdir /usr/local/src/Coin3d > cd /usr/local/src/Coin3d > cp /tmp/Coin-2.4.6.tar.gz ./ # or wherever it is saved > tar -xzvf Coin-2.4.6.tar.gz > cp /tmp/SoQt-1.4.1.tar.gz ./ # or wherever it is saved > tar -xzvf SoQt-1.4.1.tar.gz > cd Coin-2.4.6 > ./configure --disable-debug > make install # or "make -j2 install" for 2 cpus etc. > cd ../SoQt-1.4.1 > cp /tmp/soqt-accum-20070319.txt . # or wherever you saved it from above link > patch -p0 < soqt-accum-20070319.txt > ./configure --disable-debug > make install # or "make -j2 install" for 2 cpus etc.
OPTIONAL (not necc for most users): build Coin and SoQt with debug symbols avail (creates /usr/local/lib/libCoind.so* and /usr/local/lib/libSoQtd.so*)
> cd ../Coin-2.4.6 > make clean # remove previous compile > ./configure --enable-debug --with-suffix=d --with-alternate=debug > make install > cd ../SoQt-1.4.1 > make clean # remove previous compile > ./configure --enable-debug --with-suffix=d --with-alternate=debug > make install
Install GSL
The MacPorts version is fine: >port install gsl
Install ODE
The MacPorts version is fine: >port install ode
Make /usr/local/include symlinks
Note: currently the configure program is not properly looking for the include files for gsl and ode, which are installed in /opt/local/ by macports, instead of /usr/local. So you need to do this as sudo su:
> cd /usr/local/include > ln -s /opt/local/include/gsl . > ln -s /opt/local/include/ode .
Building/Installing Emergent
Emergent can be compiled either from a tar file or by downloading from subversion. Currently, we are only supporting the subversion case.
Fetch Source
Follow the instructions in the Subversion article for fetching the Emergent source.
Configure/Build Emergent
Before configuring, you need to make sure that the moc program (used by Qt and required for building) is the correct version -- if you have installed kde under macports, it is possible that you have an incorrect moc program in your path prior to the correct one.
> which moc # output should be: /usr/bin/moc
The QT dmg installs the correct moc in /usr/bin/moc. If you see something like /opt/local/bin/moc, then that is likely a problem. You can either mv that /opt/local/bin/moc to /opt/local/bin/moc-3.x or something to get it out of the way, or change your path order in /etc/profile or ~/.profile or .cshrc, or if you're actually doing kde/Qt 3.x development in addition to emergent, you'll be able to figure out a better solution.
To configure and build Emergent, navigate to the source directory you created, and run configure and make.
cd ~/emergent autoreconf ./configure # --enable-debug if you want to be able to debug make make install # need to run as su or with sudo
With the default install, the executable emergent will be in /usr/local/bin, and that is what you type to run it. Other support files will be in /usr/local/share/emergent, including demo test cases and standard library files for css.
There are .app bundles (Mac application directories) in src/emergent/bin. You can go to that directory and type, open emergent.app to run the software. If you configured with --enable-debug it is emergent_debug.app. You can then navigate to this directory in the finder, Meta+Shift+o, and drag emergent.app into your dock (or Applications directory) to make it executable from the dock in the usual way.
Debugging on Mac
Debugging on Mac is not trivial. There seems to be no ready way to get the various debug versions of the libraries to statically link together. In particular, nothing seems to want to statically link to the _debug version of the Qt frameworks. However, there is a dynamic way.
At one console (note: the 'open' command cannot be run in the background, so you have to either run emergent_debug from a system icon, or use two consoles)
> DYLD_IMAGE_SUFFIX=_debug > [path-to-app bundle]/emergent_debug.app
this tries tacking _debug onto ALL frameworks as they load, which will include the Qt frameworks -- so this will also force SoQt to use the same frameworks (so you won't get dual non-debug/debug loading, which is disastrous
Now, you need to get the process id, and launch emergent (Xxxx is the proc id)
> ps -A | grep emergent > [note the proc id Xxxx from the emergent_debug executable] > gdb gdb attach Xxxx
This will attach the debugger, and break the application. You can type 'cont' to continue it.
