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