Documentation/Building Guide/Building on MacOSX

Building OpenOffice for MacOSX using Aqua, or the Story of svdem ...

This Document tries to wrap-up the buildprocess for OpenOffice 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 endaevours, since they are used to test the capabilities of the underlying VCL Layer.

The base for this Document is the Description of the X11 Build thanksworthy provided by Eric Hoch in this Document: MacOSXBuildInstructions. Please check this document for prerequesites (perl, gnu-copy, compilers, Xcode, ...). In this step-by-step description i will only refer to the things which need to be done for each new milestone of the Master workspace SRC680.

I use the bash shell in all examples, since to my believe users of the c-shell are smart enough to figure out the differences anyway. If you want to dig deeper in the build-process have a look at the description of the build-enviroment here: http://tools.openoffice.org/build_env.html.

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

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 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:

1. checkout a given OpenOffice Milestone.
2. checkout aquavcl01 Child Workspace.
3. merge them together.
4. 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. I use the milestone m177 which worked for me at the time of this writing (August, 13th 2006). You may change this to your needs.

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.

One word of caution here: It worked out quite good to me having backup-copies of the Masterworkspace (m177) and the childworkspace (aquavcl01) and merge them manually using 'cp' rather than to checkout in the same subdirectory. I explain here for demonstration purposes only the checkout in the same subdirectory, nevertheless i recommend the two-directories-copy-later aproach.

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

mkdir src680-m177
cd src680-m177

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

Please Enter the password 'anoncvs'

checkout Milestone m177:

cvs -z3 co -r SRC680_m177 OpenOffice2

checkout Aquavcl01:

cvs -z3 co -r cws_src680_aquavcl01 OpenOffice2

Apply some patches

After you've checked out the sources you need, you have to apply the needed patches. Here an example:

patch -p0 ../patches/aquavcl01-menus_debug.diff

How our team keeps track of these patches, tests their compatibility and consolidates them remains to be seen.

One-Time preparations and scripts

Ant

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:

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

./configure

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-m177/
...

Now I go to the 'config_office' subdir and link in my startscript:

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

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

#!/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-ant-home=$BASE/apache-ant-1.6.5/ \
--with-gnu-cp=/sw/bin/cp \
--with-epm=internal \
--disable-mozab \
--disable-pasf \
--disable-gtk \
--disable-mozilla \
--with-build-version=$OOVERSION-`date +%d-%m-%y` \
--enable-debug \
--disable-fontconfig

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

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

cd src680-m177/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:

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

The main purpose of the boostrap script is to build (if necessary) the dmake utility used. 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.

This Build process takes on my box (Dual 1.8 GHz G5, 1.5GB RAM) roughly 10 hours. Be paitioned.

(Please note that on Intel machines, 'MacOSXPPCEnv.Set' should be substituted with 'MacOSXIntelEnv.Set'.)

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 :-).

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 this 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 who 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-m177//vcl/unxmacxp.pro/bin/svdem
applicat.rdb -> /opt/src/openoffice/src680-m177//vcl/unxmacxp.pro/bin/applicat.rdb

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

<?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.

URL Links

1. MacOSX X11 Build Documentation: http://wiki.services.openoffice.org/wiki/MacOSXBuildInstructions
2. Bug Database: http://www.openoffice.org/issues/query.cgi
3. Mailinglist: mac@porting.openoffice.org
4. IRC Meeting-Logs (#ooo_macport@freenode.org): http://eric.bachard.free.fr/mac/aquavcl/logs_meetings/
5. TX20: http://eric.bachard.free.fr/UTBM_TX20/reports/Carbon_vcl.pdf
6. OpenOffice Source Directory Structure: http://wiki.services.openoffice.org/wiki/Source_code_directories
7. Pavels Patch Wiki: http://blog.janik.cz/
8. Eric Bachard Wiki: http://wiki.services.openoffice.org/wiki/User:Ericb
9. Carbon: http://developer.apple.com/carbon