Documentation/Building Guide/Building on MacOSX

This document tries to wrap-up the build process for OpenOffice.org on MacOS X using the native windowing-toolkit of the platform named Aqua. The main goal is to get the demonstration programs "svdem" up and running. They act as a fairly good starting point to further endeavours, since they are used to test the capabilities of the underlying VCL layer. If this is achieved, one can build and Install the full-fledged OpenOffice.org Package. The bias of this document is to describe the cumbersome build process of OpenOffice.org rather than to give a kickstart in the coding involved to get VCL ported to Carbon. A starting point for this is Pierre de Filippis excellent Intro To Mac Porting.

I use the bash shell in all examples, since to my belief users of the C-shell are smart enough to figure out the differences anyway. If you want to dig deeper into the build process, please have a look at the description of the build enviroment here: Open OfficeBuild Environment.

Many thanks for help and assistance go to Pavel Janik and Eric Bachard.

Prerequisites

This document was derived from the description of the X11 build thanksworthy provided by Eric Hoch in this document: MacOSXBuildInstructions. Here i like to outline the things you need to buld the Aqua Version (besides the OS). Your are much better off to install the Fink Package Manager on your Apple, to resolve these dependencies (and get some cool stuff too). Go to Fink

Xcode

Xcode 2.2, 2.3 and 2.4 are known to work for Aqua development. Please add earlier versions work as well, please add them here.

Java 1.4.2+

The perl module Archive::Zip

[bash,N] perl -MCPAN -eshell install Archive::Zip

gpc

GPC is available here: ftp://ftp.cs.man.ac.uk/pub/toby/gpc/gpc231.tar.Z> Attention: Direct Link to the download but it's only a few hundred KB. Note: You can alternatively use the libart_lgpl library instead of GPC. This requires an additional configure flag (--enable-libart) and a precompiled libart library installed in a standard location, such as /usr/lib.

pkg-config

Called pkgconfig in Fink.

pkg-config can be found here : http://pkgconfig.freedesktop.org/wiki/

gnu copy

In Fink terms this is in the package fileutils.

If you prefer direct download, GNU coreutils can be found at http://www.gnu.org/software/coreutils/coreutils.html.

