# Building From Source

## Code Dependancies

Gnash has dependencies on other packages. When installing from a packaged release file (rpm, deb, whatever), you'll need to install the development versions to get the tools used to compile Gnash. The normal runtime packages installed are usually missing the headers needed to compile Gnash

### OpenGL

Gnash uses OpenGL for rendering the images. OpenGL is a 3D graphics package that support hardware acceleration. You can get the free version of OpenGL at this link: http://www.mesa3d.org

To install a binary package using apt-get (on Debian based systems), install libgl1-mesa-dev. For RPM or Yum based systems, install the libmesa-devel package.

### GtkGlExt

GtkGlExt is an optional package used instead of SDL. Gtk enables better integration into Firefox, as well as better event handling and higher level GUI constructs like menus and dialog boxes.

To install a binary package using apt-get (on Debian based systems), install gtkglext-dev. For RPM or Yum based systems, install the gtkglext-devel package.

### Pango

Pango is a dependency of GtkGlExt, and is used for font handling.

To install a binary package using apt-get (on Debian based systems), install pango-dev. For RPM or Yum based systems, install the pango-devel package.

### Atk

Atk is a dependency of GtkGlExt, and is used for accesibility support.

To install a binary package using apt-get (on Debian based systems), install atk-dev. For RPM or Yum based systems, install the atk-devel package.

### Cairo

Cairo is a dependency of GtkGlExt, and is used for 2D rendering.

To install a binary package using apt-get (on Debian based systems), install cairo-dev. For RPM or Yum based systems, install the cairo-devel package.

### Glib

Glib is a dependency of GtkGlExt, and is a collection of commonly used functions.

To install a binary package using apt-get (on Debian based systems), install glib-dev. For RPM or Yum based systems, install the glib-devel package.

### Gstreamer

Gstreamer will be used for sound and video support.in the near future, as this work is in progress.

To install a binary package using apt-get (on Debian based systems), install streamer-dev. For RPM or Yum based systems, install the gstreamer-devel package. Version 0.10 or greater is required.

### SDL

The Simple DirectMedia Layer is a cross-platform multimedia library designed to provide low level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL, and 2D video framebuffer. You can get SDL from this link: http://www.libsdl.org

To install a binary package using apt-get (on Debian based systems), install libsdl1.2-dev. For RPM or Yum based systems, install the SDL-devel package.

### PNG

PNG is a patent free image format that is comparable to `GIF`.

To install a binary package using apt-get (on Debian based systems), install libpng12-dev. For RPM or Yum based systems, install the libpng package.

### JPEG

JPEGis a lossy image format, heavily used for images because of the smaller size of the file.

To install a binary package using apt-get (on Debian based systems), install libjpeg62-dev. For RPM or Yum based systems, install the libjpeg package.

### SDL Mixer

The Simple DirectMedia Layer has an addon package called SDL Mixer, which is used to play audio files. SDL_mixer is a sample multi-channel audio mixer library. It supports any number of simultaneously playing channels of 16 bit stereo audio, plus a single channel of music. You can get SDL Mixer from this link: http://www.libsdl.org/projects/SDL_mixer/release/

To install a binary package using apt-get (on Debian based systems), install libsdl-mixer1.2-dev. For RPM or Yum based systems, install the SDL_mixer-devel package.

### libxml2

Libxml2 is the GNOME XML parser library. This is used when Gnash is configured with XL support. Libxml2 is used to parse any incoming messages when using the XML or XMLSocket ActionScript classes. You can get libxml2 from this link: http://xmlsoft.org

To install a binary package using apt-get (on Debian based systems), install libxml2-dev. For RPM or Yum based systems, install the libxml2-devel package.

### OGG Vorbis

Ogg Vorbis is a patent free audio format that is comparable (many people say better) than MP3. This is used by SDL_Mixer to play Ogg files. You can get Ogg Vorbis from this link: http://www.vorbis.com/.

