doc/README.macosx

   1 Building Enigma under MacOS X 10.6, 10.5, and 10.4
   2
   3 Overview:
   4 ---------
   5
   6 Due to which machines are available to Enigma developers, the latest
   7 version of Enigma has only been built under MacOS X 10.6. The
   8 instructions for building should apply identically under 10.4 and 10.5.
   9 The latest SDL library package no longer supports earlier versions of
  10 Mac OS and so Enigma has dropped support for 10.3 or earlier.
  11 Note that even though the build process is not run under Xcode,
  12 it does require that Xcode, which includes a number of developer tools,
  13 has been installed on the build machine.
  14
  15 Enigma is built from the command line using make. There is a make
  16 target that will create a Mac OS application bundle in a compressed
  17 disk image file, enigma.dmg. That file can be copied to a Mac without
  18 any special runtime environment having to be installed, and the Enigma
  19 app simply dropped into a folder to be ready to run. The following
  20 instructions allow you to build a universal binary that will run
  21 on both PowerPc and Intel Macs running MacOS 10.4 or later.
  22
  23 You do need some other packages installed in order to build Enigma on
  24 your MacOS X system. Earlier versions of this README used packages
  25 installed from Macports. That is no longer necessary. These instructions
  26 have you install packages in /usr/local. It is possible for libraries in
  27 that directory to conflict with other version of the same library that
  28 have been installed by Macports in its default /opt/local directory.
  29 If you normally use Macports, it may be advisable to temporarily rename
  30 /opt/local and your current /usr/local to get them out of the way,
  31 install your Enigma build environment in a  fresh /usr/local, then
  32 rename that to something like /usr/local-enigma to save it for the next
  33 time you need to build Enigma, restoring the original /opt/local and /usr/local.
  34
  35 One step in the build process uses the program mkalias which is part of osxutils,
  36 a package that can be downloaded from http://sourceforge.net/projects/osxutils/
  37 under the terms of the GNU GPL. It installs into /usr/local. If you are
  38 using a special version of /usr/local for the Enigma build, be sure to install
  39 osxutils after you have switched to that /usr/local.
  40
  41 Step 0: Create a text file to contain a shell script that you will use to
  42 build universal binaries that will work for MacOS 10.4, 10.5, and 10.6.
  43 You can name the file whatever you like, but in this README it will be
  44 referred to as builduniversal.sh. Place it somewhere convenient such as
  45 in a ~/bin directory. If you place it there and make ~/bin part of your PATH,
  46 you can refer to builduniversal.sh just by name in command lines and scripts.
  47 If you don't place it in your PATH make sure that you use the full path name
  48 wherever there is a command in the following that just says builduniversal.sh.
  49
  50 Here are the contents of builduniversal.sh:
  51
  52 #!/bin/sh
  53 # build a package for universal 10.4+ if it is configured in standard way
  54 # does the configure but not the make or make install
  55 # You can add arguments to be passed to configure
  56 # You can pass in prefix values in CFLAGS, CXXFLAGS, LDFLAGS environment variables
  57 MACOSX_DEPLOYMENT_TARGET=10.4 \
  58 UNIFLAGS="-isysroot /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.4 -arch i386 -arch ppc" \
  59 CC=/usr/bin/gcc-4.0 \
  60 CXX=/usr/bin/g++-4.0 \
  61 CFLAGS="$CFLAGS $UNIFLAGS" \
  62 CXXFLAGS="$CXXFLAGS $UNIFLAGS" \
  63 LDFLAGS="$LDFLAGS $UNIFLAGS  -Wl,-syslibroot,/Developer/SDKs/MacOSX10.4u.sdk" \
  64 ./configure --disable-dependency-tracking $*
  65
  66 Step 0b: You must make sure that the following is executed in any shell that you
  67 use during the build process. Either type this at the command line when you open
  68 a shell or put it in your ~/.profile file so it is executed automatically when you
  69 open a command line shell
  70
  71 export MACOSX_DEPLOYMENT_TARGET=10.4
  72
  73 Step 1. Download the required SDL 1.2.x libraries and related packages. At each
  74 of the following web pages you will find both a prebuilt binary framework
  75 for MacOS X in the form of a .dmg file, and the sources in the form of a
  76 compressed tar file (tar.gz, also called a 'tarball'). You will need to download both of
  77 those for each of the four packeges listed below. Note that there is a version 1.3.x
  78 of SDL that Enigma does not support. You need SDL 1.2.14, which is the last
  79 to be released in the 1.2. series. The other packages have their own version numbers.
  80
  81 SDL         http://www.libsdl.org/
  82 SDL_image   http://www.libsdl.org/projects/SDL_image/
  83 SDL_ttf     http://www.libsdl.org/projects/SDL_ttf/
  84 SDL_mixer   http://www.libsdl.org/projects/SDL_mixer/
  85
  86 Step 2: For each of the four .dmg files downloaded in Step 1, double click
  87 the dmg file to open it in the Finder, then drag the Framework folder that is revealed
  88 into the /Library/Frameworks folder. Note that the system may ask you to enter
  89 your password to authenticate yourself as an administrator. We will use the
  90 four tarballs of source code you downloaded in a later step.
  91
  92 Step 3: Download the source tarballs of the following libraries from the
  93 web sites that are indicated. In each case download the latest stable version.
  94
  95 libjpeg  http://www.ijg.org/
  96 libpng   http://www.libpng.org/pub/png/libpng.html
  97 xerces-c http://xerces.apache.org/xerces-c/build-3.html
  98 gettext  http://www.gnu.org/software/gettext/#TOCdownloading
  99
 100 Step 5. Unpack each of the source tarballs in any convenient directory.
 101 Each will go into its own subdirectory, as the tarballs are set up that way.
 102
 103 Step 6: Install the SDL library. This is the trickiest one to build as it requires a
 104 special build script that is downloaded from a bug report about SDL. The steps to build it:
 105
 106 Step 6a. Download the build script to some convenient directory.
 107 This command will get the file, naming it fatbuild.sh in the
 108 current directory.
 109
 110  curl -o fatbuild.sh "http://bugzilla.libsdl.org/attachment.cgi?id=453"
 111
 112 Step 6b. Copy the downloaded fatbuild.sh file to the build-scripts
 113 subdirectory of the unpacked SDL sources, replacing the original one that is there,
 114 then cd to the sources directory. For example,
 115
 116  cp fatbuild.sh SDL-1.2.14/build-scripts/
 117  cd SDL-1.2.14
 118
 119 Step 6c: Build SDL using the following commands. The export command doesn't have to
 120 be repeated if you remembered to do it as mentioned in Step 0b.
 121
 122      export MACOSX_DEPLOYMENT_TARGET=10.4
 123      build-scripts/fatbuild.sh
 124      sudo build-scripts/fatbuild.sh install
 125
 126 Step 7. Install each of the other seven packages that you downloaded source tarballs for
 127 by unpacking them (each will go into its own subdirectory), cd to its directory,
 128 and run the commands (assuming you have placed builduniversal.sh in your PATH)
 129
 130  builduniversal.sh
 131  make
 132  sudo make install
 133
 134 Step 8. Install ImageMagick, which is needed to generate the documentation
 135 during the build process. ImageMagick will not be part of Enigma, so it does not
 136 have to built as a universal binary as long as it can run on the build computer.
 137 To build it, download the current sources of ImageMagick from
 138   ftp://ftp.imagemagick.org/pub/ImageMagick/ImageMagick.tar.gz
 139 untar it into a convenient directory, cd to it, and build with the commands
 140
 141  ./configure
 142  make
 143  sudo make install
 144
 145 Step 9. Build Enigma:
 146
 147 Important: The configure step requires you to be logged in with access
 148 to the window system, i.e., either at the Mac keyboard or using remote
 149 screen sharing, and in a Terminal.app comand line. It will hang trying
 150 to test the SDL library if you are using ssh to log in remotely with no
 151 GUI screen.
 152
 153 Remember to perform Step 0b each time you open a new Termnal.app window.
 154
 155 Then cd to the Enigma directory tree and
 156 run the following commands which make use of the builduniversal.sh
 157 script file that was listed in step 0 and is assumed to be in your PATH
 158
 159 Important: If you have built in the Enigma directory tree before and
 160 made some change to the build environment, use make distclean to ensure
 161 that there are no files from the old build interfering with the new build
 162
 163 ./autogen.sh
 164 CFLAGS="-I/usr/local/include" CXXFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" builduniversal.sh
 165 make gmo
 166 make
 167 make macapp
 168
 169 That's it! If it all works, there will be a copy of enigma.dmg in the
 170 etc/ subdirectory and a copy of Enigma.app in etc/macfiles/
 171 subdirectory.