After installing, you should copy or rename the newly installed cp to gnucp (located at /usr/local/bin/cp or /sw/bin/cp if you used Fink) (cf. http://qa.openoffice.org/issues/show_bug.cgi?id=69711)

ccache (optional)

If you indend to build several times OpenOffice, you probably can benefit of ccache. ccache will speed up your future builds. The first time you make a build with ccache you won't notice it, but then the build will go up to five times faster.

You can install it using fink. It is simply named "ccache".

If you don't use fink, you can download it and build it yourself using the source provided at http://ccache.samba.org/

Then, in order to use it, you need to change the following environment variables : CC="ccache gcc" CXX="ccache g++"

Apache Ant 1.6.5 (optional)

Not Adviced : XCode does provide a perfectly working version of ant.

It is up to you if you prefer use this one.

An up to date version of ant is shipped with XCode.

For the OpenOffice Builds you need to have Apache's Ant in the source-directory. You have to have Ant Version 1.6.5+. My Ant usually resides in /opt/ant so i link it in from there: [bash,N]


cd src680-m187/
ln -s /opt/ant/ apache-ant-1.6.5

To set them, you just need to add these two previous parameters to your build.sh (see #One-Time preparations and scripts for details).

Some Backgroud (what is aquavcl01, EIS)

EIS

OpenOffice sources are basically kept in the CVS server located at anoncvs.services.openoffice.org. However this repository is managed by a database on top called EIS (Environment Information System) which is used to keep track of Master- and Client Workspaces. Master Workspaces are used to keep track of changes going back of the mainline trunk and undergo extensive QA-cycles. These Master Workspaces are driven to official releases. Child workspaces in contrast are copies of certain Master Workspaces used to develop and test bugfixes and additional functionality. These Child Workspaces are later (hopefully) merged back to mainlain Master Workspaces. The TX20 Report mentioned in the Links section gives a very good overview about the overall process. To learn more about Childworkspaces (CWS) have a look here: CWS.

Go to EIS http://eis.services.openoffice.org/EIS2/servlet/Logon and Logon as guest/guest to get yourself an impression. You can find information about the different workspaces, their dates and times there.

VCL (Visual Class Libraries)

Porting OpenOffice.org to a new Windowing Toolkit is mostly porting of the OpenOffice's VCL Layer (Visual Class Libraries) to the new platforms toolkit. The VCL-Layer is responsible of mapping the OpenOffice Application calls to the windowing toolkit.

The (native) OpenOffice port to MacOSX using the Aqua Windowing Toolkit is developed in a child workspace called aquavcl01. This child workspace consists of the modules (aka subdirs): canvas dtrans extensions freetype padmin scp2 sj2 solenv vcl.

The basic approach to prepare a developer's client system to succsessfully build OpenOffice/Aqua is the following:

checkout a given OpenOffice Milestone.
checkout aquavcl01 Child Workspace.
merge them together.
apply the latest patches.

The last point here is a cumbersome but nevertheless necessary operation, since this porting project is in flux. Thanks to Pavel and many others improvements are happening at tremendous pace at the moment. All of these improvements get distributed as patches/diffs against aquavcl01. Aquavcl01 needs to remain stable all the time, therefore the team needs to work on this patch-by-patch aproach at the moment.

Getting the code (checkout, merge and patch the puppy)

Now let's have a look what to check-out and where. All these milestone numbers below highly depend on the given point-in-time. The current milestone as of now (October 15th 2006) is m187. You may change this to your needs. You can finde the current milestone of each cws in the EIS database.

You also need to bear in mind that you have to access to the CVS-Server's default port (2401). If a firewall stop's you here you have to setup a CVS-Tunnel.

create a directory for a given milestone, setup CVS access:

[bash,N]


mkdir src680-m187
cd src680-m187

export CVSROOT=:pserver:anoncvs@anoncvs.services.openoffice.org:/cvs
cvs login

Please Enter the password 'anoncvs'

checkout Milestone m187 (1,5 GB):

[bash,N]


cvs -z3 co -r SRC680_m187 OpenOffice2

Once done, you'll obtain milestone 187. this not exactly what we want, because all changes concerning aquavcl01 Child workspace are not included. To complete, we need to check aquavcl01 changes.

checkout Aquavcl01 (50 MB):

1) First possibility : create a dedicated tree (cool backup )

To check aquavcl01 Child workspace, the most simple is to create aquavcl01 directory, and go inside this dir [bash,N]

mkdir aquavcl01-src 

cd aquavcl01-src

(assuming you arelady did cvs login ..etc )

[bash,N]


cvs -z3 co -r cws_src680_aquavcl01 OpenOffice2

The following modules will be present at the end :

canvas
extensions
filepicker
padmin
scp2
sfx2
solenv
dtrans
freetype
psprint
sj2
vcl

All these modules are the ones we modified to create the native version : they all are tagged "aquavcl01" (see all CVS/Tag files in the tree) and all you have to do is either rename or delete the one located in src680-m187 and replace them with the one located in aquavcl01-src.

e.g. : canvas in src680-m187 will become canvas_m187 , and then, cp canvas from aquavcl01-src into src-m187

This applies for all the modules listed above.

2) Second possibility : use a little script to extract changes : extract_aquavcl01.sh

This shell script, located in src680-m187 will contain : [bash,N]


#!/bin/bash
 list="canvas extensions filepicker padmin scp2 sfx2 solenv dtrans freetype psprint sj2 vcl"
 for i in $list ;  do 
    cd $i
    cvs up -j CWS_SRC680_AQUAVCL01_ANCHOR -j cws_src680_aquavcl01
    cd ..
 done

Then chmod +x extract_aquavcl01.sh

and run it :

./extract_aquavcl01.sh

When finished, and if no problem occurs, you should have a complete tree.

One-Time preparations and scripts

