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-XYZ
  70     --enable-XYZ=yes
  71     --enable-XYZ=auto
  72     --enable-XYZ=no
  73     --disable-XYZ
  74
  75    Cairo's various font and surface backends and other features can be
  76    enabled or disabled at configure time.  Features can be divided into
  77    three categories based on their default state:
  78
  79      * default=yes: These are the recommended features like PNG functions
  80        and PS/PDF/SVG backends.  It is highly recommended to not disable
  81        these features but if that's really what one wants, they can be
  82        disabled using --disable-XYZ.
  83
  84      * default=auto: These are the "native" features, that is, they are
  85        platform specific, like the Xlib surface backend.  You probably
  86        want one or two of these.  They will be automatically enabled if
  87        all their required facilities are available.  Or you can use
  88        --enable-XYZ or --disable-XYZ to make your desire clear, and then
  89        cairo errs during configure if your intention cannot be followed.
  90
  91      * default=no: These are the "experimental" features, and hence by
  92        default off.  Use --enabled-XYZ to enable them.
  93
  94    The list of all features and their default state can be seen in the
  95    output of ./configure --help.
  96
  97 2) Compile the package:
  98
  99    This step is very simple. Just:
 100
 101         make
 102
 103    The Makefiles included with cairo are designed to work on as many
 104    different systems as possible.
 105
 106    When cairo is compiled, you can also run some automated tests of
 107    cairo with:
 108
 109         make check
 110
 111    NOTE: Some versions of X servers will cause the -xlib tests to
 112    report failures in make check even when cairo is working just
 113    fine. If you see failures in nothing but -xlib tests, please
 114    examine the corresponding -xlib-out.png images and compare them to
 115    the -ref.png reference images (the -xlib-diff.png images might also
 116    be useful). If the results seem "close enough" please do not report
 117    a bug against cairo as the "failures" you are seeing are just due
 118    to subtle variations in X server implementations.
 119
 120 3) Install the package:
 121
 122    The final step is to install the package with:
 123
 124         make install
 125
 126    If you are installing to a system-wide location you may need to
 127    temporarily acquire root access in order to perform this
 128    operation. A good way to do this is to use the sudo program:
 129
 130         sudo make install
 131
 132 Extremely detailed build instructions
 133 -------------------------------------
 134 So you want to build cairo but it didn't come with a configure
 135 script. This is probably because you have checked out the latest
 136 in-development code via git. If you need to be on the bleeding edge,
 137 (for example, because you're wanting to develop some aspect of cairo
 138 itself), then you're in the right place and should read on.
 139
 140 However, if you don't need such a bleeding-edge version of cairo, then
 141 you might prefer to start by building the latest stable cairo release:
 142
 143         http://cairographics.org/releases
 144
 145 or perhaps the latest (unstable) development snapshot:
 146
 147         http://cairographics.org/snapshots
 148
 149 There you'll find nicely packaged tar files that include a configure
 150 script so you can go back the the simpler instructions above.
 151
 152 But you're still reading, so you're someone that loves to
 153 learn. Excellent! We hope you'll learn enough to make some excellent
 154 contributions to cairo. Since you're not using a packaged tar file,
 155 you're going to need some additional tools beyond just a C compiler in
 156 order to compile cairo. Specifically, you need the following utilities:
 157
 158         automake
 159         autoconf
 160         autoheader
 161         aclocal
 162         libtoolize
 163         pkg-config [at least version 0.16]
 164         gtk-doc (recommended)
 165
 166 Hopefully your platform of choice has packages readily available so
 167 that you can easily install things with your system's package
 168 management tool, (such as "apt-get install automake" on Debian or "yum
 169 install automake" on Fedora, etc.). Note that Mac OS X ships with
 170 glibtoolize instead of libtoolize.
 171
 172 Once you have all of those packages installed, the next step is to run
 173 the autogen.sh script. That can be as simple as:
 174
 175         ./autogen.sh
 176
 177 But before you run that command, note that the autogen.sh script
 178 accepts all the same arguments as the configure script, (and in fact,
 179 will generate the configure script and run it with the arguments you
 180 provide). So go back up to step (1) above and see what additional
 181 arguments you might want to pass, (such as prefix). Then continue with
 182 the instructions, simply using ./autogen.sh in place of ./configure.
 183
 184 Happy hacking!