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, write 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