Gnash Manual V0.3.9

The plugin currently works by creating a new window in the standalone player which is connected to the browser window in Firefox.

All movies are downloaded to /tmp and played from there. Many web pages use IE-specific JavaScript to initiate movies, which means that Firefox does not load the Gnash plugin.

The standalone player supports both SDL and GTK2. The SDL support is more portable, and the GTK support allows better integration as a Firefox plugin. When using GTK, a right-button mouse click will activate a menu which can be used to control the movie.

Many movies play without any difficulty in Gnash. Gnash supports the majority of Flash opcodes up to SWF version 7, and a wide sampling of ActionScript classes for SWF version 7. All the core ones are implemented, and many of the newer ones work, but may be missing some of the methods. All unimplemented opcodes and ActionScript classes and methods print a warning when using -v with gnash or gprocessor. Using gprocessor -v is a quick way to see why a movie isn't playing correctly.

There are plans to work towards supporting all the SWF version 8 and greater opcodes, as well as as implementing the missing methods and ActionScript classes. During the first few months of Gnash's existence as a project, most of the focus has been towards portability issues, and getting the plugin to work. Now that the plugin works, more focus will be spent on catching up to full compliance with version 7 and beyond.

Currently implemented ActionScript classes are: Array, Boolean, Date, Key, Math, Mouse, MovieClip, Number, Object, Sound, String, XML, XMLNode, and XMLSocket.

Partially implemented classes are: MovieClipLoader, NetConnection, LocalConnection, TextField, and TextFormat.

Unimplemented classes are: Accessibility, Error, Function, LoadVars, Microphone, NetStream, Selection, SharedObject, Stage, System, Button, Camera, Color, ContextMenu, CustomActions, and Video.

Unimplemented Opcodes are: Throw, Implements, Extends, enum_object, Try, new_method, enum_object, md length, md substring, md chr, delete, and get target.

There is currently no support for FLV video, more than minimal AMF data, or loading external jpegs.

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

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

AGG is the AntiGrain low-level 2D graphics library used instead of OpenGL on embedded systems. This can be used on the desktop as well, but its primary purpose is to run without OpenGL.

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

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

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

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

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

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

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

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

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

Boost is a library of portable C++ classes and templates which layer on top of STL. Boost is used for thread and mutext handling.

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

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

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

Gstreamer is used for sound and video support. It is not needed to build this release. Currently only Gstreamer version 0.10 or higher can be used.

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

FFMPEG can also be used for sound and video support. It is not needed to build this release, but is recommended if you want working sound.

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

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

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

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

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

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

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

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

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

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

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

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

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

The Mozilla development package is no longer needed to build the plugin. The required header files are now included in Gnash, so it builds without Mozilla or Firefox installed at all.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

        ../../gnash/configure --build=i686-pc-linux-gnu --host=arm-linux --prefix=/usr/local/arm/oe --disable-plugin --enable-renderer=agg --disable-shared --with-mp3-decoder=mad
      

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

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

	  make CFLAGS=-g CXXFLAGS=-g
	

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

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

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

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

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

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

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

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

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

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

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

There are currently a few standalone programs in Gnash, which serve to either assist with Gnash development or play flash movies.

The plugin is designed to work within Mozilla or Firefox, although there is Konqueror support as well. The plugin uses the Mozilla NSPR plugin API to be cross platform, and is portable, as well as being well integrated into Mozilla based browsers.

One future thought for the plugin is to use the new Firefox 1.0.5 or greater version of Firefox. This version has added a GTK drawable window which supports hardware acceleration, and is designed to support things like rendering directly into the window without needing OpenGL.

	    application/x-shockwave-flash:swf:Shockwave Gnash
        nokill embed noisy ignore_errors hidden fill swallow(Gnash) loop: gnash -v "$file" -x $window
        : gnash -v "$file" -x $window
	  

Gnash supports a debug logging system which supports both C and C++ natively. This means you can use both printf() style debug messages and C++ iostreams style, where you can print C++ objects directly as you would when using cout.

In the beginning, Gnash only supported the C API for debug logging, so it is the most heavily used in Gnash. This API was used in the log_msg() and log_error() functions, and used a callback to set them up.

It became apparent one day the callback was never needed, and I got tired of having to use c_str() on string data just to print them out.

