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

Ipe runs on Mac OS 10.8 and higher, but you should compile on an
up-to-date system.


If you have Macports...
-----------------------

... then you can install the four libraries that Ipe depends on simply
by saying:

  sudo port install libpng lua cairo freetype

Then continue below under "Now you can compile Ipe".


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

 * Install Xcode from the Mac App store:
 
   http://itunes.apple.com/us/app/xcode/id497799835

 * Agree to the Xcode license by saying this in a terminal:

     sudo xcodebuild -license

 * Install the command line tools by saying the following in a
   terminal:

     xcode-select --install

 * Get libpng, Freetype, and Cairo

   Ipe depends on these three libraries. Without using macports or
   homebrew, the easiest way to get them is to install X11 for MacOS,
   for instance by installing XQuartz from http://www.xquartz.org -
   but check first if you perhaps already have an X11 installation by
   looking for the directories /usr/X11 and /opt/X11.

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

   Alternatively, you can install the three libraries from sources:
   
   + The libpng library 

     Install from source at "http://www.libpng.org".

   + The font library 'Freetype 2'

     Install from source at "www.freetype.org".  

   + The Cairo library

     The sources are at "www.cairographics.org".  Compile with
     Freetype support, but without fontconfig.  You need the Quartz
     and PS backend (they are enabled by default), all others are
     optional (disable the X11 backends to create a smaller library).

 * 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 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
      "IPEDEPS/include" 
   Copy "liblua53.dylib" into "IPEDEPS/lib".
   (Where IPEDEPS is as you set it in the previous step.)
   
   Or use "/usr/local/include" and "/usr/local/lib", and set
   LUA_CFLAGS and LUA_LIBS appropriately in "src/macos.mak".
   
   DO NOT install "liblua53.a" on your system, to avoid accidentally
   performing a static link.


   Alternatively, 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).

 * Pdflatex or Xelatex
 
   Ipe uses Pdflatex, a PDF-producing version of Latex, to convert
   Latex source code to Postscript/PDF.  Every modern TeX installation
   includes it.  Alternatively, you can use Xelatex, which can use
   system-specific fonts and also generates PDF directly (through the
   dvipdfmx backend).

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

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

 * Now you can compile Ipe:

     cd src
     make     	
     make app

 * 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).

   Or double-click on the Ipe.app icon in the Finder.
   
   You can now use the Finder to move the "Ipe.app" bundle to
   /Applications, or anywhere else.

   Note that "Ipe.app" is linked dynamically against the four
   libraries liblua, libpng, Freetype, and Cairo.  It will not work if
   you copy the bundle to a different computer that does not have
   (compatible versions of) the libraries in the same locations.  If
   you used macports to install the libraries, make sure you don't
   accidentally remove those four macports packages.

 * You will want to add the "/Applications/Ipe.app/Contents/MacOS"
   directory to your path, so that you can start Ipe and use the tools
   ipetoipe, iperender, etc. from the command line.

 * The 'pdflatex' or 'xelatex' program must be in one of these
   locations:

     * /Library/TeX/texbin
     * /usr/texbin
     * /usr/local/texbin
     * /usr/local/bin

   If your pdflatex is somewhere else, change the PATH being searched
   in "Ipe.app/Contents/Info.plist".

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