Adding upstream version 4:7.4.7.upstream/4%7.4.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 250 insertions, 0 deletions

diff --git a/README.cross b/README.cross
new file mode 100644
index 000000000..e416469fc
--- /dev/null
+++ b/README.cross
@@ -0,0 +1,250 @@
+Cross-compiling LibreOffice
+***************************
+
+Cross-compilation works, to various degree, to the following
+platforms: iOS, Android, and Raspbian.
+
+Note that this document has not been updated very often, and not
+everything here necessarily is true any more.
+
+
+General
+-------
+
+In GNU Autoconf terminology, "build" is the platform on which you are
+running a build of some software and "host" is the platform on which
+the software you are building will run. Only in the specific case of
+building compilers and other programming tools is the term "target"
+used to indicate the platform for which the tools your are building
+will produce code. As LibreOffice is not a compiler, the "target" term
+should not be used in the context of cross-compilation.
+
+(For a case where all three of "build", "host" and "target" are
+different: consider a gcc cross-compiler running on Windows, producing
+code for Android, where the cross-compiler itself was built on
+Linux. (This is a real case.) An interesting tidbit is that such
+configurations are called "Canadian Cross".)
+
+Even though the LibreOffice build mechanism is highly unorthodox, the
+configure script takes the normal --build and --host options like any
+GNU Autoconf -based configure script. To cross-compile, you basically
+need just to specify a suitable --host option and things should work
+out nicely. In practice, many details need to be handled. See examples
+below.
+
+Note that in the case of LibreOffice, it is uncommon to run the
+configure script directly. Normally one uses the autogen.sh script.
+The autogen.sh script reads command-line options from file called
+autogen.input if it exists. The typical way of working is to keep
+the configure parameters in that file and edit it as needed.
+
+
+What is so hard, then?
+----------------------
+
+Despite the fact that the configure script takes normal --build and
+--host options, that is just the beginning. It was necessary to
+separate tests for "host" and "build" platforms in the configure
+script. See the git log for details. And the reasonably "standard"
+configure.in is just the top level; when we get down to the actual
+makefilery used to build the bits of LibreOffice, it gets much worse.
+
+
+iOS
+***
+
+iOS is the operating system on Apple's mobile devices. Clearly for a
+device like the iPad it would not be acceptable to run a normal
+LibreOffice application with overlapping windows and mouse-oriented
+GUI widgets.
+
+It makes sense to use only a part of LibreOffice's code for iOS. Lots
+of the GUI-oriented code should be left out. iOS apps that want to use
+the applicable LibreOffice code will handle all their GUI in a
+platform-dependent manner. How well it will be possible to do such a
+split remains to be seen.
+
+Obviously we want it to be possible to eventually distribute apps
+using LibreOffice code through the App Store. Technically, one
+important special aspect of iOS is that apps in the App Store are not
+allowed to load own dynamic libraries. (System libraries are used in
+the form of dynamic libraries, just like on macOS, of which iOS is
+a variant.)
+
+Thus all the libraries in LibreOffice that normally are shared
+libraries (DLLs on Windows, shared objects (.so) on Linux, dynamic
+libraries on macOS (.dylib)) must be built as static archives
+instead. This has some interesting consequences for how UNO is
+implemented and used.
+
+An iOS app is a "bundle" that contains a single executable. In an app
+using LibreOffice code, that executable then contains the necessary
+LibreOffice libraries and UNO components statically linked.
+
+The Apple tool-chain for iOS cross-building is available only for OS
+X. In order to be able to run and debug an app on an actual device
+(and not just the iOS Simulator) you need to be registered in the iOS
+Developer Program.
+
+Here is an autogen.input for iOS (device) using Xcode 4.6, on macOS 10.8:
+
+--build=i386-apple-darwin10.7.0
+--host=arm-apple-darwin10
+--enable-dbgutil
+--enable-debug
+--enable-werror
+
+For the iOS Simulator, but note that building for the simulator is
+broken at the moment (July 2014):
+
+--build=i386-apple-darwin10.7.0
+--host=arm-apple-darwin10
+--enable-ios-simulator
+--enable-dbgutil
+--enable-debug
+--enable-werror
+
+You will have to install autoconf and automake yourself before running
+autogen.sh. They are no longer included in Xcode 4.3 and later (not
+even in the add-on "command line tools").
+
+The -mmacosx-version-min=10.7 is necessary when building for the iOS
+simulator to avoid clang replacing simple calls to fprintf with calls
+to fwrite$UNIX2003 which Xcode then warns that doesn't exist on iOS.
+
+
+Android
+*******
+
+From a technical point of view the core Android OS (the kernel) is
+Linux, but everything else is different. Unlike iOS, an Android app
+can use shared objects just fine, so that aspect of UNO doesn't need
+special handling. Except that there is a silly low limit in the
+Android dynamic linker on the number of libraries you can dlopen. This
+is a limitation in user-level (but system-provided and not really
+replaceable) code, not the kernel.
+
+Thus, just like for iOS, also for Android the LibreOffice libraries
+and UNO components are built as static archives. For Android, those
+static archives, and any app-specific native code, are linked into one
+single app-specific shared library, called liblo-native-code.so.
+
+For the GUI, the same holds as said above for iOS. The GUI layer needs
+to be platform-specific, written in Java.
+
+Android cross-compilation work has been done mainly on Linux (openSUSE
+in particular). Earlier also cross-compiling from macOS was tried. The
+Android cross-compilation tool-chain (the "Native Development Kit", or
+NDK) is available for Linux, macOS and Windows, but trying to
+cross-compile LibreOffice from Windows will probably drive you insane.
+
+You will also need the Android SDK as full "make" also builds a couple
+of Android apps where the upper layer is written in Java.
+
+Use the "android" tool from the SDK to install the SDK Tools, SDK
+Platform Tools, the API 15 SDK Platform and the Android Support
+Library. If you want to run the Android apps in the emulator, you of
+course need an appropriate system image for that.
+
+Here is an autogen.input for Android on ARM when cross-compiling
+from Linux:
+
+--enable-dbgutil
+--enable-werror
+--with-distro=LibreOfficeAndroid
+--with-android-sdk=/path/to/android/sdk
+--with-android-ndk=/path/to/android/sdk/ndk/version
+
+And here is an (quite old) autogen.input for Android on X86:
+
+--with-android-ndk=/opt/libreoffice/android-ndk-r8b
+--with-android-ndk-toolchain-version=4.6
+--with-android-sdk=/opt/libreoffice/android-sdk-linux
+--build=i586-suse-linux
+--enable-ccache
+--with-distro=LibreOfficeAndroidX86
+
+A LibreOffice app for Android is being developed progress in the
+android/source directory.
+
+To run the app, do "make install" followed by either "make run" or
+starting it from Android itself. You most likely want to have an "adb logcat"
+running in another window. To debug, run "make debugrun".
+
+NB: If you happen to upgrade to Android SDK Tools 23, and the build (using
+'make verbose=t android') fails for you with:
+
+       [dx] UNEXPECTED TOP-LEVEL EXCEPTION:
+       [dx] java.io.FileNotFoundException: /local/libreoffice/android-sdk-linux/tools/support/annotations.jar (no such file or directory)
+
+you need to copy the annotations.jar from an older sdk; like
+
+wget 'http://dl-ssl.google.com/android/repository/tools_r22.6.2-linux.zip'
+unzip tools_r22.6.2-linux.zip
+cp tools/support/annotations.jar <android-sdk-linux>/tools/support/
+
+Raspbian
+********
+
+In theory, this should work also for another Linux, it does not need to be Raspbian.
+But this cross-compilation work is tested from Debian and openSUSE to Raspbian.
+
+You will need headers, pkg-config files and libraries from a Raspbian
+system to build against. Available at
+https://dev-www.libreoffice.org/extern/ . Look for the latest
+raspbian-root-*.tar.gz . For instance:
+
+$ wget https://dev-www.libreoffice.org/extern/raspbian-root-20140120.tar.gz
+$ mkdir raspbian-root
+$ cd raspbian-root
+$ tar -xf raspbian-root-20140120.tar.gz
+
+You can build cross-compiler yourself or get the executables here:
+$ git clone git://github.com/raspberrypi/tools
+
+tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian is known to work.
+
+Then create pkg-config wrapper, something like:
+$ cat > pkg-config-wrapper-host << _EOF
+#!/bin/sh
+
+if [ "$CROSS_COMPILING" = TRUE ]; then
+   SYSROOT=$HOME/lo/raspbian-root
+   export PKG_CONFIG_PATH=${SYSROOT}/usr/lib/arm-linux-gnueabihf/pkgconfig:${SYSROOT}/usr/share/pkgconfig
+   export PKG_CONFIG_LIBDIR=${SYSROOT}/usr/lib/pkgconfig
+   export PKG_CONFIG_SYSROOT_DIR=${SYSROOT}
+fi
+
+exec pkg-config "\$@"
+_EOF
+$ chmod +x pkg-config-wrapper-host
+
+This does not work with pkg-config 0.23. 0.26 is known to work.
+
+And you are ready to build with autogen.input similar to:
+
+PKG_CONFIG=<path-to-pkg-config-wrapper-host>
+CC=<path-to-arm-linux-gnueabihf-gcc> --sysroot=<path-to-raspbian_rootfs>
+CXX=<path-to-arm-linux-gnueabihf-g++> --sysroot=<path-to-raspbian_rootfs>
+--build=x86_64-unknown-linux-gnu
+--host=arm-unknown-linux-gnueabihf
+--disable-sdk
+--enable-python=system
+PYTHON_CFLAGS=-I<path-to-raspbian_rootfs>/usr/include/python2.7
+PYTHON_LIBS=-lpython2.7
+--with-java
+JAVAINC=-I<path-to-raspbian_rootfs>/usr/lib/jvm/java-6-openjdk-armhf/include
+--with-system-cairo
+--with-system-cppunit
+--with-system-icu
+--with-system-neon
+--with-system-nss
+--with-system-openldap
+--with-system-openssl
+--with-system-redland
+
+Finally, when you are ready to run the binaries in Raspbian,
+you may need to get more system libraries, who knows.
+$ sudo apt-get install libreoffice # or similar
+That installs libreoffice too, which you don't need because you have
+just built one, but I don't know how to avoid it easily.