If a filename is not specified at object construction time, a default name of gnash-dbg.log is used. If Gnash is started from the command line, the debug log will be created in the current directory. When executing Gnash from a launcher under GNOME or KDE the debug file goes in your home directory, since that's considered the current directory.

There is common functionality between using the C or C++ API. Optional output is based on flags that can be set or unset. Multiple levels of verbosity are supported, so you can get more output by supplying multiple -v options on the command line. You can also disable the creation of the debug log.

Adding a new ActionScript class is a relatively simple process. A new file is created to hold the code, with an associated header file. The file name is usually the name of the ActionScript class itself, something like XML. All implementations are written in C++. In the CVS source tree for Gnash, there is a utility file called gen-files.sh that can be used to generate a template for a new ActionScript class. At this time templates have been generated for all documented ActionScript classes.

	    class Foo {
	        public:
		    foo() {};
		    ~foo() {};
		    bool GetBar() { return _bar; }
		private:
		    bool _bar;
	    }
	    struct foo_as_object : public gnash::as_object {
	        Foo obj;
	    }
	  

	    foo_as_object *foo = env.top(0).to_object();
	    bool result = foo->obj.GetBar();
	  

	    struct foo_as_object : public gnash::as_object {
	        Foo obj;
	        foo_as_object() {
	            log_msg("\tCreating foo_as_object at %p \n", this);
	        };
	        ~foo_as_object() {
	            log_msg("\tDeleting foo_as_object at %p \n", this);
	        };
	    }:
	  

	    struct xml_as_object : public gnash::as_object {
	        XML obj;
	        xmlnode_as_object() {
	            log_msg("\tCreating xmlnode_as_object at %p \n", this);
	        };
	        ~xmlnode_as_object() {
	            log_msg("\tDeleting xmlnode_as_object at %p \n", this);
	        };
	        virtual bool get_member(const tu_stringi& name, as_value* val) {
	            if ((name == "firstChild") || (name == "childNodes")) {
	                val->set_as_object_interface(this);
		        return true;
	            }
		    if (m_members.get(name, val) == false) {
		        if (m_prototype != NULL) {
		            return m_prototype->get_member(name, val);
	                }
		        return false;
		    }
	          return true;
	      }
	  };
	  

	    obj->set_member("XML", as_value(xml_new));
	  

	  if (fn.env->top(0).get_type() == as_value::STRING) {
	     ...
	  }
	  

	    xml_obj = new xml_as_object;
	    xml_obj->set_member("load", &xml_load);
	  

	    fn.result->set_as_object_interface(xml_obj);
	  

	    void
	    xml_new(const fn_call& fn) {
	        as_value      inum;
	        xml_as_object *xml_obj;
	    
	        if (fn.nargs > 0) {
	            if (fn.env->top(0).get_type() == as_value::STRING) {
	                xml_obj = new xml_as_object;
		        tu_string datain = fn.env->top(0).to_tu_string();
		        xml_obj->obj.parseXML(datain);
		        xml_obj->obj.setupFrame(xml_obj, xml_obj->obj.firstChild(), true);
	            } else {
	                xml_as_object *xml_obj = (xml_as_object*)fn.env->top(0).to_object();
		        fn.result->set_as_object_interface(xml_obj);
		        return;
	            }
	        } else {
	            xml_obj = new xml_as_object;
	            xml_obj->set_member("load", &xml_load);
	            xml_obj->set_member("loaded", &xml_loaded);
	        }
	        fn.result->set_as_object_interface(xml_obj);
	    }
	  

	      as_obj->set_member("nodeName", as_value("HelloWorld"));
	    

	      // Call the hasChildNodes() function
	      if (node.hasChildNodes() == true) {
	          trace("CHILDREN");
	      }
	      // Get the value of the nodeName property
	      if (node.nodeName == "HelloWorld") {
	          trace("MATCHED");
	      }
	    