OpenOffice building gets configured by the popular open-source configuration-management package 'autoconf'. So you can do your beloved './configure' command, but in our case this is done in the 'config_office' subdirectory. To save the configure parameters and use them with different milestones I used to link-in my shellscript to fire up the ./configure line.

My directory-structure looks like this:

bin/
src680-m176/
src680-m182/
...

Now I go to the 'config_office' subdir and link in my startscript: [bash,N]


cd src680-m187/config_office/
ln -s ../../bin/build.sh

And this is how 'build.sh' looks like:

[bash,N]


#!/bin/sh
export BASE=`pwd|sed 's/\/config_office//'`
export OOVERSION=`echo $BASE|sed 's/^\/.*\///'`
echo Building from      : $BASE
echo OpenOffice Version : $OOVERSION
./configure \
--with-lang="de en-US" \
--with-jdk-home=/Library/Java/Home/ \
--with-gnu-cp=/sw/bin/cp \
--with-epm=internal \
--disable-mozab \
--disable-odk \
--disable-pasf \
--disable-gtk \
--disable-mozilla \
--with-build-version=$OOVERSION-`date +%d-%m-%y` \
--disable-fontconfig \
--disable-neon \
--without-nas

--disable-odl will avoid you to download some windows dll which is not needed for aqua-build. --disable-pasf : pasf stands for Portable Audio System file. As we want to use system library rather than portable ones, we disabled this. However, at this time not all functionality will be available with pasf disabled. You might willing to use --with-pasf if you want working audio in your build. --disable-nas : nas stands for Network Audio System, it uses X11, if you want to use it in your build, just remove this flag. You will need to install the X11 package provided in your CDs/DVD Mac OS X installation. X11 SDK from xCode tools is not required for build this.

This is allowedly a pretty much limited setup, but my overall goal is to get people to have 'svdem' build to start coding rather than to have a production ready build for the final release. Therefore I switched off most of the stuff. How these offical builds are done in the long run is to be decided when we get there.

Doing the build (about 4,5 GB)

Fine, now we have a (hopefully) working 'build.sh' in the config_office subdir. We need to run it beforehand:

cd src680-m187/config_office/
./build.sh

This will setup the necessary includefiles and create a couple of files in the parent directory (bootstrap, MacOSXPPCEnv.Set.sh, MacOSXPPCEnv.Set). If you are using the sh, ksh or bash you only need to take care for 'MacOSXPPCEnv.Set.sh'.

Now we need to get back to our base-directory, run the bootstrap script, source our Enviroment (MacOSXPPCEnv.Set.sh) and finally start the build-process:

On PowerPC :

cd ..
./bootstrap
source MacOSXPPCEnv.Set.sh
time dmake

Or (on Mac Intel ) :

cd ..
./bootstrap
source MacOSXIntelEnv.Set.sh
time dmake

The main purpose of the boostrap script is to build (if necessary) the dmake utility used. Dmake once was a unix make-clone made by wticorp but got incorporated into OpenOffice since it was orphaned. For more information about dmake, it's history and manpage have a look here: http://tools.openoffice.org/dmake/index.html

Sourcing MacOSXPPCEnv.Set.sh is very important not only for building but also for running svdem later on. Here all the Enviroment-Variables for the Build will be set up. For a detailed descripton see Environment_Variables. Please note that on Intel machines, 'MacOSXPPCEnv.Set' should be substituted with 'MacOSXIntelEnv.Set'.

This Build process takes on my box (Dual 1.8 GHz G5, 1.5GB RAM) roughly 10 hours. Be paitioned. What can you do meanwhile? Do this: [bash,N]


while true ; do find . -maxdepth 1 -type d -anewer MacOSXPPCEnv.Set.sh |wc -l ; sleep 5; done

and wait till the number reaches 174

Creating Debug-Versions of Modules

Is it possible to build the complete set ?

Currently not possible, and not adviced.

is it possible to build some modules with symbols ?

Yes, and that's the simplest way to proceed. Some modules, like sal and vcl can be rebuilt using debug.

Example :

