Gnash Manual version 0.4.0

Rob Savoye


����������
������

Document maintainer: Ann Barcomb


��������������
����������

This manual describes version 0.8.0 of Gnash.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You can find a copy of the GFDL at this link or in the file COPYING-DOCS distributed with this manual.

Revision History
Revision Gnash Manual version 0.4.0June 2007

Ann Barcomb Rewritten for software version 0.8.0.

Free Software Foundation

Revision Gnash Manual version 0.3.0Oct 2006

Rob Savoye Updated for the alpha release.

Free Software Foundation


Table of Contents

Introduction
Gnash Overview
Flash Support
Using Gnash
Gnash Command Line Options
Gnash Interactive Control Keys
User Configuration File
Installing and Configuring Gnash
Using a Package Manager
Building from Source
Getting the Source
Code Dependencies
Documentation Dependencies
Testing Dependencies
Configuration
Building from Source
Installation
Reporting Bugs
Compile the latest Gnash build
Determine if the bug was previously reported
Review the bug writing guidelines
Filing a bug report
Glossary
Authors
A. GNU Free Documentation License
0. PREAMBLE
1. APPLICABILITY AND DEFINITIONS
2. VERBATIM COPYING
3. COPYING IN QUANTITY
4. MODIFICATIONS
5. COMBINING DOCUMENTS
6. COLLECTIONS OF DOCUMENTS
7. AGGREGATION WITH INDEPENDENT WORKS
8. TRANSLATION
9. TERMINATION
10. FUTURE REVISIONS OF THIS LICENSE
Addendum

Introduction

Gnash is a free Flash movie player, which can be used as a stand-alone application or as a browser plugin.

Gnash Overview

Gnash started life as GameSWF, a free Flash movie player with fairly good Flash format v7 compliance. In December 2005, Gnash was forked from GameSWF and repackaged in the GNU project style. The objective of Gnash is to create an industrial strength Flash movie player which can be widely deployed.

Gnash can be used as a stand-alone player, as a Mozilla Firefox plugin, or as a Konqueror plugin ('Kpart'). The plugin works by creating a new window in the stand-alone player which is connected to the browser window.

Flash Support

Gnash supports the majority of Flash opcodes up to SWF version 7, and a wide sampling of ActionScript classes for SWF version 7. There are plans to work towards greater support for SWF 8 and beyond. AMF support is minimal.

Using Gnash

Gnash can be used as a standalone player or as a plugin. Using it as a standalone player, you can execute any flash movie from the command line by just supplying the file name. No command line options are required to just play the movie using the default actions. So if you type:

gnash samples/car_smash.swf

It will create a window and play the movie. In this case it's a simple animation of a car driving, swerving, and finally crashing.

Gnash Command Line Options

While by default no options are necessary, there are options that can be used to change Gnash's basic behavior.

gnash [options] file

-h

Print usage information.

-s factor

Scale the movie up/down by the specified factor.

-c

Produce a core file instead of letting SDL trap it. By default, SDL traps all signals, but sometimes a core file is desired to assist with debugging.

-d num

Number of milliseconds to delay in main loop. The main loop polls continuously with a delay to adjust how long Gnash sleeps between iterations of the loop. The smaller the number, the higher the CPU load gets, and of course, the more iterations of the main command loop.

-p

Run full speed (no sleep) and log frame rate.

-a

Enable Actionscript debugging.

-v

Be verbose; i.e. print debug messages to stdout.

-va

Be verbose about movie Actions.

-vp

Be verbose about parsing the movie. Warning: this can generate a lot of text, and can affect the performance of the movie you are playing.

-ml bias

Specify the texture LOD bias (float, default is -1) This affects the fuzziness of small objects, especially small text.

-w

Write a debug log called gnash-dbg.log. This will record of all the debug messages whether they are printed to the screen or not.

-j

Specify the width of the window. This is mostly used only by the plugin.

-k

Specify the height of the window. This is mostly used only by the plugin.

-1

Play once; exit when/if movie reaches the last frame. This is the default.

-r [0|1|2|3]