Parameters are passed to the callback functions for a class's methods and properties using the fn_call data structure. This data structure contains all the incoming parameters for a callback, as well as it contains the final result from the callback to be passed back into the player.

	    xml_as_object *xml_obj = (xml_as_object*)fn.this_ptr;
	    if (fn.nargs) {
	        filespec = fn.env->bottom(fn.first_arg_bottom_index).to_string;
	    }
	  

	  if (fn.nargs > 0) {
	   name = fn.env->top(0).to_string());
	  }
	

	  if (fn.nargs > 0) {
	      if (fn.env->top(0).get_type() == as_value::STRING) {
	          name = fn.env->top(0).to_string);
	      } 
	      if (fn.env->top(0).get_type() == as_value::NUMBER) {
	          value = fn.env->top(0).to_number);
	      } 
	  }
	

	     foo_as_object *foo_obj = (foo_as_object*)fn.this_ptr;
	     bool bar = foo_obj->obj.GetBar();
	  

	    // Set the argument to the function event handler based on
	    // whether the load was successful or failed.
	    ret = xml_obj->obj.load(filespec);
	    fn.result->set_bool(ret);
	  

As of March, 2006, these are the few opcodes that haven't been implemented for full SWF version 7 compliance. SWF version 8 adds a few more that currently aren't listed here.

FIXME:

FIXME:

All of the main values in Gnash as used by the interpreter, are usually an as_value class. This is a generic object to hold data. The supported data types for an object are BOOLEAN, STRING, NUMBER, OBJECT, C_FUNCTION, AS_FUNCTION. You can retrieve the value of an as_value using the conversion methods. For example, to_tu_string returns the value as string using the Gnash small STL library. Similarly, to_number would return this same value as a double.

as_value is often used as the initializer for a property or the data for a callback. This is done so the type of the object is specified along with the data.

	    // Set the callback for a new XML object
	    obj->set_member("XML", as_value(xml_new));

	    // Set the property to the value of text
	    obj->set_member("nodeName", as_value(text));
	    
	    // Set the property to null, but at least it exists
	    obj->set_member("nodeValue", as_value(""));
	  

	    // Get the name of an object
	    name = fn.env->top(0).to_string());

	    // Get the value of an object
	    value = fn.env->top(1).to_number);

	  

FIXME:

FIXME:

Sounds can be divided into two groups: event-sounds and soundstreams. Event-sounds are contained in a single SWF frame, but the playtime can span multiple frames. Soundstreams can be (and normally are) divided between the SWF frames the soundstreams spans. This means that if a gotoframe-action jumps to a frame which contains data for a soundstream, playback of the stream can be picked up from there.

When Gnash parses a SWF-file, it creates a sound handler if possible and hands over the sounds to it. Since the event-sounds are contained in one frame, the entire event-sound is retrieved at once, while a soundstream maybe not be completely retrieved before the entire SWF-file has been parsed. But since the entire soundstream doesn't need to be present when playback starts, it is not necessary to wait.

When a sound is about to be played Gnash calls the sound handler, which then starts to play the sound and return. All the playing is done by threads (in both SDL and Gstreamer), so once started the audio and graphics are not sync'ed with each other, which means that we have to trust both the graphic backend and the audio backend to play at correct speed.

The current SDL sound backend has replaced the original sound handler, based on SDL_mixer, which by design had some limitations, making it difficult to implement needed features such as support for soundstreams. The SDL sound backend supports both event-sounds and soundstreams, using Gnash's internal ADPCM, and optionally MP3 support, using either FFMPEG or LIBMAD. When it receives sound data it is stored without being decoded, unless it is ADPCM, which is decoded in the parser. When playing, backend relies on a function callback for retrieving output sound, which is decoded and re-sampled if needed, and all sound output is mixed together. The current SDL sound backend was made since Gnash needed a working sound backend as soon as possible, and since the gstreamer backend at the time suffered from bugs and/or lack of features in gstreamer. The result was the most complete and best sound handler so far. The advantages of the SDL sound handler is speed, and ease of use, while its only real disadvantage is that it has to be compiled with MP3 support, which some Linux distributions will probably not like...

The Gstreamer backend, though not complete, supports both soundstreams and event-sounds. When receiving sound data it stores it compressed, unless if it's ADPCM event-sounds, which it decodes by the parser. When the playback starts, the backend setup a Gstreamer bin containing a decoder (and other things needed) and places it in a Gstreamer pipeline, which plays the audio. All the sound data is not passed at once, but in small chunks, and via callbacks the pipeline gets fed. The advantages of the Gstreamer backend is that it supports both kind of sounds, it avoids all the legal MP3-stuff, and it should be relatively easy to add VORBIS support. The drawbacks are that it has longer "reply delay" when starting the playback of a sound, and it suffers under some bugs in Gstreamer that are yet to be fixed.