To install a binary package using apt-get (on Debian based systems), install libogg-dev. For RPM or Yum based systems, install the libogg package.

### libMAD

libMad is a high-quality MPG decoder for audio files. All variations of the MP3 format are supported. http://www.underbit.com/products/mad/. You can get libMAD from this link: http://xmlsoft.org

To install a binary package using apt-get (on Debian based systems), install libmad0-dev. For RPM or Yum based systems, install the libmad package.

### Mozilla/Firefox

The Mozilla development package is no longer needed to build the plugin. The required header files have been added to the Gnash so it builds without Mozilla or Firefox installed at all.

To install a binary package using apt-get (on Debian based systems), install mozilla-dev or firefox-dev. For RPM or Yum based systems, install the mozilla-devel or firefox-devel package.

## Documentation Dependancies

### Docbook

Docbook is an industry standard XML format for technical documentation. It is used by many projects, as there are free software implementations of the Docbook style-sheets and tools. It is used by both the GNOME project, and the Linux Documentation Project.. It is customizable by using style-sheets for each output device. Default style-sheets are included for a variety of print formats, like `PDF` and `HTML`.

You can get Docbook from this link: http://sourceforge.net/project/showfiles.php?group_id=21935#files.

To install a binary packages using apt-get (on Debian based systems), install the docbook, docbook-xsl, docbook-xml, docbook-dsssl,and docbook-utils packages. For RPM or Yum based systems, install the docbook, docbook-style-xsl, docbook-style-dsssl, and docbook-utils packages.

### DocBook2X

DocBook2X is a software package that converts DocBook documents into the traditional Unix man page format and the GNU Texinfo format. It supports tables for man pages, internationalization, and easy customization of the output using XSLT. This package is used to convert the Gnash documentation into HTML and Texinfoformats. Texinfo can later be converted to standard GNU `info` pages.

You can get DocBook2X from this link: http://docbook2x.sourceforge.net/. Texinfo is available at this link: http://ftp.gnu.org/gnu/texinfo/.

To install a binary package of DocBook2X using apt-get (on Debian based systems), install docbook2x. For RPM or Yum based systems, install the docbook2x package. To install a binary package of Texinfo using apt-get (on Debian based systems), install texinfo. For RPM or Yum based systems, install the texinfo package.

### FOP

FOP (Formatting Objects Processor) is the world's first print formatter driven by XSL formatting objects (XSL-FO) and the world's first output independent formatter. It is a `Java` application that reads a formatting object (FO) tree and renders the resulting pages to a specified output. Output formats currently supported include PDF, PCL, PS, SVG, XML, Print, AWT, MIF and Text. The default output target is PDF.

You can get `fop` from this link: http://xmlgraphics.apache.org/fop/. Currently only `fop version 0.20.5` works with the current DocBook tools.

### Java

The `fop` processor is a `Java` application, so it needs a Java runtime to work. This is installed on many platforms by default, but unfortunately `fop` doesn't work with the GCJ runtime. There is apparently work being done on FOP to make it usable, but for now, this means installing Sun Java.

In addition to the default `j2re` package, you also need to install `JAI`, the Java Advanced Imaging library. You can get `JAI` from this link. `JAI` is not required, and the `PDF` file will be generated. It will just be missing all the graphics.

`Fop` also requires an environment variable to be set. This is JAVA_HOME. This needs to point to the top directory where your `Sun j2re` is installed. If you have any other problems with your Java installation, you can also try adding the `Sun j2re` path to the `CLASSPATH` environment variable.

## Configuring The Code

