| Hacking Cairo |
| ============= |
| |
| This is a high-level guide to how the cairo distribution is organized |
| and how to get started hacking on it. Make sure you read through the |
| file README before continuing. |
| |
| |
| Coding Style |
| ------------ |
| |
| The easiest way to write code in the cairo style is to follow code close |
| to the place you are hacking, but if you want a written down set of |
| rules, see file CODING_STYLE. |
| |
| Files for backends that depend on languages other than C (C++ or |
| Objective C for example) may use features specific to those languages. |
| For example, "//" comments are allowed, though discouraged, in those files. |
| |
| |
| Contact |
| ------- |
| |
| Various ways to get in touch with other cairo developers and maintainers |
| have been enumerated at: |
| |
| http://cairographics.org/contact/ |
| |
| Most of that information is also reflected in the following sections. |
| |
| |
| Mailing Lists |
| ------------- |
| |
| There are various mailing lists that are useful when developing cairo |
| code. A complete list is always available at: |
| |
| http://cairographics.org/lists/ |
| |
| It is recommended that cairo developers subscribe to all those lists. |
| The cairo list by itself generates much more traffic than the others |
| combined, so developers and contributors should not be intimidated by |
| the -commit and -bugs lists. |
| |
| |
| Bug Tracking System |
| ------------------- |
| |
| We use a standard bugzilla bug tracking system available at: |
| |
| http://bugs.freedesktop.org/ |
| |
| See file named BUGS for detailed information on reporting bugs. In short, |
| for straight bug reports, it's best to report them there such that they |
| are not lost or forgotten. For discussion of new features or |
| complicated issues, use the mailing list. |
| |
| |
| IRC |
| --- |
| |
| It's a great idea to hang around the cairo IRC channel if you have any |
| interest in cairo. We use the #cairo channel on irc.freenode.net. |
| |
| Make sure you introduce yourself if your nick is not easy to match to |
| the name you use on the mailing list. |
| |
| |
| Version Control System |
| ---------------------- |
| |
| We use /git/ for version control. See: |
| |
| http://cairographics.org/download/ |
| |
| TODO: |
| Add links to some git tutorials or better, write a few paragraphs |
| about how to use git to efficiently hack on cairo. |
| |
| |
| Build System |
| ------------ |
| |
| We use the autotools build system with cairo, but with various |
| customizations and advanced features. Reading configure.in is your |
| best bet to understanding it, or just ask on IRC. |
| |
| To bootstrap the build system run ./autogen.sh. After that the |
| regular "./configure; make; make install" sequence can be used. |
| See file named INSTALL for more details. |
| |
| There is limited support for a win32 build system. |
| See README.win32 and Makefile.win32 files in various directories. |
| |
| |
| ChangeLog |
| --------- |
| |
| We generate ChangeLog files automatically from the git commit log. |
| No manual ChangeLog writing is necessary. |
| |
| |
| Copyrights and Licensing |
| ------------------------ |
| |
| The cairo library is dual-licensed under LGPL and MPL. See file named |
| COPYING for details. The test suites are more liberal. For example, |
| GPL code is allowed in the test suites, though it's always better to |
| keep things simple. |
| |
| When writing new code, update the file headers to add your (or your |
| employers) copyright line and contributor line. If adding new files |
| or splitting a file, copy the file header from other files. |
| |
| |
| Source Code |
| ----------- |
| |
| The library source code and headers live in the src/ directory. |
| See src/README for more information. |
| |
| |
| Regression Test Suite |
| --------------------- |
| |
| Cairo has a fairly extensive regression-testing suite. Indeed, without |
| these tests it would be impossible to make a cairo release without |
| introducing tens of regressions. We still manage to introduce |
| regressions with each release even with the hundreds of tests we already |
| have. |
| |
| The regression test suite is located under the test/ directory. |
| See test/README for more information. |
| |
| |
| Performance Test Suite |
| ---------------------- |
| |
| There is a small performance-testing suite for cairo. |
| |
| The performance test suite is located under the perf/ directory. |
| See perf/README for more information. |
| |
| |
| Boilerplate |
| ----------- |
| |
| The cairo-boilerplate is a small private library used by the regression |
| and performance test suites. It includes the boilerplace code needed |
| to initialize various backends for the test suites, as well as allow |
| tweaking some of the internal workings of the backends for more testing. |
| |
| The boilerplate code is localted under the boilerplate/ directory. |
| See boilerplate/README for more information. |
| |
| |
| Documentation |
| ------------- |
| |
| Cairo uses the gtk-doc system for reference API documentation. |
| |
| The reference documentation is located under doc/public. |
| See doc/public/README for more information. |
| |
| For more documentation including frequently asked questions, tutorials, |
| samples, roadmap, todo list, etc visit: |
| |
| http://cairographics.org/documentation/ |
| |
| Some of those should gradually be moved to doc/. |
| |
| |
| Utilities |
| --------- |
| |
| There are a few useful utilities we have developed that are either |
| useful when writing code using cairo, or writing cairo, or useful in |
| general. These tools can be found under the util/ directory. |
| See util/README for more information. |
| |
| |
| Releasing |
| --------- |
| |
| Now you are a cairo maintainer, so what? See file named RELEASING. |
| |