mutter/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>Turns on debugging. Possible values are: yes -  all
                  glib asserts, checks and runtime clutter verbose messages;
                 minimum - just glib cast checks and runtime clutter verbose
                 messagaes; no - no glib asserts or checks and no runtime
                 clutter verbose messages; default=yes.
                 </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]</term>
                <listitem>
                  <para>Select the Clutter backend; default=glx.
                  </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>For developing an application with Clutter, the recommended
          way of installing it using the <ulink href="http://www.macports.org/">MacPorts</ulink>
          project, by simply invoking:</para>

          <informalexample><programlisting>
            $ sudo port install clutter
          </programlisting></informalexample>

          <para>on a terminal, after installing and updating MacPorts.</para>

          <para>For developing Clutter itself, the recommended way of building
          it OSX is to use <ulink href="http://live.gnome.org/Jhbuild">Jhbuild</ulink>,
          following the documentation for building the GTK+ stack as shown
          <ulink href="http://developer.imendio.com/projects/gtk-macosx/build-instructions">here</ulink>.</para>

          <para>
            Jhbuild depends on SVN, which can be installed on OSX by using
            the <ulink href="http://www.macports.org/">MacPorts</ulink>
            project.
          </para>

          <para>
            XCode should also be installed, either from the OSX installation
            disk or downloading it from the Apple website. It is recommended
            to also install the X11 development files, even though Clutter
            does not strictly depend on them.
          </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>

      </section>

    </section>

  </partintro>
</part>