README.md 4.49 KB
Newer Older
1 2 3
Clutter
=======

4
What is Clutter?
5 6 7 8 9 10 11 12 13 14
----------------

Clutter is an open source software library for creating fast, compelling,
portable, and dynamic graphical user interfaces.

Requirements
------------

Clutter currently requires:

15 16 17 18 19 20
  * [GLib](https://gitlab.gnome.org/GNOME/glib)
  * [JSON-GLib](https://gitlab.gnome.org/GNOME/json-glib)
  * [Atk](https://gitlab.gnome.org/GNOME/atk)
  * [Cairo](http://cairographics.org)
  * [Pango](https://gitlab.gnome.org/GNOME/pango)
  * [Cogl](https://gitlab.gnome.org/GNOME/cogl)
21 22 23

On X11, Clutter depends on the following extensions:

24 25 26 27 28
  * XComposite
  * XDamage
  * XExt
  * XInput 2.x
  * XKB
29 30 31

If you are building the API reference you will also need:

32
  * [GTK-Doc](https://gitlab.gnome.org/GNOME/gtk-doc)
33 34 35

If you are building the additional documentation you will also need:

36 37
  * xsltproc
  * jw (optional, for generating PDFs)
38 39 40

If you are building the Introspection data you will also need:

41
  * [GObject-Introspection](https://gitlab.gnome.org/GNOME/gobject-introspection)
42 43 44 45 46 47

Resources
---------

The official Clutter website is:

48
  - https://www.clutter-project.org/
49 50 51

The API references for the latest stable release are available at:

52
  - https://developer.gnome.org/clutter/stable/
53 54 55

The Clutter Cookbook is available at:

56
  - https://developer.gnome.org/clutter-cookbook/
57 58 59

New releases of Clutter are available at:

60
  - https://download.gnome.org/sources/clutter/
61 62 63 64

To subscribe to the Clutter mailing lists and read the archives, use the
Mailman web interface available at:

65
  - https://mail.gnome.org/mailman/listinfo/clutter-list
66

67
New bugs should be filed on GitLab:
68

69
  - https://gitlab.gnome.org/GNOME/clutter/issues/new
70 71 72 73 74 75 76 77 78 79 80

Clutter is licensed under the terms of the GNU Lesser General Public
License, version 2.1 or (at your option) later: see the `COPYING` file
for more information.

Building and Installation
-------------------------

To build Clutter from a release tarball, the usual autotool triad should
be followed:

81 82 83 84 85
```sh
  $ ./configure
  $ make
  # make install
```
86

87
To build Clutter from a Git clone, run the `autogen.sh` script instead
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
of the configure one. The `autogen.sh` script will run the configure script
for you, unless the `NOCONFIGURE` environment variable is set to a non-empty
value.

See also the [BuildingClutter][building-clutter] page on the wiki.

Versioning
----------

Clutter uses the common "Linux kernel" versioning system, where
even-numbered minor versions are stable and odd-numbered minor
versions are development snapshots.

Different major versions break both API and ABI but are parallel
installable. The same major version with differing minor version is
expected to be ABI compatible with other minor versions; differing
micro versions are meant just for bug fixing. On odd minor versions
the newly added API might still change.

The micro version indicates the origin of the release: even micro
numbers are only used for released archives; odd micro numbers are
only used on the Git repository.

Contributing
------------

114 115 116 117
If you want to hack on and improve Clutter check the
[HACKING](./docs/HACKING) file for general implementation guidelines, and
the [HACKING.backends](./docs/HACKING.backends) for backend-specific
implementation issues.
118

119 120 121 122
The [CODING STYLE](./docs/CODING_STYLE) file contains the rules for writing
code conformant to the style guidelines used throughout Clutter. Remember:
the coding style is mandatory; patches not conforming to it will be rejected
by default.
123 124 125

The usual workflow for contributions should be:

126 127 128 129 130 131
  1. Fork the repository
  2. Create a branch (`git checkout -b my_work`)
  3. Commit your changes (`git commit -am "Added my awesome feature"`)
  4. Push to the branch (`git push origin my_work`)
  5. Open a new merge request
  6. Sit back, relax and wait for feedback and eventual merge
132 133 134 135

Bugs
----

136
Bugs should be reported here:
137

138
  - https://gitlab.gnome.org/GNOME/clutter/issues/new 
139 140 141

In the report you should include:

142 143 144 145 146 147
  * what system you're running Clutter on;
  * which version of Clutter you are using;
  * which version of GLib and OpenGL (or OpenGL ES) you are using;
  * which video card and which drivers you are using, including output of
    glxinfo and xdpyinfo (if applicable);
  * how to reproduce the bug.
148 149 150 151 152 153 154 155

If you cannot reproduce the bug with one of the tests that come with Clutter
source code, you should include a small test case displaying the bad
behaviour.

If the bug exposes a crash, the exact text printed out and a stack trace
obtained using gdb are greatly appreciated.

156
[building-clutter]: https://wiki.gnome.org/Projects/Clutter/Building