It would probably be desirable to make more backends in the future, either because other and better backend systems are brought to our attention, or perhaps because an internal sound handling is better suited for embedded platform with limited software installed.

Gstreamer uses pipelines, bins and elements. Pipelines are the main bin, where all other bins or elements are places. Visually the audio pipeline in Gnash looks like this:

	 ___
	|Bin|_
	|___| \
	 ___   \ _____       ____________
	|Bin|___|Adder|_____|Audio output|
	|___|   |_____|     |____________|
	 ___   /
	|Bin|_/
	|___|

      

There is one bin for each sound which is being played. If a sound is played more the once at the same time, multiple bins will be made. The bins contains:

	|source|---|capsfilter|---|decoder|---|aconverter|---|aresampler|---|volume|

      

In the source element we place parts of the undecoded sound data, and when playing the pipeline will pull the data from the element. Via callbacks it is refilled if needed. In the capsfilter the data is labeled with the format of the data. The decoder (surprise!) decodes the data. The audioconverter converts the now raw sound data into a format accepted by the adder, all input to the adder must in the same format. The audio re-sampler re-samples the raw sound data into a sample accepted by the adder, all input to the adder must in the same sample rate. The volume element makes it possible to control the volume of each sound.

When a sound is done being played it emits a End-Of-Stream-signal (EOS), which is caught by an event-handler-callback, which then makes sure that the bin in question is removed from the pipeline. When a sound is told by Gnash to stop playback before it has ended playback, we do something (not yet finally implemented), which makes the bin emit an EOS, and the event-handler-callback will remove the sound from the pipeline. Unfortunately Gstreamer currently has a bug which causes the entire pipeline to stop playing when unlinking an element from the pipeline; so far no fix is known.

Gstreamer also contains a bug concerning linking multiple elements to the adder in rapid succession, which causes to adder to "die" and stop the playback.

Currently Gnash uses three other tools to help with testing. Two of these are free compilers for the Flash format. This lets us write simple test cases for Gnash to test specific features, and to see how the features operate.

The primary compiler used at this time is Ming. Since release 0.3, Ming includes a command-line compiler, makeswf. This allows test case development to be done entirely with free tools.

The other tools are optional. DejaGnu is used to run multiple test cases in an automated manner. DejaGnu is used by many other GNU projects like GCC and Samba.

ActionScript test cases are located under testsuite/actionscript.all/; these are organized in one file for the ActionScript class. Other Ming-generated tests are under testsuite/ming-misc.all/; these are typically used to test specific tag types. Full movies are located in testsuite/movies.all/ and sample movies are found in testsuite/samples/. Other directories in testsuite/ are (or shall be) used for other kind of tests.

Writing ActionScript tests is very simple. The makeswf compiler makes use of the C preprocessor, thus allowing the inclusion of definitions for macros and external files. We use these feature to provide common utilities for test units.

Each test unit sets an rcsid variable, includes the check.as file and performs some checks using the provided macros. Here is an example:

	  // This variable will be used by check.as
	  // to show testcase info as part of the test runs.
	  rcsid="Name and version of this testcase, usually the RCS id";
	  
	  #include "check.as"
	  
	  // Test object creation
	  check(new Object() instanceOf Object);
	  
	  // Test parseInt
	  check(isNaN(parseInt('none')));

	  // Test assignment
	  var a = 1;
	  check_equals(a, 1);
	  
	  // .. your tests here ...
	

The check(expr) macro will trace PASSED or FAILED together with the expression being evaluated and the line number of the check. This is the format expected by DejaGnu.

The check_equals(obtained, expected) macro uses equality operator == to check for equality. When possible, use of the check_equals() macro is preferred over check() because it shows what the actual result was in case of a failure.

Additionally, the check.as file provides a transparent way to send results to a TextField rather then using trace. This is very useful when you use a flash player without tracing support.

Test units are built by running make TestName-v#.swf. This will use TestName.as as source and the value of # as target version. Allowed target version are from 5 to 8 (inclusive).

Note that if you get a syntax error from the compiler, the line number will refer to the pre-processed file. This file is called TestName.as.pp or TestName-v#.swf.frame#.pp (depending on Ming version) and it's not thrown away by makeswf to make debugging easier.

