summaryrefslogtreecommitdiff
path: root/HACKING
diff options
context:
space:
mode:
authorBehdad Esfahbod <behdad@behdad.org>2008-09-02 20:20:49 -0400
committerBehdad Esfahbod <behdad@behdad.org>2008-09-02 20:24:08 -0400
commit59262577708ddb656851624377efb2a671fa8ca3 (patch)
tree2c75bd94e2cfe3efb333b0b1509c0540181af100 /HACKING
parent5cb3e66305b25a3380f2ca5829ac81e4a27e76d0 (diff)
Revamp the build system.
Quick summary of changes: - Move list of cairo source files out of src/Makefile.am and into src/Sources.mk, - Generate files src/Config.mk and src/Config.mk.win32 that choose the right set of source files and headers based on configured backends and features. This drastically simplifies building using other build systems. The src/Makefile.win32 file needs to be updated to reflect these changes. - Add README files to various directories, - Add toplevel HACKING file.
Diffstat (limited to 'HACKING')
-rw-r--r--HACKING165
1 files changed, 165 insertions, 0 deletions
diff --git a/HACKING b/HACKING
new file mode 100644
index 000000000..a69c45083
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,165 @@
+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/
+
+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, right 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.
+
+There is limited support for a win32 build system.
+See src/Makefile.win32.
+
+
+ChangeLog
+---------
+
+We generate ChangeLog files automatically from the git commit log.
+No manual ChangeLog writing is necessary.
+
+
+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.
+