Update credits

[lyx.git] / INSTALL.MacOSX

diff --git a/INSTALL.MacOSX b/INSTALL.MacOSX
index 68767b3e96d59fb989f840a21d2f274ce7189e44..3acceb66a088e82a09dd16893db165e1fbcc8bb4 100644 (file)
--- a/INSTALL.MacOSX
+++ b/INSTALL.MacOSX
@@ -1,74 +1,277 @@
-Building LyX/Mac-1.5
+Building LyX/Mac-2.0

 Ronald Florence <ron@18james.com>
 Ronald Florence <ron@18james.com>

-Modified by Bennett Helm <bennett.helm@fandm.edu> and by Anders
-Ekberg <anek@mac.com>.
+Modified by Bennett Helm <bennett.helm@fandm.edu>,
+Anders Ekberg <anek@mac.com>,
+Jean-Marc Lasgouttes <lasgouttes@lyx.org> and
+Stephan Witt <st.witt@gmx.de>.

 
 LyX/Mac is built from the LyX source, the GPL-licensed Trolltech
 Qt/Mac library, and a custom application bundle.
 
 You will need the MacOSX development tools. The procedure described
 
 LyX/Mac is built from the LyX source, the GPL-licensed Trolltech
 Qt/Mac library, and a custom application bundle.
 
 You will need the MacOSX development tools. The procedure described

-here builds LyX linked with a static Qt library. 
+here builds LyX linked with a shared Qt library. Also note that
+building LyX/Mac requires gcc version 4.0 or higher.
+
+You may build LyX with different SDK versions resulting in different
+minimum required MacOSX versions. The first supported version is
+10.4 (Tiger) for which the build has to use gcc4.0.

 
 PREREQUISITES
 
 
 PREREQUISITES
 

