From 59262577708ddb656851624377efb2a671fa8ca3 Mon Sep 17 00:00:00 2001 From: Behdad Esfahbod Date: Tue, 2 Sep 2008 20:20:49 -0400 Subject: 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. --- HACKING | 165 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 HACKING (limited to 'HACKING') 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. + -- cgit v1.2.1