summaryrefslogtreecommitdiffstats
path: root/gfx/cairo/cairo/INSTALL
blob: dfff8bebbaa4063497ab685c4f50668c706595a8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
Quick-start build instructions
------------------------------
1) Configure the package:

	./configure

2) Compile it:

	make

3) Install it:

	make install

This final step may require temporary root access (eg. with sudo) if
you don't have write permission to the directory in which cairo will
be installed.

NOTE: If you are working with source from git/cvs rather than from a tar
file, then you should use ./autogen.sh in place of ./configure
anywhere it is mentioned in these instructions.

More detailed build instructions
--------------------------------
1) Configure the package

   The first step in building cairo is to configure the package by
   running the configure script. [Note: if you don't have a configure
   script, skip down below to the Extremely detailed build
   instructions.]

   The configure script attempts to automatically detect as much as
   possible about your system. So, you should primarily just accept
   its defaults by running:

	./configure

   The configure script does accept a large number of options for
   fine-tuning its behavior. See "./configure --help" for a complete
   list. The most commonly used options are discussed here.

   --prefix=PREFIX

	This option specifies the directory under which the software
	should be installed. By default configure will choose a
	directory such as /usr/local. If you would like to install
	cairo to some other location, pass the director to configure
	with the --prefix option. For example:

		./configure --prefix=/opt/cairo

	would install cairo into the /opt/cairo directory. You could
	also choose a prefix directory within your home directory if
	you don't have write access to any system-wide directory.

	After installing into a custom prefix, you will need to set
	some environment variables to allow the software to be
	found. Assuming the /opt/cairo prefix and assuming you are
	using the bash shell, the following environment variables
	should be set:

		PKG_CONFIG_PATH=/opt/cairo/lib/pkgconfig
		LD_LIBRARY_PATH=/opt/cairo/lib
		export PKG_CONFIG_PATH LD_LIBRARY_PATH

	(NOTE: On Mac OS X, at least, use DYLD_LIBRARY_PATH in place
	       of LD_LIBRARY_PATH above.)

    --enable-quartz
    --enable-atsui
    --enable-xcb
    --enable-glitz
    --enable-beos
    --enable-os2
    --enable-directfb

	Some of cairo's backends are marked as experimental and will
	not be built by default. If you would like to build and
	experiment with these backends, you will need to pass one of
	the above options to the configure script. You may need to
	have certain libraries installed first as discussed in the
	dependencies section of the README file.

    --disable-xlib
    --disable-win32
    --disable-png
    --disable-freetype
    --disable-ps
    --disable-pdf
    --disable-svg

	Cairo's configure script detects the libraries needed to build
	each stable backend, and when it finds them, enables each
	backend. If you would like to override this detection and
	disable a backend, (even when it would be possible to build
	it), use one of the options above to disable the backend.

2) Compile the package:

   This step is very simple. Just:

	make

   The Makefiles included with cairo are designed to work on as many
   different systems as possible.

   When cairo is compiled, you can also run some automated tests of
   cairo with:

	make check

   NOTE: Some versions of X servers will cause the -xlib tests to
   report failures in make check even when cairo is working just
   fine. If you see failures in nothing but -xlib tests, please
   examine the corresponding -xlib-out.png images and compare them to
   the -ref.png reference images (the -xlib-diff.png images might also
   be useful). If the results seem "close enough" please do not report
   a bug against cairo as the "failures" you are seeing are just due
   to subtle variations in X server implementations.

3) Install the package:

   The final step is to install the package with:

	make install

   If you are installing to a system-wide location you may need to
   temporarily acquire root access in order to perform this
   operation. A good way to do this is to use the sudo program:

	sudo make install

Extremely detailed build instructions
-------------------------------------
So you want to build cairo but it didn't come with a configure
script. This is probably because you have checked out the latest
in-development code via git. If you need to be on the bleeding edge,
(for example, because you're wanting to develop some aspect of cairo
itself), then you're in the right place and should read on.

However, if you don't need such a bleeding-edge version of cairo, then
you might prefer to start by building the latest stable cairo release:

	http://cairographics.org/releases

or perhaps the latest (unstable) development snapshot:

	http://cairographics.org/snapshots

There you'll find nicely packaged tar files that include a configure
script so you can go back the the simpler instructions above.

But you're still reading, so you're someone that loves to
learn. Excellent! We hope you'll learn enough to make some excellent
contributions to cairo. Since you're not using a packaged tar file,
you're going to need some additional tools beyond just a C compiler in
order to compile cairo. Specifically, you need the following utilities:

	automake (1.8 or newer)
	autoconf
	libtool

Hopefully your platform of choice has packages readily available so
that you can easily install things with your system's package
management tool, (such as "apt-get install automake" on Debian or "yum
install automake" on Fedora, etc.). Note that Mac OS X ships with it's
own utility called libtool which is not what you want, (the one you do
want goes by the name of glibtool).

Once you have all of those packages installed, the next step is to run
the autogen.sh script. That can be as simple as:

	./autogen.sh

Or, if you're using Mac OS X, you'll have to let it know to use
glibtool by instead doing:

	LIBTOOLIZE=glibtoolize ./autogen.sh

But before you run that command, note that the autogen.sh script
accepts all the same arguments as the configure script, (and in fact,
will generate the configure script and run it with the arguments you
provide). So go back up to step (1) above and see what additional
arguments you might want to pass, (such as prefix). Then continue with
the instructions, simply using ./autogen.sh in place of ./configure.

Happy hacking!