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

-------------------------------------------------------------------Quickstart for Linux

-------------------If you have a recent Mint, Ubuntu, or Debian system, the following
steps will install the necessary libraries and tools:
sudo apt-get install checkinstall zlib1g-dev libqt4-dev
sudo apt-get install libfreetype6-dev libcairo2-dev libjpeg8-dev
sudo apt-get install liblua5.2-dev gsfonts
On Fedora, use the following steps instead:
sudo yum -y install zlib-devel qt-devel freetype-devel cairo-devel
sudo yum -y install lua-devel ghostscript-fonts urw-fonts libjpeg8-dev
Now you can compile and install Ipe into /usr/local:
(Note that 7.x.y has to be replaced by the current Ipe version!)
cd src
make IPEPREFIX=/usr/local IPE_USE_ICONV=-DIPE_USE_ICONV
sudo checkinstall --pkgname=ipe --pkgversion=7.x.y --backup=no \
--fstrans=no --default make install IPEPREFIX=/usr/local
sudo cp ../fontmaps/gsfonts-fontmap.xml \
/usr/local/share/ipe/7.x.y/fontmap.xml
sudo ldconfig
The line with "checkinstall" makes sure that Ipe is installed as
package "ipe". If you no longer need Ipe, or to remove it before
compiling the next release, you can completely remove it from your
system by saying
sudo rm /usr/local/share/ipe/7.x.y/fontmap.xml
sudo apt-get remove ipe
Quickstart for MacOS 10.6 and higher
-----------------------------------If you have macports, you can compile and install Ipe by simply saying
sudo port install ipe
This will take a long time (run it over night!), and may not compile
the latest version if the macports recipe has not yet been updated.
With a little manual work, you can compile Ipe without using macports,
as follows:
* Install Qt4
Run the binary installer "qt-opensource-mac-4.8.6-1.dmg" for the Qt
SDK for Mac from "http://download.qt.io/archive/qt/4.8/".
Later versions of Qt4.8 should work, Qt5 is not supported or
tested.

