Documentation/Building Guide/Building on MacOSX
This document tries to wrap-up the build process for OpenOffice.org on Mac OS X using the native windowing-toolkit of the platform named Aqua.
An important 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 purpose 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.
We use the bash shell in all examples, since to our 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 environment here: OpenOffice.org Build Environment.
Contents
- 1 Prerequisites
- 2 Some Background (what is aquavcl01, EIS)
- 3 Getting the code (checkout, merge and patch the puppy)
- 4 List of Patches for a given Milestone
- 5 List of Patches requiring testing before for integration
- 6 Doing the build (about 4,5 GB)
- 7 Debug
- 8 Installing, preparing and running OpenOffice.org
- 9 External links
- 10 Screenshots
Prerequisites
This document was derived from the description of the X11 build thanksworthy provided by Eric Hoch in this document: MacOSXBuildInstructions. Here we would like to outline the things you need to build the Aqua Version (besides the OS).
Mandatory
Xcode
This is (with GNU cp, soon optional) the only mandatory part to be installed to build Aqua version of OpenOffice.org.
Current verified working version is XCode 2.4.1
If you really cannot use XCode 2.4.1 nor XCode 2.4:
Xcode 2.2, 2.3 are known to work for Aqua development. If any earlier versions work as well, please add them here.
X11SDK (soon optional)
A dependency for Mozilla plugin needs some prototype defined in some Xlib.h header.
Please note, this dependency is not needed in runtime, but only at buildtime.
X11SDK.pkg archive is located in your Tiger's DVD, and has to be installed in the case of you're using Mozilla prebuild archives
This issue should be fixed soon.
Strongly recommended
ccache
If you intend 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 using bash, and just before doing configure command line:
export CC="ccache gcc" export CXX="ccache g++"
Some Background (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 successfully 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 (April 11th 2007) is m208. You may change this to your needs. You can find 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-m208 cd src680-m208 export CVSROOT=:pserver:anoncvs@anoncvs.services.openoffice.org:/cvs cvs login
Please Enter the password 'anoncvs'
checkout Milestone m208 (1,5 GB):
[bash,N]
cvs -z3 co -r SRC680_m208 OpenOffice2
Once done, you'll obtain milestone 208. 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 already 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
fpicker
padmin
sal
scp2
sfx2
solenv
dtrans
freetype
psprint
sj2
vcl
toolkit
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-m202 and replace them with the one located in aquavcl01-src.
e.g. : canvas in src680-m208 will become canvas_m208 , and then, cp canvas from aquavcl01-src into src-m208
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-m208 will contain:
[bash,N]
- !/bin/bash
list="canvas extensions fpicker padmin scp2 sfx2 solenv dtrans freetype psprint sj2 vcl sal toolkit" for i in $list ; do
mv $i $i-m208 cvs -z3 co -r cws_src680_aquavcl01 $i
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-m182/ src680-m196/ ...
Now I go to the 'config_office' subdir and link in my startscript:
[bash,N]
cd src680-m208/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-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-odk 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.
--without-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.
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.
PLEASE NOTE: Current milestone for Aqua build is m208 (older milestones are deprecated)
| Milestone | Patch to apply | Status |
|---|---|---|
| m208 | Modify the Bundle using Ericb's patch => see below | hack, but verified working |
| deprecated m202 | Modify the Bundle using Pavel Janik's patch => see below | works fine |
| deprecated m202 | see List of Patches requiring testing before for integration | work in progress |
List of Patches requiring testing before for integration
All patches that developers have that need testing or peer review should be added here.
Modify the Bundle
Soon included in the sources
[ericb's patch ]to modify the bundle, and make Aqua build start with a simple double clic
salatslayout.cxx: new implementation of text layout has to be tested.
Native FilePicker
Note: This is experimental stuff, and we suppose aquavcl01 is built and aqua bundle works (X11 backport in progress)
1) Download this patch
2) put it in your root sources dir
3) apply it:
test first:
patch --dry-run -p0<aquafilepicker01_complete2.diff
If no problem occurs, apply it for true:
patch -p0<aquafilepicker01_complete2.diff
4) replace fpicker from aquavcl01 with fpicker from aqufilepicker01
mv fpicker fpicker_aquavcl01
(supposing your CVSROOT ..etc is correct)
cvs -z4 co -r cws_src680_aquafilepicker01 fpicker
5) in scp2, sfx2, fpicker: remove unxmacx{p | i}.pro , rebuild and deliver
6) recreate a new bundle (build instsetoo_native , install the .dmg, run Paval fix_installed_OOO script ..)
7) activate native fpicker:
WARNING: don't use Mac tools for that, but correct text editor. Else the following changes will FAIL, and corrupt your OpenOffice.org preferences
-> add or adjust this, keeping in mind only one Misc section can be used (but several properties are possible in Misc):
<node oor:name="Misc"> <prop oor:name="UseSystemFileDialog" oor:type="xs:boolean"> <value>true</value> </prop> </node>
in ~/Library/Application Support/OpenOffice.org/2/user/registry/data/org/openoffice/Office/Common.xcu
If unsure, make a backup of your file and use this: Common.xcu
8) enjoy:)
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-m202/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 MacOSXX86Env.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 Environment-Variables for the Build will be set up. For a detailed description see Environment_Variables. Please note that on Intel machines, 'MacOSXPPCEnv.Set' should be substituted with 'MacOSXX86Env.Set'.
This Build process takes on my box (Dual 1.8 GHz G5, 1.5GB RAM) roughly 10 hours. Be patient. 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
Debug
Installing, preparing and running OpenOffice.org
(soon obsolete : with last bundle modifications, drag and drop the bundle, double click and go ! )
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.
Prepare the installation [Optional]
WARNING : Either you use Pavel Janik's at runtime(see below) OR Ericb's patch at buildtime instead (see above), but NOT both
After the OpenOffice 2.2 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.2.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:
If you applied Pavel's script, just double click the Bundle and enjoy.
If you want to trace (using gdb e.g.), just do:
cd <INSTALL_DIR>/OpenOffice.org\ 2.3.app/Contents/program
and run:
gdb --args soffice.bin
(add any breakpoint you want)
r to run OpenOffice.org
Note: see below for other possible options
Warning : if you applied Ericb's patch, program does not exist anymore, because the next changes are about creat the exact tree awaited by Mac OS X for any regular application :
<instal_dir>/OpenOffice.org\ 2.3.app/Contents/MacOS
Native menus are defaults. If you want to use vcl menus, do: AQUA_NATIVE_MENUS=FALSE ./soffice.bin
Note: options to not recover is -norestore , and to bypass the user informations to fill in, use -nofirststartwizard
AQUA_NATIVE_MENUS=FALSE ./soffice.bin -nofirststartwizard -norestore
Notice the enviroment variable here. AQUA_NATIVE_MENUS is experimental stuff created by Pavel, SAL_NO_NWF was created some times ago, and is located in vcl/source/window/window.cxx . At the moment we have:
| Variable | Function |
|---|---|
| SAL_NO_NWF=TRUE | disable native controls code |
| AQUA_NATIVE_MENUS=FALSE | disable 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.
External links
- Bug Database
- Mailinglist: mac@porting.openoffice.org (subscribe is mandatory )
- IRC Meeting-Logs (#ooo_macport@freenode.org): Previous_Mac_Meeting_logs MacOSXPortMeetings
- 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/aqua_menus_05_nov_06/
- 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
- Aqua look (the begining):
More menus: http://eric.bachard.free.fr/mac/aquavcl/screenshots/aqua_menus_05_nov_06/index.html
