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
  28 This library is GPL-licensed and can be downloaded from
  29 <http://trolltech.com/developer/downloads/qt/mac/>.
  30 An alternative location is <ftp://ftp.qt.nokia.com/qt/source>.
  31 To compile it, create a directory where you want to install Qt4.
  32 In the following, the full path to this directory is called /path/to/Qt4
  33 Decompress Qt/Mac in a convenient directory, cd to the top of the
  34 Qt source hierarcy, and enter:
  35
  36      ./configure -opensource -silent -shared -release -universal -fast \
  37        -no-exceptions -no-webkit -no-qt3support -no-javascript-jit -no-dbus \
  38        -nomake examples -nomake demos -nomake docs \
  39        -nomake tools -no-framework \
  40        -prefix /path/to/Qt4
  41      make
  42      make install
  43
  44 This will result in an Qt library set for i386 and ppc applications.
  45
  46 To build Qt with Tiger support run configure with:
  47
  48      CC=gcc-4.0 OBJC=gcc-4.0 CXX=g++-4.0 \
  49        ./configure -opensource -silent -shared -release -universal -fast \
  50        -sdk /Developer/SDKs/MacOSX10.4u.sdk \
  51        -no-exceptions -no-webkit -no-qt3support -no-javascript-jit -no-dbus \
  52        -nomake examples -nomake demos -nomake docs \
  53        -nomake tools -no-framework \
  54        -prefix /path/to/Qt4
  55
  56 To build the libraries with 64bit architecture you have to replace the
  57 "-universal" option with "-arch x86_64". Note: you cannot build Qt with
  58 32bit and 64bit mixed architecture mode. (At least not with Qt4.6)
  59 And the build with 64bit has known problems - so it's not recommended.
  60
  61 Furthermore Apples developer documentation states:
  62 "Although 64-bit executables make it easier for you to manage large
  63 data sets ..., the use of 64-bit executables may raise other issues.
  64 Therefore you should transition your software to a 64-bit executable
  65 format only when the 64-bit environment offers a compelling advantage
  66 for your specific purposes."
  67
  68
  69 2. [Needed only for developmental builds:] automake, version 1.10.1
  70 or higher (check with automake --version). Probably the easiest
  71 way to get this is to use MacPorts (from http://www.macports.org/)
  72 and install automake using
  73
  74      sudo port install automake
  75
  76
  77 3. [Needed only for developmental builds:] gettext version >= 0.18
  78 (check with gettext --version). If the installed version is
  79 insufficient the easiest way to obtain a later version is to use
  80 MacPorts (from http://www.macports.org/) and install gettext
  81 using:
  82
  83      sudo port install gettext
  84
  85
  86 4. pkg-config >= 0.9.0. Again, the simplest way is through MacPorts:
  87
  88      sudo port install pkgconfig
  89
  90
  91 5. To build with included spell checker (ASpell):
  92 The aspell library is GPL-licensed and can be downloaded from
  93 ftp://ftp.gnu.org/gnu/aspell or one of the mirrors.
  94 At the time of writing aspell-0.60.tar.gz is the current version.
  95 Unpack the tarball in the same directory where you placed the
  96 git checkout or LyX tarball.
  97
  98 BUILD INSTRUCTIONS
  99
 100 In what follows, /path/to/LyX.app is the location where you want LyX
 101 to create the LyX binary. You should substitute something appropriate,
 102 like: ~/Desktop/LyX.app. Also, substitute the appropriate path to
 103 where you installed Qt for /path/to/Qt4 (as above).
 104
 105 Dependent on the Qt-libraries you have and the build system you're using
 106 you have to tell configure the compiler and compiler options to use.
 107 If your Qt-libraries don't match your compiler defaults you may
 108 adjust some environment variables to do so.
 109
 110
 111 1. Environment
 112
 113 (a) Qt-4.6 self compiled universal libs
 114
 115    Since MacOSX 10.6 the default is to compile 64bit applications.
 116    We have to change the default if using that build system.
 117
 118    export CPPFLAGS="-arch i386"
 119    export LDFLAGS="-arch i386"
 120
 121 (b) Qt-4.6 libraries 64bit
 122
 123    You're at least on MacOSX 10.6 and don't have to change anything.
 124    Note: Your LyX binary will run only on 10.6 64bit Intel machines.
 125    Additionally you'll have to provide your Qt libraries somehow...
 126    FIXME: actually this is a dream, 64bit LyX crashes on startup!
 127
 128 (c) Qt-4.6 self compiled libraries with Tiger support
 129
 130    You have to choose the gcc4.0 compiler suite and the correct SDK:
 131
 132    export CC=gcc-4.0
 133    export OBJC=gcc-4.0
 134    export CXX=g++-4.0
 135    export CPPFLAGS="-arch i386 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.4"
 136    export LDFLAGS="-arch i386 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.4"
 137
 138 (d) When working without pkgconfig or pkgconfig fails to detect Carbon and Appkit frameworks
 139
 140    Current pkgconfig from macports is able to detect the frameworks Qt4 is using.
 141    The build of LyX succeeds because the frameworks are added automatically to the linker options.
 142    If you need to add them yourself because of link errors, e. g.
 143       lyx Undefined symbols: "_FSPathMakeRef"...
 144    you have to verify the required frameworks with otool and add them to the LDFLAGS.
 145
 146    Check the output of
 147       otool -L /path/to/QT4/lib/libQtGui.dylib
 148    and look for lines with Frameworks.
 149
 150    Currently there are two different Qt4 builds available for download:
 151    * with Tiger support it's with Carbon. You have to add
 152    export LDFLAGS="$LDFLAGS -framework ApplicationServices -framework Carbon -framework AppKit"
 153    * with Cocoa framework without Tiger support you have to add
 154    export LDFLAGS="$LDFLAGS -framework ApplicationServices -framework Cocoa -framework AppKit"
 155
 156    Note: The latter is untested.
 157
 158 (e) When working with the Qt4 frameworks provided by Nokia
 159
 160    We have to help again with some environment variables to make configure work.
 161
 162    In case pkgconfig is installed... disable it.
 163    The Qt4 frameworks come without the required .pc files.
 164
 165    export PKG_CONFIG=""
 166
 167    The required compiler flags to compile a Qt4 application has to be provided.
 168
 169    export QT_CORE_CFLAGS="-FQtCore"
 170    export QT_CORE_LIBS="-framework QtCore"
 171    export QT_FRONTEND_CFLAGS="-FQtGui"
 172    export QT_FRONTEND_LIBS="-framework QtGui"
 173
 174    Depending on the architecture and target os add the compiler flags:
 175
 176    - for default SDK
 177    export CPPFLAGS="-arch i386"
 178    export CPPFLAGS="$CPPFLAGS -I/Library/Frameworks/QtCore.framework/Headers"
 179    export CPPFLAGS="$CPPFLAGS -I/Library/Frameworks/QtGui.framework/Headers"
 180    export LDFLAGS="-arch i386 -framework ApplicationServices -framework Carbon -framework AppKit"
 181
 182    - or to force 10.5 SDK
 183
 184    export CPPFLAGS="-arch i386 -isysroot /Developer/SDKs/MacOSX10.5.sdk -mmacosx-version-min=10.4"
 185    export CPPFLAGS="$CPPFLAGS -I/Developer/SDKs/MacOSX10.5.sdk/Library/Frameworks/QtCore.framework/Headers"
 186    export CPPFLAGS="$CPPFLAGS -I/Developer/SDKs/MacOSX10.5.sdk/Library/Frameworks/QtGui.framework/Headers"
 187    export LDFLAGS="-arch i386 -isysroot /Developer/SDKs/MacOSX10.5.sdk -mmacosx-version-min=10.4"
 188    export LDFLAGS="$LDFLAGS -framework ApplicationServices -framework Carbon -framework AppKit"
 189
 190    Note: it may depend on Qt4 frameworks what actually works.
 191    The 4.6.2 frameworks has to be used with 10.5 SDK.
 192
 193
 194 2. Configure and build
 195
 196 (a) Official Releases (compile from tar-ball)
 197
 198    cd to the top of the LyX source hierarchy, and enter:
 199
 200      ./configure \
 201          --with-version-suffix=-2.0 \
 202          --with-libiconv-prefix=/usr \
 203          --with-x=no \
 204          --prefix=/path/to/LyX.app \
 205          --with-qt-dir=/path/to/Qt4
 206      make
 207      make install-strip
 208
 209 (Note that the --with-version-suffix=-2.0 option will result in LyX's
 210 user's directory being located at ~/Library/Application Support/LyX-2.0)
 211
 212
 213 (b) Developmental Versions (git checkouts)
 214
 215 Building LyX from developmental sources requires a few more steps.
 216 Instead of the instructions above, do the following:
 217
 218    cd to the top of the LyX source hierarchy, and enter:
 219
 220      ./autogen.sh
 221      ./configure \
 222          --with-version-suffix=-2.0 \
 223          --with-libiconv-prefix=/usr \
 224          --with-x=no \
 225          --disable-stdlib-debug \
 226          --prefix=/path/to/LyX.app \
 227          --with-qt-dir=/path/to/Qt4
 228      make
 229      make install-strip
 230
 231
 232 (c) Distribution build
 233
 234 The distribution package build of LyX is supported by the shell script
 235 "LyX-Mac-binary-release.sh" in the development sub-directory of the
 236 LyX source hierarchy.
 237
 238 Please read the script if you're about to make a distributable disk image.
 239
 240 To use it, cd to the top of the LyX source hierarchy, and enter:
 241
 242    sh development/LyX-Mac-binary-release.sh --with-qt-dir=/path/to/Qt4
 243
 244 This script automates all steps of the build process.
 245 It detects the sources for Qt4, Aspell and Hunspell when placed in a
 246 sibling directory and builds them ready to use for LyX packaging.
 247 These libraries are then bundled with the LyX application as private
 248 frameworks. Therefore the Qt4 libraries are build as frameworks.
 249 Per default the resulting LyX application is build for ppc and i386
 250 to be usable on all systems from Tiger upwards.
 251
 252
 253 (d) Development Versions (git checkouts and Qt4 frameworks)
 254
 255 Instead of the instructions in (b), do the following:
 256
 257    cd to the top of the LyX source hierarchy, and enter:
 258
 259      ./autogen.sh
 260      ./configure \
 261          --with-version-suffix=-2.0 \
 262          --with-libiconv-prefix=/usr \
 263          --with-x=no \
 264          --disable-stdlib-debug \
 265          --prefix=/path/to/LyX.app
 266      make
 267      make install-strip
 268
 269    Note: The produced binary depends on the frameworks in location
 270    /Library/Frameworks.  These frameworks have to match the frameworks
 271    you used on build.
 272
 273
 274 3. Disclaimer
 275
 276 The information on this page is believed to be accurate, has been used
 277 successfully on many systems and sites, and has benefited from the
 278 comments and suggestions of many users. Due to the variations in
 279 individual systems, this information is conveyed as is with no
 280 warranty of any kind.
 281
 282 For more information on LyX/Mac, see <http://wiki.lyx.org/Mac/Mac>.