Sometimes an expression is only supported by a specific SWF version, or it's evaluated differently by different SWF versions. For this purpose the framework provides an OUTPUT_VERSION macro that you can use to switch code based on output version. For example:

	  #if OUTPUT_VERSION >= 7
	  check(_root.getSWFVersion == OUTPUT_VERSION);
	  #endif
	  
	

Ming-based test cases are located in testsuite/misc-ming.all and contain a test generator and a test runner. The test generator (usually a C program) is used to produce the SWF file, while the test runner (a C++ program) will run it using a MovieTester class. Note that only the test generator needs Ming, not the test runner, so if Ming isn't installed on the user's host, the test cases can still be run as long as SWF has been distributed.

Producing tests using Ming has the advantage that you can easily see and modify the full source code for the SWF movie, and you can use some facilities provided by the Gnash testing framework to easily run tests.

For generic Ming API documentation, see http://www.libming.org.

	check(SWFMovie mo, const char* expr)

		Evaluate an ActionScript expression.

	xcheck(SWFMovie mo, const char* expr)

		Evaluate an ActionScript expression.
		A failure is expected
		(for cases where the call exposes a known bug).

	check_equals(SWFMovie mo, const char* obtained, const char* expected)

		Evaluate an ActionScript expression against an expected output.

	xcheck_equals(SWFMovie mo, const char* obtained, const char* expected)

		Evaluate an ActionScript expression against an expected output.
		A failure is expected (for cases where the call exposes a known bug).

	print_tests_summary(SWFMovie mo)

                This will print a summary of tests run, and should be
		called as the last step in your SWF generator.

	

