Mac: converted compile instructions from RTF to markdown (#636)

* Mac: converted compile instructions to MD

macosx/ReadMe.md

@@ -0,0 +1,656 @@
+# title: GRASS GIS Mac OS X Build
+
+(and other Mac notes)
+
+**Table of Contents**
+
+- Quickstart
+- About
+- Building GRASS
+    - Optimization
+    - Configure Example
+    - Leopard Notes
+    - Building an Installer Package
+    - Bundling Libraries and Programs
+- Developer Notes
+- Help Files
+- Addon Modules
+- Dependency Build Notes
+    - Universal Aqua Tcl/Tk
+    - Universal GPSBabel
+    - Universal NetPBM
+    - Universal FFMPEG
+
+Quickstart
+==========
+
+To build a Mac OS X application, add this to your configure options:
+
+\--prefix=/Applications \--enable-macosx-app
+
+About
+=====
+
+This builds GRASS as a Mac OS X application, more or less.
+
+The startup wrapper is a simple AppleScript that fires up a custom
+grass.sh (instead of the standard grass6x) and quits, leaving grass.sh
+running in a new Terminal window. The custom grass.sh takes care of some
+default and required environment settings (so the user doesn\'t have to
+fiddle with .bash\_profile), makes sure X11 in running, then starts
+init.sh.
+
+Building GRASS
+==============
+
+Building GRASS as a Mac OS X application is pretty much the same as for
+a unix build (see the \"INSTALL\" document for details). For an
+application, just add this option to configure:
+
+\--enable-macosx-app
+
+With this option, the \--prefix specified is the path where GRASS.app
+will be installed. The default GRASS prefix is /usr/local, but for a Mac
+OS X application it should be /Applications. It is not possible to have
+alternative default prefixes in configure, so you must set
+\--prefix=/Applications yourself for configure.
+
+The makefile tries to figure out the location of the GDAL programs, from
+the configured GDAL libs. This is set in grass.sh, and if it doesn\'t
+correctly figure it out (some GRASS commands fail to find needed GDAL
+commands), set GDAL\_BIN before running make:
+
+export GDAL\_BIN=\[/path/to/gdal/bin\]
+
+[Universal Build]{.underline}
+
+The GRASS build system is very friendly to a Universal build (unlike
+libtool-based builds). *This applies to a standard unix build as well as
+the app build.* First, a couple things to check:
+
+**• The Universal SDK**. *This is only needed when building on OSX 10.4
+PPC - the Intel system is all Universal, and so is 10.5 for both
+architectures (though you may still want to use an SDK).* Using the SDK
+forces GCC to use an alternate root for everything, so if a dependency
+is not in the SDK (/usr/local is NOT in the SDK), you will get
+configure, compile and link errors about missing stuff. To fix this,
+create symlinks in the SDK to where you have your extra dependencies.
+The SDKs in Leopard are mostly taken care of.
+
+For example, /usr/local:
+
+sudo ln -s /usr/local /Developer/SDKs/MacOSX10.4u.sdk/usr/local
+
+For Leopard, there may be problems locating bin programs. Add the
+following:
+
+sudo ln -s /usr/local/bin /Developer/SDKs/MacOSX10.4u.sdk/usr/local/bin
+
+sudo ln -s /usr/local/bin /Developer/SDKs/MacOSX10.5.sdk/usr/local/bin
+
+If there are subfolders involved that are not already in the SDK, add
+them first. Say you have some libraries in /Users/Shared/unix (I put my
+static libraries there):
+
+sudo mkdir -p /Developer/SDKs/MacOSX10.4u.sdk/Users/Shared
+
+ln -s /Users/Shared/unix
+/Developer/SDKs/MacOSX10.4u.sdk/Users/Shared/unix
+
+For /Library/Frameworks:
+
+sudo mkdir -p /Developer/SDKs/MacOSX10.4u.sdk/Library
+
+sudo ln -s /Library/Frameworks
+/Developer/SDKs/MacOSX10.4u.sdk/Library/Frameworks
+
+**• Universal Dependencies**. Make sure all your extra dependencies are
+Universal.
+
+**• Tiger+**. This will NOT work on anything less than OSX 10.4.
+
+If those check OK, here\'s what to do. Simply add the universal flags to
+all compile and link commands. This is done by setting CFLAGS, CXXFLAGS
+and LDFLAGS before configuring the build. The basic flags are:
+
+-arch ppc -arch i386
+
+If you are building on OSX 10.4 PPC only, also add this:
+
+-isysroot /Developer/SDKs/MacOSX10.4u.sdk
+
+Put it all together, for an Intel Mac on OSX 10.4 or any Mac on 10.5+:
+
+export CFLAGS=\"-arch ppc -arch i386\"
+
+export CXXFLAGS=\"-arch ppc -arch i386\"
+
+export LDFLAGS=\"-arch ppc -arch i386\"
+
+Or for OSX 10.4 PPC:
+
+export SDKROOT=/Developer/SDKs/MacOSX10.4u.sdk
+
+export CFLAGS=\"-arch ppc -arch i386 -isysroot \$SDKROOT\"
+
+export CXXFLAGS=\"-arch ppc -arch i386 -isysroot \$SDKROOT\"
+
+export LDFLAGS=\"-arch ppc -arch i386 -isysroot \$SDKROOT\"
+
+For OSX 10.5, you can also build for 64bit (all processors except the
+first Intel Core Duo), just add:
+
+-arch ppc64 -arch x86\_64
+
+Optimization
+------------
+
+By default, GRASS configures with debugging symbols turned on (the
+\"-g\" flag), and level 2 optimization (\"-O2\"). If you don\'t want
+debugging on (it greatly increases the binary size) or want to use a
+different optimization, just add an optimization flag to the above
+CFLAGS and CXXFLAGS exports. Specifying an optimization disables
+debugging. Some common optimizations are (see the gcc man page for
+complete details):
+
+-O2 most optimizations, a common default
+
+-O3 high
+
+-Os optimize for speed, also keep the binary size small (the Apple
+standard)
+
+If you want debugging with a different optimization flag, use one of the
+above optimization flags plus \"-g\".
+
+Remember to separate all flags with spaces.
+
+Configure Example
+-----------------
+
+As an example, to build GRASS using my frameworks and Tcl/Tk as built in
+the build notes below, this should work *(for a standard unix build,
+just remove the \--prefix and \--enable-macosx-app flags)*:
+
+./configure \--with-freetype
+\--with-freetype-includes=\"/Library/Frameworks/FreeType.framework/unix/include/freetype2
+/Library/Frameworks/FreeType.framework/unix/include\"
+\--with-freetype-libs=/Library/Frameworks/FreeType.framework/unix/lib
+\--with-gdal=/Library/Frameworks/GDAL.framework/Programs/gdal-config
+\--with-geos=/Library/Frameworks/GEOS.framework/Programs/geos-config
+\--with-proj
+\--with-proj-includes=/Library/Frameworks/PROJ.framework/unix/include
+\--with-proj-libs=/Library/Frameworks/PROJ.framework/unix/lib
+\--with-proj-share=/Library/Frameworks/PROJ.framework/Resources/proj
+\--with-jpeg-includes=/Library/Frameworks/UnixImageIO.framework/unix/include
+\--with-jpeg-libs=/Library/Frameworks/UnixImageIO.framework/unix/lib
+\--with-png-includes=/Library/Frameworks/UnixImageIO.framework/unix/include
+\--with-png-libs=/Library/Frameworks/UnixImageIO.framework/unix/lib
+\--with-tiff-includes=/Library/Frameworks/UnixImageIO.framework/unix/include
+\--with-tiff-libs=/Library/Frameworks/UnixImageIO.framework/unix/lib
+\--without-postgres \--without-mysql \--with-odbc \--with-sqlite
+\--with-sqlite-libs=/Library/Frameworks/SQLite3.framework/unix/lib
+\--with-sqlite-includes=/Library/Frameworks/SQLite3.framework/unix/include
+\--with-fftw-includes=/Library/Frameworks/FFTW3.framework/unix/include
+\--with-fftw-libs=/Library/Frameworks/FFTW3.framework/unix/lib
+\--with-cxx
+\--with-tcltk-includes=\"/Library/Frameworks/Tcl.framework/Headers
+/Library/Frameworks/Tk.framework/Headers
+/Library/Frameworks/Tk.framework/PrivateHeaders\"
+\--with-tcltk-libs=/usr/local/lib \--with-x \--without-motif
+\--without-glw \--with-opengl=aqua \--without-readline
+\--prefix=/Applications \--enable-macosx-app
+
+That\'s a long line, but you have to be very explicit in the GRASS
+configure (and yes, the UnixImageIO framework is used multiple times).
+
+If you don\'t have the PROJ framework programs folder in your shell
+PATH, it will fail to find nad2bin. To correct this set NAD2BIN before
+running configure:
+
+export NAD2BIN=/Library/Frameworks/PROJ.framework/Programs/nad2bin
+
+Sometimes, for mysterious reasons so far, the automatic check for X11
+fails. Depending on various conditions, you may immediately notice this
+because configure stops. If X11 isn\'t found automatically, add this to
+the configure line *(this applies to both the unix build and app
+build)*:
+
+\--x-includes=/usr/X11R6/include \--x-libraries=/usr/X11R6/lib
+
+To install the new Python GUI (see REQUIREMENTS.html and
+gui/wxpython/README, wxpython installer available at
+[wxpython.org](http://wxpython.org/)), add this to configure (fill in
+the correct version at x.x.x.x for the wxpython you have installed):
+
+\--with-python
+
+\--with-wxwidgets=/usr/local/lib/wxPython-unicode-x.x.x.x/bin/wx-config
+
+Note: as of wxpython 2.8.8.0 you can use an external wxpython with the
+system Python on Leopard.
+
+If you want ffmpeg support (see build instructions below), add this:
+
+\--with-ffmpeg \--with-ffmpeg-includes=\"/usr/local/include
+/usr/local/include/libavcodec /usr/local/include/libavdevice
+/usr/local/include/libavformat /usr/local/include/libavutil
+/usr/local/include/libswscale\" \--with-ffmpeg-libs=/usr/local/lib
+
+For cairo support (see build instructions at
+[kyngchaos.com](http://www.kyngchaos.com/macosx:build:cairo)), add this:
+
+\--with-cairo \--with-cairo-includes=/usr/local/include/cairo
+\--with-cairo-libs=/usr/local/lib \--with-cairo-ldflags=-lcairo
+
+Leopard Notes
+-------------
+
+• Linker Problem
+
+The linker in Leopard\'s GCC from Xcode 3.0 has a bit of a problem with
+some libraries, notably X11\'s libGL. When trying to link libGL (for
+example), it spits back an error:
+
+ld: cycle in dylib re-exports with /usr/X11/lib/libGL.dylib for
+architecture i386
+
+Xcode 3.1 does not have this problem. In other words, make sure to
+install the latest Xcode.
+
+Building an Installer Package
+-----------------------------
+
+After running make, make bindist will assemble an installer package.
+This will have the name \"GRASS-\[version\].pkg\" and will be found in
+the macosx folder in the GRASS source. On Tiger, there **will be** some
+**non-fatal errors** - *this is normal* and the installer package is
+still generated correctly.
+
+The installer takes care of binary installation, and creating the
+/Library/GRASS support folder and Help Viewer link.
+
+This installer currently does NOT do any verification of installed
+dependencies or system version.
+
+Bundling Libraries and Programs
+-------------------------------
+
+Additional dependent libraries and programs can be bundled with the
+application package to make a more portable and easily installed GRASS
+application. See macosx/pkg/bundle.make for details.
+
+GRASS uses DYLD\_LIBRARY\_PATH, which is set to the application\'s lib
+folder, so it will find any libraries that are there that are not found
+in their expected locations. It also adds the application bin folder to
+the PATH, so helper programs installed there will be found.
+
+There is NO need to bundle *everything*. Bundling readily available
+libraries and programs installed in standard locations is not necessary.
+Some things you might want to bundle include:
+
+\- GPSBabel (CLI)
+
+\- NetPBM programs (just what is used in GRASS)
+
+\- other support CLI programs for script modules
+
+\- ffmpeg libraries
+
+\- Postgres library (libpq)
+
+Things to leave out:
+
+\- applications that duplicate the above items (ie GPSBabel.app)
+
+\- /Library/Frameworks stuff
+
+Developer Notes
+===============
+
+The applescript startup and grass.sh can be customized if desired, ie
+for a more complex startup that might give the user a dialog for startup
+options. They just provide the basic core to build upon.
+
+Help Files
+==========
+
+Help files are linked into the OSX help system. Independent of what
+browser you choose to open help files (GRASS\_HTML\_BROWSER), you can
+open Help Viewer from almost any application\'s Help menu (it\'s best to
+use Mac Help from the Finder Help menu), and GRASS Help will be
+available in the Library menu.
+
+Since they are linked to the help system, if GRASS.app is moved or
+renamed, the link will be broken. This may change in the future.
+
+Addon Modules
+=============
+
+modbuild deprecated (not installed now). Makefile changes in progress to
+allow compiling external modules.
+
+Dependency Build Notes
+======================
+
+They apply to any OSX build, not just an application package build:
+
+Universal Aqua Tcl/Tk
+---------------------
+
+The simplest way to install Tcl/Tk Aqua is to download
+[ActiveTcl](http://www.activestate.com/Products/activetcl/) from
+ActiveState. This will give you a universal 32bit Tcl/Tk Aqua (64bit is
+currently not possible). [Make sure to run the *convenience* commands
+below.]{.underline}
+
+To make it easier to configure for GRASS (and other software), run these
+commands in a Terminal:
+
+sudo ln -sf /Library/Frameworks/Tcl.framework/Versions/8.5/Tcl
+/usr/local/lib/libtcl.dylib
+
+sudo ln -sf /Library/Frameworks/Tcl.framework/Versions/8.5/Tcl
+/usr/local/lib/libtcl8.5.dylib
+
+sudo ln -sf
+/Library/Frameworks/Tcl.framework/Versions/8.5/libtclstub8.5.a
+/usr/local/lib/libtclstub8.5.a
+
+sudo ln -sf /Library/Frameworks/Tk.framework/Versions/8.5/Tk
+/usr/local/lib/libtk.dylib
+
+sudo ln -sf /Library/Frameworks/Tk.framework/Versions/8.5/Tk
+/usr/local/lib/libtk8.5.dylib
+
+sudo ln -sf /Library/Frameworks/Tk.framework/Versions/8.5/libtkstub8.5.a
+/usr/local/lib/libtkstub8.5.a
+
+Universal GPSBabel
+------------------
+
+A universal GPSBabel CLI executable is now included in the OSX binary
+from [www.gpsbabel.org](http://www.gpsbabel.org/). This does not need to
+be 64bit.
+
+Universal NetPBM
+----------------
+
+NetPBM is not too hard to build, it\'s just weird. These instructions
+use my UnixImageIO framework for the tiff, jpeg, png and jasper
+libraries.
+
+First, grab the [NetPBM](http://netpbm.sourceforge.net/) source and
+unzip it. Now it gets strange - it\'s an interactive configuration, and
+the various stages don\'t communicate with each other. Cd to the source
+folder in a Terminal and:
+
+./configure
+
+**\<enter\>** to begin
+
+Platform \[darwin\] ==\> **\<enter\>**
+
+Netpbm shared library directory \[default\] ==\> **/usr/local**
+
+> *choose where you will install it*
+>
+> *default is NOT /usr/local or any location at all, so you MUST set
+> this*
+
+regular or merge \[regular\] ==\> **\<enter\>**
+
+static or shared \[shared\] ==\> **\<enter\>**
+
+> *could use static, since GRASS only needs a few of the progs*
+
+\'\#include\' argument or NONE \[\<inttypes.h\>\] ==\> **\<enter\>**
+
+What is your JPEG (graphics format) library?
+
+library filename or \'none\' \[libjpeg.so\] ==\>
+**/Library/Frameworks/UnixImageIO.framework/unix/lib/libjpeg.dylib**
+
+JPEG header directory \[default\] ==\>
+**/Library/Frameworks/UnixImageIO.framework/Headers**
+
+What is your TIFF (graphics format) library?
+
+library filename or \'none\' \[libtiff.so\] ==\>
+**/Library/Frameworks/UnixImageIO.framework/unix/lib/libtiff.dylib**
+
+TIFF header directory \[default\] ==\>
+**/Library/Frameworks/UnixImageIO.framework/Headers**
+
+What is your PNG (graphics format) library?
+
+library filename or \'none\' \[libpng.so\] ==\>
+**/Library/Frameworks/UnixImageIO.framework/unix/lib/libpng.dylib**
+
+PNG header directory \[default\] ==\>
+**/Library/Frameworks/UnixImageIO.framework/Headers**
+
+What is your Z (compression) library?
+
+library filename or \'none\' \[libz.so\] ==\> **-lz**
+
+Z header directory \[default\] ==\> **\<enter\>**
+
+Documentation URL \[http://netpbm.sourceforge.net/doc/\] ==\>
+**\<enter\>**
+
+> *ignore warning about libz*
+
+echo \"JASPERLIB =
+/Library/Frameworks/UnixImageIO.framework/unix/lib/libjasper.dylib\"
+\>\> Makefile.config
+
+echo \"JASPERHDR\_DIR =
+/Library/Frameworks/UnixImageIO.framework/Headers\" \>\> Makefile.config
+
+For Tiger:
+
+echo \"CC = /usr/bin/gcc -arch ppc -arch i386 -isysroot
+/Developer/SDKs/MacOSX10.4u.sdk\" \>\> Makefile.config
+
+For Leopard:
+
+echo \"CC = /usr/bin/gcc -arch ppc -arch i386 -arch ppc64 -arch
+x86\_64\" \>\> Makefile.config
+
+make
+
+make package pkgdir=/path/to/some/temp/dir
+
+> *it will create the folder and copy all binaries there*
+
+sudo ./installnetpbm
+
+then answer some more questions:
+
+Where is the install package you created with \'make package\'?
+
+package directory (/tmp/netpbm) ==\> **/path/to/some/temp/dir**
+
+> *same location as specified in the make package step (lack of
+> inter-communication!)*
+
+install prefix (/usr/local/netpbm) ==\> **/usr/local**
+
+> *same location used for the Netpbm shared library directory (again,
+> lack of inter-communication!)*
+>
+> *(it may ask you if you want to create the dir)*
+
+It\'ll ask for subfolders for bin, lib, data, headers, man
+
+For data, type: **/usr/local/share/netpbm**
+
+For man, type: **/usr/local/share/man**
+
+For the rest, use the defaults
+
+don\'t create the manweb.conf file
+
+And that\'s it.
+
+Universal FFMPEG
+----------------
+
+[version:]{.underline} [0.5](http://www.ffmpeg.org/download.html)
+
+FFMPEG is constantly changing, and release versions are rare. For
+simplicity use the 0.5 release version. If you know anything about SVN
+you can try for a more up-to-date FFMPEG. Some options used below are
+not in more recent SVN versions, so if configure complains about an
+invalid option, just remove it.
+
+This will build a basic FFMPEG as dynamic libraries for use with GRASS.
+The default static libraries don\'t work now because of reloc errors and
+the need for extra link flags. No extra formats are included, such as
+mp3lame and xvid. None of the ffmpeg programs are included either (GRASS
+doesn\'t need them).
+
+It\'s a multi-step build, 1 for each architecture. Create a folder
+inside the source for each arch:
+
+mkdir build-i386
+
+mkdir build-ppc
+
+and also for Leopard:
+
+mkdir build-x86\_64
+
+mkdir build-ppc64
+
+For i386 and ppc arches, if building on Tiger, you must add the
+following to extra-cflags and extra-ldflags in the configure command:
+
+-isysroot /Developer/SDKs/MacOSX10.4u.sdk
+
+For i386:
+
+cd build-i386
+
+../configure \--enable-shared \--disable-static \--disable-debug
+\--disable-ffserver \--disable-network \--enable-gpl \--enable-pthreads
+\--enable-swscale \--disable-vhook \--disable-ffplay \--disable-ffmpeg
+\--disable-amd3dnow \--arch=i386 \--extra-cflags=\"-arch i386\"
+\--extra-ldflags=\"-arch i386\"
+
+If you are building *on* a PPC Mac, you need to add the flag
+\"\--enable-cross-compile\" to the above configure command.
+
+make
+
+sudo make install
+
+Install at this point installs everything. We don\'t care about the
+installed libraries yet, we just need the headers there.
+
+Now, the PPC build:
+
+cd ../build-ppc
+
+../configure \--enable-shared \--disable-static \--disable-debug
+\--disable-ffserver \--disable-network \--enable-gpl \--enable-pthreads
+\--enable-swscale \--disable-vhook \--disable-ffplay \--disable-ffmpeg
+\--enable-altivec \--arch=ppc \--extra-cflags=\"-arch ppc\"
+\--extra-ldflags=\"-arch ppc\"
+
+make
+
+Don\'t install this one, there is no need.
+
+If you are building for Leopard, also do the 64bit varieties, otherwise
+skip to the lipo step below.
+
+For x86\_64:
+
+cd build-x86\_64
+
+../configure \--enable-shared \--disable-static \--disable-debug
+\--disable-ffserver \--disable-network \--enable-gpl \--enable-pthreads
+\--enable-swscale \--disable-vhook \--disable-ffplay \--disable-ffmpeg
+\--disable-amd3dnow \--arch=x86\_64 \--extra-cflags=\"-arch x86\_64\"
+\--extra-ldflags=\"-arch x86\_64\"
+
+Again, if you are building *on* a PPC Mac, you need to add the flag
+\"\--enable-cross-compile\" to the above configure command.
+
+make
+
+And ppc64:
+
+cd ../build-ppc64
+
+../configure \--enable-shared \--disable-static \--disable-debug
+\--disable-ffserver \--disable-network \--enable-gpl \--enable-pthreads
+\--enable-swscale \--disable-vhook \--disable-ffplay \--disable-ffmpeg
+\--enable-altivec \--arch=ppc64 \--extra-cflags=\"-arch ppc64\"
+\--extra-ldflags=\"-arch ppc64\"
+
+Here, if you are building *on* an Intel Mac, you need to add the flag
+\"\--enable-cross-compile\" to the above configure command. Also, it
+will fail to completely identify it as 64bit, so you need to fix 2
+files.
+
+In **config.h**, find the HAVE\_PPC64 define and set it to 1:
+
+\#define HAVE\_PPC64 1
+
+In **config.mak**, add this line to the end of the file:
+
+HAVE\_PPC64=yes
+
+Then finish:
+
+make
+
+Now use lipo to merge them together, first drop down to the ffmpeg
+source folder:
+
+cd ..
+
+For each of the libraries:
+
+libavcodec
+
+libavdevice
+
+libavformat
+
+libavutil
+
+libswscale
+
+run the following lipo command (fill in the [libname]{.underline} in all
+places). For Leopard:
+
+sudo lipo -create
+build-ppc/[libname]{.underline}/[libname]{.underline}.dylib
+build-i386/[libname]{.underline}/[libname]{.underline}.dylib
+build-ppc64/[libname]{.underline}/[libname]{.underline}.dylib
+build-x86\_64/[libname]{.underline}/[libname]{.underline}.dylib -output
+/usr/local/lib/[libname]{.underline}.dylib
+
+For Tiger:
+
+sudo lipo -create
+build-ppc/[libname]{.underline}/[libname]{.underline}.dylib
+build-i386/[libname]{.underline}/[libname]{.underline}.dylib -output
+/usr/local/lib/[libname]{.underline}.dylib
+
+Done.
+
+© 2006-2008 by the GRASS Development Team
+
+This program is free software under the GNU General Public License
+(\>=v2).
+
+\- William Kyngesburye
+
+<kyngchaos@kyngchaos.com>
+
+<http://www.kyngchaos.com/>