0 disables rendering and sound (good for batch tests).

1 enables rendering and disables sound (default setting).

2 enables sound and disables rendering.

3 enables rendering and sound.

-t sec

Timeout and exit after the specified number of seconds. This is useful for movies which repeat themselves.

-g

Start Gnash with a Flash debugger console so one can set break points or watchpoints.

-x id

This specifies the X11 window ID to display in; this is mainly used by plugins.

-b bits

Bit depth of output window (for example, 16 or 32). Appropriate bit depths depend on the renderer and GUI library used.

-u url

Set the _url member of the root movie. This is useful when you download a movie and play it from a different location. See also the -U switch.

-U baseurl

Set base url for this run. URLs are resolved relative to this base. If omitted defaults to the _url member of the top-level movie (see the -u switch).

-P parameter

Parameters are given in ParamName=Value syntax and are mostly useful to the plugin to honour EMBED tags attributes or explicit OBJECT PARAM tags. A common use for -P is to provide FlashVars (ie: -P "FlashVars=home=http://www.gnu.org").

Gnash Interactive Control Keys

While a movie is playing, there are several control keys. These can be used to step through frames, pause the playing, and control other actions.

CTRL-Q

Quit/Exit.

CTRL-W

Quit/Exit.

ESC

Quit/Exit.

CTRL-P

Toggle Pause.

CTRL-R

Restart the movie.

CTRL-[ or kp-

Step back one frame.

CTRL-] or kp+

Step forward one frame.

CTRL-T

Debug. Test the set_variable() function.

CTRL-G

Debug. Test the get_variable() function.

CTRL-M

Debug. Test the call_method() function.

CTRL-B

Toggle the background color.

User Configuration File

Gnash supports a configuration file which lives in the users home directory. This file is called .gnashrc. In this you can have default settings which will be used by Gnash when running standalone, or as a browser plugin. Any command line options override these values.

Gnash supports three types of configuration variables. The three types are an on/off value, a numeric value, or in the case of the whitelist and blacklist, a list of hostnames as ASCII text.

localdomain

This value can be set to either on or off, and controls the loading of external Flash movies over a network. Traditionally this tells Gnash to only load Flash movies from the existing domain.

localhost

This value can be set to either on or off, and controls the loading of external Flash movies over a network. This is a stricter version of the localdomain setting as this allows the loading of Flash movies to the same host Gnash is running on.

whitelist

This is a list of hostnames, separated by a colon :. If this list is not empty, only external flash movies from these hosts are allowed to load.

blacklist

This is a list of hostnames, separated by a colon :. External flash movies from these domains are never allowed to load. If whitelist is present and not empty, blacklist is not used.

delay

Gnash uses a timer based event mechanism to advance frames at a steady rate. This lets one override the default setting in Gnash to play a movie slower or faster.

verbosity

This is a numeric value which defines the default level of verbosity from the player.

MalformedSWFVerbosity

This value can be set to either on or off, and controls whether malformed SWF errors should be printed. If set to true, verbosity level is automatically incremented. Set 'verbosity' to 0 afterwards to hush.

ASCodingErrorsVerbosity

This value can be set to either on or off, and controls whether ActionScript coding errors should be printed. If set to true, verbosity level is automatically incremented. Set 'verbosity' to 0 afterwards to hush.

debuglog

This is the full path and name of debug logfile as produced by Gnash.

writelog

This value can be set to either on or off, and controls whether a debug log is always written by Gnash, or not at all.

sound

This value can be set to either on or off, and controls the sound of the standalone player. By default Gnash enables playing the sound in any Flash movie. Refer to pluginsound to control sound for the browser plugin.

pluginsound

This value can be set to either on or off, and controls the sound of the player when running as a browser plugin. By default, sound is enabled when using Gnash as a browser plugin. Refer to sound for information about standalone player sound control.

EnableExtensions

Set to ``on'' to enable extensions. Off by default.

StartStopped

Set to ``on'' to have the GUI start in "stop" mode. This is useful in particular for the plugin, so you have to explicitly start any movie on a webpage. Off by default.

