Introduction

Build environment

The build instructions below are based on the assumption that the build environment is a Fedora10 installation. 

A copy of the installation disks can be found here. http://fedoraproject.org/get-fedora

It is important that the GCC tools are installed when the Fedora installation is installed.

Cross-development

The clutter libraries  and test environment  are first built on a Fedora installation, and then the resultant executables and libraries can then be copied over to a MOBLIN2 platform.

Virtualisation

The steps below can be undertaken on a virtual machine, the only restriction being that not all virtual machines support video acceleration  

The tests

There are a number of tests that can be used to benchmark the clutter library. The benchmark performance is measured by how many Frames Per Second (FPS) are achieved.

Building the Clutter Libraries

Downloading the sources

The sources for the clutter library can be obtained by using the following command.

In a development directory of your choosing download the sources

   git clone git://git.clutter-project.org/clutter

   git clone git://git.clutter-project.org/clutter-box2d

Progress for each download should be reported similar the following:

$ git clone git://git.clutter-project.org/clutter

Initialized empty Git repository in /home/intel/dv/clutter/clutter/.git/
remote: Counting objects: 25225, done.
remote: Compressing objects: 100% (10261/10261), done.
remote: Total 25225 (delta 20575), reused 18319 (delta 14944)
Receiving objects: 100% (25225/25225), 6.99 MiB | 104 KiB/s, done.
Resolving deltas: 100% (20575/20575), done.

Building the Sources

Directory structure should look similar to this:

             <dev-dir>/clutter/
            <dev-dir>/clutter-box2d

In each of these sub directories build the libraries as follows:

Choosing which compiler

Building with GCC

For our installation, we'll use the environment variable  $PREFIX custom directory so as not to override any existing installation

     export PREFIX=/opt/custom/gcc
    ./autogen.sh --prefix=$PREFIX

Building with ICC

To build the library with the Intel compiler use the following commands

    export CC=icc
    export CXX=icc

   export PREFIX=/opt/custom/icc
  ./autogen.sh --prefix=$PREFIX

Continuing the build

When autogen has completed you should get a message similar to the display below 

  
                                  Clutter    0.9.7
                         ====================
                                  prefix:   /opt/custom/gcc
                                Flavour:   glx/gl
                                 XInput:   no
                          GL headers:   GL/gl.h
                    Image backend:   gdk-pixbuf
                       Target library:   libclutter-glx-0.9.la
               Clutter debug level:   yes
                 COGL debug level:   minimum
                      Compiler flags:   -Wall -Wshadow -Wcast-align -Wno-uninitialized -Wno-strict-aliasing -Wempty-body -Wformat-security -Winit-self
        Build API documentation:   no
  Build manual documentation:   no
         Build introspection data:   auto

Now build the source by calling make

The progress of the make will be reported, the last few lines looking similar to this:

   Making all in tools
     CC    disable-npots.o
     LINK  libdisable-npots-static.la
     LINK  libdisable-npots.la
   Making all in po

Installing the new library

To install the new library call:

make install

Note, depending on the permissions of the installation directory (set with the $PREFIX variable in the previous steps) you may need to do this as root.

Building the tests

The test directory has a number of tests. The README describes the tests as follows 

"The conform/ tests should be non-interactive unit-tests that verify a single feature is behaving as documented. See conform/ADDING_NEW_TESTS for more details.

 The micro-bench/ tests should be focused performance test, ideally testing a single metric. Please never forget that these tests are synthetic and if you are using them then you understand what metric is being tested. They probably don't reflect any real world application loads and the intention is that you use these tests once you have already determined the crux of your problem and need focused feedback that your changes are indeed improving matters. There is no exit status requirements for these tests, but they should give clear feedback as to their performance. If the frame rate is the feedback metric, then the test should forcibly enable FPS debugging.

 The interactive/ tests are any tests who's  status can not be determined without a user looking at some visual output, or providing some manual input etc. This covers most of the original Clutter tests. Ideally some of these tests will be migrated into the conformance/ directory so they can be used in automated nightly tests."

To build the tests, from the top level of the test directory do: 

    make

The build will report:

    Making all in data
    Making all in conform
    Making all in interactive
    Making all in micro-bench
    Making all in tools

Running the tests

Having built the tests, each test can be run from the command line.

Automatic running of  tests.

Many of the tests do not run to completion, but keep running,  The script in the appendix below gives an example of how the tests can be automatically called and killed after a predefined time.

Appendix 1 -  Script to drive test cases

#!/usr/bin/perl
# list of tests TODO: EDIT THESE TO YOUR REQUIREMENTS
@Tests=("test-actors", "test-behave", "test-clip","test-cogl-offscreen","test-cogl-primitives","test-cogl-tex-convert","test-cogl-tex-foreign","test-cogl-tex-getset","test-cogl-tex-polygontest","test-cogl-tex-tile","test-depth","test-layout","test-multistage","test-pixmap","test-project","test-random-text","test-rotate","test-scale","test-script","test-sharder","test-text","test-texture-quality","test-textures","test-threads","test-unproject","test-viewport");

#@Tests=("test-actors", "test-behave");
@Results=();

# for each test run it for 10 seconds
my $Timeout = 10;
## chdir interactive;
my $bStarted = 0;

foreach my $Test (@Tests)
{
    # print "executing $Test\n ";
    eval {
        local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
        alarm $Timeout;
        # system("./$Test --clutter-show-fps > res.$Test.txt");

        # mark end of prev test
        push @Results, "END" if $bStarted;
        push @Results, "TEST:$Test\n-----------------------\n";
        $bStarted = 1;
        open (RUN,"./$Test --clutter-show-fps &|");
        while(<RUN>)
        {
            push @Results, $_;
        }
        alarm 0;
    };
    if ($@)
    {
        die unless $@ eq "alarm\n"; # propagate unexpected errors
        # timed out
        system("killall -9 lt-test-interactive");
     }
}
# mark the end of the last test
push @Results, "END" if $bStarted;

# process the results
my $NumTests = 0;
my $Total = 0;
my $Max = 0;
my $Min = 9999;
my $TestName="";

print "\nName Min Max NumTests Average\n";
foreach my $Line (@Results)
{
    if($Line=~/^TEST:(.*)/)
    {
        # print "IN TEST $Line";
        $TestName= $1;
        chomp $TestName;
        $NumTests = 0;
        $Total = 0;
        $Max = 0;
        $Min = 9999;
    }

    if($Line=~/END/)
    {
        # print "IN END :$Line";
        $Average = 0;
        $Average = $Total/$NumTests if $NumTests > 0;
        print "$TestName $Min $Max $NumTests $Average\n";
    }

    if($Line=~/\*\*\* FPS: (.*) \*\*\*/)
    {
        # print "IN FPS: $Line";
        $NumTests++;
        $Total = $Total + $1;
        $Max = $1 if $1 > $Max;
        $Min = $1 if $1 < $Min;
    }
}

print "exiting ..\n";
 

 Appendix 2 - Essential notes on installing Fedora  

When installing Fedora you must install the Software Development tools.