Gnash uses GNU Autoconf ( http://www.gnu.org/software/autoconf) for configuration. All the standard configure options apply.

By default, `make install' will install all the files in `/usr/local/bin', `/usr/local/lib' etc. You can specify an installation prefix other than `/usr/local' using `--prefix', for instance `--prefix=$HOME'.

Occasionally the default paths for a development package aren't correct. There is a series of options that can be used to adjust these paths to your own setup. By default, Gnash will look in all the standard places for these tools.

A configure script can support many options, but they fall into two main types. The first type are options to enable or disable features. The second type is used to specify custom paths for development packages that can't be found by the default searching and testing.

### Specifying A Custom Path

This set of options typically use a `--with-[name]` naming convention. A Prefix can often be supplied, which is the top level directory that can be used to look for the other sub directories. Most options of this type have two variations, one to specify a path to the header files, and another to specify a path to the libraries. This lets you override the default paths `configure` finds, or specify your own paths.

By default, none of the options should be required unless you want Gnash to use a specific version of a development package, or the configure test for Gnash fails to find the component. There are a lot of options, but Gnash has a lot of dependencies. If you find a configure test is failing on your machine, please submit a patch or file a bug report.

--x-includes=DIR

  X include files are in DIR.

--x-libraries=DIR

  X library files are in DIR.

--with-libxml=PFX

  Prefix to where libxml is installed.

--with-libxml-libraries=DIR

  Directory where libxml library is installed.

--with-libxml-includes=DIR

  Directory where libxml header files are installed.

--with-docbook=DIR

  Directory where the DocBook style-sheets are installed.

--with-sdl-prefix=PFX

  Prefix where SDL is installed.

--with-sdl_mixer-incl

  Directory where sdl_mixer header is installed.

--with-sdl_mixer-lib

  Directory where sdl_mixer library is installed.

--with-zlib-incl

  Directory where zlib header is installed.

--with-zlib-lib

  Directory where zlib library is installed.

--with-jpeg-incl

  Directory where jpeg header is installed.

--with-jpeg-lib

  Directory where jpeg library is installed.

--with-png-incl

  Directory where png header is installed.

--with-png-lib

  Directory where png library is installed.

--with-qt-dir

  Directory where QT is installed. This is only used by the Klash plugin.

--with-qt-includes

  Directory where the QT header files are installed. This is only used by the Klash plugin.

--with-qt-libraries

  Directory wherethe QT libraries are installed. This is only used by the Klash plugin.

--with-plugindir

  This is the directory to install the Firefox plugin in.

--with-ming

  Ming is used to build testcases, but not by the Gnash player itself.

--with-mad_incl

  Directory where libmad header is installed.

--with-mad_lib

  Directory where libmad library is installed.

--with-ogg_incl

  Directory where the libogg headers are installed.

--with-ogg_lib

  Directory where the libogg library is installed.

--with-gstreamer-incl

  Directory where the Gstreamer headers are installed. Gstreamer version 0.10 or greater must be used.

--with-gstreamer-lib

  Directory where the Gstreamer library is installed. Gstreamer version 0.10 or greater must be used.

--with-opengl-includes

  Directory where OpenGL (libMesa) headers are installed.

--with-opengl-lib

  Directory where the OpenGL (libMesa) library is installed.

--with-glext-incl

  Directory where GtkGlExt headers are installed.

--with-glext-lib

  Directory where the GtkGlExt library is installed.

--with-gtk2-incl

  Directory where the Gtk2 headers are installed.

--with-gtk2-lib

  Directory where the Gtk2 library is installed.

--with-cairo_incl

  Directory where the Cairo headers are installed.

--with-cairo-lib

  Directory where the Cairo library is installed.

--with-glib-incl

  Directory where the Glib headers are installed.

--with-glib-lib

  Directory where the Glib library is installed.

--with-pango-incl

  Directory where the Pango headers are installed.

--with-pango-lib

  Directory where the Pango library is installed.

--with-atk-incl

  Directory where the ATK headers are installed.

--with-atk-lib

  Directory where the ATK library is installed.

--with-pthread-incl

  Directory where the Pthread headers are installed.

--with-pthread-lib

  Directory where the Pthread library is installed.

### Configure Options

In addition to being able to specify your the directories for various sub components, there are also some switches that can be used at configuration time to enable or disable various features of Gnash. There are defaults for all of these options. These are typically used only by developers who don't have all the other development packages installed, and wants to limit what is required for a quite build of `Gnash`.

--disable-xml

  Disable support for XML. The default is to support XML.

--disable-fork

  Disable the plugin forking the standalone player,and using a thread for the player instead. Currently forking the standalone player will give you the best results.

--disable-plugin

  Disable building the plugin. By default the Mozilla Firefox plugin will be built if all the required files are found by configure. Configure `--with-plugindir` to specify where the plugin should be installed.

--disable-glext

  Disable using GtkGlExt, which forces the use of SDL instead. By default if the GtkGL extension for Gtk is found by configure, the GTK enabled GUI is built.

--enable-klash

  Enable support for Konqueror plugin.

--enable-libsuffix

  /lib directory suffix (64,32,none=default). This is only used by Klash.

--enable-embedded

  Link to Qt-embedded, don't use X. This is only used by Klash.

--enable-qtopia

  Link to Qt-embedded, link to the Qtopia Environment. This is only used by Klash.

--enable-mac

  Link to Qt/Mac (don't use X). This is only used by Klash.

--enable-sdk-install

  Enable installing the libraries and headers as an SDK.

--enable-testing

  Enable testing specific methods

--enable-lotsa-warnings

  Turn on tons of GCC compiler warnings. By default only `-Wall` is ued with GCC.

--enable-ghelp

  Enable support for the GNOME help system.

--enable-dom

  When using the XML library, parse the messages using a DOM based parser. This is the default.

--enable-xmlreader

  When using the XML library, parse the messages using a SAX based parser.

--enable-dmalloc

  Enable support for the DMalloc memory debugging tool.

--enable-i810-lod-bias

  Enable fix for Intel 810 LOD bias problem. Older version of libMesa on the Intel i810 or i815 graphics processor need this flag or Gnash will core dump. This has been fixed in newer versions (summer 2005) of libMesa.

You can control other flags used for compiling using environment variables. Set these variables before configuring, and they will be used by the configure process instead of the default values.

CXX

  C++ compiler command.

LDFLAGS

  linker flags, e.g. -L[library directory] if you have libraries in a nonstandard directory.

CPPFLAGS

  C/C++ preprocessor flags, e.g. -I[headers directory] if you have headers in a nonstandard directory.

CXXFLAGS

  C++ compiler flags.

### Cross Compiling And Configuration

To cross configure and compile Gnash, you first need to build a target system on your workstation. This includes cross compilers for the target architecture, and typically some system headers. You will also need `libxml2`, `libpng`, `libjpeg`, `sdl`, `sdl mixer`, `opengl`, and `ogg` development packages built for the target system.

If you need to build up a targe system from scratch, there is a good document and shell script at this web site: http://frank.harvard.edu/~coldwell/toolchain/.

After I built up an arm system in /usr/arm using the shell script from this web sitem, I then cross compiled all the other libraries I needed. The fun part is trying to get libMesa to cross compile, because it's not really setup for it.

So to build for an arm based system on an x86 based systems, configure like this:

    	../gnash/configure --target=arm-unknown-linux-gnu --prefix=/usr/arm --host=arm-unknown-linux-gnu --build=i686-pc-linux-gnu --disable-plugin

The important options here are the ones that specify the architectures for the build.

--target

  The target architecture. This is the architecture the final executables are supposed to run on.

--host

  The host architecture. This is the architecture the executables are supposed to run on. This is usually the same as `--target` except when building a Canadian Cross. This is when you build a cross compiler on a Unix machine, that runs on a `win32` machine, producing code for yet a third architecture, like the `ARM`.

--build

  This is the system this build is running on.

You also want to use `--disable-plugin`, since it's doubtful you have a full Firefox development system for your target architecture. This will drop all the plugin specific configuration tests, and not try to compile the plugin.

## Building Gnash

After managing to configure Gnash, building the code is simple. Gnash is built using `GNU make`.

### Compiling The Code

After configuring, typing `make` will compile the code. No options are necessary. If desired, you can redefine the variables used by `make` on the command line when invoking the program. The few flags of interest are `CFLAGS` and `CXXFLAGS`, often used to turn on debugging or turn off optimizing. Invoking make as in this example would build all the code with debugging turned on, and optimizing turned off. The default values for both of these variables is `-O2 -g`.

    	  make CFLAGS=-g CXXFLAGS=-g

If the compilation ends with an error, check the output of configure and make sure nothing required to build Gnash is missing.

### Processing The Documentation

By default, the documentation isn't built at all. It isn't even built when typing `make install` from the top level build directory. It's only built when specified with a specific target in the generated `Makefile` in the `doc/C/` sub-directory. All the docs are built in this directory when executing a `make install`.

There is a target for each output format, `make html`, `make pdf`, `make info`, and `make man`. A higher level target, `make alldocs`, builds the four main formats for the documentation.

Gnash also has support to use Doxygen to produce `HTML` pages documenting the internals of Gnash. While this is not necessarily internals documentation, it does give very useful information about all the files, the classes, a cross reference, and other data.

You need to have Doxygen installed to produce these docs. If you do have it installed, typing `make apidoc` in the `doc` directory will make these docs under a sub directory of `apidoc/html`

## Installation

Gnash installs it's libraries so they can be found in the runtime path for the Gnash executable. Unless the --prefix option is used at configuration time, the libraries get installed in /usr/local/lib. If you install Gnash in a non-standard location, you have to specify this runtime path by one of two means.

The traditional way that works on all Unix platforms is to set the LD_LIBRARY_PATH environment variable to $prefix/lib. You can have multiple paths in this variable as long as they are separated by a colon ":" character.

For GNU/Linux systems, the custom path to the libraries can be added to the /etc/ld.so.conf file. After adding the custom path, then run (as root) the `ldconfig` command to update the runtime cache.

### What Code Gets Installed and Where

Several libraries get installed, as well as the three executables. All the libraries, `libbase, libgeometry, libgbackend, libserver, and libmoxsdk` get installed in the directory pointed to by `$prefix`. This variable is set by the `--prefix` option at configure time, and if not specified, it defaults to `/usr/local`. All the libraries get installed in `$prefix/lib` where most packages also install their libraries.

The plugin gets installed in the plugins directory of the version of the`Firefox` or `Mozilla` you have the development packaged installed for. For builds from Mozilla CVS, the default installation directory is `/usr/local/lib/firefox-[version number]/plugins/`. The default system directory used when installing packages is `/usr/lib/mozilla/plugins`. Note that you have to be `root` to install files in a system directory. For some reason when the plugin is installed in the users `$HOME/.mozilla/plugins` or `$HOME/.firefox/plugins` directory, unresolved symbols from deep within Firefox appear.

The executables get installed in a `bin` directory of the directory specified by `$prefix`. Once again, this path defaults to `/usr/local/bin` if a special prefix wasn't configured in.

If using a single file-system `NFS`mounted to multiple platforms, you can specify an additional options, `--exec-prefix`. This is where all the platform dependent executables and libraries can get installed.

### What Documentation Gets Installed and Where

The documentation only installs when GNOME Help support is enabled by using `--enable-ghelp`. Because GNOME help files get installed in a system directory when building from source, you need to either change the permissions on the destination directory, or do the install as `root`. The default directory for GNOME Help files is: `/usr/local/share/gnash/doc/gnash/C/`.

A config file in the Gnash source tree, `doc/C/gnash.omf` is used to specify under which menu item Gnash is listed in the GNOME Help system.