mutter-performance-source/doc/reference/clutter/building-clutter.xml

<part id="building-clutter">
  <partinfo>
    <author>
      <firstname>Emmanuele</firstname>
      <surname>Bassi</surname>
      <affiliation>
        <address>
          <email>ebassi@openedhand.com</email>
        </address>
      </affiliation>
    </author>
  </partinfo>

  <title>Building Clutter</title>

  <partintro>

    <section id='dependencies'>
      <title>Clutter Dependencies</title>

      <variablelist>
        <varlistentry>
          <term>GLib</term>
          <listitem>
            <para>A general-purpose utility library, not specific to
            graphical user interfaces. GLib provides many useful data
            types, macros, type conversions, string utilities, file
            utilities, a main loop abstraction, and so on.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>GObject</term>
          <listitem>
            <para>The GLib Object System provides the required
            implementations of a flexible, extensible and intentionally
            easy to map (into other languages) object-oriented framework
            for C.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Pango</term>
          <listitem>
            <para>Pango is a library for laying out and rendering
            text, with an emphasis on internationalization.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Backend Windowing System Library</term>
          <listitem>
            <para>GLX, EGL (1.1), SDL, Cocoa (OS X) and WGL (Windows)</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Graphics Rendering </term>
          <listitem>
            <para>Open GL (1.4+) or Open GL ES (1.1 or 2.0) </para>
          </listitem>
        </varlistentry>
      </variablelist>

    </section>

    <section id='building-instructions'>
      <title>Platform-specific instructions</title>

      <section id='building-linux'>
        <title>Linux</title>

        <para>If you are using Debian or Ubuntu, you can install pre-compiled
        binary packages the normal Debian way following the instructions at
        <ulink type="http" url="http://debian.o-hand.com/">
        http://debian.o-hand.com/</ulink>.
        </para>

        <para>To build Clutter clutter from sources, get the latest source
        archives from <ulink type="http"
        url="http://www.clutter-project.org/sources/">
        http://www.clutter-project.org/sources/</ulink>. Once you have extracted
        the sources from the archive execute the following commands in the
        top-level directory:
        </para>

        <literallayout>
    $ ./configure
    $ make
    # make install
        </literallayout>

        <para>You can configure the build with number of additional arguments
        passed to the configure script, the full list of which can be obtained
        by running ./configure --help. The following arguments are specific to
        Clutter:

            <variablelist>
              <varlistentry>
                <term>--enable-debug=[no/minimum/yes]</term>
                <listitem>
                  <para>Controls the Clutter debugging level. Possible values
                  are: yes (all GLib asserts, checks and runtime debug
                  messages); minimum - just GLib cast checks and runtime
                  debug messages; no (no GLib asserts or checks and no
                  runtime debug messages). The default is yes for development
                  cycles, and minimum for stable releases. You should not use
                  no, unless the only performance critical paths are the
                  GLib type system checks.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>--enable-cogl-debug=[no/minimum/yes]</term>
                <listitem>
                  <para>Controls the COGL debugging level, similarly to
                  --enable-debug.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>--enable-maintainer-flags=[no/yes]</term>
                <listitem>
                  <para>Use strict compiler flags; default=no.
                  </para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>--enable-gtk-doc</term>
                <listitem>
                  <para>Use gtk-doc to build documentation; default=no.
                  </para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>--enable-manual=[no/yes]</term>
                <listitem>
                  <para>Build application developers manual; requires jw and
                  xmlto binaries; default=no.
                  </para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>--with-flavour=[glx/eglx/eglnative/sdl/win32/osx/fruity]</term>
                <listitem>
                  <para>Select the Clutter backend; default=glx.
                  </para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>--with-imagebackend=[gdk-pixbuf/quartz/internal]</term>
                <listitem>
                  <para>Select the image loading backend; default is
                  set to gdk-pixbuf on Linux and Windows, and to quartz
                  on OS X. The internal image loading backend should only
                  be used when porting to a new platform or for testing
                  purposes, and its stability or functionality are not
                  guaranteed.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>--with-gles=[1.1/2.0]</term>
                <listitem>
                  <para>Select the version of GLES to support in COGL;
                  default is 1.1.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>--with-json=[internal/check]</term>
                <listitem>
                  <para>Select whether to use the internal copy of
                  JSON-GLib to parse the ClutterScript UI definition
                  files, or to check for the system installed library;
                  default is internal.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>--enable-xinput=[no/yes]</term>
                <listitem>
                  <para>Whether to enable XInput 1 support; default is
                  no.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>--enable-introspection=[no/auto/yes]</term>
                <listitem>
                  <para>Whether to generate GObject Introspection data
                  at build time; default is auto.</para>
                </listitem>
              </varlistentry>

            </variablelist>

        </para>

      </section>

      <section id='building-windows'>
        <title>Windows</title>
          <para>
            The recommended way of building Clutter for Windows is using the
            <ulink type="http" url="http://www.mingw.org/">mingw</ulink> tool
            chain. One option is to cross-compile Clutter under Linux -- you
            can use the script found in the <filename>build/mingw/</filename>
            directory to simplify the process (the script takes care of setting
            up the necessary dependencies).
          </para>

          <para>
            If you wish to build Clutter using mingw direcly under Windows, you
            can do so the normal *nix way (described above) using the mingw
            POSIX shell. Should you prefer to use Microsoft Visual Studio, a
            project file for MSVC 2005 is located in the
            <filename>build/msvc_2k5/</filename> directory. In either case, you
            will need to first install the required dependencies.
            </para>
            <para>
            There are currently two backends that are supported on
            Windows. One uses the Win32 and WGL APIs directly and the
            other is built on top of SDL. You must choose one of the
            backends when running the configure script using the
            following argument:
            <variablelist>
              <varlistentry>
                <term>--with-flavour=[win32/sdl]</term>
                <listitem>
                  <para>Select the Clutter backend; default=glx.
                  </para>
                </listitem>
              </varlistentry>
            </variablelist>
            </para>
      </section>

      <section id='building-osx'>
          <title>OSX</title>
	  <para>Currently the only way to install Clutter for developing
	  applications, or hacking on Clutter itself, is to build it yourself.
	  The recommended route is to install the dependencies with
	  the <ulink href="http://www.macports.org/">MacPorts</ulink>
          project, by simply invoking:</para>

          <informalexample><programlisting>
            $ sudo port install pango libpixman-devel cairo-devel
          </programlisting></informalexample>

          <para>on a terminal, after installing and updating MacPorts.
	  This should give you all of the required dependencies for building
	  Clutter 1.0.</para>

          <para>
            XCode should also be installed, either from the OSX installation
            disk or downloading it from the Apple website.
          </para>

          <para>
            The Clutter Quartz backend is built by passing the
            <literal>--with-flavour=osx</literal> command line argument
            to the configure script. If not passed, the GLX backend will
            be built. By default, the Quartz backend depends on CoreGraphics
            in order to load images into textures, but it can also depend
            on GDK-Pixbuf or an internal, highly experimental PNG and JPEG
            loader.
          </para>

          <para>
            GTK-Doc is not working on OSX, so API reference generation
            should also be disabled when building Clutter, by using
            the <literal>--disable-docs</literal> and
            <literal>--disable-gtk-doc</literal> command line argument
            to the configure script.
          </para>

	  <para>
	    GTK introspection and shave support are untested on OSX so it is
	    also recommended that you disable these with the
	    <literal>--disable-shave</literal> and
	    <literal>--disable-introspection</literal>.
	  </para>

	  <para>
	    If building on top of MacPorts, as recommended, the following
	    configure command should suffice:
	    <informalexample><programlisting>
	    ./configure --disable-gtk-doc --disable-docs --disable-shave
	    --with-flavour=osx --disable-introspection --prefix=/opt
	    </programlisting></informalexample>
      </section>

    </section>

  </partintro>
</part>