Documentation/Building Guide/Building on Windows

This document tries to fill a gap. The existing documentation about building OOo on Windows mainly reads like “Building OOo on Windows explained for Linux developers�. I will summarize it and try to add some comments that address people that are already developing on Windows and now want to get to know about building OOo. So this document is also for those who are not used to unix like command line interfaces, tar balls etc. Of course you must be familiar with a command line, but you don't need to be a shell wizard. But it wouldn't hurt if you are.

I collected information from several places:

http://tools.openoffice.org/dev_docs/build_windows_tcsh.html#BuildRequirements

http://wiki.services.openoffice.org/wiki/Windows

http://wiki.services.openoffice.org/wiki/CPAN_install

http://website.openoffice.org/support/en/howtos/1.html

For a rough estimation I give some download, install and build times. They have been measured on a Athlon 64 X2 3800 (2GHz) dual core machine with 1GByte RAM and a 300 GB SATA disk. My internet connection is a 4MBit DSL broadband connection.

I created this document for building OOo using Microsoft Visual Studio 2005 Express, the “free� (as in beer) offering from Microsoft. It also works with Microsoft Visual Studio 2003, the small differences are mentioned in the text. Using Microsoft Visual Studio 2005 should work also but until now I have no proof for this.

The first thing you need is the build environment. We are using Cygwin, a Windows program that emulates a complete Unix command line environment.

Download and install Cygwin

Go to http://www.cygwin.com und download the current version. If you already have Cygwin installed: you will need at least version 1.5.10. If you are using version 1.5.18 you must download a special version of the cygwin1.dll as described here.

Cygwin has a web based installation process that is described here. I used the “Install from Internet� method and it worked like a charm. Cygwin consists of some basic and a lot of optional packages. As building OOo needs some to these optional packages you have to select them in the installer. Unfortunately the list of packages mentioned at the URL shown above is incomplete, some more are listed here. Here's a complete list of the needed packages:

Category Archive: unzip, zip

Category Devel : bison, cvs, flex, gcc-g++, make, openssl-devel (only needed for perl modules for CWS tooling, see below)

Category Libs: openssl

Category Net: openssh

Category Perl: perl (Perl)

Category Shells: rxvt, tcsh

Category Utils: patch

Category Web: lynx, wget

The installer will automatically check some more packages needed by thosed listed here. The total amount of disk space is 46 MB for the download and 174 MB for the Cygwin installation, including all the additional Perl modules shown below. The whole process took roughly 20 minutes.

Within the Cygwin Toolkit, some executables might be realised as symlinks, namely awk.exe, gunzip.exe, tar.exe. This might lead to a break of the build later, and the symlinks should be replaced with copies of the command they link to. You can check this in the cygwin shell by calling e.g.

ls -l /bin/awk.exe

whether awk.exe is a symlink. For instance, awk.exe could be a link to gawk.exe, in which case you should copy gawk.exe to awk.exe:

cd /bin

rm awk.exe

cp gawk.exe awk.exe

