Geografic-Information-System/macosx

:exclamation: Instructions below are not up-to-date. Update in progress.

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

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

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. 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 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 ↵

Platform [darwin] ==> ↵

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] ==> ↵

static or shared [shared] ==> ↵

could use static, since GRASS only needs a few of the progs

'#include' argument or NONE [<inttypes.h>] ==> ↵

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] ==> ↵

Documentation URL [http://netpbm.sourceforge.net/doc/] ==> ↵

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: 0.5

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] in all places). For Leopard:

sudo lipo -create \
    build-ppc/[LIBNAME]/[LIBNAME].dylib \
    build-i386/[LIBNAME]/[LIBNAME].dylib \
    build-ppc64/[LIBNAME]/[LIBNAME].dylib \
    build-x86_64/[LIBNAME]/[LIBNAME].dylib \
    -output /usr/local/lib/[LIBNAME].dylib

For Tiger:

sudo lipo -create \
    build-ppc/[LIBNAME]/[LIBNAME].dylib \
    build-i386/[LIBNAME]/[LIBNAME].dylib \
    -output /usr/local/lib/[LIBNAME].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/