My current Gnash configuration file looks like this:

  
    #
    # Gnash client options
    #

    # Only access remote content from our local domain
    set localdomain on

    # Only access content from our local host
    set localhost on

    # These sites are OK
    # uncommenting the following line will allow load of external
    # movies *only* from the specified hosts.
    #set whitelist www.doonesbury.com:www.cnn.com:www.9news.com

    # Don't access content from these sites
    set blacklist www.doubleclick.com:mochibot.com

    # The delay between timer interrupts
    set delay 50

    # The default verbosity level
    set verbosity 1

    # Be verbose about malformed SWF
    set MalformedSWFVerbosity true

    # Be verbose about AS coding errors
    set ASCodingErrorsVerbosity true

    # The full path to the debug log
    set debuglog ~/gnash-dbg.log

    # Write a debug log to disk
    set writelog on

    # Enable or Disable sound for the standalone player
    set sound on

    # Enable or Disable sound for the standalone player
    set pluginsound on

  

Installing and Configuring Gnash

There are two ways of installing Gnash: using a package manager or installing from source.

Using a Package Manager

Gnash is available as a package for a number of Linux and BSD distributions, such as Ubuntu, Debian, FreeBSD, and OpenBSD. There is also an unofficial Fedora RPM. This is not an extensive list, and you are advised to search if you wish to use a package manager on a different system.

Building from Source

Installing from source will involve the following steps: getting the source, resolving dependencies, configuration, compilation, testing, and installation. The Gnash installation process is fairly standard:

  ./autogen.sh
  ./configure <options>
  make
  make check
  make install
  

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

Presently, Gnash source is about 16 MB when extracted and configured. Compilation requires about 100 MB of harddrive space. A minimum of 128 MB of physical RAM is recommended for compiling.

Getting the Source

Gnash is available as a release tarball, a development checkout, or a development snapshot.

Releases

The source can be acquired from a GNU FTP Mirror. The release version is intended to be stable, and is probably your best choice if the release took place recently. If you need features or fixes which were introduced after the release, consider a CVS checkout or the daily snapshot.

To download, select a mirror near you, then choose the gnash directory.

Repository

The latest development sources are available via anonymous CVS (leave the password blank). This is recommended if you need features or bug fixes which were introduced after the last release. Look at the daily snapshot if you experience difficulty accessing the repository.

First set the environment variable CVS_RSH to 'ssh', as shown in this example, which uses the GNU Bourne-Again shell (bash):

  export CVS_RSH="ssh"
  cvs -z3 -d:pserver:anonymous@cvs.sv.gnu.org:/sources/gnash co gnash
      

It is also possible to browse the repository on the web.

Snapshot

The daily development snapshot can be downloaded from http://www.gnashdev.org/dev_snapshots/. This is the best option if you need changes which were introduced after the last release of Gnash, but are unable to download directly from the repository.

Code Dependencies

Gnash has a number of dependencies on other packages. If you install the dependencies using a package manager, be certain to install the development versions of the packages. The normal versions are often missing the headers Gnash needs to compile.

Table�1.�Code Dependency Table

