README
1Cairo - Multi-platform 2D graphics library
2https://cairographics.org
3
4What is cairo
5=============
6Cairo is a 2D graphics library with support for multiple output
7devices. Currently supported output targets include the X Window
8System (via both Xlib and XCB), quartz, win32, and image buffers,
9as well as PDF, PostScript, and SVG file output. Experimental backends
10include OpenGL, BeOS, OS/2, and DirectFB.
11
12Cairo is designed to produce consistent output on all output media
13while taking advantage of display hardware acceleration when available
14(for example, through the X Render Extension).
15
16The cairo API provides operations similar to the drawing operators of
17PostScript and PDF. Operations in cairo include stroking and filling
18cubic Bézier splines, transforming and compositing translucent images,
19and antialiased text rendering. All drawing operations can be
20transformed by any affine transformation (scale, rotation, shear,
21etc.).
22
23Cairo has been designed to let you draw anything you want in a modern
242D graphical user interface. At the same time, the cairo API has been
25designed to be as fun and easy to learn as possible. If you're not
26having fun while programming with cairo, then we have failed
27somewhere---let us know and we'll try to fix it next time around.
28
29Cairo is free software and is available to be redistributed and/or
30modified under the terms of either the GNU Lesser General Public
31License (LGPL) version 2.1 or the Mozilla Public License (MPL) version
321.1.
33
34Where to get more information about cairo
35=========================================
36The primary source of information about cairo is:
37
38 https://cairographics.org/
39
40The latest versions of cairo can always be found at:
41
42 https://cairographics.org/download
43
44Documentation on using cairo and frequently-asked questions:
45
46 https://cairographics.org/documentation
47 https://cairographics.org/FAQ
48
49Mailing lists for contacting cairo users and developers:
50
51 https://cairographics.org/lists
52
53Roadmap and unscheduled things to do, (please feel free to help out):
54
55 https://cairographics.org/roadmap
56 https://cairographics.org/todo
57
58Dependencies
59============
60The set of libraries needed to compile cairo depends on which backends
61are enabled when cairo is configured. So look at the list below to
62determine which dependencies are needed for the backends of interest.
63
64For the surface backends, we have both "supported" and "experimental"
65backends. Further, the supported backends can be divided into the
66"standard" backends which can be easily built on any platform, and the
67"platform" backends which depend on some underlying platform-specific
68system, (such as the X Window System or some other window system).
69
70As an example, for a standard Linux build similar to what's shipped by
71your distro, (with image, png, pdf, PostScript, svg, and xlib surface
72backends, and the freetype font backend), the following sample commands
73will install necessary dependencies:
74
75 Debian (and similar):
76
77 apt-get build-dep cairo
78
79 Fedora (and similar):
80
81 yum install libpng-devel zlib-devel libXrender-devel fontconfig-devel
82
83Technically you probably don't need pixman from the distribution since
84if you're manually compiling Cairo you probably want an updated pixman
85as well. However, if you follow the default settings and install pixman
86to /usr/local, your Cairo build should properly use it in preference to
87the system pixman.
88
89
90Supported, "standard" surface backends
91------------------------------------
92 image backend (required)
93 ------------------------
94 pixman >= 0.30.0 https://cairographics.org/releases
95
96 png support (can be left out if desired, but many
97 ----------- applications expect it to be present)
98 libpng http://www.libpng.org/pub/png/libpng.html
99
100 pdf backend
101 -----------
102 zlib http://www.gzip.org/zlib
103
104 postscript backend
105 ------------------
106 zlib http://www.gzip.org/zlib
107
108 svg backend
109 -----------
110 [none]
111
112Supported, "platform" surface backends
113-----------------------------------
114 xlib backend
115 ------------
116 X11 https://freedesktop.org/Software/xlibs
117
118 xlib-xrender backend
119 --------------------
120 Xrender >= 0.6 https://freedesktop.org/Software/xlibs
121
122 quartz backend
123 --------------
124 MacOS X >= 10.4 with Xcode >= 2.5
125
126 win32 backend
127 -------------
128 Microsoft Windows 2000 or newer[*].
129
130 xcb backend
131 -----------
132 XCB https://xcb.freedesktop.org
133
134Font backends (required to have at least one)
135---------------------------------------------
136 freetype font backend
137 ---------------------
138 freetype >= 2.1.9 http://freetype.org
139 fontconfig http://fontconfig.org
140
141 quartz-font backend
142 -------------------
143 MacOS X >= 10.4 with Xcode >= 2.4
144
145 win32 font backend
146 ------------------
147 Microsoft Windows 2000 or newer[*].
148
149 [*] The Win32 backend should work on Windows 2000 and newer
150 (excluding Windows Me.) Most testing has been done on
151 Windows XP. While some portions of the code have been
152 adapted to work on older versions of Windows, considerable
153 work still needs to be done to get cairo running in those
154 environments.
155
156 Cairo can be compiled on Windows with either the gcc
157 toolchain (see http://www.mingw.org) or with Microsoft
158 Visual C++. If the gcc toolchain is used, the standard
159 build instructions using configure apply, (see INSTALL).
160 If Visual C++ is desired, GNU make is required and
161 Makefile.win32 can be used via 'make -f Makefile.win32'.
162 The compiler, include paths, and library paths must be set
163 up correctly in the environment.
164
165 MSVC versions earlier than 7.1 are known to miscompile
166 parts of cairo and pixman, and so should be avoided. MSVC
167 7.1 or later, including the free Microsoft Visual Studio
168 Express editions, produce correct code.
169
170Experimental surface backends
171-----------------------------
172 beos backend
173 ------------
174 No dependencies in itself other than an installed BeOS system, but cairo
175 requires a font backend. See the freetype dependency list.
176
177 os2 backend
178 -----------
179 Cairo should run on any recent version of OS/2 or eComStation, but it
180 requires a font backend. See the freetype dependency list. Ready to use
181 packages and developer dependencies are available at Netlabs:
182 ftp://ftp.netlabs.org/pub/cairo
183
184
185Compiling
186=========
187See the INSTALL document for build instructions.
188
189
190History
191=======
192Cairo was originally developed by Carl Worth <cworth@cworth.org> and
193Keith Packard <keithp@keithp.com>. Many thanks are due to Lyle Ramshaw
194without whose patient help our ignorance would be much more apparent.
195
196Since the original development, many more people have contributed to
197cairo. See the AUTHORS files for as complete a list as we've been able
198to compile so far.
199
README.win32
1Building Cairo on Windows
2=========================
3There are two primary ways to build Cairo on Windows. You can use a
4UNIX emulation based setup, such as Cygwin or MSYS, with the
5conventional configure script shipped with Cairo releases. In this
6configuration, you will build with GCC and (implicitly) libtool. In
7the Cygwin case you end up with a DLL that depends on Cygwin and
8should be used only from Cygwin applications. In the MSYS case you end
9up with a "normal" Win32 DLL that can be used either from GCC- or
10Microsoft Visual C++-compiled code. In theory, this technique is no
11different than the ordinary build process for the Cairo library. In
12practise there are lots of small details that can go wrong.
13
14The second way is to use a GNU-compatible make, but build using
15Microsoft's Visual C++ compiler to produce native libraries. This is
16the setup this README.win32 is written for. Also the DLL produced this
17way is usable either from GCC- or MSVC-compiled code.
18
19Tools required
20==============
21You will need GNU make, version 3.80 or later. Earlier versions or
22other modern make implementations may work, but are not guaranteed to.
23
24You will also need Microsoft Visual C++. Version 7 has been most
25heavily tested, but other versions are likely to work fine.
26
27Libraries required
28==================
29Cairo requires a compatible version of the pixman library. Full build
30instructions are beyond the scope of this document; however, using the
31same tools, it should be possible to build pixman simply by entering
32the pixman/src directory and typing:
33
34 make -f Makefile.win32 CFG=release
35
36Depending on your feature set, you may also need zlib and libpng.
37
38Building
39========
40There are a few files that you will need to edit. First, you must
41determine which features will be built. Edit
42build/Makefile.win32.features and set the features as desired. Note
43that most features have external dependencies; specifically,
44CAIRO_HAS_PNG_FUNCTIONS requires libpng to be present, and
45CAIRO_HAS_PS_SURFACE and CAIRO_HAS_PDF_SURFACE both require zlib.
46
47To ensure that the compiler can find all dependencies, you may need to
48edit build/Makefile.win32.common. In particular, ensure that
49PIXMAN_CFLAGS contains a -I parameter pointing to the location of
50your pixman header files and that PIXMAN_LIBS points to the actual
51location of your pixman-1.lib file. You may also need to edit the
52various occurrences of CAIRO_LIBS to point to other libraries
53correctly. Note also that if you wish to link statically with zlib,
54you should replace zdll.lib with zlib.lib.
55
56Finally, from the top Cairo directory, type:
57
58 make -f Makefile.win32 CFG=release
59
60If this command succeeds, you will end up with src/release/cairo.dll.
61To successfully use Cairo from your own programs, you will probably
62want to move this file to some central location. You will also
63probably want to copy the Cairo header files. These should be placed
64in a cairo subdirectory (for instance, c:/code/common/include/cairo).
65The exact set to copy depends on your features and is reported to you
66at the end of the build.
67