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>.
8 LyX/Mac is built from the LyX source, the GPL-licensed Trolltech
9 Qt/Mac library, and a custom application bundle.
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.
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.
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
26 1. Qt/Mac Opensource Edition, version 4.
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:
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 \
44 This will result in an Qt library set for i386 and ppc applications.
46 To build Qt with Tiger support run configure with:
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 \
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.
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."
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
74 sudo port install automake
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
83 sudo port install gettext
86 4. pkg-config >= 0.9.0. Again, the simplest way is through MacPorts:
88 sudo port install pkgconfig
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 svn checkout or LyX tarball.
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).
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.
113 (a) Qt-4.6 self compiled universal libs
115 Since MacOSX 10.6 the default is to compile 64bit applications.
116 We have to change the default if using that build system.
118 export CPPFLAGS="-arch i386"
119 export LDFLAGS="-arch i386"
121 (b) Qt-4.6 libraries 64bit
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!
128 (c) Qt-4.6 self compiled libraries with Tiger support
130 You have to choose the gcc4.0 compiler suite and the correct SDK:
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"
138 (d) When working without pkgconfig or pkgconfig fails to detect Carbon and Appkit frameworks
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.
147 otool -L /path/to/QT4/lib/libQtGui.dylib
148 and look for lines with Frameworks.
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"
156 Note: The latter is untested.
158 (e) When working with the Qt4 frameworks provided by Nokia
160 We have to help again with some environment variables to make configure work.
162 In case pkgconfig is installed... disable it.
163 The Qt4 frameworks come without the required .pc files.
167 The required compiler flags to compile a Qt4 application has to be provided.
169 export QT4_CORE_CFLAGS="-FQtCore"
170 export QT4_CORE_LIBS="-framework QtCore"
171 export QT4_FRONTEND_CFLAGS="-FQtGui"
172 export QT4_FRONTEND_LIBS="-framework QtGui"
174 Depending on the architecture and target os add the compiler flags:
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"
182 - or to force 10.5 SDK
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"
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.
194 2. Configure and build
196 (a) Official Releases (compile from tar-ball)
198 cd to the top of the LyX source hierarchy, and enter:
201 --with-version-suffix=-2.0 \
202 --with-libiconv-prefix=/usr \
204 --prefix=/path/to/LyX.app \
205 --with-qt4-dir=/path/to/Qt4
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)
213 (b) Developmental Versions (svn checkouts)
215 Building LyX from developmental sources requires a few more steps.
216 Instead of the instructions above, do the following:
218 cd to the top of the LyX source hierarchy, and enter:
222 --with-version-suffix=-2.0 \
223 --with-libiconv-prefix=/usr \
225 --disable-stdlib-debug \
226 --prefix=/path/to/LyX.app \
227 --with-qt4-dir=/path/to/Qt4
231 Note that by default svn versions use some extra debugging code that
232 somewhat slows LyX down. If it is a real problem, you can pass the
233 option --enable-build-type=release to configure.
236 (c) Distribution build
238 The distribution package build of LyX is supported by the shell script
239 "LyX-Mac-binary-release.sh" in the development sub-directory of the
240 LyX source hierarchy.
242 Please read the script if you're about to make a distributable disk image.
244 To use it, cd to the top of the LyX source hierarchy, and enter:
246 sh development/LyX-Mac-binary-release.sh --with-qt4-dir=/path/to/Qt4
248 This script automates all steps of the build process.
249 It detects the sources for Qt4, Aspell and Hunspell when placed in a
250 sibling directory and builds them ready to use for LyX packaging.
251 These libraries are then bundled with the LyX application as private
252 frameworks. Therefore the Qt4 libraries are build as frameworks.
253 Per default the resulting LyX application is build for ppc and i386
254 to be usable on all systems from Tiger upwards.
257 (d) Developmental Versions (svn checkouts and Qt4 frameworks)
259 Instead of the instructions in (b), do the following:
261 cd to the top of the LyX source hierarchy, and enter:
265 --with-version-suffix=-2.0 \
266 --with-libiconv-prefix=/usr \
268 --disable-stdlib-debug \
269 --prefix=/path/to/LyX.app
273 Note: The produced binary depends on the frameworks in location
274 /Library/Frameworks. These frameworks have to match the frameworks
280 The information on this page is believed to be accurate, has been used
281 successfully on many systems and sites, and has benefited from the
282 comments and suggestions of many users. Due to the variations in
283 individual systems, this information is conveyed as is with no
284 warranty of any kind.
286 For more information on LyX/Mac, see <http://wiki.lyx.org/Mac/Mac>.