NameLevelVersionDescriptionExplanationapt-get packageRPM/Yum package
BoostRequired1.32 or higher Boost is a library of portable C++ classes and templates. In Gnash, Boost libraries are used extensively. libboost-thread-devliboost-thread-dev
libxml2Required Libxml2 is the GNOME XML parser library and is available at http://xmlsoft.org. This library is used to parse messages in the XML or XMLSocket ActionScript classes. libxml2-devlibxml2-devel
AGGPossibly Required2.4 or higher AGG is the AntiGrain low-level 2D graphics library. Gnash requires the installation of at least one renderer. AGG is considered the best supported renderer for Gnash. libagg-devagg-devel
OpenGLPossibly Required OpenGL is a standard specification defining a cross-language cross-platform API for writing applications which produce 3D and 2D graphics. It supports hardware acceleration. You can download a free implementation from http://www.mesa3d.org. Gnash requires the installation of at least one renderer. libgl1-mesa-devlibmesa-devel
CairoPossibly Required Cairo is a 2D graphics library with support for multiple output devices. It will automatically use graphic card acceleration when available, and has an experimental OpenGL backend. Gnash requires the installation of at least one renderer. Cairo is considered the least supported renderer for Gnash. libcairo2-devcairo-devel
GTKPossibly Required2.2 or higher GTK is the GIMP Toolkit GUI library. It uses Cairo internally. Gnash requires the installation of at least one GUI library. GTK is considered to be the best supported GUI library option for Gnash. libgtk2.0-devgtk-devel
GtkGlExtPossibly Required GtkGlExt integrates OpenGL into GTK. This library is required in order to use the GTK GUI library in conjunction with the OpenGL renderer. libgtkglext1-devgtkglext-devel
SDLPossibly Required The Simple DirectMedia Layer is a cross-platform multimedia library which provides abstraction for audio, graphics, sound and input APIs. SDL is available from http://www.libsdl.org. Gnash requires the installation of at least one GUI library. SDL may also be used as a sound handler regardless of whether it is employed as a GUI library. The GUI library is poorly supported in Gnash, but the sound handler is the best supported in Gnash. libsdl1.2-devSDL-devel
FLTKPossibly Required2.0 or higher The Fast Light ToolKit is a portable GUI library which is intended as a replacement for the SDL GUI. Gnash requires the installation of at least one GUI library. FLTK may be used in conjunction with the Cairo and AGG renderers. No distribution packages are available.No distribution packages are available.
KDEPossibly Required Kdelibs is a collection of libraries needed to compile KDE applications. Gnash requires the installation of at least one GUI library. Kdelibs is also required for the Kpart plugin for Konqueror. kdelibs4-devkdelibs-devel
libMADOptional libMAD is MPEG audio decoder. libMAD is one of the available options for sound handling. libmad0-devlibmad-devel
GstreamerOptional Gstreamer is a video handler. If you would like video playback, you must install one of the video handlers. libgstreamer0.8-devgstreamer-devel
gst-ffmpegPossibly Required gst-ffmpeg allows you to use the FFMPEG decoder with Gstreamer. This package is required if you would like to use Gstreamer as a video handler. gstreamer0.8-ffmpeg-devgstreamer-ffmpeg-devel
FFMPEGPossibly Required FFMPEG is a video handler. If you would like video playback, you must install one of the video handlers. It is also a dependency of gst-ffmpeg. ffmpeg-devffmpeg-devel
JPEGOptional JPEG is a lossy image format which is heavily used for images. This library is used for rendering JPEGs. libjpeg62-devlibjpeg
PNGOptional PNG is a patent-free image format which is comparable to GIF. This library is used for rendering PNGs. libpng12-devlibpng
libcurlOptional libcurl is the multiprotocal file transfer library. This library is used for URL downloading. libcurl4-gnutlslibcurl
automakePossibly Required1.6.0 Automake is a tool for generating Makefile.in files. This package is required to run autogen.sh, which is a requirement if you are using the development source from CVS. automakeautomake
autoconfPossibly Required2.59 Autoconf is a package for generating configure scripts. This package is required to run autogen.sh, which is a requirement if you are using the development source from CVS. autoconfautoconf
gettextPossibly Required0.14.6 Gettext is part of the GNU Translation Project. This package is required to run autogen.sh, which is a requirement if you are using the development source from CVS. gettextgettext
libtoolPossibly Required1.5.22 This is a generic library support script. This package is required to run autogen.sh, which is a requirement if you are using the development source from CVS. libltdl3-devlibtool

Documentation Dependencies

The following packages are used to build Gnash's documentation.

Table�2.�Documentation Dependency Table