Take similar action for gunzip.exe and tar.exe (in my case the latter wasn't a link). In case you overlook something here you will get a helpful error message in the configuration step (configure) later.

Cygwin uses the command line shell “bash� by default. Building OOo is also possible using the shell “tcsh�, though some problems have been reported (see below). All commands written in this document are meant to be used in a bash (except explicitly told differently).

Download and install MS compiler and tools

Currently building on Windows needs a Microsoft Visual Studio C++ compiler. The regular builds are done with Visual Studio 2003 that is available from Microsoft at a price. Building using the free (as in “free beer�) compiler Visual Studio 2005 Express works fine and is explained here.

You can download the compiler from Microsoft. The download is a setup.exe with a 2.8 MB. If the setup is started it downloads additional content from the Web. You only need to select the Graphical IDE. More can be downloaded later if you want, but for building and debugging OOo you will not need more than the basic package. The download and installation took me roughly 10 minutes and 220 MB on my hard disk.

Next step is installing the Microsoft Macro Assembler (MASM). MASM is part of the paid version of Visual Studio but for the “Express� version you have to download it separately. It's only a very small download. This step can be omitted if you already have a paid version of Visual Studio as it is contained in it.

I had a problem with the MASM installer on all machines where I used it: the setup started but then suddenly disappeared from the screen. I found a hanging msiexec.exe in the task manager and had to kill it manually. Fortunately the MASM was obviously installed correctly. It appeared in the “Add and remove software� dialog and the “ml.exe� was installed to “Vc/Bin� folder of VC8.

You also must download and install the Microsoft Windows Platform SDK. The usual instructions recommend to download it from

here but I followed the recommendations from the Visual C++ site. There you can find a link (download requires Genuine Windows Validation). The setup is again web based. You can either user the “Typical� installation or select “Custom� setup deselect the packages you don't need. You need at least the following packages:

Microsoft Windows Core SDK

Microsoft Web Workshop (IE) SDK

Microsoft Internet Information Server (IIS) SDK

Microsoft Data Access Services (MDAC) SDK

Microsoft DirectShow SDK

You can deselect all 64Bit parts, all samples, all source code modules and (if you want) every documentation. In total the installation filled 438 MB of my harddisk space (including the documentation, but without all other optional parts).

The first installation option is called “Register Environment Variables� and it is deselected by default. You shouldn't change this as selecting it will add directories with blanks to your PATH variable. This (or more precisely the quotes surrounding them) will cause troubles in Cygwin (see below). It is also possible that other installed programs can't cope with the changed PATH variable as the installer of the Platform SDK explicitly warns.

The only drawback of not selecting this option is that if you wanted to use the platform SDK for other projects except OOo you would have to take care for the correct environment yourself. The platform SDK creates some start menu entries for suitable configured shells.

There is a library called “libcp.lib� in the “Lib� directory of the SDK; when I made the configuration step the configure tool complained about it and I had to delete/move it. I couldn't find any information or documentation about that but the instructions from configure to remove the lib worked for me (as all other hints from that tool also BTW!).

You have to apply a small patch to one of the Platform SDK header files as described here.

Another SDK that could be downloaded and installed is the Direct X9 SDK. If you don't want to download it you can disable DirectX support in the configuration step. The current regular builds are done with a version that is no longer available for download so one has to use Google or other sources to find a download of the SDK. The OOo pages mention several links, outdated as well as working links. I took the one from here (Genuine Windows Validation required). This is a 509 MB download. Downloading, unpacking and installing took 30 minutes. As I deselected the sources and sample the resulting installation only was 189 MB.

Download of additional files

You have to download some more files that you have to put in some prepared locations of the OOo source tree later. Here's the list of files to download (with links) and the locations in the source tree:

GDI+ Redistributable (Genuine Windows Validation required)	external/
unicows.dll	external/unicows
dbghelp.dll	external/dbghelp
instmsiw.exe and instmsia.exe	external/msi
msvcp80.dll and msvcr80.dll (found in c:\WINDOWS/WinSxS/x86_Microsoft.VC80.CRT_1fc8b3b9a1e18e3b_8.0.50727.42_x-ww_0de06acd/msvc	external/msvcp80
GPC	external/gpc
Mozilla binary distribution	moz/wntmsci10.pro
msvcr71.dll and msvcp71.dll for Mozilla libraries (use Google)

All the files except GPC, the Mozilla binaries and the ms...80.dll can be found in any OOo 2.x installation set also so you can save the download by stealing it from your OOo installation.

The Mozilla files are necessary as OOo uses some Mozilla components. Building the corresponding sources is not possible with the VC2005 compiler so you have to use the precompiled libraries. They have been compiled with the MSVC2003 compiler and so you also need the msvx71 libraries mentioned above. You could also disable all functionality based on the Mozilla libraries in the configuration step later and so save you downloading the binaries and the MS libraries.

= Downloading and installing additional Perl modules =

As explained in our wiki some perl modules must be installed with CPAN. The necessary command in the cygwin shell is

perl -MCPAN -e shell

If this command is executed the first time CPAN will ask for configuration. The autoconfiguration worked fine for me. I used the prompted installation just to see what is asked but always presses “Enter� in each step. Please note that CPAN is not able to deal with usernames containing spaces. To work around this fact, when CPAN asks you to specify the CPAN build and cache directory, change the default suggestion to /cpan.

At the end the CPAN shell appeared and is ready to accept commands for installations. Each module is installed by typing “Install $MODULENAME�. The modules that must be installed are:

Archive::Zip

XML::Parser (though it seems that this is already installed; doesn't hurt to do it)

URI

LWP:UserAgent

SOAP::Lite

The last three modules are only needed if you want to use the CWS tooling. These tools are necessary if you want to create and maintain your own Child Workspaces.

CPAN will detect if a selected module depends on other modules and it will offer to download them also.

= Downloading and installing Java and other tools =

Some OOo components as well as some build tools of OOo require Java. So you must download a JDK and the Java make utility Ant. It's not necessary to read the whole installation instructions from Ant. After downloading the package just copy the bin and lib folders from it into a directory that you specfiy as ant-home in the configure step.

All OOo builds can be done with JDK 1.4.2. If your build is based at leat on milestone m158 you can also use JDK 1.5.0.

If a self contained Windows installer is desired in addition to the MSI installer files NSIS is needed, but it is optional. If NSIS is not present the build will ignore this step.

Getting the source code

Source code is available via CVS or as a source tarball. Downloading and unpacking the latter needs less bandwidth but tarballs are not available for every milestone build. If you wanted to work on a particular milestone or CWS you have to get the source directly from the cvs.

You will place your code somewhere in your file system. In the following text this root directory will be called SRC_ROOT.

We have some documentation about working with cvs on OOo. Here's a short description how you can download the whole OOo2 source. You have to use the following commands to get e.g. the milestone m206 (with the cvs branch tag SRC680_m206):

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

cvs login ( use the CVS password: anoncvs when you are asked for it)

cd SRC_ROOT

cvs co -r SRC680_m206 OpenOffice2

“OpenOffice2� will check out all modules that are needed for OOo2.x; it is also possible to check out single modules. Checking out OpenOffice2 took me roughly 50 minutes. If you already have a cvs tunnel working you can of course use this one instead of the anoncvs access.

If you got the tarball, e.g. the one for version 2.2.0, you can unpack it with

tar -xvzf OOo_2.2.0_src.tar.gz

Once you have the source tree you can copy all the extenal files listed in the table above into the appropriate locations.

Setting up the build environment

Finally the “configure� tool is used to create the environment. It checks that all software, hardware, and system requirements for the build are satisfied, and creates configuration files called winenv.set (for tcsh) and winenv.set.sh (for bash) that are used to set all necessary build environment variables. If configure detects a problem it will stop and give you a useful (really!) hint how to fix it. You have to call “configure� from the SRC_ROOT/config_office directory.

The resulting configuration files are created in the SRC_ROOT directory. A top-level makefile script makefile.mk and the script bootstrap that are located in the config_office directory are moved into SRC_ROOT folder as well. This is due to technical reasons: The SRC_ROOT directory in the cvs tree can only hold directories. On the other hand, the top-level makefile.mk should logically be placed in the top-level directory SRC_ROOT. The cvs tree holds these files in config_office and configure copies them up.

Before running configure, make sure that all needed programs are in the system path or start configure with the appropriate command line switches. Make also sure that the PATH variable in your cygwin shell does not contain any blanks and quotes.

There are a number of options that you can use with the configure script. To display these options, type the following command:

./configure --help

Here's my configure call:

./configure \

--with-directx-home=/cygdrive/c/Programme/MicrosoftDirectXSDK \

--with-cl-home="/cygdrive/c/Programme/Microsoft Visual Studio 8/VC" \

--disable-activex \

--disable-build-mozilla \

--with-frame-home="/cygdrive/c/Programme/Microsoft Platform SDK" \

--with-midl-path="/cygdrive/c/Programme/Microsoft Platform SDK/Bin" \

--with-asm-home="/cygdrive/c/Programme/Microsoft Visual Studio 8/VC" \

--with-jdk-home="/cygdrive/d/openoffice.org/r/j2sdk1.4.2_11" \

--with-csc-path="/cygdrive/c/Windows/Microsoft.NET/Framework/v2.0.50727" \

--with-ant-home=/ant\

--with-use-shell=bash

You might notice that many paths contain spaces and quotes. Obviously configure managed to convert them into the short file names so that the PATH variable I got later on is fine. For whatever reason this didn't work for the DirectXSDK so that I bit the bullet, deinstalled it and reinstalled it to a path without blanks (as you can see in my configure script).

Most parameters are self-explanatory, but some options might need an explanation.

The Visual Studio 2005 Express compiler does not contain everything needed to build the OOo ActiveX control so I disabled it here. If you are using a “complete� Visual Studio (no “Express� version) you can omit this if you want.

OOo uses some Mozilla components. As mentioned above it is not possible to build them from the sources using the Visual Studio 2005 compiler. So I disabled the build with an appropriate option. Disabling the Mozilla components completely is not recommended, using the binaries works quite fine.

Cygwin starts with a “bash� shell by default as already mentioned. My document explains how to build with this shell. Using a tcsh is possible though it may sometimes lead to problems (memory allocation errors, hanging builds) so I don't recommend to use it. Unfortunately using “tcsh� is still the default setting created by configure (as the first builds where done using it) and so I told configure that the bash should be used instead. If you want to try using tcsh remove the “--with-use-shell� parameter shown above and build with tcsh as explained below. In case the build breaks at some place you can manually patch your winenv.set.sh file and exchange the line

SHELL=�/usr/bin/tcsh�

with

SHELL=�/usr/bin/bash�

and the line

“USE_SHELL=�tcsh�

with

“USE_SHELL=�bash�

Then close the tcsh and build again with bash as explained below.

After running configure you must create the dmake make utility that is needed for the build of OpenOffice.org. This done from the SRC_ROOT directory by calling

./bootstrap

If you experiment with the newest sources from the cvs-tree, mind that updates to the configure process may not happen via updates of configure (the script file) but via the files configure.in and set_soenv.in. The configure script itself is created from configure.in using the autoreconf command. The perl script set_soenv is created when you run configure from set_soenv.in.

If you need to modify or create a correct configure you would run commands like the following:

SRC_ROOT> cd config_office

config_office> cvs update configure.in

config_office> autoreconf

to update the configure script. If you only use code from the snapshot releases on the web, you don't need to be concerned about this.

Build Instructions

Now you are ready to build OpenOffice.org. In every Cygwin instance you have to set the environment variables from the generated configuration file(s).

If you are using bash then call

. winenv.set.sh

or if you are using tcsh call

source winenv.set

Now you have two options to build the whole Office. You can either call “dmake� in SRC_ROOT or you can go to the “instsetoo_nativ� directory and use “build� that allows you to control the build process a bit better:

SRC_ROOT> cd instsetoo_native

SRC_ROOT> build -- all -P4

The “-P4� tells the build tools to start 4 parallel running processes. Using more than one process will speed up the build as it avoids that CPU time is wasted waiting for disk i/o. As a rule of thumb twice as much processes as you have CPU cores is a good number, so “-P4� is fine for my dual core Athlon 64 X2. On this machine (described at the top of this document) the complete build took roughly 2,5 hours. The whole tree takes 8,1GB after a successful build.

Sometimes a build breaks. You will get an error message that tells you which modules have to be rebuilt (and a recommendatation for the necessary build command that you can use after you have fixed the problems). It seems that at least on Windows the build breaks without an obvious reason and redoing the build is enough to “fix� the problem.

For more options of “build� call

SRC_ROOT> build -- help

If you decide to rebuild a module or build each module individually (mind dependencies!), you also will have to use the “build� tool.

A subsequent deliver will copy all created binaries, libraries etc. into the solver tree:

SRC_ROOT/(module)> build

SRC_ROOT/(module)> deliver