← Back to branch summary

~ubuntu-branches/ubuntu/karmic/moon/karmic

« back to all changes in this revision

Viewing changes to cairo/HACKING

  • Committer: Bazaar Package Importer
  • Author(s): Jo Shields
  • Date: 2009-02-14 12:01:08 UTC
  • Revision ID: james.westby@ubuntu.com-20090214120108-06539vb25vhbd8bn
Tags: upstream-1.0
Import upstream version 1.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
cairo/HACKING
 
1
Hacking Cairo
 
2
=============
 
3
 
 
4
This is a high-level guide to how the cairo distribution is organized
 
5
and how to get started hacking on it.  Make sure you read through the
 
6
file README before continuing.
 
7
 
 
8
 
 
9
Coding Style
 
10
------------
 
11
 
 
12
The easiest way to write code in the cairo style is to follow code close
 
13
to the place you are hacking, but if you want a written down set of
 
14
rules, see file CODING_STYLE.
 
15
 
 
16
Files for backends that depend on languages other than C (C++ or
 
17
Objective C for example) may use features specific to those languages.
 
18
For example, "//" comments are allowed, though discouraged, in those files.
 
19
 
 
20
 
 
21
Contact
 
22
-------
 
23
 
 
24
Various ways to get in touch with other cairo developers and maintainers
 
25
have been enumerated at:
 
26
 
 
27
        http://cairographics.org/contact/
 
28
 
 
29
Most of that information is also reflected in the following sections.
 
30
 
 
31
 
 
32
Mailing Lists
 
33
-------------
 
34
 
 
35
There are various mailing lists that are useful when developing cairo
 
36
code.  A complete list is always available at:
 
37
 
 
38
        http://cairographics.org/lists/
 
39
 
 
40
It is recommended that cairo developers subscribe to all those lists.
 
41
The cairo list by itself generates much more traffic than the others
 
42
combined, so developers and contributors should not be intimidated by
 
43
the -commit and -bugs lists.
 
44
 
 
45
 
 
46
Bug Tracking System
 
47
-------------------
 
48
 
 
49
We use a standard bugzilla bug tracking system available at:
 
50
 
 
51
        http://bugs.freedesktop.org/
 
52
 
 
53
See file named BUGS for detailed information on reporting bugs.  In short,
 
54
for straight bug reports, it's best to report them there such that they
 
55
are not lost or forgotten.  For discussion of new features or
 
56
complicated issues, use the mailing list.
 
57
 
 
58
 
 
59
IRC
 
60
---
 
61
 
 
62
It's a great idea to hang around the cairo IRC channel if you have any
 
63
interest in cairo.  We use the #cairo channel on irc.freenode.net.
 
64
 
 
65
Make sure you introduce yourself if your nick is not easy to match to
 
66
the name you use on the mailing list.
 
67
 
 
68
 
 
69
Version Control System
 
70
----------------------
 
71
 
 
72
We use /git/ for version control.  See:
 
73
 
 
74
        http://cairographics.org/download/
 
75
 
 
76
TODO:
 
77
Add links to some git tutorials or better, right a few paragraphs
 
78
about how to use git to efficiently hack on cairo.
 
79
 
 
80
 
 
81
Build System
 
82
------------
 
83
 
 
84
We use the autotools build system with cairo, but with various
 
85
customizations and advanced features.  Reading configure.in is your
 
86
best bet to understanding it, or just ask on IRC.
 
87
 
 
88
To bootstrap the build system run ./autogen.sh.  After that the
 
89
regular "./configure; make; make install" sequence can be used.
 
90
See file named INSTALL for more details.
 
91
 
 
92
There is limited support for a win32 build system.
 
93
See README.win32 and Makefile.win32 files in various directories.
 
94
 
 
95
 
 
96
ChangeLog
 
97
---------
 
98
 
 
99
We generate ChangeLog files automatically from the git commit log.
 
100
No manual ChangeLog writing is necessary.
 
101
 
 
102
 
 
103
Copyrights and Licensing
 
104
------------------------
 
105
 
 
106
The cairo library is dual-licensed under LGPL and MPL.  See file named
 
107
COPYING for details.  The test suites are more liberal.  For example,
 
108
GPL code is allowed in the test suites, though it's always better to
 
109
keep things simple.
 
110
 
 
111
When writing new code, update the file headers to add your (or your
 
112
employers) copyright line and contributor line.  If adding new files
 
113
or splitting a file, copy the file header from other files.
 
114
 
 
115
 
 
116
Source Code
 
117
-----------
 
118
 
 
119
The library source code and headers live in the src/ directory.
 
120
See src/README for more information.
 
121
 
 
122
 
 
123
Regression Test Suite
 
124
---------------------
 
125
 
 
126
Cairo has a fairly extensive regression-testing suite.  Indeed, without
 
127
these tests it would be impossible to make a cairo release without
 
128
introducing tens of regressions.  We still manage to introduce
 
129
regressions with each release even with the hundreds of tests we already
 
130
have.
 
131
 
 
132
The regression test suite is located under the test/ directory.
 
133
See test/README for more information.
 
134
 
 
135
 
 
136
Performance Test Suite
 
137
----------------------
 
138
 
 
139
There is a small performance-testing suite for cairo.
 
140
 
 
141
The performance test suite is located under the perf/ directory.
 
142
See perf/README for more information.
 
143
 
 
144
 
 
145
Boilerplate
 
146
-----------
 
147
 
 
148
The cairo-boilerplate is a small private library used by the regression
 
149
and performance test suites.  It includes the boilerplace code needed
 
150
to initialize various backends for the test suites, as well as allow
 
151
tweaking some of the internal workings of the backends for more testing.
 
152
 
 
153
The boilerplate code is localted under the boilerplate/ directory.
 
154
See boilerplate/README for more information.
 
155
 
 
156
 
 
157
Documentation
 
158
-------------
 
159
 
 
160
Cairo uses the gtk-doc system for reference API documentation.
 
161
 
 
162
The reference documentation is located under doc/public.
 
163
See doc/public/README for more information.
 
164
 
 
165
For more documentation including frequently asked questions, tutorials,
 
166
samples, roadmap, todo list, etc visit:
 
167
 
 
168
        http://cairographics.org/documentation/
 
169
 
 
170
Some of those should gradually be moved to doc/.
 
171
 
 
172
 
 
173
Utilities
 
174
---------
 
175
 
 
176
There are a few useful utilities we have developed that are either
 
177
useful when writing code using cairo, or writing cairo, or useful in
 
178
general.  These tools can be found under the util/ directory.
 
179
See util/README for more information.
 
180
 
 
181
 
 
182
Releasing
 
183
---------
 
184
 
 
185
Now you are a cairo maintainer, so what?  See file named RELEASING.
 
186