NameLevelVersionDescriptionExplanationapt-get packageRPM/Yum package
DocbookRequired Docbook is is an industry-standard XML format for technical documentation. You can download it from http://sourceforge.net/project/showfiles.php?group_id=21935#files. Gnash documentation is written in Docbook. docbook-utils and docbook-dsssldocbook-dtd41-sgml and docbook-style-dsssl
DocBook2XOptional This software package converts Docbook documents to the traditional man page format, GNU Texinfo format, and HTML (via Texinfo) format. It is available at http://docbook2x.sourceforge.net/. DocBook2X is required to produce HTML and Texinfo formats. docbook2xdocbook2x
TexinfoPossibly Required Texinfo can be used to convert DocBook2X output into GNU info pages. You can download it from http://ftp.gnu.org/gnu/texinfo/. Texinfo is required if you wish to product GNU info pages. texinfotexinfo
FOPOptional0.20.5 Formatting Objects Processor is a print formatter driven by XSL formatting objects. It is a Java application which can output PDF, PCL, PS, SVG, XML, Print, AWT, MIF, and Text. It is available at http://xmlgraphics.apache.org/fop/. FOP is required for PDF output. fopfop
Java (j2re)Possibly Required FOP requires Sun's Java runtime (GCJ does not work with FOP). You can download it from http://java.sun.com. Sun's Java runtime (j2re) is required to use FOP. Download the package from Sun. Download the package from Sun.
JAIPossibly Required Sun's Java Advanced Imaging API can be downloaded from http://java.sun.com/products/java-media/jai/iio.html. JAI is required if you wish to include graphics in a PDF file being generated with FOP. Download the package from Sun. Download the package from Sun.

If you install j2re, set the JAVA_HOME environment variable to the top directory of the j2re installation. If you encounter problems with the Java installation, you may also need to add this path to the CLASSPATH environment variable.

Testing Dependencies

Gnash tries to run as many tests as possible, but will simply skip tests if the tools to run them are unavailable.

Table�3.�Testing Dependency Table

NameLevelVersionDescriptionExplanationapt-get packageRPM/Yum package
MingOptional0.4.0_beta4 or higher Ming is an ActionScript compiler. Ming is the primary compiler for ActionScript testcases. No distribution packages are available.No distribution packages are available.
MtascOptional Mtasc is an ActionScript compiler. Mtasc is used in some tests. mtascNo distribution packages are available.
swfdecOptional Swfdec is a Flash player. Swfdec is used in some testcases. No distribution packages are available.Unofficial package swfdec
DejaGnuOptional DejaGnu is a testing framework. DejaGnu is used to run multiple tests in an automated fashion. dejagnudejagnu

Configuration

Gnash uses GNU Autoconf for configuration.

If you opted to download the development checkout of Gnash, the configure script will not be included. It can be created by running autogen.sh from the source root directory:

  ./autogen.sh
  

Note that there are some dependencies for autogen.

All the standard configure options are avaiable. In addition, Gnash has two types of options: those which enable or disable features, and those which specify custom paths for development packages which aren't found during the default search. A complete list of all configuration options, including standard ones, can be seen by typing:

  ./configure --help
  

Read further for a more detailed explanation of Gnash-specific options.

The syntax for running configure is as follows:

  configure <options>
  

The example below shows the configure options which create the smallest working standalone version of Gnash. In this example, configure is being run from the source root directory:

  ./configure --disable-debugger --disable-cygnal --disable-docbook --disable-plugin --enable-media=mad --enable-gui=sdl
  

Features

Some switches can be used during configuration to enable or disable features of Gnash. Some of the most important configuration options are:

  • --enable-gui lets you specify your GUI of choice. The default option is GTK.

  • --enable-renderer allows a renderer to be chosen. The default renderer is OpenGL.

  • --enable-media permits a media handler to be selected. The default is FFMPEG with SDL sound.

A complete list of available features follows.

--disable-debugger

Disable support for the Flash debugger. The debugger is mainly of interest to Flash developers.

--enable-dmalloc

Enable support for the DMalloc memory debugging tool.

--enable-dom

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

--enable-embedded

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

--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.

--enable-ghelp

Enable support for the GNOME help system.

--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-gui=gtk|sdl|kde|fltk|fb

Select the Graphic User Interface to use (just one at a time please).