To rebuild sal with symbols included, do:

[bash,N] cd sal rm -rf unxmacxp.pro build debug=true

and recopy the libs into the bundle. gdb will display the symbols, and make your life easier.

Note : debug string is tested, and DEBUG is active when debug string is not empty. So debug=t works too.

How change gdb options, and use e.g. -g -ggdb or -gdwarf-2 ?

To rebuild the module, you just have to modify the option in solenv/inc/unxmacx.mk, replacing -g with -ggdb

Known issues

Sometimes a build error, or a runtime error, may be seen in the normal build,  
but the error goes away when --enable-debug is used or if the module is compiled with debug=true.

The DEBUG build turns off optimisation, so this is a hint that compiler optimisation causes the error.

The error might be due to incorrect code or a compiler fault. Such errors might not be seen on all platforms,

and might not be seen in different compiler versions on one platform.

If the code can not be fixed there is a workaround using NOOPTFILES to build specified files with no optimisation.

Example :

jvmfwk on Mac OS X: build jvmfwk in m183 on Mac OS X Intel leads to Bus Error when javaldx is run.

Solution : use trial and error to rebuild individual files with debug=true. This proves the problem lies with vendorbase.cxx

Have a look in sc/source/core/data/makefile.mk for an example to use NOOPTFILES

To solve our problem: just add : NOOPTFILES= $(SLO)$/vendorbase.obj in the corresponding makefile.

Take care in case some .IF is needed to prevent interference with other platforms.

There's some additional information around debugging on Christians Page User:CL#2006-09-03

Building and running svdem

We want to run the demonstration programs called "svdem". There are a couple of binaries called "svdem", which area they cover is still somewhat unclear to me, I hope some of you guys can shed some light here. But hey, this is a wiki! Just correct here :-).

svdem from VCL

To have the VCL Testprogram build you have to do:

cd vcl; build --all

This should have created a file called "svdem" here: vcl/unxmacxp.pro/bin/svdem. If you managed to build these binaries, you are nearly there. What you need now, is a wrapper directory structure to make this binary a fellow Mac OSX application. I mean the ones which have this structure:

svdem.app/
svdem.app/Contents
svdem.app/Contents/Info.plist
svdem.app/Contents/MacOS
svdem.app/Contents/MacOS/applicat.rdb
svdem.app/Contents/MacOS/svdem

You can basically create this structure anywhere you want. And you can link-in the file you just created (svdem). So you build up this structure once and link-in the freshly created svdem there:

ls -l svdem applicat.rdb
svdem -> /opt/src/openoffice/src680-m187//vcl/unxmacxp.pro/bin/svdem
applicat.rdb -> /opt/src/openoffice/src680-m187//vcl/unxmacxp.pro/bin/applicat.rdb

Now only the Info.plist file is missing, so here we go:

[xml,N]


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>CFBundleDevelopmentRegion</key>
        <string>English</string>
        <key>CFBundleDisplayName</key>
        <string>SvDem</string>
        <key>CFBundleExecutable</key>
        <string>svdem</string>
        <key>CFBundleIdentifier</key>
        <string>com.yourcompany.svdem</string>
        <key>CFBundleInfoDictionaryVersion</key>
        <string>6.0</string>
        <key>CFBundlePackageType</key>
        <string>APPL</string>
        <key>CFBundleSignature</key>
        <string>????</string>
        <key>CFBundleVersion</key>
        <string>1.0</string>
        <key>LSRequiresCarbon</key>
        <true/>
</dict>
</plist>

If you created the directory structure properly you can do './svdem' in the 'svdem.app/Contents/MacOS/' directory. You should see the svdem coming up.

svdem from svtools

Copy the application package you created for the vcl svdem.
Source your MacOSX[PPC-Intel]Env.Set.sh
Go into svtools/workben
build svdem using dmake in the workben directory
link the svdem and applicat.rdb from Contents/MacOS to the ones located in svtools/unxmacxp.pro/bin

You are done : you can now source your environment and run svdem using your usual shell.

Installing, preparing and running OpenOffice.org