If you want/need to use a different compiler for your test cases (there's plenty of open source tools for generating SWF out there), you can still make use of a loadable SWF utility provided as part of the Gnash testsuite to let your test consistent with the rest of the suite.

The loadable module is called Dejagnu.swf and is built during make check under testsuite/misc-ming.all. In order to use it you will need to load it into your SWF. We currently load it with an IMPORT tag for our ActionScript based test cases, but you can probably also use loadMovie or whatever works in the target SWF you're generating. Just make sure that the module is initialized before using it. You can check this by inspecting the dejagnu_module_initialized variable, which will be set to 'true' when all initialization actions contained in the Dejagnu.swf file are executed.

Once the module is loaded you will be able to invoke the following functions, all registered against the _root sprite (effects of _lockroot untested):

	check(expression, [message]);

		Evaluate the expression.
		Trace result (PASSED: expression / FAILED: expression).
		If fails, *visually* trace the failure.
		If second argument is given, it will be used instead of
		'expression' for printing results.

	check_equals(obtained, expected)

		Evaluate an expression against an expected output.
		Trace result (PASSED: obtained == expected / FAILED: expected X, obtained Y)
		If fails, *visually* trace the failure.

	xcheck(expression, [message]);

		Evaluate the expression.
		Trace result (XPASSED: expression / XFAILED: expression).
		If fails, *visually* trace the failure.
		If second argument is given, it will be used instead of
		'expression' for printing results.

	xcheck_equals(obtained, expected)

		Evaluate an expression against an expected output.
		Trace result (XPASSED: obtained == expected / XFAILED: expected X, obtained Y)
		If fails, *visually* trace the failure.

	note(string)

		Print string, both as debugging and *visual* trace.

	totals()

                Print a summary of tests run, both as debugging and *visual* traces.

	

Visual traces are lines of text pushed to a textarea defined by the Dejagnu.swf module. The textarea is initially placed at 0, 50 and is 600x800 in size. You can resize/move the clip after loading it. Also, you can completely make the clip invisible if that bothers you. The important thing is the *debuggin* trace (call to the trace function). The latter will be used by the testing framework.

See section Writing Test Runners for information about writing a test runners for your self-contained tests.

Test runners are executables that run one or more tests, writing results in Dejagnu form to standard output.

The Dejagnu form uses a standard set of labels when printing test results. These are:

The following labels may also appear:

MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
        sh $(srcdir)/../generic-testrunner.sh $(top_builddir) MyTest.swf > $@
        chmod +x $@
	

MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
        sh $(srcdir)/../generic-testrunner.sh -r2 $(top_builddir) MyTest.swf > $@
        chmod +x $@
	

All extensions have the same requirements, namely setting up a few defined function callbacks, which the Gnash VM then uses to do the right thing. The initial two function callbacks are for handling the interface of the newly created object so that Gnash can find and use it.

The first function is commonly called attachInterface, and this sets the other function callbacks for all the methods this class supports. The method callbacks are attached to the parent class by using set_member() to set a C function pointer to the string value used in the Flash movie.

	// setup so DummyClass.func1() and DummyClass.func2() work from Flash.
	static void
	attachInterface(as_object *obj)
	{
            obj->set_member("func1", &ext_func1);
            obj->set_member("func2", &ext_func2);
	}
      

The second function is commonly called getInterface(), and this returns a smart pointer to the new object. Gnash uses smart pointers for all ActionScript class definitions. (and many other things)

	static as_object*
	getInterface()
	{
	    static boost::intrusive_ptr<as_object> o;
	    if (o == NULL) {
	        o = new as_object();
	    }
	    return o.get();
	}
      

This is the callback that gets executed when constructing a new object for the VM. In this example we'll assume the new ActionScript class is called DummyExt, and has two methods, func1 and func2.

	static void
	dummyext_ctor(const fn_call& fn)
	{
	    DummyExt *obj = new DummyExt();

	    attachInterface(obj);
	    fn.result->set_as_object(obj); // will keep alive
	}
      

Allocate the new object and return a smart pointer.

	std::auto_ptr<as_object>
	init_dummyext_instance()
	{
	    return std::auto_ptr<as_object>(new DummyExt());
	}
      

Initialize the extension. This is looked for by the extension handling code in each extension, and is executed when the extension is loaded. This is the main entry point into the extension. This function can be found because the prefix of dummyext, which also matches the file name of the extension. Gnash uses the name of the extension file itself when looking for the init function.

        extern "C" {
	    void
	    dummyext_class_init(as_object &obj)
	    {
	        static boost::intrusive_ptr<builtin_function> cl;
	        if (cl == NULL) {
	            cl = new builtin_function(&dummyext_ctor, getInterface());
	            attachInterface(cl.get());
	        }
	
	        VM& vm = VM::get();
		std::string name = "DummyExt";
		if ( vm.getSWFVersion() < 7 ) {
	            boost::to_lower(name, vm.getLocale());
		}
		obj.init_member(name, cl.get());
	    }
        } // end of extern C
      

The callbacks are all C functions. Like all the other code that implements ActionScript, parameters to the function are passed in using the fn_call data structure. The return code, if any, is also returned using this data structure. this_ptr is the object that the method is a member of.

	// Creates a new button with the label as the text.
	void func1(const fn_call& fn)
	{
	    DummyExt *ptr = dynamic_cast<DummyExt *>(fn.this_ptr);
	    assert(ptr);
	
	    if (fn.nargs > 0) {
	        const char *label = fn.arg(0).to_string();
		bool ret = ptr->dummy_text_label(label);
		fn.result->set_bool(ret);
	    }
	}
      

The GTK ActionScript class follows the same API as Gtk2, even down to the same arguments to the same function names. This means you're actually programming GTK,you're just using ActionScript instead of python, perl, or C. This extension makes it possible to write Flash movies that use the Gtk2 widgets for user interface components.

Flash movies are traditionally forbidden from accessing the filesystem, but this may be necessary for some embedded applications. Especially in the case of a user console, currently there is no way to get input into a Flash movie but through a TextField.

The MySQL ActionScript class follows the same API as MySQL, even down to the same arguments to the same function names. This enables a Flash movie to have direct access to a MySQL database. Traditionally Flash movies have had no datatbase support, they either hsad to use arrays, or use XML to communicate to an application specific external database daemon.

The AMF format is used in the LocalConnection, SharedObject, NetConnection, and NetStream ActionScript classes. This is a means of binary data interchange between Flash movies, or between a Flash player and a Flash server.

Like the RTMP messages, an AMF packet header can be of a variable size. The size is either the same as the initial header of the RTMP message, or a 1 byte header, which is commonly used for streaming audio or video data.

The body of an AMF packet may look something like this example. The spaces have been added for clarity.

      02  0007 636f6e6e656374