--------------------------------------------------------------------
            Building and installing Ipe on Unix
--------------------------------------------------------------------

Required components
-------------------

Before you can compile Ipe, you will need to have the following tools
and libraries:

 * The Qt toolkit

   You need to have version 4.0.0 or higher. Make sure you not only
   have the runtime libraries but the development package as well.

   If you are using Linux, you may already have Qt installed, but
   probably not Qt 4. If you don't have Qt 4, get the sources from
   www.trolltech.com and install them following the instructions.

   The Ipe build process relies on "qmake", a Makefile-generation tool
   that is part of Qt.  You will need the version of qmake that comes
   with Qt 4.

 * The compression library 'zlib'

   Very likely you already have it on your system (check for the
   include file "zlib.h").  If not, obtain it from "www.gzip.org/zlib"
   and install it.

 * The font library 'Freetype 2'

   On Linux, you most likely already have this on your system.
   Otherwise, you can probably install it as a binary package.  If
   not, install from the sources at "www.freetype.org".

   Make sure your version of Freetype is at least 2.0.8.  Ipe will not
   compile with earlier versions.  Also, Freetype versions 2.1.6 to
   2.1.7 contain a bug that stops Ipe from working.  Freetype 2.1.8
   works fine.

   Freetype can be one of the problematic parts of installing Ipe.  If
   compiling Ipe is successfull, but when running it, only empty boxes
   are displayed instead of text, you very probably have a problem
   with Freetype.  If you compile a new version of Freetype for Ipe,
   be careful that Ipe uses header files and library from the same
   version.  Ipe detects when header files and libary version do not
   match and will tell you as soon as it tries to display any text.

 * The 14 standard Postscript fonts

   If you create text objects using the 14 standard Postscript fonts
   (Times, Helvetica, Courier) the font doesn't need to be embedded in
   the PDF file. Still, Ipe needs access to the font to display it on
   the screen, and that's why you need to provide these 14 font files.

   The fonts are probably already on your system, for instance in
   subdirectories of "/usr/share/texmf/fonts/type1/urw", under the
   names
   
   ucrb8a.pfb ucrbo8a.pfb ucrr8a.pfb ucrro8a.pfb uhvb8a.pfb
   uhvbo8a.pfb uhvr8a.pfb uhvro8a.pfb usyr.pfb utmb8a.pfb utmbi8a.pfb
   utmr8a.pfb utmri8a.pfb uzdr.pfb

   Identical fonts may also be in "/usr/X11R6/lib/X11/fonts/Type1",
   "/usr/share/libwmf/fonts", or "/usr/share/ghostscript/fonts" (even
   multiple times), but then probably under the following names:

   n019003l.pfb n019004l.pfb n019023l.pfb n019024l.pfb n021003l.pfb
   n021004l.pfb n021023l.pfb n021024l.pfb n022003l.pfb n022004l.pfb
   n022023l.pfb n022024l.pfb s050000l.pfb d050000l.pfb

   Your system may have a fontmap file describing all the fonts on the
   system in XML-format, similar to the supplied file
   "tetex-fontmap.xml".  If so, Ipe can directly read this file and
   find the fonts, and all you need to do is to provide the path to
   the fontmap.

   If not, the supplied "tetex-fontmap.xml" may already be correct, if
   you have a standard teTeX installation (most Linux distributions
   do).  If not, you can check for the location of the necessary
   files, and create your own fontmap.  If you use relative paths in
   the fontmap, they are interpreted relative to the directory
   containing the fontmap file.

   Finally, you can take the path of least resistance, and download
   "urw-fonts.zip" from the same place where you got Ipe.  The
   supplied "urw-fontmap.xml" works for these fonts unchanged.

 * 'Pdflatex'

   Ipe uses Pdflatex, a PDF-producing version of Latex, to convert
   Latex source code to Postscript/PDF.  Nearly every Latex
   installation already includes Pdflatex.  However, some
   installations still seem to use very ancient versions of Pdflatex,
   which do not support the interface used by Ipe.
  
   To verify the Pdflatex version, simply call "pdflatex" from the
   command line and check what version it reports.  You should get a
   message like one of the following:

     This is pdfTeX, Version 3.14159-13d (Web2C 7.3.1)
     This is pdfTeX, Version 3.14159-14h-pretest-20010310 (Web2C 7.3.3.1)
     This is pdfTeX, Version 3.14159-1.10a-beta-20021101 (MiKTeX 2.2)

   In Pdftex version is the number after the TeX version (3.14159). In
   these examples, 0.13d, 0.14h, and 1.10a.  You need to have at least
   0.14f. If your Pdftex version is too old, you'll need to install a
   newer version. Check "www.tug.org/applications/pdftex" for where to
   get it.  

   You can go ahead and compile and install Ipe without updating
   Pdflatex first.  Pdflatex is not used during the compilation, and
   Ipe will actually work fine as long as you don't call the function
   "Run Latex" and don't try to save to Postscript or PDF format.


Configuring and building Ipe
----------------------------

There are some pieces of information you need to provide to the Ipe
build process by editing "src/config.pri".

If your Freetype include files (check for "ft2build.h") and library
("libfreetype.so") are not on the standard path, add the correct
paths.  Note that many Linux distributions have a somewhat weird,
historically grown Freetype setup.  Although "ft2build.h" is in
"/usr/include", you still need to add "/usr/include/freetype2" to your
include path.  If your system has a directory "usr/include/freetype2",
this is probably the case on your system.

If your Zlib include file ("zlib.h") and library ("libz.so") are not
on the standard path, add the correct paths.

Finally, define the Ipe directory structure.  Normally, you would only
have to define IPEPREFIX properly, depending on where you want 
Ipe to be installed.  

Indicate in IPEFONTMAP the path for "fontmap.xml" (if you are using a
system fontmap, indicate the correct path; if you are using/making one
specifically for Ipe place the fontmap in this location).

Indicate in IPEBROWSER the program you wish to use for viewing the
on-line manual.  The user can later override all these definitions
using environment variables.

These steps will build Ipe:

     cd src
     qmake
     make
     make install

If "qmake" is not on your path, check your Qt installation for its
location, and add that to your path.  You may need to do "make
install" as superuser (depending on where you are installing Ipe).

If you have made a "fontmap.xml" for Ipe, move it into the location
you specified in "config.pri".  In case you are using "urw-fonts.zip",
move "urw-fontmap.xml" to "IPEPREFIX/share/ipe/IPEVERS/fontmap.xml",
and unpack the 14 fonts from "urw-fonts.zip" into
"IPEPREFIX/share/ipe/IPEVERS/fonts" (assuming you haven't changed the
standard definition of IPEFONTMAP).  Note that "make install" DOES NOT
install any fontmap -- you have to do this one step manually.

Note that the Ipe library is a shared library, and so your dynamic
linker has to find "libipe.so.*".  If you have chosen a standard
library directory for IPELIBDIR, saying "ldconfig" (as superuser) will
be enough to run Ipe.

If you installed in a different location, such as "/opt/ipe-6.0", you
can make a small script called "ipe" like the following, and put it in
your path:

#!/bin/sh
export LD_LIBRARY_PATH="/opt/ipe-6.0/lib/:$LD_LIBRARY_PATH"
/opt/ipe-6.0/bin/ipe $* &

Alternatively, you could put links to the library in a standard
location (as superuser):

    ln -f -s IPELIBDIR/lib* /usr/lib
    ldconfig

Another alternative is to add IPELIBDIR to your system's standard
library path, usually by editing "/etc/ld.so.conf" and running
"ldconfig".

--------------------------------------------------------------------