GTK
The GTK+ toolkit, which is the default GUI. Said to interwork particularly well with firefox.
SDL
Simple DirectMedia Layer, a simple and portable GUI. Its sound facilities are used when --enable-media=ffmpeg|mad regoardless of whether it is also in charge of the GUI.
KDE
An interface adapted to the KDE Desktop Environment. This must be selected when building the Konqueror plugin "klash". Furthermore, the only renderer that currently works with KDE is opengl.
FLTK
Fast Light ToolKit, low on resource usage. Since all build using fltk are now broken, we declare it "for developers".
FB
The Linux Frame Buffer, also known as /dev/fb0. AGG is the only renderer that can currently be used with the framebuffer GUI.
--enable-i810-lod-bias

Enable fix for Intel 810 LOD bias problem. Older versions 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.

--disable-klash

Disable support for Konqueror plugin. If --enable--plugin is specified, and support for building KDE programs is found, Klash is built by default. This option limits the plugin to only the Mozilla/Firefox one.

--enable-libsuffix

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

--enable-mac

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

--enable-media=ffmpeg|mad|gst

Select the specified media decoder and sound engine. FFMPEG and MAD use the SDL sound engine; GST uses its own. Mixing this with --enable-sound=gst is invalid. Using ffmpeg is the default decoder.

You should only select one media decoder.

--enable-plugin

Enable building the plugin. By default the Mozilla Firefox plugin won't be built, even if all the required files are found by configure. Configure --with-plugindir= to specify where the plugin should be installed.

--enable-qtopia

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

--enable-renderer=opengl|cairo|agg

Enable support for the a graphics backend. Currently only opengl and agg work sufficiently. OpenGL is used when you have hardware accelerated graphics. AGG i used when you don't have hardware accelerated graphics. Typically most desktop machines have OpenGL support, and most embedded systems don't. OpenGl is the default when building Gnash, although the quality of AGG's rendering is currently superior to OpenGL.

--enable-sdk-install

Enable installing the libraries and headers as an SDK.

--disable-shared

Enable installing the shared libraries and headers. Note that the extensions mechanism may not work if shared libraries are disabled.

--enable-strict

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

--enable-testing

Enable testing-specific methods.

--enable-xmlreader

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

Specifying Custom Paths

By default, none of these options should be required unless you want Gnash to use a specific version of a development package, or if the configure test fails to find a component. Please report the problem if a configure test fails.

The following custom path options are available:

--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-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 where the 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 test cases, 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.

--with-agg-incl

Directory where the AGG (Antigrain) headers are installed.

--with-agg-lib

Directory where the AGG (Antigrain) library is installed.

--with-ffmpeg-incl

Directory where the FFMPEG headers are installed.

--with-ffmpeg-lib

Directory where the FFMPEG library is installed.

--with-boost-incl

Directory where the Boost headers are installed.

--with-boost-lib

Directory where the Boost library is installed.

--with-curl-incl

Directory where the libCurl headers are installed.

--with-curl-lib

Directory where the libCurl library is installed.

Cross Compiling

To cross configure and compile Gnash, begin by building a target system on your workstation. This includes cross compilers for the target architecture, and some system headers. You will also need the following packages to be built for the target system: libxml2, libpng (if used), libjpeg (if used), your GUI library, your renderer, and your video handler (if used). The page http://frank.harvard.edu/~coldwell/toolchain/ has instructions on building a target system from scratch and offers a shell script to make the process easier.

Note that you may have some difficulties getting libMesa (opengl) to cross compile.

The important configuration options are the ones which specify the architecture for the build:

--target

The target architecture, where the final executables are expected to run.

--host

The host architecture, where the executables are expected to run. Usually this is the same as the --target, except when building a compiler as a Canadian Cross. In this case, you might build a cross compiler on a UNIX system which runs on a win32 machine, producing code for a third architecture, such as ARM. In this example, --target would be 'arm-unknown-linux-gnu', while --host would be 'win32'.

--build

This is the system the build is running on.

The following example of configure builds for an ARM system on an x86 system. It was run after an ARM system was built in /usr/arm and other required libraries were cross compiled.

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

Building from Source

Once you have configured Gnash, you are ready to build the code. Gnash 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 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 isn't built, even when you install Gnash. 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 need to 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
    

