# Building from Source

## Overview

The typical process of building from source will involve getting the source, build dependencies, configuration, compilation, testing, and installation. A simplified overview of the process would be:

            ./autogen.sh
            ./configure
            make
            make check
            make install

If you are compiling with GCC you will need to use a machine with at least 128 megabytes of physical RAM; 64MB is not enough for a couple of the files, even with swap enabled and optimisation turned off. With less than 512 megabytes available, many build combinations can still be a long and painful experience.

At present the &app; source is about 30 MB extracted and configured and requires a total of about 125 megabytes to compile it.

Continue reading for detailed step-by-step instructions of the entire procedure.

## Getting The Source

### Releases

Tarballs of official releases can be found in the download area of the project's GNU Savannah page at http://savannah.gnu.org/projects/gnash or under http://ftp.gnu.org/gnu/gnash

### Git Access

The latest &app; development sources are available via git. Use the following commands to check them out:

    	git clone git://git.sv.gnu.org/gnash.git
    	cd gnash

You can then update your copy from the main repository using:

    	  git pull

At any time, other temporary development branches may also be available. Replace exp with the branch name to check these out.

    	  git checkout -b exp origin/exp

If you only have access to the internet via a web proxy, you will find daily source snapshots of the latest CVS tree in http://www.gnashdev.org/dev_snapshots

&codedependencies; &testdependencies; &docdependencies;

&configuration;

Once you have &app; configured, you are ready to build the code. &app; is built using GNU make.

## Compiling the Code

The most basic way to compile code is simply:

    	make

If the compilation ends with an error, check the output of configure and ensure that you are not missing any required prerequisites. The output of `make` can be verbose; you may wish to pipe the output to a file.

The variables used by `make` can be redefined when the program is invoked, if you desire it. The most interesting flags are CFLAGS and CXXFLAGS, which are often used to enable debugging or turn of optimization. The default value for both of these variables is -O2 -g. A list of influential environment variables can be seen in the configuration help:

    ./configure --help

In the following example, debugging is enabled and optimization is disabled:

    make CFLAGS=-g CXXFLAGS=-g

## Creating the Documentation

By default, documentation is not built when you install &app;. This is because there are a number of dependencies for the documentation. Documentation is built when it is specified with a specific target in the generated `Makefile` in the `doc/C` sub-directory. If you type `make install` in this directory, all documents will be built.

You must specify a target output format when you wish to create documentation. The available output formats are: `html`, `pdf`, `info`, `man`, and `alldocs`. It is also possible to output `GNOME help` if the configure option `--enable-ghelp` was used. The `alldocs` target will build all output formats except GNOME help. For example, to create HTML output, type:

    	make html

&app; also uses Doxygen to produce HTML documentation of &app; internals. You must have Doxygen installed to produce this documentation, which is built from the `doc` directory with the command (documents will be placed in the subdirectory `apidoc/html`):

    	make apidoc

## Running the Tests

Before beginning the potentially lengthy install, it is wise to test the installation. If a test fails, please report it by following the instructions for reporting a bug.

### Using DejaGnu

The easiest way to run &app;'s test suite is to install DejaGnu. After installing DejaGnu, run:

    	  make check

#### Increasing Verbosity

If you encounter a problem with a test, increasing the verbosity may make the issue easier to spot. Additional details are visible when RUNTESTFLAGS are used to add the verbose and all options. The `verbose` option prints more information about the testing process, while the `all` option includes details on passing tests.

    	    make check RUNTESTFLAGS="-v -a"

#### Running Some Tests

It is possible to run just a single test, or a subdirectory of tests, by specifying the directory or compiled test file.

Some tests rely on testsuite/Dejagnu.swf, which in turn relies on Ming. This file is created when you run `make check` for the entire testsuite, and can also be created on demand:

    	    make -C testsuite Dejagnu.swf

In this example, the `clip_as_button2` test is compiled and run:

    	    make -C testsuite/samples clip_as_button2-TestRunner
    	    cd testsuite/samples && ./clip_as_button2-TestRunner

This creates and runs all the tests in the directory `movies.all`:

    	    make -C testsuite/movies.all check

### Running The Tests Manually

You may also run test cases by hand, which can be useful if you want to see all the debugging output from the test case. Often the messages which come from deep within &app; are most useful for development.

The first step is to compile the test case, which can be done with `make XML-v#.swf` where the '#' is replaced with the target SWF version or versions. For example:

    	  make XML-v{5,6,7,8}.swf

#### Movie tests

This creates a SWF movie version of the test case, which can be run with a standalone SWF player. For instance, the target for SWF version 6 could be run with &app;:

    	    gnash -v XML-v6.swf

#### ActionScript Unit Tests

Unit tests for ActionScript classes in `testsuite/actionscript.all` are run without a graphical display:

    	    gprocessor -v XML-v6.swf

&install;

&crosscompiling;