mutter/doc/reference/clutter/building-clutter.xml
Joshua Lock 58f1dfcf35 docs: Fix OS X docs to install Ports in correct order
The order in which the MacPorts are installed is important otherwise we open
the user up to a world of pain.
This patch also tweaks the OS X docs to follow the formatting of the rest of
the docs and to discuss the option of GtkDoc.

http://bugzilla.openedhand.com/show_bug.cgi?id=1865
2009-11-06 11:48:08 +00:00

307 lines
11 KiB
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>
Before you start you should install XCode either from the OSX
installation disk or by downloading it from the Apple website.
</para>
<para>
Note: These instructions have only been tested on OS X 10.6
(a.k.a Snow Leopard)
</para>
<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 libpixman-devel cairo-devel pango gtk-doc
</programlisting></informalexample>
<para>
on a terminal, after installing and updating MacPorts.
This should give you all of the required dependencies for building
Clutter.
</para>
<para>
It should be noted that building gtk-doc pulls in a lot of other
MacPorts dependencies and takes some considerable time. You can omit
this dependency so long as you disable documentation when you are
configuring the build with
<literal>--disable-gtk-doc --disable-docs</literal>
</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 introspection is untested on OSX (as there isn't a MacPorts
package) so it is recommended that you disable this with the
<literal>--disable-introspection</literal>.
</para>
<para>
If building on top of MacPorts, as recommended, the following
configure command should suffice:
</para>
<informalexample><programlisting>
./configure --with-flavour=osx --disable-introspection --prefix=/opt
</programlisting></informalexample>
</section>
</section>
</partintro>
</part>