Gnash also uses Doxygen to produce HTML documentation of Gnash 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

If a test fails, please report it by following the instructions for reporting a bug.

Using DejaGnu

The easiest way to run Gnash'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. Verbose prints more information about the testing process, while all includes details on passing tests.

  make check RUNTESTFLAGS="-v -a"
        

Running Some Tests

It is possible to run just a particular test, or 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 would create and run 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 Gnash 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 Flash movie version of the test case, which can be run with a standalone Flash player. For instance, the target for SWF version 6 could be run with Gnash:

   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
        

Installation

Installation is done with the command:

  make install
  

Gnash installs a number of libraries, namely: libbase, libgeometry, libbackend, libserver, and libmozsdk. Executables consist of the (optional) plugin, gprocessor, cygnal, and gnash. Documentation may also be installed. The installation location is controlled with the --prefix configure option.

Note that if you are using a single file-system NFS mounted to multiple platforms, the configuration option --exec-prefix may be used to specify where platform-dependent executables and libraries are installed.

Libraries

Installed libraries are located in /usr/local/lib by default. If the --prefix option was used in configuration, the libraries will be installed in the directory lib inside the path you specified. If the libraries are stored in a non-standard location, you need to identify the path in one of two ways.

The traditional way to do this on UNIX platforms is to set the LD_LIBRARY_PATH variable to the path plus /lib. For example, if you installed in /home/gnash, the LD_LIBRARY_PATH path would be /home/gnash/lib. Multiple paths are delimited with a colon (':').

GNU/Linux allows the custom path to be added to /etc/ld.so.conf. After adding the path, run ldconfig as root to update the runtime cache.

Executables

The Mozilla plugin is installed into the plugins directory of the system installed Firefox or Mozilla, if development packages are installed for either of them. Otherwise, the default is /usr/lib/mozilla/plugins. You may also specify the plugin installation directory by using the --with-plugindir option to configure.

The remaining executables will be installed in the bin subdirectory of the directory specified by during configuration. If no path was specified, the default is /usr/local/bin.

Documentation

Documentation is not built by default; please refer to the section on documentation for more information on building documentation.

man and info will be installed in /usr/local/share/man and /usr/local/share/info respectively, unless the --mandif or --infodir configuration options are used.

GNOME help documentation uses the directory /usr/local/share/gnash/doc/gnash/C/ by default. A configuration file in the Gnash source tree, doc/C/gnash.omf is used to specify under which menu item Gnash appears in the GNOME help system.

Reporting Bugs

The better your bug report is, the easier it will be for the developers to address the issue. Please follow the three steps described below before filing a bug report:

Compile the latest Gnash build

Obtain a copy of the latest development checkout or development snapshot. Put the source in an empty directory, then configure and compile Gnash.

If you are able to replicate the bug, proceed to the next step.

If the bug does not persist, the problem may have been solved, or the issue may involve your environment. By creating a fresh build of your original version and trying to replicate the bug you can determine if it is an environmental issue or a resolved bug. If you are able to replicate the bug, the problem has been fixed and there is no need to file a bug report.

If the bug is no longer visible, the problem may be related to your environment. Try to determine the source of the conflict so that you can include this information in your bug report.

Determine if the bug was previously reported

Search the Gnash bug tracker to see if the bug has already been identified.

If the issue has already been reported, you should not file a bug report. However, you may add some additional information to the ticket if you feel that it will be beneficial to the developers. For instance, if someone reported a memory issue on Ubuntu GNU/Linux, and you noticed the same problem on OpenBSD, your stacktrace would be useful. Conversely, adding a "me too" note to a feature request is not helpful.

Review the bug writing guidelines

A good bug report should be precise, explicit, and discrete. This means that there should be just one bug per ticket, and that a ticket should contain the following information:

  • An overview of the problem;
  • Instructions on how to replicate the bug;
  • A description of what happened when you performed the steps to replicate the bug, and what you expected to happen;
  • Your system information: operating system name and version, as well as the versions of major dependencies;
  • The release number or checkout timestamp for the version of Gnash where you observe the problem;
  • The file config.log, which should be attached as a file; and
  • A descriptive title.