Here I like to outline the steps to run OpenOffice.org after a successful build from the sources. Running the native Aqua Version of OpenOffice.org is somewhat tricky at the moment, since the installation procedure and mode are not in their final state. So right now one has to manually do some preparations to run the Office suite. This will change in the future when we are about to release some Alpha Builds to a wider audience.

Drag & Drop Install the Application from the Diskimage

When you are one of the lucky few (Don't give up, Eric!), who have a successful build, you are going to see something like this as the last lines of the build:

.
.
.
......................................................................................................................................................
   (CRC32 $11685D33: DiscRecording 3.1.3f2 (Apple_HFS : 2))
Ressourcen hinzufügen…
......................................................................................................................................................
Dauer: 15.406s
Dateigröße: 144732418 Bytes, Prüfsumme: CRC32 $14E0BB67
Bearbeitete Sektoren: 773848, 773845 komprimiert
Geschwindigkeit: 24.5M Bytes/Sek
Ersparnis: 63.5 %
created: /opt/src/openoffice/src680-m182/instsetoo_native/unxmacxp.pro/OpenOffice/install/de/OpenOffice.org-2.0.4_de.dmg

In this final step the ""instsetoo_native"" target creates the install Diskimages using Apple's 'hdiutil'. In my case it gives its output in German. After this disk image(s) have been created, double click the disk image to mount it (or type open <path to the DMG Image>) , and then move the icon named "OpenOffice.org 2.0" to your Applications folder (or any other folder you want this program to reside). The "OpenOffice.org 2.0" icon shown in the Finder is in fact a subdirectory called "OpenOffice.org 2.0.app". Subdirectories named ".app" (along with some well-know files inside like Info.plist, etc) are called Bundles in Apple's lingo.

Prepare the installation

After the OpenOffice 2.0 Application has been copied to its destination, you have to go into this bundle and run a small shell script provided by Pavel Janik to prepare soffice.bin (OpenOffice.org launcher) for running. You have to run this script in the directory where a Universal Binary called "droplet" is located. This "droplet" binary was used to fire-off the X11 version of OpenOffice.org. Expect this to change, but as of now we have to do it like this.

I have put my OpenOffice.org build in my home directory's private "Application" folder (/Users/schmidtm/Applications), so please change this path to your installation. Now go to into the bundle and run the script:

cd /Users/schmidtm/Applications/OpenOffice.org 2.0.app/Contents/MacOS
/opt/src/openoffice/bin/fix_installed_OOo

[bash,N]

#!/bin/bash

[ ! -f droplet ] && {
    echo "Please run me in the directory, where binary named droplet is located."
    exit 0
}

mv THIRDPARTYLICENSEREADME.html help presets share ..
mv droplet droplet.orig
mv program/* .
rmdir program

cd ..
ln -sf MacOS program
sed 's#droplet#soffice.bin#' Info.plist >Info.plist.new
mv Info.plist.new Info.plist
cd MacOS

Run the soffice.bin

We're nearly through, let's fire-off the binary:

AQUA_NATIVE_MENUS=TRUE AQUA_NATIVE_CONTROLS=TRUE ./soffice.bin -nofirststartwizard -norestore

Notice the enviroment variable here. It's experimental stuff created by Pavel. At the moment we have:

Variable	Function
AQUA_NATIVE_CONTROLS=TRUE	enable native controls code
AQUA_NATIVE_MENUS=TRUE	enable experimental native menus code

Both changes are marked with comments in the source code, and when we remove them in the future, native controls and native menus will be enabled by default.

Hack : to enable native controls and native menus by defaut without have to define an environment variable, just comment as follow :

in vcl/aqua/source/gdi/salnativewidgets.cxx , around line 55 :


/*
    static const char *pExperimental = getenv ("AQUA_NATIVE_CONTROLS");

    if ( !pExperimental || strcasecmp(pExperimental, "TRUE") )
        return FALSE;
*/

in vcl/aqua/source/window/salmenu.cxx, around line 124 :


/*
    static const char *pExperimental = getenv ("AQUA_NATIVE_MENUS");

    if ( !pExperimental || strcasecmp(pExperimental, "TRUE") )
        return FALSE;
*/

List of Patches for a given Milestone

Here is a list of Patches one has to apply against a given Milestone of SRC680 (including CWS aquavcl01). Please keep the older Milestones here, since people are probably still on these Versions.

Milestone	Patch to apply	Status
m187	Patch 1: to avoid systematical crashes in runtime you'll have to apply vcl67 patch in vcl Patch 2 : to simply start OpenOffice.org after applying Pavel's script (else, launch OpenOffice.org using a terminal is mandatory) apply i69373	OK
m187	To avoid crashes with several entries in menu apply about_workaround patch in vcl/aqua/source/window	Work in progress
(old) m184	Patch 1: sw : 68810 Mozilla plugin: to fix extensions and moz plugin build, building or not mozilla plugin, a fix has been included into aquavcl01. This change does includes both the mandatory np_sdk changes and extensions changes (see macmozplugfix cws). Patch 2: to avoid systematical crashes in runtime you'll have to apply vcl67 patch in vcl Patch 3 : to simply start OpenOffice.org after applying Pavel's script (else, launch OpenOffice.org using a terminal is mandatory, apply i69373	OK
(old) m184	To avoid crashes with several entries in menu apply about_workaround patch in vcl/aqua/source/window	Work in progress
(old) m184	Localization issue (menus will appear in english-US) : Apply this patch in the root directory of OpenOffice.org sources, to fix menu localization	(included in some cws )

External links

Bug Database: http://www.openoffice.org/issues/query.cgi
Mailinglist: mac@porting.openoffice.org
IRC Meeting-Logs (#ooo_macport@freenode.org): http://eric.bachard.free.fr/mac/aquavcl/logs_meetings/
TX20: http://eric.bachard.free.fr/UTBM_TX20/reports/Carbon_vcl.pdf
OpenOffice Source Directory Structure: http://wiki.services.openoffice.org/wiki/Source_code_directories
Pavels Patch Wiki: http://blog.janik.cz/
Eric Bachard Wiki: http://wiki.services.openoffice.org/wiki/User:Ericb
Christian Lippka Wiki: http://wiki.services.openoffice.org/wiki/User:CL
Carbon: http://developer.apple.com/carbon
EIS: http://eis.services.openoffice.org/EIS2/servlet/Logon
Runtime Configuration: http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/index.html
OpenOffice Domain Developer http://wiki.services.openoffice.org/wiki/DomainDeveloper

Screenshots

Eric Bachard screenshots (some are from Stephan Schaefer) http://eric.bachard.free.fr/mac/aquavcl/screenshots/
Most recent: http://eric.bachard.free.fr/mac/aquavcl/screenshots/scrollbar_01sept
Pavel Janik screenshots http://blog.janik.cz/images/MacOSX/2006-08-10
Important screenshot (eventloop issue) : http://blog.janik.cz/images/MacOSX/ => See : OOoMenus-separator-and-disabled_entries.png
Native Menus :

Documentation/Building Guide/Building on MacOSX

Contents

Prerequisites

Xcode

Java 1.4.2+

The perl module Archive::Zip

gpc

pkg-config

gnu copy

ccache (optional)

Apache Ant 1.6.5 (optional)

Some Backgroud (what is aquavcl01, EIS)

EIS

VCL (Visual Class Libraries)

Getting the code (checkout, merge and patch the puppy)

create a directory for a given milestone, setup CVS access:

checkout Milestone m187 (1,5 GB):

checkout Aquavcl01 (50 MB):

One-Time preparations and scripts

Doing the build (about 4,5 GB)

Creating Debug-Versions of Modules

Building and running svdem

svdem from VCL

svdem from svtools

Installing, preparing and running OpenOffice.org

Drag & Drop Install the Application from the Diskimage

Prepare the installation

Run the soffice.bin

List of Patches for a given Milestone

External links

Screenshots

Views

Personal tools

Navigation

Search

Tools