This manual describes version 0.8.5 of Gnash.
Copyright © 2005, 2006, 2007, 2008 Free Software Foundation
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.
Table of Contents
List of Tables
Table of Contents
Gnash is a free SWF movie player. It is available as a stand-alone application or as a plugin for several popular web browsers. It supports playing media from a disk or streaming over a network connection. Some popular video sharing sites like YouTube are supported on a wide variety of devices from embedded ones to modern desktops.
Gnash has a better focus on security, allowing the user tight control of all network or disk based I/O. Gnash also supports extending ActionScript by creating your own classes. You can write wrappers for any development library, and import them into the player much like Perl or Python does.
This manual is primarily focused on users interested in how to get Gnash installed from a package, and basic usage as a web browser plugin. For more technical details, please refer to the Gnash Reference manual.
Gnash is known to compile for most any POSIX and ANSI C++ conforming system if you have all the dependent libraries installed. Systems we test on, and which Gnash is known to run on are Ubuntu, Fedora, Debian, Mandriva, OpenBSD, NetBSD, FreeBSD, Win32, and Darwin (OSX) primarily. Occasionally other platforms are built, primarily by those distribution maintainers. This includes BeOS, Haiku, Syllable, OS/2, Solaris, Slackware, and Gentoo.
Gnash is capable of reading up to SWF v9 files and opcodes, but primarily supports SWF v7, with better SWF v8 and v9 support under heavy development. Since the 0.8.2 release, Gnash includes initial parser support for SWF v8 and v9. Not all ActionScript 2 classes are implemented yet, but all of the most heavily used ones are. Many ActionScript 2 classes are partially implemented; there is support for all of the commonly used methods of each class.
Gnash has implemented about 80% of ActionScript v2.0, and has begun implementing ActionScript v3.0. Gnash supports the majority of Flash opcodes up to SWF v9, and a wide sampling of ActionScript classes for SWF v8.
As ActionScript 3 is a more developed version of ActionScript 2, many of the same classes work for both. Support has been added to Gnash's ActionScript library to support the new ActionScript 3 filters, which get applied to every class. Implementing ActionScript classes is often the easiest way for new Gnash developers to make a contribution without a deep internal knowledge of Gnash.
Gnash has included video support since early 2007, but this is an ever changing field of reverse engineering. Many of the popular video sharing sites use SWF v8 or v9, which Gnash supports imperfectly. This is improving all the time, so often builds from a development snapshot will work when using the older release packaged in your distribution doesn't. You can find daily snapshots of the latest CVS tree at: http://www.gnashdev.org/dev_snapshots.
Gnash uses ffmpeg for codecs, so any file supported by Mplayer should work with Gnash. Gnash supports the loading of patent free codecs like Ogg Vorbis or Theora from disk based files, while work is being done to support these codecs when embedded in a SWF file. Ffmpeg contains the codecs used by the current SWF defintion, FLV, VP6 (ON2), H.263, H.264, and MP3.
Table of Contents
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 Gnash 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.
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
The latest Gnash development sources are available via bzr. Use the following commands to check them out:
mkdir gnash cd gnash bzr branch http://bzr.savannah.gnu.org/r/gnash/trunk
At any time, other temporary development branches may also be available. Replace trunk with the branch name to check these out. You can update your copy from the main repository using:
cd trunk bzr pull
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
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 often lack the headers Gnash needs to compile.
Some dependencies have other dependencies: for instance, GTK also needs glib2, atk, and pango to produce a fully linked executable. Different distributions also use differing dependencies, sometimes a package will depend on libxml2 on one system, but libexpat on another.
Table 2.1. Code Dependency Table
Name | Level | Version | Description | Explanation | apt-get package | RPM/Yum package | BSD package |
---|---|---|---|---|---|---|---|
Boost | Required | 1.32 or higher | Boost is a library of portable C++ classes and templates. | In Gnash, Boost libraries are used extensively, primarily boost-gthread and boost-date-time. Boost is used for thread and mutext handling. |
libboost-thread-dev, libboost-date-time-dev libboost-dev
|
libboost-thread-devel, libboost-date-time-devel
|
boost-headers, boost-libs, or just boost
|
AGG | Possibly Required | 2.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-dev | agg-devel | agg |
OpenGL | Possibly 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, although it doesn't support hardware acceleration. | Gnash requires the installation of at least one renderer. If you don't have a hardware accelerated driver, you're better off using AGG for the renderer. | libgl1-mesa-dev | libmesa-devel | mesa | |
Cairo | Possibly 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-dev | cairo-devel | cairo | |
GTK | Possibly Required | 2.2 or higher | GTK is the GIMP Toolkit GUI library used by the GNOME desktop. It uses Cairo internally. Gtk enables better integration with Firefox, as well as better event handling and higher level GUI constructs like menus and dialog boxes. | 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-dev | gtk-devel | gtk+2 |
GtkGlExt | Possibly 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-dev | gtkglext-devel | gtkglext | |
SDL | Possibly 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-dev | SDL-devel | SDL-1.2 | |
FLTK | Possibly Required | 2.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. | No distribution packages are available. |
KDE | Possibly 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. | kdelibs3-dev, kdebase-dev | kdelibs-devel, kdebase-devel | kdelibs, kdebase | |
Gstreamer | Optional | Gstreamer is a video handler. | If you would like video playback, you must install one of the video handlers. | libgstreamer0.8-dev | gstreamer-devel | gstreamer-0.10 | |
gst-ffmpeg | Possibly 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-dev | gstreamer-ffmpeg-devel | gstreamer-ffmpeg | |
FFMPEG | Possibly Required | FFMPEG is a video handler. | If you would like video playback, you must install one of the video handlers. When using the gstreamer-ffmpeg plugin, ffmpeg doesn't need to be installed, as it's part of the plugin. For systems without Gstreamer support, ffmpeg can be used directly. | ffmpeg-dev | ffmpeg-devel | ffmpeg | |
JPEG | Required | JPEG is a lossy image format which is heavily used for images. | This library is used for reading external JPEGs and JPEG data embedded in SWF files. | libjpeg62-dev | libjpeg | jpeg | |
PNG | Required | PNG is a patent-free image format which is comparable to GIF. | This library is used for loading external PNG images (part of the SWF8 specification) and for writing images in the PNG format. | libpng12-dev | libpng | png | |
GIF | Required | GIF is a common image format that should now be free of patent restrictions. GIF. | This library is used for loading external GIF images (part of the SWF8 specification). | libungif-dev | libungif-devel | gif | |
libcurl | Optional | libcurl is the multiprotocal file transfer library. | This library is used for URL downloading. | libcurl4-gnutls | libcurl | curl | |
Glib2 | Optional | Glib2 is a dependency of Gtk, and is a collection of commonly used functions. | This library is used for convenience. | glib2-dev | glib2-devel | glib2 | |
Atk | Optional | Atk is a dependency of Gtk, and is used for accessibility support. | This library is used for accessiblity.. | atk-dev | atk-devel | atk | |
Pango | Optional | Pango is a dependency of Gtk, and is used for font handling. | This library is used for font handling. | pango-dev | pango-devel | pango | |
automake | Possibly Required | 1.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. | automake | automake | automake |
autoconf | Possibly Required | 2.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. | autoconf | autoconf | autoconf |
gettext | Possibly Required | 0.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. | gettext | gettext | gettext |
libtool | Possibly Required | 1.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-dev | libtool | libtool |
Gnash tries to run as many tests as possible, but will silentl skip tests if the tools to run them are unavailable.
Table 2.2. Testing Dependency Table
Name | Level | Version | Description | Explanation | apt-get package | RPM/Yum package | BSD package |
---|---|---|---|---|---|---|---|
Ming | Optional | 0.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. | No distribution packages are available. |
Mtasc | Optional | 1.12 or higher | Mtasc is an ActionScript compiler. | Mtasc is used in some tests. | mtasc | No distribution packages are available. | No distribution packages are available. |
swfc | Optional | part of swftools 0.8.1 | Swfc is an swf compiler. | Swfc is used in some testcases. | No distribution packages are available. | No distribution packages are available. | No distribution packages are available. |
swfmill | Optional | 0.2.12 | Swfmill is an XML-based SWF (Shockwave Flash) processing tool. | Swfmill is used in some testcases. | No distribution packages are available. | No distribution packages are available. | No distribution packages are available. |
Python | Optional | 2.4 or higher | Python is a scripting language. | Python is used by part of the testing framework. | python | python | python |
DejaGnu | Optional | 1.4 or higher | DejaGnu is a testing framework. | DejaGnu is used to run multiple tests in an automated fashion. | dejagnu | dejagnu | dejagnu |
The following packages are used to build Gnash's documentation.
Table 2.3. Documentation Dependency Table
Name | Level | Version | Description | Explanation | apt-get package | RPM/Yum package | BSD package |
---|---|---|---|---|---|---|---|
Docbook | Required | 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-dsssl
|
docbook-dtd41-sgml and docbook-style-dsssl
| docbook | |
DocBook2X | Optional | 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. | docbook2x | docbook2x | docbook2x | |
DocBook-utils | Optional | This software package converts Docbook documents to the traditional man page format, GNU Texinfo format, and HTML (via Texinfo) format. | DocBook-utils is required to produce HTML and Texinfo formats. | docbook-utils | docbook-utils | docbook-utils | |
Texinfo | Possibly 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 produce GNU info pages. | texinfo | texinfo | texinfo | |
FOP | Optional | 0.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. | fop | fop | fop |
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. | ||
JAI | Possibly 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.
Gnash, like most GNU projects, allows a user to select various options before compiling its source code. These options include selecting from the available features, specifying custom paths for installation, and cross compiling support uses GNU Autoconf for configuration.
If you opted to download the development snapshot 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 available. In addition, Gnash has two types of options: those that enable or disable features, and those that specify custom paths for development packages which are not found during the default search. A complete list of all configuration options, including standard ones, can be seen by typing:
./configure --help | less
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-plugin --enable-media=ffmpeg --enable-gui=sdl
By default, you shouldn't need to supply any options to configure. The configure script will attempt to determine what to build based on the development libraries you have installed. The default configuration for Gnash is both GTK and KDE GUIs, the AGG renderer, and Gstreamer for multimedia support, with no extensions built.
Being highly portable, Gnash has many configuration options available, and not all are supposed to work together. A common mistake when configuring Gnash is to supply too many options, overdriving Gnash's ability to do the right thing.
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 AGG.
--enable-media
permits a media handler to be
selected. The default is Gstreamer.
A complete list of available features follows.
Table 2.4. Configuration Options - Features
Option | Function |
---|---|
--enable-debugger | Enable support for the Flash debugger. The debugger is mainly of interest to Flash developers, and is still under development. |
--enable-lirc | Enable support for the LIRC remote control protocol. |
--enable-cygnal | Build the Cygnal streaming media server. |
--disable-menus | Disable building all the menus for the GUI. THis is used by mobile devices without as much screen space. |
--enable-docbook | Enable the generation of HTML, INFO, and MAN versions of the documentation from the Docbook XML. You will then be able to use make html, make info, and make man commands. By default, man,info and html pages are generated. |
--enable-gui=gtk|sdl|kde|fltk|fb|hildon|alp | Select the Graphic User Interface to use (choose one).
|
--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. |
--enable-media=ffmpeg|gst|none
|
Select the specified media decoder and sound engine.
FFMPEG uses the SDL sound engine; GST uses its own.
You should only select one media decoder. |
--disable-nsapi
--enable-nsapi
| Force disable/enable building the NPAPI plugin.
By default the Mozilla plugin is built if the GTK gui
is selected. Specify the
--with-npapi-plugindir= option to specify where the
plugin should be installed.
|
--disable-kparts
--enable-kparts
| Force disable/enable building the KPARTS plugin. By default the
KDE plugin is built if the kde gui is selected.
Specify the --with-kde-plugindir= and
--with-kde-servicesdir= options (or more generally
the --with-kde-pluginprefix= one) to specify where the
plugin should be installed. The default installation dir is extracted
from kde-config.
|
--disable-plugins
| Disable build of both kparts and npapi plugins |
--enable-renderer=opengl|cairo|agg
| Enable support for a graphics backend. Currently
only opengl and
agg work sufficiently. Use OpenGL
when you have hardware accelerated graphics. Use AGG
when you do not have hardware accelerated
graphics or when you are building for a wide audience.
Typically most desktop machines have OpenGL
support, and most embedded systems do not. AGG is the
default when building Gnash, although the speed of OpenGL's
rendering is currently superior to AGG. |
--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 verbose GCC compiler warnings. By default only
-Wall is used with GCC. |
--enable-fps-debug
| Enable FPS debugging code. When this feature is compiled in you can use the -f switch of Gnash to have FPS printed at regular intervals. |
--enable-write | Makes the Mozilla plugin write the currently playing SWF movie to /tmp .
|
--disable-sa-launcher | Drops the NPAPI plugin support for writing a standalone executable launcher script for the currently playing SWF movie to /tmp . Note that you'll still need to add a 'writelauncher' string to your GNASH_OPTIONS environment variable for the script to be created, even if the compile-time support is enabled.
|
--disable-mit-shm
| Disable support for the MIT-SHM X extensions. Currently support is only available using GTK gui and AGG renderer. Keeping it enabled is not a problem as it will not be used if not available in the current X session. |
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:
Table 2.5. Custom Path Options
Option | Function |
---|---|
--x-includes=DIR
| X include files are in DIR. |
--x-libraries=DIR
| X library files are in DIR. |
--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-plugins-install=user|system|prefix
| This option sets the install policy for NPAPI (mozilla) and KPARTS (kde) plugins. Policy 'user' means plugin will be installed only for the configuring user. Policy 'system' will try to find a systemwide place for plugins (to enable for all). Policy 'prefix' will install under ${prefix} (npapi/kparts subdirs); WARNING: if 'prefix' policy is given, plugins won't be found w/out further enabling procudures. The default policy is 'user', can be overridden for specific plugins. |
--with-npapi-install=user|system|prefix
| This option sets the install policy for NPAPI plugin. Policy 'user' means plugin will be installed in ~/.mozilla/plugins; 'system' will try to find an existing system-wide mozilla plugin dir (or bail out if not found); 'prefix' will install under ${prefix}/npapi. |
--with-npapi-plugindir
| This is the directory to install the NPAPI (Mozilla) plugin in. By default it goes to ~/.mozilla/plugins. |
--with-kparts-install=user|system|prefix
|
This option sets the install policy for all KPARTS (kde) files.
Policy 'user' means plugin will be installed in ~/.kde;
'system' will find out using kde-config (or bail out if not found);
'prefix' will install under ${prefix}/kparts.
The actual prefix can be overridden using
--with-kde-pluginprefix
or the fine-tuned options.
The default at time of writing (2008-05-18) is 'user'.
|
--with-kde-pluginprefix
|
This option sets the default install dir for all KPARTS (kde) files.
The plugin will be installed in PREFIX/lib/kde3, use
-with-kde-plugindir to override. The service file in
PREFIX/share/services, use --with-kde-servicesdir to
override. The config file in PREFIX/share/config, use
--with-kde-configdir to override. The
appdata file in PREFIX/share/apps/klash, use
--with-kde-appsdatadir to override.
|
--with-kde-plugindir
| This is the directory to install the KPARTS (kde) plugin in. By default it is what's set by --with-kde-pluginprefix or what's returned by kde-config --install module --expandvars, or $(prefix)/share/services if kde-config is not found. |
--with-kde-servicesdir
| This is the directory to install the KPARTS (kde) service in. By default it is what's set by --with-kde-pluginprefix or what's returned by kde-config --install services --expandvars, or $(libdir)/kde3 if kde-config is not found. |
--with-kde-configdir
| This is the directory to install the KPARTS (kde) config files in. By default it is what's set by --with-kde-pluginprefix or what's returned by kde-config --install config --expandvars, or $(prefix)/share/config if kde-config is not found. |
--with-kde-appsdatadir
| This is the directory to install the KPARTS (kde) application data files in. By default it is what's set by --with-kde-pluginprefix or what's returned by kde-config --install data --expandvars, or $(prefix)/share/apps if kde-config is not found. |
--with-ming
| Ming is used to build test cases, but not by the Gnash player itself. |
--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. |
Once you have Gnash configured, you are ready to build the code. Gnash is built using GNU make.
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
By default, documentation is not built 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 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
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
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.
The easiest way to run Gnash's test suite is to install DejaGnu. After installing DejaGnu, run:
make check
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"
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
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
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 Gnash:
gnash -v XML-v6.swf
Now that Gnash has been compiled and tested, use the following command to install it:
make install
The above command installs the standalone player. If the correct
files were found by configure and if the
--disable-plugin
option was not specified, the
Gnash browser plugin is also installed.
Gnash installs a number of libraries,
namely: libgnashbase,
libgnashamf, libgnashmedia,
libserver, and libgnashplugin.
Executables
consist of the (optional) plugin, gprocessor
,
cygnal
, dumpshm
,
soldumper
, and gnash
.
Documentation may also be installed.
The installation location is controlled with the
--prefix configure
option, except for plugins, which are explicitly set with
--plugin-dir.
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.
Installed libraries are located in
/usr/local/lib
by default.
If the --prefix option was used during the
configuration step, 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 must 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.
The Mozilla plugin is built from headers (the Mozilla SDK) provided with Gnash and
does not need extra development packages to be installed. By default, the
plugin is installed to ~/.mozilla/plugins/
. To enable
the plugin for other users, copy the file libgnashplugin.so
to .mozilla/plugins/
in their home directory.
You may also specify the plugin installation directory by using the
--with-plugindir
option
at configuration time.
These defaults are likely to change in future versions of Gnash.
The remaining executables are installed in the bin
subdirectory of the directory specified by during configuration.
If no path was specified, the default is
/usr/local/bin
.
Documentation is not built by default; please refer to the section on documentation for more information on building documentation.
man and info
are installed in /usr/local/share/man
and /usr/local/share/info
respectively, unless
the --mandir
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.
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 to cross compile all the dependencies normally needed to build Gnash. This can on occasion be a daunting process, as not all libraries will cross configure and cross compile. There is more information about cross compiling all the dependant packages on the http://www.gnashdev.org web site.
If you need to build your own tool chain, that is beyond the scope of this manual. There are various resources on the web for howto's on building GCC based cross toolchains. Two popular sites are http://frank.harvard.edu/~coldwell/toolchain/ and http://www.kegel.com/crosstool/. This can also be a very time consuming and frustrating process, even for experienced developers.
Because the process of building your own cross tool chain can be harder than one may wish, there are several other cross development environments that simulate a native environment to make it easier to develop. These also let you develop for both native and cross builds. Several popular ones are Access Linux Platform, Scratchbox, Open Embedded, Maemo.
To build for an ARM based system on an x86 based systems, configure like this using the traditional style cross toolchain, configure like this:
../../gnash/configure --build=i686-pc-linux-gnu --host=arm-linux --prefix=/usr/local/arm/oe --disable-nsapi --disable-kparts --enable-gui=fb --enable-renderer=agg --disable-shared --disable-menus
The important configuration options are the ones which specify the architecture for the build:
The target architecture, where the final executables are expected to run.
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'.
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
Table of Contents
The Gnash project relies on the community of Gnash users to test the player. Feedback is critical to any successful project. Not only does it let us know that people use Gnash, but it helps us understand the community's needs. Gnash uses a bug tracker on http://savannah.gnu.org to manage these reports.
When filing a report, please follow the guidelines below. The better your bug report is, the easier it will be for the developers to address the issue. Bug reports without enough information will be asked to provide this information anyway. Adding critical details, like the Operating System you are on, its version, and any relevant error messages from Gnash that you get.
For starters, it's a good idea to obtain a copy of the latest snapshot. Although Gnash is primarily released as source, the Gnash build infrastructure allows the automated building of binary packages. Often the version of Gnash as packaged by a GNU/Linux or BSD distribution is based on the last official release, which could be months out of date. It helps us, if this is the case, for you to try a newer packaged build of Gnash.
You can get a fresh binary package of Gnash, as well as recent source packages from http://www.getgnash.org/packages .
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.
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 development 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;
A descriptive title.
Include any additional information that you feel might be useful to the developers.
After following the steps described above, you can file a bug report at https://savannah.gnu.org/bugs/?group=gnash.
I know any discussion of coding styles leads to strong opinions, so I'll state simply I follow the GNU Coding Standards. Where there is some flexibility as to the location of braces, I prefer mine on the end of a line when using an if, while, or do statement. I find this more compact style easier to read and parse by eye. I'm also a big fan of always using braces around if statements, even if they're one liners.
Here's my tweaked style settings for Emacs, the one true editor to rule them all.
(defconst my-style '((c-tab-always-indent . t) (c-auto-newline . t) (c-hanging-braces-alist . ( (brace-list-intro) (namespace-open) (inline-open) (block-open) (brace-list-open) (brace-list-close) (brace-entry-open) (brace-else-brace) (brace-elseif-brace) (class-open after) (class-close) (defun-open after) (defun-close) (extern-lang-open) (inexpr-class-open) (statement-open) (substatement-open) (inexpr-class-close))) (c-hanging-colons-alist . ((member-init-intro before) (inher-intro) (case-label after) (label after) (access-label after))) (c-offsets-alist . ( (innamespace . 0) (case-label . 2) )) (c-cleanup-list . ( (scope-operator) (empty-defun-braces) (brace-else-brace) (brace-elseif-brace) (defun-close-semi) (list-close-comma) ) ) ;; no automatic newlines after ';' if following line non-blank or inside ;; one-line inline methods (add-to-list 'c-hanging-semi&comma-criteria 'c-semi&comma-no-newlines-before-nonblanks) (add-to-list 'c-hanging-semi&comma-criteria 'c-semi&comma-no-newlines-for-oneline-inliners) ; (knr-argdecl-intro . -) (c-echo-syntactic-information-p . t) ) "My GNU Programming Style")
Another coding consideration: comments are good! Over commenting isn't good. Here is an over commented example:
counter++; // increment counter
Gnash also uses Doxygen style comments. These are processed by Doxygen when building a cross reference of all the classes, and is a good way to help push internals documentation from the depths of the code into documentation where it can be seen by others.
Doxygen style comments for C++ code involves simply using three slashes /// instead of the standard two slashes // used for C++ comments. Here's a short comment block for the XML::cloneNode() method:
/// \brief copy a node /// /// Method; constructs and returns a new XML node of the same type, /// name, value, and attributes as the specified XML object. If deep /// is set to true, all child nodes are recursively cloned, resulting /// in an exact copy of the original object's document tree. XMLNode & XML::cloneNode(XMLNode &newnode, bool deep) { ... }
The \brief keyword means that the text becomes associated when listing all the classes on the generated web pages. The text after the blank link becomes the detailed description which appears on the generated web page for that class and method.
Gnash is maintained by Rob Savoye. Other active developers
are: Sandro Santilli, Bastiaan Jacques, Udo Giacomozzi, Chad
Musick, Benjamin Wolsey, Zou Lunkai, and Russ Nelson. Please
send all comments and suggestions to
<gnash-dev@gnu.org>
. Past and sometimes current
developers are Tomas Groth and Markus Gothe.
Gnash was initially derived from GameSWF.
GameSWF is maintained by
Thatcher Ulrich <tu@tulrich.com>
. The following
people contributed to GameSWF:
Mike Shaver, Thierry Berger-Perrin,
Ignacio Castaño, Willem Kokke, Vitaly Alexeev, Alexander Streit,
and Rob Savoye.
Version 1.1, March 2000
Copyright © 2000 Free Software Foundation, Inc.
Table of Contents
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.
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.
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.
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.
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 .
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."
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.
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.
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.
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.
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.
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 2008, Free Software Foundation.
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 noInvariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
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.