INSTALL

   1 Quick-start build instructions
   2 ------------------------------
   3 1) Configure the package:
   4
   5         ./configure
   6
   7 2) Compile it:
   8
   9         make
  10
  11 3) Install it:
  12
  13         make install
  14
  15 This final step may require temporary root access (eg. with sudo) if
  16 you don't have write permission to the directory in which cairo will
  17 be installed.
  18
  19 NOTE: If you are working with source from git/cvs rather than from a tar
  20 file, then you should use ./autogen.sh in place of ./configure
  21 anywhere it is mentioned in these instructions.
  22
  23 More detailed build instructions
  24 --------------------------------
  25 1) Configure the package
  26
  27    The first step in building cairo is to configure the package by
  28    running the configure script. [Note: if you don't have a configure
  29    script, skip down below to the Extremely detailed build
  30    instructions.]
  31
  32    The configure script attempts to automatically detect as much as
  33    possible about your system. So, you should primarily just accept
  34    its defaults by running:
  35
  36         ./configure
  37
  38    The configure script does accept a large number of options for
  39    fine-tuning its behavior. See "./configure --help" for a complete
  40    list. The most commonly used options are discussed here.
  41
  42    --prefix=PREFIX
  43
  44         This option specifies the directory under which the software
  45         should be installed. By default configure will choose a
  46         directory such as /usr/local. If you would like to install
  47         cairo to some other location, pass the director to configure
  48         with the --prefix option. For example:
  49
  50                 ./configure --prefix=/opt/cairo
  51
  52         would install cairo into the /opt/cairo directory. You could
  53         also choose a prefix directory within your home directory if
  54         you don't have write access to any system-wide directory.
  55
  56         After installing into a custom prefix, you will need to set
  57         some environment variables to allow the software to be
  58         found. Assuming the /opt/cairo prefix and assuming you are
  59         using the bash shell, the following environment variables
  60         should be set:
  61
  62                 PKG_CONFIG_PATH=/opt/cairo/lib/pkgconfig
  63                 LD_LIBRARY_PATH=/opt/cairo/lib
  64                 export PKG_CONFIG_PATH LD_LIBRARY_PATH
  65
  66         (NOTE: On Mac OS X, at least, use DYLD_LIBRARY_PATH in place
  67                of LD_LIBRARY_PATH above.)
  68
  69     --enable-quartz
  70     --enable-atsui
  71     --enable-xcb
  72     --enable-glitz
  73     --enable-beos
  74     --enable-os2
  75     --enable-directfb
  76
  77         Some of cairo's backends are marked as experimental and will
  78         not be built by default. If you would like to build and
  79         experiment with these backends, you will need to pass one of
  80         the above options to the configure script. You may need to
  81         have certain libraries installed first as discussed in the
  82         dependencies section of the README file.
  83
  84     --disable-xlib
  85     --disable-win32
  86     --disable-png
  87     --disable-freetype
  88     --disable-ps
  89     --disable-pdf
  90     --disable-svg
  91
  92         Cairo's configure script detects the libraries needed to build
  93         each stable backend, and when it finds them, enables each
  94         backend. If you would like to override this detection and
  95         disable a backend, (even when it would be possible to build
  96         it), use one of the options above to disable the backend.
  97
  98 2) Compile the package:
  99
 100    This step is very simple. Just:
 101
 102         make
 103
 104    The Makefiles included with cairo are designed to work on as many
 105    different systems as possible.
 106
 107    When cairo is compiled, you can also run some automated tests of
 108    cairo with:
 109
 110         make check
 111
 112    NOTE: Some versions of X servers will cause the -xlib tests to
 113    report failures in make check even when cairo is working just
 114    fine. If you see failures in nothing but -xlib tests, please
 115    examine the corresponding -xlib-out.png images and compare them to
 116    the -ref.png reference images (the -xlib-diff.png images might also
 117    be useful). If the results seem "close enough" please do not report
 118    a bug against cairo as the "failures" you are seeing are just due
 119    to subtle variations in X server implementations.
 120
 121 3) Install the package:
 122
 123    The final step is to install the package with:
 124
 125         make install
 126
 127    If you are installing to a system-wide location you may need to
 128    temporarily acquire root access in order to perform this
 129    operation. A good way to do this is to use the sudo program:
 130
 131         sudo make install
 132
 133 Extremely detailed build instructions
 134 -------------------------------------
 135 So you want to build cairo but it didn't come with a configure
 136 script. This is probably because you have checked out the latest
 137 in-development code via git. If you need to be on the bleeding edge,
 138 (for example, because you're wanting to develop some aspect of cairo
 139 itself), then you're in the right place and should read on.
 140
 141 However, if you don't need such a bleeding-edge version of cairo, then
 142 you might prefer to start by building the latest stable cairo release:
 143
 144         http://cairographics.org/releases
 145
 146 or perhaps the latest (unstable) development snapshot:
 147
 148         http://cairographics.org/snapshots
 149
 150 There you'll find nicely packaged tar files that include a configure
 151 script so you can go back the the simpler instructions above.
 152
 153 But you're still reading, so you're someone that loves to
 154 learn. Excellent! We hope you'll learn enough to make some excellent
 155 contributions to cairo. Since you're not using a packaged tar file,
 156 you're going to need some additional tools beyond just a C compiler in
 157 order to compile cairo. Specifically, you need the following utilities:
 158
 159         automake (1.8 or newer)
 160         autoconf
 161         libtool
 162
 163 Hopefully your platform of choice has packages readily available so
 164 that you can easily install things with your system's package
 165 management tool, (such as "apt-get install automake" on Debian or "yum
 166 install automake" on Fedora, etc.). Note that Mac OS X ships with it's
 167 own utility called libtool which is not what you want, (the one you do
 168 want goes by the name of glibtool).
 169
 170 Once you have all of those packages installed, the next step is to run
 171 the autogen.sh script. That can be as simple as:
 172
 173         ./autogen.sh
 174
 175 Or, if you're using Mac OS X, you'll have to let it know to use
 176 glibtool by instead doing:
 177
 178         LIBTOOLIZE=glibtoolize ./autogen.sh
 179
 180 But before you run that command, note that the autogen.sh script
 181 accepts all the same arguments as the configure script, (and in fact,
 182 will generate the configure script and run it with the arguments you
 183 provide). So go back up to step (1) above and see what additional
 184 arguments you might want to pass, (such as prefix). Then continue with
 185 the instructions, simply using ./autogen.sh in place of ./configure.
 186
 187 Happy hacking!