Include any additional information that you feel might be useful to the developers.

Filing a bug report

After following the steps described above, you can file a bug report.

Glossary

ActionScript

ActionScript, or "AS", is the scripting language for Flash applications. It is compiled to bytecode, which is a subset of the SWF format.

AMF

AMF is the object format used by Flash for shared objects and streaming video.

DocBook

DocBook is a markup language for presentation-neutral documentation, such as manuals.

Doxygen

Doxygen is a documentation generator for for multiple languages which uses comments in the source code to create stand-alone documentation.

extensions

A Gnash extension is a plugin (not a browser plugin) which implements additional functionality beyond what is covered by Flash specification. These are shared libraries which are loaded at runtime.

Flash

The term Flash is used to describe both the Adobe IDE for creating SWF files, and the technology itself. Gnash documentation uses the latter definition.

GUI

A GUI is a "graphical user interface". In Gnash, the GUI library provides a wrapper for mouse and keyboard events, menus, windowing (where available) and a drawing area. You must choose a GUI library during the configuration stage.

Klash

Klash was the name given to the stand-alone instance of Gnash which used the KDE GUI. It has been replaced with an implementation using Qt. Some documentation may incorrectly refer to the Konqueror plugin as Klash. The plugin was renamed Kpart.

Kpart

Kpart is a plugin for Konqueror which is enabled with the configuration option --enable-klash.

Mesa

Mesa is the free software OpenGL implementation. Gnash documentation will sometimes use the terms 'OpenGL' and 'Mesa' interchangeably.

plugin

The term plugin is used in Gnash to refer to both any Gnash browser plugin, as well as the Firefox plugin specifically. The Konqueror plugin is called Kpart. Sometimes, the term is used in an even more generic sense to refer to extensions.

renderer

The renderer is the subsystem of Gnash which renders content. Only one renderer may be used; it is chosen during configuration.

Available renderers are: AGG, OpenGL, and Cairo. In terms of feature completeness, AGG comes first; followed by OpenGL and then Cairo. In most cases, AGG is preferred for performance, except cases where it is beneficial to have hardware accelerated rendering (for example, when you have a very slow CPU but a very fast graphics card). In this case OpenGL should be used.

sound handler

The sound handler is the part of Gnash which handles both event sounds and streaming sound. Audio from external sources are also handled through the sound handler when SDL is used. The sound handler must be selected during configuration.

There are currently two sound handlers available in Gnash: SDL and Gstreamer. The SDL sound handler uses ffmpeg or libmad for decoding mp3-audio, although it can be built without mp3-support. The Gstreamer-sound handler uses the available plugins to decode the audio, so it might not work if some important plugins are missing. The SDL sound handler is recommended.

SWF

SWF is the file format for Flash movies.

Authors

Gnash is maintained by Rob Savoye . Other active developers are: Sandro Santilli, Bastiaan Jacques, and Tomas Groth. Please send all comments and suggestions to .

Rob Savoye is available for consulting on a variety of renewable energy and open source technologies. Please refer to http://www.senecass.com for more information.

Gnash was initially derived from GameSWF. GameSWF is maintained by Thatcher Ulrich . The following people contributed to GameSWF: Mike Shaver, Thierry Berger-Perrin, Ignacio Casta�o, Willem Kokke, Vitaly Alexeev, Alexander Streit, and Rob Savoye.

A.�GNU Free Documentation License

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or non-commercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. COPYING IN QUANTITY

If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

  • A.� Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

  • B.� List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).

  • C.� State on the Title Page the name of the publisher of the Modified Version, as the publisher.

  • D.� Preserve all the copyright notices of the Document.

  • E.� Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

  • F.� Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

  • G.� Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

  • H.� Include an unaltered copy of this License.

  • I.� Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

  • J.� Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

  • K.� In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

  • L.� Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

  • M.� Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.

  • N.� Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version .

5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document , on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

Addendum

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

Copyright YEAR YOUR NAME.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License".

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.