BUILD.unix

BUILDING WINGS 3D ON UNIX-LIKE SYSTEMS (including MacOS X)
==========================================================

This guide describes how you can build Wings on unix-like
systems, such as GNU Linux, FreeBSD, Solaris, and MacOS X.

After the general build instructions, there are separate
instructions for building a complete, standalone installation
package for MacOS X and for other Unix systems.

$Id$

Required software
=================

The following software is needed to get Wings running
at all. Additional software is required if you want to
run all plug-ins and to build an installation package.

- The Wings source files. http://www.wings3d.com

- Erlang/OTP R13B or later. http://www.erlang.org

- SDL development library. http://www.libsdl.org.
  (There are pre-built libraries for most platforms.)

- ESDL 1.0 or later. http://esdl.sf.net

- A GNU compatible "make" program. Included with most unix-like
  systems; otherwise get it from http://www.gnu.org.

- bunzip2 for unpacking the Wings source tar file.
  Included with most unix-like systems; otherwise get it
  from http://sources.redhat.com/bzip2.

- OpenGL header files and libraries.

Summary of build process
========================

The following is a quick summary of the build process.

* Download and install Erlang/OTP.
* Download and install SDL.
* Install OpenGL header files (if needed).
* Download and install ESDL.
* Download and upnpack the Wings source file.
* Run "make".

Installing Erlang/OTP
=====================

Build Erlang/OTP according to the instructions in the README file.

I recommend running "configure" with the following options:

	./configure --enable-threads --disable-hipe

Threads must be enabled to make sure that Erlang emulator is linked with
reentrant libraries. (--enable-threads is default on *most* platforms nowadays,
but better safe than sorry.)

HiPE is not used by Wings; but the reason I recommend disabling it is
that disabling HiPE also disables the use of floating point exceptions.
Floating point exceptions have caused Wings to crash occasionally.

When you have built Erlang/OTP, modify the PATH environment variable
so that the "erl" and "erlc" programs can be started from a shell prompt.

Installing SDL
==============

Install SDL, if not already installed. On Linux systems, the SDL may be
already pre-installed. You'll probably need to install header files,
though, by installing the "SDL-devel" package.

Make sure that the "sdl-config" program is found in PATH.

I build SDL from source, using the following configure commands:

./configure --disable-video-aalib --disable-video-directfb --prefix=$HOME
make
make install

That will install the library and header files in my home directory,
not disturbing the pre-installed SDL libraries installed in the system.

The --disable-video-aalib option disables use of aalib, to avoid problems
running the built Wings on other Linux distributions that don't have
aalib. I use --disable-video-directfb because the directfb stuff
caused build problems and it is not required by Wings anyway.

Installing OpenGL header files
==============================

Even though OpenGL support comes pre-installed in many Linux distributions,
you may need to install header files to be able to succefully compile
ESDL.

For instance, in openSuse you'll need to install the "mesa-devel" package.

Installing ESDL
===============

Download ESDL and unpack it.

Make sure that the "sdl-config" program can be found in PATH.
Verify like this:

which sdl-config

sdl-config --libs

Compile by running "make" from the source directory of ESDL.

Set the environment variable ESDL_PATH to point to top of the
compiled ESDL installation.

Unpacking the Wings source code
===============================

If you have the GNU tar program, use the "tar" program with
the "j" flag to tell it to decompress using the "bunzip2" program.

Example:

$ tar jxf wings-1.0.tar.bz2

Otherwise, feed the output of "bzcat" to tar:

$ bzcat wings-0.1.0.tar.bz2 | tar xf -

The build steps that follow assume that you are in the wings source
directory.

Example:

$ cd wings-1.0.tar.bz2

Building Wings
==============

Build Wings from the directory where the sources where unpacked.

Example:

$ pwd
/home/bjorng/wings-1.0
$ make
.
.
.
<A lot of output follows>
.
.
.
$ 

To run the Wings you have just build, you'll need to write a command line
similar to this:

	erl -smp disable -pa $ESDL_PATH/ebin -pa <MY_WINGS_PATH>/ebin -run wings_start start_halt

where you should substitute <MY_WINGS_PATH> with the path to the Wings
source directory.

Example:

$ erl -smp disable -pa $ESDL_PATH/ebin -pa /home/bjorng/wings-1.0/ebin -run wings_start start_halt
$

Instead of writing the command line every time you want to start Wings,
you can package it in a script like this:

#!/bin/sh
exec erl -smp disable -pa $ESDL_PATH/ebin -pa /home/bjorng/wings-1.0/ebin -run wings_start start_halt ${1+"$@"}

Notes:

[1] "exec" kills the shell process running the script, saving a
    tiny amount of system memory.

[2] The "${1+"$@"}" thing passes along any arguments (or none) to Wings,
    allowing Wings to open up a wings file when it starts.

[3] The "-smp disable" flag is necessary if you have a multi-core/multi-CPU
    computer. Wings will only work with the single-threaded Erlang emulator.


Building an installation package for MacOS X
============================================

To build everything and pack it into a DMG file, you'll need:

- Xcode 3.0. Older versions may work, but I haven't tested them
  with modern versions of Wings.

- The FBX library. http://www.autodesk.com/fbx

Make sure that your current directory is the directory in which the
sources were unpacked.

Example:

$ pwd
/Users/bjorng/wings_releases/wings-1.0
$

To build all (including the installer), run the following command:

$ make macosx
.
.
.
<A lot of output follows>
.
.
.
$

When everything is done, there should be a file named like

	wings-1.0-macosx.dmg

in the current directory.


Building an installation package for Linux (and other Unix systems)
===================================================================

To build everything and put it into an installation package,
you'll need the following additional software:

- makeself.sh for building the installation package
  (a self-extractable bzip2 archive). http://megastep.org/makeself

- libjpeg for build the jpeg plug-in. libjpeg is pre-installed in most Linux
  distributions. You'll probably need to install header files, though, by
  installing the package libjpg-devel. Otherwise, get the sources from:
  http://www.ijg.org

Make sure that your current directory is the directory in which the
sources were unpacked.

Example:

$ pwd
/Users/bjorng/wings_releases/wings-1.0
$

To build all (including the installation package),
run the following command:

$ make unix
.
.
.
<A lot of output follows>
.
.
.
$

When everything is done, there should be a file named like

	wings-1.0-linux.bzip2.run

in the current directory.