Revision as of 08:43, 19 July 2009

Overview

Template:Documentation/Windows

It requires that you are familiar with a command line, but not that you are a UNIX shell wizard.

If this document is not enough for you or if you have a problem that is not addressed you can send a mail to the mailing list dev@openoffice.org (subscription is recommended) or you can meet OOo developers on IRC in the channel #dev.openoffice.org at freenode.de. If you just want to give some feedback about the documentation please also use the mailing list.

You might want to know how many time and disk space installing the build environment will cost you. For a rough estimation I give some download, install and build times. They have been measured on an Athlon 64 X2 3800 (2GHz) dual core machine with 1GByte RAM and a 300 GB SATA disk. My internet connection is a 8MBit DSL broadband connection.

I created this document for building OOo 2.x and 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 (without the “Express”) should work also but until now I have only one known case as a proof for this. But meanwhile things have become even more complicated because on the way to OpenOffice.org 3.0 the compiler was changed again and now the recommended compiler is Visual Studio 2008 (Express). Please see [[1]] for more details.

Building works fine on Windows XP. It should work also on Windows 2000. I have no information about it but I assume that using Windows 98/ME is not a good idea (Visual Studio Express 2005 cannot be installed on Windows 98, so you'd probably need the full version of Visual Studio 2003 - but Windows 98 is unsupported for OpenOffice.org 3.0 anyway Cloph). I have no personal experience with building on Vista, but I got reports that it works in the same way.

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

Requirements

hardware requirements

• 1 or more reasonable fast CPUs (x-way CPU recommended)
• 1 GB RAM (2 GB recommended)
• 10 GB free disk space

software requirements

• Windows XP/Vista
• C/C++ Compiler:
  • Visual C++ 2008 Express Compiler (basic install, no optional parts requiered) or

alternatively, the Standard or better version of VS 2008

• • Visual Studio 2003 is the reference compiler for OpenOffice.org 2.x
  • Visual Studio 2008 is the reference compiler for OpenOffice.org 3.x
  • Visual Studio 2005 Express should work fine
• Java:
  • JDK 1.4.2 for OpenOffice.org 2.x
  • JDK 1.5 for OpenOffice.org 3.x
  • JDK 1.6 for DEV300 milestones >= m37 and all OOo310 versions (older milestones will fail in the hsqldb module)
• Windows SDK for Windows Server 2008. ¹
• SDK Redistributable: GDI
• Cygwin Toolkit from with (dll version 1.5.10) or later
• unicows.dll from (Microsoft Layer for Unicode)²
• dbghelp.dll from Microsoft³
• Apache Ant (version 1.6.5 or later)
• prebuild Mozilla
• msvcr71.dll, msvcp71.dll
• Microsoft_VC90_CRT_x86.msm, Microsoft_VC90_DebugCRT_x86.msm, policy_9_0_Microsoft_VC90_CRT_x86.msm, policy_9_0_Microsoft_VC90_DebugCRT_x86.msm⁴
• general polygon clipper library release 2.31
• optional: Nullsoft Scriptable Install System (NSIS)⁵
• optional: DirectX SDK⁶

Installation and Preparation of Build Tools

Setting up Cygwin

Go to http://www.cygwin.com/ and download and install the current version. Template:Documentation/Note

Make sure that you keep the filetype set to “Unix/binary”.

Required additional packages

Cygwin consists of some basic and a lot of optional packages. As building OOo needs some of these optional packages you have to select them in the installer. Here's a complete list of the needed packages:

• Category Archive:
  • unzip
  • zip
• Category Devel :
  • autoconf
  • bison
  • flex
  • gcc-g++
  • gperf
  • make
  • openssl-devel (only needed for perl modules for CWS tooling, see below)
  • cvs (for 2.x code line and 3.0 code line)
  • subversion (for 3.x code line, minimum version 1.5.5)
• Category Libs
  • openssl
• Category Net
  • openssh
  • ncftp
• Category Perl
  • perl
• Category Shells
  • rxvt
• Category Utils
  • patch
  • gnupg
• Category Web
  • lynx
  • wget

Template:Documentation/Note

Template:Documentation/Note

Breaking links to executables

Within the Cygwin Toolkit, some executables might be symlinks: awk.exe and gunzip.exe, tar.exe (in older releases only). This can lead to a break of the build later, and the symlinks should be replaced by copies of the command they link to.

To check this, execute:

ls -l /bin/awk.exe

whether e.g. awk.exe is a symlink. In version 1.5.24-2 awk.exe is a link to gawk.exe. The shell will show this by putting out “awk.exe -> gawk.exe”. In this case gawk.exe must be copied to awk.exe by executing:

cd /bin
rm awk.exe
cp gawk.exe awk.exe

In case you overlook something here or you have a newer Cygwin version with additional symlinks not mentioned here it's not a problem. You will get a helpful error message about an existing link in the configuration step (configure) later. The message will tell you which link you have to remove and you can do it following the advice given above for the awk.exe/gawk.exe pair. http://tldp.org/LDP/GNU-Linux-Tools-Summary/html/GNU-Linux-Tools-Summary.html

Template:Documentation/Tip

Installing additional Perl modules in cygwin

As explained 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. Choose autoconfiguration.

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
• Crypt::SSLeay

CPAN will detect if a selected module depends on other modules and it will offer to download them also. As explained please just confirm this.

Template:Documentation/Note

I got an error message from CPAN somewhat like the following: C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\bin\cygiconv-2.dll to same address as parent(0x7C0000) != 0x7D0000 To fix this, I had to exit the Cygwin shell, run cmd.exe, then type "c:\cygwin\bin\ash.exe" to start the minimal shell, then type /bin/rebaseall. Then CPAN worked when I ran it again.

I got another error when cygwin was performing make install: ERROR: Can't create '/usr/bin'; Do not have write permissions on '/usr/bin' I can actually write to /usr/bin; however when I do ls -ld /usr/bin, cygwin reports no write permission; and chmod u+w /usr/bin gives Permission denied. This causes the install process to fail when it checks permissions. As a kludge, I installed vim, and edited line 368 of /usr/lib/perl5/5.10/ExtUtils/Install.pm, replacing this: return -w $dir; with this: return 1; which allowed installation to proceed.

Adding required files to the build tree

Here's the list of files to download (with links) and the locations in the source tree where you must put them:

Template:Documentation/Tip

Template:Documentation/Note

Building

configure

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. Before running configure, make sure that all needed programs are in the system path or start configure with the appropriate command line switches. If configure detects a problem it will stop and give you a useful hint how to fix it.

You will find the configure script in $SRC_ROOT. The resulting configuration files are created there too.

sample configure calls

./configure \
 --disable-directx \
 --with-cl-home="/cygdrive/d/develop/msvc/VC" \
 --disable-activex \
 --disable-atl \
 --disable-build-mozilla \
 --with-frame-home="/cygdrive/d/develop/MSDK/v6.1" \
 --with-psdk-home="/cygdrive/d/develop/MSDK/v6.1" \
 --with-midl-path="/cygdrive/d/develop/MSDK/v6.1/Bin" \
 --with-asm-home="/cygdrive/d/develop/msvc/VC" \
 --with-jdk-home="/cygdrive/d/develop/j2sdk1.4.2_11" \
 --with-csc-path="/cygdrive/c/Windows/Microsoft.NET/Framework/v3.5" \
 --with-ant-home=/ant \
 --with-use-shell=bash

./configure --disable-build-mozilla --with-use-shell=bash --disable-activex --with-win32
--with-cl-home="/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/VC"
--with-midl-path="/cygdrive/c/Program Files/Microsoft SDKs/Windows/v6.1/Bin"
--with-csc-path="/cygdrive/c/WINDOWS/Microsoft.NET/Framework/v3.5"
--with-frame-home="/cygdrive/c/Program Files/Microsoft SDKs/Windows/v6.1"
--with-asm-home="/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/VC/Bin"
--with-jdk-home="/cygdrive/c/j2sdk1.4.2_11" .
--disable-directx --disable-epm
--with-ant-home=/cygdrive/c/apache-ant-1.6.5
--with-psdk-home="/cygdrive/c/Program Files/Microsoft SDKs/Windows/v6.1"

Make sure that the PATH variable in your cygwin shell does not contain any blanks and quotes.

Paths might have problems with spaces. Install requirements into pathes without them. Alternatively, feel free to install the various packages using the default path containing spaces and then use the mixed short path for the configure stage. The mixed short path can be obtained using Cygwin's cygpath tool, eg: $ cygpath -m -s "c:\Program Files\Microsoft Visual Studio 9.0\VC" c:/PROGRA~1/MICROS~1.0/VC The with-psdk-home setting needs a case-sensitive path name. I recommend to use case-sensitive usage in all cases - it's good to get used to case sensitivity if you are going to work with Cygwin.

Template:Documentation/Note Template:Documentation/Note Template:Documentation/Tip Template:Documentation/Tip Template:Documentation/Tip Template:Documentation/Tip Template:Documentation/Tip

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 SCM 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 to update the configure script:

SRC_ROOT> cd config_office
config_office> cvs update configure.in
config_office> autoconf

If you only use code from the snapshot releases on the web, you don't need to be concerned about this. If you are working on a Child Workspace you should rerun the configure script after each resync.

Build Instructions

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

If you are using bash got to your SRC_ROOT folder and call

. winenv.set.sh

(be aware of the space after the dot) 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_native” 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-3 hours. The whole tree used 8,1GB after a successful build. The disk space required for OOO300_m7 grew to 10,7GB. Extra space is required if debugging, eg with debug symbols enabled on 5 projects it grew further to 16GB.

Some build times for comparison (as reported by users):

• Athlon XP 64 2 GHz, 1 GB RAM - 3 hours
• Athlon 1,15 GHz, 1 GB RAM - 18,5 hours
• Core2 Duo 2 GHz, 1GB RAM - 3 hours
• Core2 Quad 2,4 GHz, 4GB RAM - 1,5 hours

There are some special things in the way how OOo builds its modules. Every module has an “output” folder (with some subfolders for the different kinds of generated output) that is created the first time a build is done in the module. The name of this folder is “wntmsci10.pro” for builds with MSVC++2003, “wntmsci11.pro” for builds with MSVC++2005 and "wntmsci12.pro" for builds with MSVC++2008 (for the meaning of the "pro" extension see below). After a successful build of a module some of the generated files are copied to the output folder of the “solver” module by executing a tool called “deliver” (this is automatically called by build --all for each of the modules). Other modules will take these “delivered” files (header files, libraries etc.) to resolve their dependencies. The content of the solver module will also be used to pack the installation sets in the final step.

Sometimes a build breaks. You will get an error message that tells you which modules have to be rebuilt. It seems that at least on Windows in rare cases the build (especially a multi processor build) breaks without an obvious reason and redoing the build is enough to “fix” the problem. I didn't experience that in the last months but don't be surprised if it happens to you. Of course a build can break for “real” reasons also if you changed something in the source code. “build” will always tell you the modules it couldn't build successfully and you can then go to any folder inside the module(s) and fix the problems.

The build system recommends to use the “--from” parameter of the build command to continue the build where it broke after you have fixed the problem. Rumours are that this is not reliable everytime. So if you can bear the extra minutes that “build” needs to detect already built modules you should restart your build with “build --all” from inside instsetoo_native as you did the first time just to avoid uncertainties. For more options of “build” call

SRC_ROOT> build – help

After a successful build you will find the OOo installation set in

instsetoo_native/wntmscixx.pro/OpenOffice/msi/Install/en-US

“instsetoo_native” is the module that packs the installation set.

If you already have a version of OOo installed you can install your freshly built version in parallel by installing it with setup /a that just unpacks all files without any system registration.

If you decide to rebuild a module or build each module individually (mind dependencies!), you also will have to use the “build” tool from inside a folder of these modules. A “build” of a single module will not call “deliver” automatically as described above for the “build --all” case. You must call is manually to get the usual files copied to the solver tree so that other modules or the packaging module can use them.

SRC_ROOT/(module)> build
SRC_ROOT/(module)> deliver

You can copy all new files manually to the appropriate places in your installation. There's no need to rebuild and install the complete installation set if you only want to rebuild some parts.

Special Debug Builds with --enable-dbgutil

OpenOffice.org can be built in a "non-pro" version where special debug assertions are enabled ("pro" means "product"). This is supported for Windows/Cygwin starting with the m218 milestone of the SRC680 codeline and all released code lines starting with OOo 2.3.

To enable this kind of build you must add the "--enable-dbgutil" switch to your "configure" command line. If you are building with a MSVC++2005 or MSVC++2008 compiler and you didn't disable the mozilla parts you will also need the debug DLLs for the MSVC2003 compiler runtime, msvcr71d.dll and msvcp71d.dll. You can download them from the internet and copy them into the external/msvcp71 folder.

In milestones older than SRC680m223 you also have to change the d.lst file in the external/prj folder. Add the following lines:

..\msvcp71\msvcp71d.dll %_DEST%\bin%_EXT%\msvcp71d.dll
..\msvcp71\msvcr71d.dll %_DEST%\bin%_EXT%\msvcr71d.dll

You can build the non-pro version in the same source tree as the pro-version, all created files go into wntmsci10, wntmsci11 or wntmsci12 folders, without the "pro" extension as in case of the "normal" builds.

When you work with the non-pro version you might see some error messages or warnings at runtime. In most cases you can safely assume that you have found a bug. The non-pro version is a bit slower than the pro version.

Notes

• csc.exe comes from the c:\WINDOWS\Microsoft.NET\Framework\v1.1.4322 directory, you might need --with-csc-path.
• Beware of using /c/ instead of /cygdrive/c/.
• Avoid trailing slashes in configure parameters. They sure cause problems for --with-psdk-home.
• Using some not quite latest cygwin releases (1.5.18/1.5.19) can lead to tcsh freezing in places - the build will appear to hang. You can fix this by running ls /proc/$nnn/fd where $nnn is the number of the process. Or just run

 ls /proc/*/fd

to "unhang" the process. See issue 51560 for more info...

Noone so far created a reproducible hang that doesn't require the whole OOo environment, and to make it worse, there are those who cannot reproduce the hang at all ( Works fine here ;) (User:Vq) ). Until someone provides a recipe to reproduce this problem with a small testcase we have to hope that the cygwin developers accidentally fix this problem.

• With cygwin 1.5.18, makecab.exe hangs when run from the build process (but it works fine when run standalone). So you definitely want to use a snapshot and avoid cygwin 1.5.18, unless you enjoy wasting half a week of your life debugging like I did ...

• With later Cygwin versions (various 1.5.19 and 1.5.20 snapshots) hangs have been noticed at least by me (User:TorLillqvist) at various stages of the build on a hyperthreading (Pentium 4) machine, while doing the same build using the exact same Cygwin version on a single-processor machine worked fine. So it might be a good idea to turn off hyperthreading.

• If you get errors like "too long line in ddf file" during the MSI installer build this is caused by too long filenames. Try setting your TEMP/TMP environment variable to something short like "C:\tmp". There is a 255 char line limit for dds files and class names like "InvalidAuthenticationMechanismException" push the envelope. Shaving of 10-15 chars puts us back just under the limit.

Avoid using winzip

Avoid using winzip to extract the downloaded source archive. Observed problems include:

• CR-LF errors that can affect makefiles and cause compile errors
• Certain files unpacked into root folder, esp. likely when actual path is deeply nested (e.g. foo/bar/source/foo/java/org/x/y/z/w/LongFileName.hmm) which again causes mysterious compile errors.

Use the tar from Cygwin instead:

tar xvzf OOo_2.0.2_src.tar.gz

• If you fail to getting together a working installation of Cygwin, one possibility is to use a known-to-work combination of Cygwin packages, i.e. a direct copy of some other user's Cygwin tree. User:TorLillqvist has such a tree (from late 2006) zipped up at http://download.go-oo.org/tstnvl/tml/tml-cygwin.zip . Don't hesitate to ask for advice if necessary.

Installation and Preparation of Build Tools for older OOo versions

Visual Studio 2005 Express (OpenOffice.org 2.x)

In case you still can find a copy of the 2005 Express compiler setup and it still works 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. The complete (not Web based) compiler installation set still can be downloaded as an ISO-image (~450 MB) from the Manual Installation site.

Next step when you plan to use the “Express” version is installing the Microsoft Macro Assembler (MASM). MASM is part of the paid version of Visual Studio (so you can skip that part if you are using it) but for the “Express” version you have to download it separately. It's only a very small download. 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). WARNING: don't install the new Vista platform SDK that is needed for the 2008 Express compiler (see below), the 2005 Express Compiler does not work with it.

The setup is again web based. You can either user the “Typical” installation or select “Custom” setup and 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
• Microsoft Windows Installer SDK

You can deselect all 64Bit parts of these packages, 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).

Warning: 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 Windows programs (not only Cygwin) 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 shells with a suitable configured environment so that shouldn't be a problem.

There is a library called “libcp.lib” in the “Lib” directory of the SDK; it must be either moved away or renamed. You can read more about this here.

There is another thing you have to change in the Platform SDK: you have to apply a small patch to one of the Platform SDK header files as described here.

See Also

Template:Documentation/Note

Footnotes

¹Template:Documentation/Note ²Template:Documentation/Note ³Template:Documentation/Note ⁴Template:Documentation/Note ⁵Template:Documentation/Note

It used to be that newer version of NSIS broke the build (see Issue 85657 ), but it seems that in now works for NSIS up to 2.3.7.

⁷ Template:Documentation/Note

Current (as of 2008/01) versions of the DirectX9 SDK and Windows Platform SDK do not fit to each other. To be able to build with DirextX enabled, you need to patch one file in the Platform SDK. See http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID2743771 for details.

Do not use a DirectX10 SDK!