INSTALL.MacOSX

   1 Building LyX/Mac-2.0
   2 Ronald Florence <ron@18james.com>
   3 Modified by Bennett Helm <bennett.helm@fandm.edu>,
   4 Anders Ekberg <anek@mac.com>,
   5 Jean-Marc Lasgouttes <lasgouttes@lyx.org> and
   6 Stephan Witt <st.witt@gmx.de>.
   7
   8 LyX/Mac is built from the LyX source, the GPL-licensed Trolltech
   9 Qt/Mac library, and a custom application bundle.
  10
  11 You will need the MacOSX development tools. The procedure described
  12 here builds LyX linked with a shared Qt library. Also note that
  13 building LyX/Mac requires gcc version 4.0 or higher.
  14
  15 You may build LyX with different SDK versions resulting in different
  16 minimum required MacOSX versions. The first supported version is
  17 10.4 (Tiger) for which the build has to use gcc4.0.
  18
  19 PREREQUISITES
  20
  21 Note: Only Qt/Mac is needed for building official LyX releases, and
  22 so steps 2 and 3 can be skipped in these cases. Those wanting to
  23 build developmental versions must have automake and gettext as
  24 well.
  25
  26 1. Qt/Mac Opensource Edition, version 4.
  27 This library is GPL-licensed and can be downloaded from
  28 <http://trolltech.com/developer/downloads/qt/mac/>. To compile it,
  29 create a directory where you want to install Qt4. In the following,
  30 the full path to this directory is called /path/to/Qt4
  31 Decompress Qt/Mac in a convenient directory, cd to the top of the
  32 Qt source hierarcy, and enter:
  33
  34      ./configure -opensource -silent -shared -release -universal -fast \
  35        -no-exceptions -no-webkit -no-qt3support -no-javascript-jit -no-dbus \
  36        -nomake examples -nomake demos -nomake docs \
  37        -nomake tools -no-framework \
  38        -prefix /path/to/Qt4
  39      make
  40      make install
  41
  42 This will result in an Qt library set for i386 and ppc applications.
  43
  44 To build Qt with Tiger support run configure with:
  45
  46      CC=gcc-4.0 OBJC=gcc-4.0 CXX=g++-4.0 \
  47        ./configure -opensource -silent -shared -release -universal -fast \
  48        -sdk /Developer/SDKs/MacOSX10.4u.sdk \
  49        -no-exceptions -no-webkit -no-qt3support -no-javascript-jit -no-dbus \
  50        -nomake examples -nomake demos -nomake docs \
  51        -nomake tools -no-framework \
  52        -prefix /path/to/Qt4
  53
  54 To build the libraries with 64bit architecture you have to replace the
  55 "-universal" option with "-arch x86_64". Note: you cannot build Qt with
  56 32bit and 64bit mixed architecture mode. (At least not with Qt4.6)
  57 And the build with 64bit has known problems - so it's not recommended.
  58
  59
  60 2. [Needed only for developmental builds:] automake, version 1.10.1
  61 or higher (check with automake --version). Probably the easiest
  62 way to get this is to use MacPorts (from http://www.macports.org/)
  63 and install automake using
  64
  65      sudo port install automake
  66
  67 3. [Needed only for developmental builds:] gettext version >= 0.12
  68 (check with gettext --version). If the installed version is
  69 insufficient the easiest way to obtain a later version is to use
  70 MacPorts (from http://www.macports.org/) and install gettext
  71 using:
  72
  73      sudo port install gettext
  74
  75 4. pkg-config >= 0.9.0. Again, the simplest way is through MacPorts:
  76
  77      sudo port install pkgconfig
  78
  79
  80 5. To build with included spell checker (ASpell):
  81 The aspell library is GPL-licensed and can be downloaded from
  82 ftp://ftp.gnu.org/gnu/aspell or one of the mirrors.
  83 At the time of writing aspell-0.60.tar.gz is the current version.
  84 Unpack the tarball in the same directory where you placed the
  85 svn checkout or LyX tarball.
  86
  87 BUILD INSTRUCTIONS
  88
  89 In what follows, /path/to/LyX.app is the location where you want LyX
  90 to create the LyX binary. You should substitute something appropriate,
  91 like: ~/Desktop/LyX.app. Also, substitute the appropriate path to
  92 where you installed Qt for /path/to/Qt4 (as above).
  93
  94 Dependent on the Qt-libraries you have and the build system you're using
  95 you have to tell configure the compiler and compiler options to use.
  96 If your Qt-libraries don't match your compiler defaults you may
  97 adjust some environment variables to do so.
  98
  99 1. Environment
 100
 101 (a) Qt-4.6 libraries from Nokia or self compiled universal libs
 102
 103         Since MacOSX 10.6 the default is to compile 64bit applications.
 104         We have to change that with if on that build system.
 105
 106         export CPPFLAGS="-arch i386"
 107         export LDFLAGS="-arch i386"
 108
 109 (b) Qt-4.6 libraries 64bit
 110
 111         You're at least on MacOSX 10.6 and don't have to change anything.
 112         Note: Your LyX binary will run only on 10.6 64bit Intel machines.
 113         Additionally you'll have to provide your Qt libraries somehow...
 114         FIXME: actually this is a dream, 64bit LyX crashes on startup!
 115
 116 (c) Qt-4.6 libraries self compiled with Tiger support
 117
 118         You have to choose the gcc4.0 compiler suite and the correct SDK:
 119
 120         export CC=gcc-4.0
 121         export OBJC=gcc-4.0
 122         export CXX=g++-4.0
 123         export CPPFLAGS="-arch i386 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.4"
 124         export LDFLAGS="-arch i386 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.4"
 125
 126 (d) When working without pkgconfig or pkgconfig fails to detect frameworks
 127
 128    Current pkgconfig from macports is able to detect the frameworks Qt4 is using.
 129         The build of LyX succeeds because the frameworks are added automatically to the linker options.
 130         If you need to add them yourself because of link errors, e. g.
 131                 lyx Undefined symbols: "_FSPathMakeRef"...
 132         you have to verify the required frameworks with otool and add them to the LDFLAGS.
 133
 134         Check the output of
 135                 otool -L /path/to/QT4/lib/libQtGui.dylib
 136         and look for lines with Frameworks.
 137
 138         Currently there are two different Qt4 builds available for download:
 139         * with Tiger support it's with Carbon. You have to add
 140         export LDFLAGS="$LDFLAGS -framework ApplicationServices -framework Carbon -framework AppKit"
 141         * with Cocoa framework without Tiger support you have to add
 142         export LDFLAGS="$LDFLAGS -framework ApplicationServices -framework Cocoa -framework AppKit"
 143
 144         Note: The latter is untested.
 145
 146 2. Configure and build
 147
 148 (a) Official Releases (compile from tar-ball)
 149
 150         cd to the top of the LyX source hierarchy, and enter:
 151
 152      ./configure \
 153               --with-version-suffix=-2.0 \
 154                         --prefix=/path/to/LyX.app \
 155                         --with-qt4-dir=/path/to/Qt4
 156      make
 157      make install-strip
 158
 159 (Note that the --with-version-suffix=-2.0 option will result in LyX's
 160 user's directory being located at ~/Library/Application Support/LyX-2.0)
 161
 162
 163 (b) Developmental Versions (svn checkouts)
 164
 165 Building LyX from developmental sources requires a few more steps.
 166 Instead of the instructions above, do the following:
 167
 168         cd to the top of the LyX source hierarchy, and enter:
 169
 170      ./autogen.sh
 171      ./configure \
 172               --with-version-suffix=-2.0 \
 173               --disable-stdlib-debug \
 174                         --prefix=/path/to/LyX.app \
 175                         --with-qt4-dir=/path/to/Qt4
 176      make
 177      make install-strip
 178
 179 Note that by default svn versions use some extra debugging code that
 180 somewhat slows LyX down. If it is a real problem, you can pass the
 181 option --enable-build-type=release to configure.
 182
 183
 184 (c) Distribution build
 185
 186 The distribution package build of LyX is supported by the shell script
 187 "LyX-Mac-binary-release.sh" in the development sub-directory of the
 188 LyX source hierarchy.
 189
 190 Please read the script if you're about to make a distributable disk image.
 191
 192 To use it, cd to the top of the LyX source hierarchy, and enter:
 193
 194         sh development/LyX-Mac-binary-release.sh --with-qt4-dir=/path/to/Qt4
 195
 196 This script automates all steps of the build process.
 197 It detects the sources for Qt4, Aspell and Hunspell when placed in a
 198 sibling directory and builds them ready to use for LyX packaging.
 199 These libraries are then bundled with the LyX application as private
 200 frameworks. Therefore the Qt4 libraries are build as frameworks.
 201 Per default the resulting LyX application is build for ppc and i386
 202 to be usable on all systems from Tiger upwards.
 203
 204 The information on this page is believed to be accurate, has been used
 205 successfully on many systems and sites, and has benefited from the
 206 comments and suggestions of many users. Due to the variations in
 207 individual systems, this information is conveyed as is with no
 208 warranty of any kind.
 209
 210 For more information on LyX/Mac, see <http://wiki.lyx.org/Mac/Mac>.