README.md

   1 Clutter
   2 =======
   3
   4 What is Clutter?
   5 ----------------
   6
   7 Clutter is an open source software library for creating fast, compelling,
   8 portable, and dynamic graphical user interfaces.
   9
  10 Requirements
  11 ------------
  12
  13 Clutter currently requires:
  14
  15 * [GLib](http://git.gnome.org/browse/glib)
  16 * [JSON-GLib](http://git.gnome.org/browse/json-glib)
  17 * [Atk](http://git.gnome.org/browse/atk)
  18 * [Cairo](http://cairographics.org)
  19 * [Pango](http://git.gnome.org/browse/pango)
  20 * [OpenGL ≥ 1.3 (or 1.2 + multitexturing), or OpenGL ES 2.0 (or 1.1)](http://khronos.org)
  21 * GLX, AGL, WGL or an EGL implementation
  22
  23 Clutter also has optional dependencies:
  24
  25 * [GDK-Pixbuf](http://git.gnome.org/browse/gdk-pixbuf)
  26
  27 On X11, Clutter depends on the following extensions:
  28
  29 * XComposite
  30 * XDamage
  31 * XExt
  32 * XFixes
  33 * XInput (1.x or 2.x)
  34 * XKB
  35
  36 If you are building the API reference you will also need:
  37
  38 * [GTK-Doc](http://git.gnome.org/browse/gtk-doc)
  39
  40 If you are building the additional documentation you will also need:
  41
  42 * xsltproc
  43 * jw (optional, for generating PDFs)
  44
  45 If you are building the Introspection data you will also need:
  46
  47 * [GObject-Introspection](http://git.gnome.org/browse/gobject-introspection)
  48
  49 If you want support for profiling Clutter you will also need:
  50
  51 * [UProf](git://github.com/rib/UProf.git)
  52
  53 Resources
  54 ---------
  55
  56 The official Clutter website is:
  57
  58         http://www.clutter-project.org/
  59
  60 The API references for the latest stable release are available at:
  61
  62         http://docs.clutter-project.org/docs/clutter/stable/
  63         http://docs.clutter-project.org/docs/cogl/stable/
  64         http://docs.clutter-project.org/docs/cally/stable/
  65
  66 The Clutter Cookbook is available at:
  67
  68         http://docs.clutter-project.org/docs/clutter-cookbook/
  69
  70 New releases of Clutter are available at:
  71
  72         http://source.clutter-project.org/sources/clutter/
  73
  74 The Clutter blog is available at:
  75
  76         http://www.clutter-project.org/blog/
  77
  78 To subscribe to the Clutter mailing lists and read the archives, use the
  79 Mailman web interface available at:
  80
  81         http://lists.clutter-project.org/
  82
  83 New bug page on Bugzilla:
  84
  85         http://bugzilla.clutter-project.org/enter_bug.cgi?product=clutter
  86         http://bugzilla.clutter-project.org/enter_bug.cgi?product=cogl
  87
  88 Clutter is licensed under the terms of the GNU Lesser General Public
  89 License, version 2.1 or (at your option) later: see the `COPYING` file
  90 for more information.
  91
  92 Building and Installation
  93 -------------------------
  94
  95 To build Clutter from a release tarball, the usual autotool triad should
  96 be followed:
  97
  98 1. ./configure
  99 2. make
 100 3. make install
 101
 102 To build Clutter from a Git clone, run the autogen.sh script instead
 103 of the configure one. The `autogen.sh` script will run the configure script
 104 for you, unless the `NOCONFIGURE` environment variable is set to a non-empty
 105 value.
 106
 107 See also the [BuildingClutter][building-clutter] page on the wiki.
 108
 109 Versioning
 110 ----------
 111
 112 Clutter uses the common "Linux kernel" versioning system, where
 113 even-numbered minor versions are stable and odd-numbered minor
 114 versions are development snapshots.
 115
 116 Different major versions break both API and ABI but are parallel
 117 installable. The same major version with differing minor version is
 118 expected to be ABI compatible with other minor versions; differing
 119 micro versions are meant just for bug fixing. On odd minor versions
 120 the newly added API might still change.
 121
 122 The micro version indicates the origin of the release: even micro
 123 numbers are only used for released archives; odd micro numbers are
 124 only used on the Git repository.
 125
 126 Contributing
 127 ------------
 128
 129 If you want to hack on and improve Clutter check the `HACKING` file for
 130 general implementation guidelines, and the `HACKING.backends` for
 131 backend-specific implementation issues.
 132
 133 The `CODING_STYLE` file contains the rules for writing code conformant to
 134 the style guidelines used throughout Clutter. Remember: the coding style
 135 is mandatory; patches not conforming to it will be rejected by default.
 136
 137 The usual workflow for contributions should be:
 138
 139 1. Fork the repository
 140 2. Create a branch (`git checkout -b my_work`)
 141 3. Commit your changes (`git commit -am "Added my awesome feature"`)
 142 4. Push to the branch (`git push origin my_work`)
 143 5. Create an [Bug][1] with a link to your branch
 144 6. Sit back, relax and wait for feedback and eventual merge
 145
 146 Bugs
 147 ----
 148
 149 Bugs should be reported to the Clutter Bugzilla at:
 150
 151         http://bugzilla.clutter-project.org/enter_bug.cgi?product=clutter
 152         http://bugzilla.clutter-project.org/enter_bug.cgi?product=cogl
 153
 154 You will need a Bugzilla account.
 155
 156 In the report you should include:
 157
 158 * what system you're running Clutter on;
 159 * which version of Clutter you are using;
 160 * which version of GLib and OpenGL (or OpenGL ES) you are using;
 161 * which video card and which drivers you are using, including output of
 162   glxinfo and xdpyinfo (if applicable);
 163 * how to reproduce the bug.
 164
 165 If you cannot reproduce the bug with one of the tests that come with Clutter
 166 source code, you should include a small test case displaying the bad
 167 behaviour.
 168
 169 If the bug exposes a crash, the exact text printed out and a stack trace
 170 obtained using gdb are greatly appreciated.
 171
 172
 173
 174 [building-clutter]: http://wiki.clutter-project.org/wiki/BuildingClutter
 175 [1]: http://bugzilla.gnome.org/enter_bug.cgi?product=clutter