-1. Qt/Mac Free Edition, version 4. This library is GPL-licensed
-and can be downloaded from
-<http://www.trolltech.com/download/qt/mac.html>. You will need to 
-compile it yourself (as described below).
-
-2. automake, version 1.5 or higher (check with automake --version). 
-Probably the easiest way to get this is to use DarwinPorts (from
-http://darwinports.opendarwin.org/getdp/) and install automake
-using
-    sudo port install automake
-
-3.  gettext version >= 0.12 (check with gettext --version)
-If the installed version is insufficient the 
-easiest way to obtain a later version is to get DarwinPorts 
-(from http://darwinports.opendarwin.org/getdp/) and install gettext 
-using
+Note: Only Qt/Mac is needed for building official LyX releases, and
+so steps 2 and 3 can be skipped in these cases. Those wanting to
+build developmental versions must have automake and gettext as
+well.
+
+1. Qt/Mac Opensource Edition, version 4.
+
+This library is GPL-licensed and can be downloaded from
+<http://trolltech.com/developer/downloads/qt/mac/>.
+An alternative location is <ftp://ftp.qt.nokia.com/qt/source>.
+To compile it, create a directory where you want to install Qt4.
+In the following, the full path to this directory is called /path/to/Qt4
+Decompress Qt/Mac in a convenient directory, cd to the top of the
+Qt source hierarcy, and enter:
+
+     ./configure -opensource -silent -shared -release -universal -fast \
+       -no-exceptions -no-webkit -no-qt3support -no-javascript-jit -no-dbus \
+       -nomake examples -nomake demos -nomake docs \
+       -nomake tools -no-framework \
+       -prefix /path/to/Qt4
+     make
+     make install
+
+This will result in an Qt library set for i386 and ppc applications.
+
+To build Qt with Tiger support run configure with:
+
+     CC=gcc-4.0 OBJC=gcc-4.0 CXX=g++-4.0 \
+       ./configure -opensource -silent -shared -release -universal -fast \
+       -sdk /Developer/SDKs/MacOSX10.4u.sdk \
+       -no-exceptions -no-webkit -no-qt3support -no-javascript-jit -no-dbus \
+       -nomake examples -nomake demos -nomake docs \
+       -nomake tools -no-framework \
+       -prefix /path/to/Qt4
+
+To build the libraries with 64bit architecture you have to replace the
+"-universal" option with "-arch x86_64". Note: you cannot build Qt with
+32bit and 64bit mixed architecture mode. (At least not with Qt4.6)
+And the build with 64bit has known problems - so it's not recommended.
+
+Furthermore Apples developer documentation states:
+"Although 64-bit executables make it easier for you to manage large
+data sets ..., the use of 64-bit executables may raise other issues.
+Therefore you should transition your software to a 64-bit executable
+format only when the 64-bit environment offers a compelling advantage
+for your specific purposes."
+
+
+2. [Needed only for developmental builds:] automake, version 1.10.1
+or higher (check with automake --version). Probably the easiest
+way to get this is to use MacPorts (from http://www.macports.org/)
+and install automake using
+
+     sudo port install automake
+
+
+3. [Needed only for developmental builds:] gettext version >= 0.18
+(check with gettext --version). If the installed version is
+insufficient the easiest way to obtain a later version is to use
+MacPorts (from http://www.macports.org/) and install gettext
+using:
+

      sudo port install gettext
 
 
      sudo port install gettext
 
 

+4. pkg-config >= 0.9.0. Again, the simplest way is through MacPorts:
+
+     sudo port install pkgconfig
+
+
+5. To build with included spell checker (ASpell):
+The aspell library is GPL-licensed and can be downloaded from
+ftp://ftp.gnu.org/gnu/aspell or one of the mirrors.
+At the time of writing aspell-0.60.tar.gz is the current version.
+Unpack the tarball in the same directory where you placed the
+git checkout or LyX tarball.
+

 BUILD INSTRUCTIONS
 
 BUILD INSTRUCTIONS
 

-Note that building LyX/Mac requires gcc version 4.0 or higher. (You
-can check your version  by entering "gcc -v" in the Terminal; you
-can change your gcc version to version 4.0, for example, by entering
-"sudo gcc_select 4.0".)
+In what follows, /path/to/LyX.app is the location where you want LyX
+to create the LyX binary. You should substitute something appropriate,
+like: ~/Desktop/LyX.app. Also, substitute the appropriate path to
+where you installed Qt for /path/to/Qt4 (as above).

 
 

-1. Create a directory where you want to install QT4. In the following, 
-the full path to this directory is called /path/to/QT4
-Decompress Qt/Mac in a convenient directory, cd to the top of the
-Qt source hierarcy, and:
+Dependent on the Qt-libraries you have and the build system you're using
+you have to tell configure the compiler and compiler options to use.
+If your Qt-libraries don't match your compiler defaults you may
+adjust some environment variables to do so.
+
+
+1. Environment
+
+(a) Qt-4.6 self compiled universal libs
+
+   Since MacOSX 10.6 the default is to compile 64bit applications.
+   We have to change the default if using that build system.
+
+   export CPPFLAGS="-arch i386"
+   export LDFLAGS="-arch i386" 
+
+(b) Qt-4.6 libraries 64bit
+
+   You're at least on MacOSX 10.6 and don't have to change anything.
+   Note: Your LyX binary will run only on 10.6 64bit Intel machines.
+   Additionally you'll have to provide your Qt libraries somehow...
+   FIXME: actually this is a dream, 64bit LyX crashes on startup!
+
+(c) Qt-4.6 self compiled libraries with Tiger support
+
+   You have to choose the gcc4.0 compiler suite and the correct SDK:
+
+   export CC=gcc-4.0
+   export OBJC=gcc-4.0
+   export CXX=g++-4.0
+   export CPPFLAGS="-arch i386 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.4"
+   export LDFLAGS="-arch i386 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.4"
+
+(d) When working without pkgconfig or pkgconfig fails to detect Carbon and Appkit frameworks
+
+   Current pkgconfig from macports is able to detect the frameworks Qt4 is using.
+   The build of LyX succeeds because the frameworks are added automatically to the linker options.
+   If you need to add them yourself because of link errors, e. g.
+      lyx Undefined symbols: "_FSPathMakeRef"...
+   you have to verify the required frameworks with otool and add them to the LDFLAGS.
+
+   Check the output of
+      otool -L /path/to/QT4/lib/libQtGui.dylib
+   and look for lines with Frameworks.
+
+   Currently there are two different Qt4 builds available for download:
+   * with Tiger support it's with Carbon. You have to add
+   export LDFLAGS="$LDFLAGS -framework ApplicationServices -framework Carbon -framework AppKit" 
+   * with Cocoa framework without Tiger support you have to add
+   export LDFLAGS="$LDFLAGS -framework ApplicationServices -framework Cocoa -framework AppKit" 

 
 

-     ./configure -static -no-exceptions -nomake examples -nomake tools -prefix /path/to/QT4
+   Note: The latter is untested.
+
+(e) When working with the Qt4 frameworks provided by Nokia
+
+   We have to help again with some environment variables to make configure work.
+
+   In case pkgconfig is installed... disable it.
+   The Qt4 frameworks come without the required .pc files.
+
+   export PKG_CONFIG=""
+
+   The required compiler flags to compile a Qt4 application has to be provided.
+
+   export QT_CORE_CFLAGS="-FQtCore"
+   export QT_CORE_LIBS="-framework QtCore"
+   export QT_FRONTEND_CFLAGS="-FQtGui"
+   export QT_FRONTEND_LIBS="-framework QtGui"
+
+   Depending on the architecture and target os add the compiler flags:
+
+   - for default SDK
+   export CPPFLAGS="-arch i386"
+   export CPPFLAGS="$CPPFLAGS -I/Library/Frameworks/QtCore.framework/Headers"
+   export CPPFLAGS="$CPPFLAGS -I/Library/Frameworks/QtGui.framework/Headers"
+   export LDFLAGS="-arch i386 -framework ApplicationServices -framework Carbon -framework AppKit" 
+
+   - or to force 10.5 SDK
+
+   export CPPFLAGS="-arch i386 -isysroot /Developer/SDKs/MacOSX10.5.sdk -mmacosx-version-min=10.4"
+   export CPPFLAGS="$CPPFLAGS -I/Developer/SDKs/MacOSX10.5.sdk/Library/Frameworks/QtCore.framework/Headers"
+   export CPPFLAGS="$CPPFLAGS -I/Developer/SDKs/MacOSX10.5.sdk/Library/Frameworks/QtGui.framework/Headers"
+   export LDFLAGS="-arch i386 -isysroot /Developer/SDKs/MacOSX10.5.sdk -mmacosx-version-min=10.4"
+   export LDFLAGS="$LDFLAGS -framework ApplicationServices -framework Carbon -framework AppKit" 
+
+   Note: it may depend on Qt4 frameworks what actually works.
+   The 4.6.2 frameworks has to be used with 10.5 SDK.
+
+
+2. Configure and build
+
+(a) Official Releases (compile from tar-ball)
+
+   cd to the top of the LyX source hierarchy, and enter:
+
+     ./configure \
+         --with-version-suffix=-2.0 \
+         --with-libiconv-prefix=/usr \
+         --with-x=no \
+         --prefix=/path/to/LyX.app \
+         --with-qt-dir=/path/to/Qt4

      make
      make

-     make install
-     cd /path/to/QT4/lib
-     rm *.la
-     
-If you don't prescribe -nomake examples -nomake tools in the
-configuration you need to make sure you have some 20+ GB of free hard
-disk space. Else the installation is about 1GB.
+     make install-strip
+
+(Note that the --with-version-suffix=-2.0 option will result in LyX's
+user's directory being located at ~/Library/Application Support/LyX-2.0)

 
 
 
 

-2. The LyX/Mac application bundle skeleton (LyX.app) can be found in 
-the LyX source hierarchy at development/MacOSX. Copy this bundle to a
-directory. In the following, the full path to this directory is called
-/path/to/LyX.app. (The default settings assume that this path is
-/Applications/LyX.app.)
+(b) Developmental Versions (git checkouts)

 
 

-3. cd to the top of the LyX source hierarchy, and:
+Building LyX from developmental sources requires a few more steps.
+Instead of the instructions above, do the following:
+
+   cd to the top of the LyX source hierarchy, and enter:
+
+     ./autogen.sh
+     ./configure \
+         --with-version-suffix=-2.0 \
+         --with-libiconv-prefix=/usr \
+         --with-x=no \
+         --disable-stdlib-debug \
+         --prefix=/path/to/LyX.app \
+         --with-qt-dir=/path/to/Qt4
+     make
+     make install-strip
+
+
+(c) Distribution build
+
+The distribution package build of LyX is supported by the shell script
+"LyX-Mac-binary-release.sh" in the development sub-directory of the
+LyX source hierarchy.
+
+Please read the script if you're about to make a distributable disk image.
+
+To use it, cd to the top of the LyX source hierarchy, and enter:
+
+   sh development/LyX-Mac-binary-release.sh --with-qt-dir=/path/to/Qt4
+
+This script automates all steps of the build process.
+It detects the sources for Qt4, Aspell and Hunspell when placed in a
+sibling directory and builds them ready to use for LyX packaging.
+These libraries are then bundled with the LyX application as private
+frameworks. Therefore the Qt4 libraries are build as frameworks.
+Per default the resulting LyX application is build for ppc and i386
+to be usable on all systems from Tiger upwards.
+
+
+(d) Development Versions (git checkouts and Qt4 frameworks)
+
+Instead of the instructions in (b), do the following:
+
+   cd to the top of the LyX source hierarchy, and enter:

 
 

-     export LDFLAGS="-framework Carbon -framework OpenGL -framework AGL -framework QuickTime -lz -framework Cocoa"

      ./autogen.sh
      ./autogen.sh

-     ./configure --prefix=/path/to/LyX.app --disable-concept-checks --with-version-suffix=-1.5 --with-qt4-dir=/path/to/QT4 --enable-optimization=-Os --without-x --with-included-gettext --with-frontend=qt4 --disable-stdlib-debug
+     ./configure \
+         --with-version-suffix=-2.0 \
+         --with-libiconv-prefix=/usr \
+         --with-x=no \
+         --disable-stdlib-debug \
+         --prefix=/path/to/LyX.app

      make
      make install-strip
 
      make
      make install-strip
 

-(Note that the --with-version-suffix=-1.5 option will result in LyX's
-user's directory being located at ~/Library/Application Support/LyX-1.5.)
+   Note: The produced binary depends on the frameworks in location
+   /Library/Frameworks.  These frameworks have to match the frameworks
+   you used on build.
+
+
+3. Disclaimer

 
 The information on this page is believed to be accurate, has been used
 successfully on many systems and sites, and has benefited from the
 
 The information on this page is believed to be accurate, has been used
 successfully on many systems and sites, and has benefited from the