* Install Lua
Download the prebuild binaries from
http://luabinaries.sourceforge.net/download.html
You need the "lua-5.2.1_MacOS107_lib.tar.gz" package only. Copy
the header files ("lua.h" and other ".h" files) into
"/usr/local/include".
Copy "liblua52.dylib" into "/usr/local/lib".
DO NOT install "liblua52.a" on your system, to avoid accidentally
performing a static link.
* Now you can either manually compile and install Ipe, or you can
build a MacOS application bundle (which you can then install on
several machines).
(1) Simple compile and install:
cd src
make IPEPREFIX=/usr/local
sudo make install IPEPREFIX=/usr/local
sudo cp ../fontmaps/mactex2011-fontmap.xml \
/usr/local/share/ipe/7.x.y/fontmap.xml
(where 7.x.y has to be replaced by the current Ipe version)
(2) To build an application bundle, just run the script
"mac_make_bundle.sh". (Line #4 of the script contains
the Ipe version number - make sure it's set properly!)
cd src
bash mac_make_bundle.sh
The bundle will contain Qt and Lua, so you do not need to
install those manually to install Ipe on another Mac.
If something doesn't work for you, please read below to check the
details!
-------------------------------------------------------------------Supported platforms
------------------Ipe should compile on most Unix platforms and on Microsoft Windows.
Mac OS X is not an officially supported platform - while it is based
on a Unix kernel, the Apple application infrastructure is proprietary
and quite different from standard Unix. I do not own an Apple
computer, and cannot help you with building or installing Ipe on Mac
OS.
-------------------------------------------------------------------Required components
------------------Before you can compile Ipe, you will need to have the following tools
and libraries:

* GNU make
The Ipe makefiles are written for GNU make. A Linux system will
already have it. On other Unix systems, GNU make is often
installed as 'gmake'. Otherwise, install it yourself from
www.gnu.org. Other "make" implementations will not work!
MacOS 10.6 already has this.
* 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.
MacOS 10.6 already has this.
* The font library 'Freetype 2'
On Linux, you most likely already have this on your system. You
will need the development package (on Debian/Ubuntu, this is
"libfreetype6-dev").
MacOS 10.6 already has this.
The original sources are at "www.freetype.org". You need version
2.1.8 or newer.
* The Cairo library (version 1.8.0 or higher)
The Gnome desktop uses this high-quality rendering library, so you
may already have it. You will need the development package,
e.g. on Debian/Ubuntu "libcairo2-dev".
MacOS 10.6 already has this.
You can also install from sources at "www.cairographics.org". If
you compile Cairo yourself, note that you only need the image and
svg surfaces (backends). You also need freetype support, but no
fontconfig. Since Ipe does not need any platform-dependent
backends, Cairo should compile fine on any platform.
* The libpng library
Linux and MacOS 10.6 already have this.
You can also install from source at "http://www.libpng.org".
* The libjpeg library (version 6 or higher)
Linux and MacOS 10.6 already have this.
You'll need the development package, e.g. on Debian/Ubuntu
"libjpeg8-dev". You can also use libjpeg-turbo instead (the
package "libjpeg-turbo8-dev"), from http://libjpeg-turbo.virtualgl.org/.
* The Lua language (version 5.2)
Lua is an embeddable scripting language. On Debian/Ubuntu, install

"liblua5.2-dev". Or compile from source at "www.lua.org" - the

sources are ANSI C and compile very easily. Ipe requires Lua 5.2,
and will not work with Lua 5.1.
Make sure that you build a DYNAMIC library. Ipe will not work if
Lua is linked statically (linking statically would include three
copies of the Lua interpreter, resulting in random crashes).
On Mac OS 10.6, you can use the prebuild binaries from
http://luabinaries.sourceforge.net/download.html
See the Quickstart above for installation. If you compile Lua
yourself, note that "make macosx" compiles a static library - but
you really MUST compile a shared library, so you need to modify the
Makefile.
* The Qt toolkit (version 4.5 or higher)
On Linux, you most likely already have it. On Debian/Ubuntu, you
would need the package "libqt4-dev".
On MacOS 10.6, run the Qt binary installer (see Quickstart
instructions above).
You can also find the sources at "qt.digia.com". You only need the
QtCore and QtGui libraries.
* 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 path of least resistance would be to download the fonts as
"urw-fonts.zip" from the same place where you got Ipe. Use the
supplied file "urw-fontmap.xml" as the fontmap for these fonts (see
below for installation of the fontmap).
However, very likely you have these fonts already on your system,
for instance in "/usr/share/fonts/type1/gsfonts/" under the 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
Identical fonts may also be in subdirectories of
"/usr/share/texmf/fonts/type1/urw" or
"/usr/share/texmf-texlive/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
Your system may have a fontmap file describing all the fonts on the
system in XML-format, similar to the supplied files
"gsfonts-fontmap.xml" and "texlive-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, one of the supplied fontmaps may already be correct. On

Debian/Ubuntu, "gsfonts-fontmap.xml" should be correct if you have
the "gsfonts" package installed.
On Mac OS X with MacTeX-2011, you can use "mactex2011-fontmap.xml".
(You may have to update the year in the file.)
Otherwise 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.
* Pdflatex
Ipe uses Pdflatex, a PDF-producing version of Latex, to convert
Latex source code to Postscript/PDF. Every modern TeX installation
includes it.
Ipe likes Pdftex 1.40. If you have an earlier version of Pdftex,
set the environment variable IPEANCIENTPDFTEX when running Ipe.
Configuring and building Ipe
---------------------------There are some pieces of information you need to provide to the Ipe
build process by editing "src/config.mak" (in many cases you can also
just give the definitions on the make command line, see below).
You first have to indicate the location of the required components
listed above. On Linux, you probably have a correctly working
'pkg-config' script, and the default settings should work.
You'll have to check that the Lua package name is correct - try saying
pkg-config --modversion lua5.2
If the package isn't found, try 'lua' or 'lua52'.
Second, you have to define the Ipe directory structure. Normally, you
would only need 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).
These steps will then build Ipe:
cd src
make
make install
Instead of editing "src/config.mak", you can also set the variables in
the make call, e.g.:
cd src
make IPEPREFIX=/usr IPEFONTMAP=/etc/ipe/fontmap.xml
sudo make install IPEPREFIX=/usr

You may need to do "make install" as root (depending on whether you

have write permission to the installation location).
Installing a fontmap
-------------------If you have made a "fontmap.xml" for Ipe, move it into the location
you specified in "config.mak". 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.
Dynamic linking
--------------The Ipe libraries are shared libraries, and so your dynamic linker has
to find "libipe*.so". If you have chosen a standard library directory
for IPELIBDIR, saying "sudo ldconfig" will be enough to run Ipe.
If you installed in a different location, such as "/opt/ipe7", you
can make a small script called "ipe" like the following, and put it in
your path:
#!/bin/sh
export LD_LIBRARY_PATH="/opt/ipe7/lib/:$LD_LIBRARY_PATH"
/opt/ipe7/bin/ipe $* &
Alternatively, you could put links to the library in a standard
location:
sudo ln -f -s IPELIBDIR/lib* /usr/lib
sudo ldconfig
--------------------------------------------------------------------