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