--------------------------------------------------------------------
            Building Ipe on Mac OS X
--------------------------------------------------------------------

Ipe can be compiled on Mac OS 10.6 (Snow Leopard) and higher.


Macports
--------

If you have macports, the easiest way to compile and install Ipe is to
simply say 

    sudo port install ipe

This will take a long time (run it over night!).


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

Quickstart
----------

You can compile Ipe without using macports as follows:

 * Install Qt

   Run the binary installer "qt-mac-opensource-4.8.2.dmg" for the Qt
   SDK for Mac from "http://download.qt.io/archive/qt/4.8/".

   I am not using Qt5 on Mac OS X because it is not compatible with
   Mac OS 10.6 (Snow Leopard).

 * Get libpng, Freetype, and Cairo

   Ipe depends on these three libraries. The easiest way to get them
   is to install X11 for MacOS, for instance by installing XQuartz
   (you may already have it).  Mac OS X came with X11 by default until
   Mac OS 10.7 or so.

   Edit "src/macosx.mak" and set X11LIBS to the base of your X11
   installation.

 * Install Lua

   Download the prebuild binaries from 
      http://luabinaries.sourceforge.net/download.html

   You need the "lua-5.3_MacOS1010_lib.tar.gz" package only.  

   Unzip the package.
   
   Copy the header files ("lua.h" and other ".h" files) into
      "X11LIBS/include" 
   Copy "liblua53.dylib" into "X11LIBS/lib".
   (Where X11LIBS is as you set it in the previous step.)
   
   DO NOT install "liblua53.a" on your system, to avoid accidentally
   performing a static link.

 * Now you can compile Ipe:

     cd src
     make     	
     make app
     cp ../fontmaps/mactex2011-fontmap.xml \
     	  ../../build/Ipe.app/Contents/Resources/fontmap.xml

 * Ipe is now available as a MacOS app in "build/Ipe.app".

   You can start it from the command line by saying

     open ../build/Ipe.app

   (assuming you are still in the "src" directory).

   You can also use the Finder to move the "Ipe.app" bundle to
   /Applications, or anywhere else.

   But note that "Ipe.app" is linked against your Qt installation and
   the three libraries libpng, Freetype, and Cairo.  It will not work
   if you copy the bundle to a different computer that does not have
   the libraries in the same locations.
   
If something doesn't work for you, please read below to check the
details!

--------------------------------------------------------------------
Detailed instructions
--------------------------------------------------------------------

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

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

 * The libpng library

   Mac OS has this in an X11 installation like XQuartz. 

   If you wish to build without an X11 installation, install from
   source at "http://www.libpng.org".

 * The font library 'Freetype 2'

   Mac OS has this in an X11 installation like XQuartz. 

   If you wish to build without an X11 installation, install from 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)

   Mac OS has this in an X11 installation like XQuartz. 

   If you wish to build without an X11 installation, install from the
   sources at "www.cairographics.org".  Compile with Freetype support,
   but without fontconfig.

 * The Lua language (version 5.2 or 5.3)

   Lua is an embeddable scripting language. Ipe requires Lua 5.2 or
   Lua 5.3, and will not work with Lua 5.1.

   Download binaries as described in the Quickstart above, or compile
   from source at "www.lua.org" - the sources are ANSI C and compile
   very easily.  Make sure that you build a DYNAMIC (shared) library.
   Unfortunately, "make macosx" compiles a static library - but you
   really MUST compile a shared library, so you need to modify the
   Makefile.

   Ipe will not work if Lua is linked statically (linking statically
   would include three copies of the Lua interpreter, resulting in
   random crashes).

 * 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.
   Ipe uses a fontmap file "fontmap.xml" to find the files on your
   system.
       
   If you are using MacTeX, you have the fonts on your computer
   already, and you can use "mactex2011-fontmap.xml" as "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.  

 * Pdflatex

   Ipe uses Pdflatex, a PDF-producing version of Latex, to convert
   Latex source code to Postscript/PDF.  Every modern TeX installation
   includes it, in particular MacTeX.

   If you still have a version of Pdftex earlier than 1.40, set the
   environment variable IPEANCIENTPDFTEX when running Ipe.


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

There are some pieces of information you can provide to the Ipe build
process by editing "src/macos.mak" (in many cases you can also just
give the definitions on the make command line or by setting an
environment variable).

These steps will then build Ipe:

     cd src
     make
     make app

You should also add the fontmap you prepared above, by copying it
into "build/Ipe.app/Contents/Resources".  This step is not done by the
build process.

As explained in the quickstart, Ipe is built as a Mac OS app in
"build/Ipe.app".  You can start it from the command line using "open",
or move the entire app bundle to a location of your choice (in
particular, to /Applications).

If you work on the command line, you can also start Ipe by giving the
path to the executable itself. You may wish to set a shell alias, for
instance

alias ipe=/Applications/Ipe.app/Contents/MacOS/ipe

Or add this directory to your path, allowing you to run the command
line tools that come with Ipe (ipetoipe, iperender, ipeextract, etc).

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