EnvironmentSetup/Windows

Overview

Goals

Here are described the basics you need to build the Windows version of OOo4Kids

Please help us to improve it. Thanks !!

We suppose that you are familiar with a command line, but not more. 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@education.openoffice.org (subscription is recommended) or you can meet OOo developers on IRC in the channel #education.openoffice.org at irc.freenode.net.

You either need a good internet connexion (like ADSL or close to that)

Building works fine on Windows XP. It should work also on Windows 2000. Building on Vista, should work the same way.

Hardware requirements

Recommended values for the build :

• processor >= 1,5 GHz
• the recommended compiler is Visual Studio 2008 (Express) ( => Visual Studio 2010 has unfixed build issues)
• 1 or more reasonable fast CPUs (x-way CPU recommended)
• 1 GB of RAM (2 GB recommended)
• 20 GB free disk space (100 GB recommended if you want to build several milestones)

Tools

As described, build on Windows needs a lot of installed software. Please note that the list below is not definitive, and will be reduced to the strict minimum as soon as possible.

All the software described below is mandatory, and will be divided in :

• Software provided by Microsoft
• Other software

OOo is not and will probably never be buildable in the Visual Studio IDE. But it is *debuggable* in it very nicely though. [FIXME: investigate ...]

Notes on Java, Apache ant and Mozilla :

=> The Windows version of OOo4Kids does not need Java, nor apache ant nor Mozilla at all.

Software provided by Microsoft

Windows XP (prefered) or Windows Vista

A registered version of Windows XP (minimal requirement) is mandatory.

Visual Studio 2008 Express

• C/C++ Compiler: Microsoft Visual C++ Compiler is the recommended compiler for building OpenOffice.org. It should be at least Microsoft Visual C++ 2008 Compiler Suite, either the commercial or the freely available Express Edition are reported to work.

This compiler was released in November 2007.

• Visual C++ 2008 Express Compiler You don't need to install any optional parts.
• or alternatively, the Standard or better version of VS 2008

Windows SDK for Windows Server 2008 and .NET Framework 3.5

• Windows SDK for Windows Server 2008 and .NET Framework 3.5. ¹
• Framework SDK 3.5 full package

1. Also supports Vista. This is either a DVD image or a net installer. You can either mount the DVD with a suitable tool, burn it do a DVD or use tools like winrar that can extract files from ISO files directly. You don't need to install samples or documentation (saves a lot of disk space). Will also install the .NET Framework 3.5 SDK.

It might be best to install the Windows SDK into the default directory, and if not that into one without capital letters in the path. I used D:\Dev\Win_SDK\ and received some linking errors in the Python module (see Issue 88568).

These environment variables needs to be set:

WINDOWS_VISTA_PSDK=TRUE

FIX ME :

The "Framework SDK 3.5 full package" didn't work for me.

DirectX SDK

• You will need DirectX 9 SDK. You can grab it here

Files for external folder

gpc

=> As described above, gpc files will have to be located in external/gpc directory, in your sources tree

• The gpc general polygon clipper library release 2.31, located at http://www.cs.man.ac.uk/aig/staff/alan/software/. Download and unpack the tarball. You should have the files gpc.c and gpc.h in $SRC_ROOT/external/gpc.

Microsoft Layer for Unicode (unicows.dll)

• The Microsoft Layer for Unicode (unicows.dll). Get it from the Microsoft site and put it into $SRC_ROOT/external/unicows. (Note: Microsoft seems to enjoy changing the exact location of this file. You may have to search Microsoft's website.) Last time it was seen here.
• Platform SDK Redistributable: GDI+

dbghelp.dll

• The dbghelp.dll from Microsoft. Get it from the Microsoft site and put it into $SRC_ROOT/external/dbghelp. (Note: You may have to search Microsoft's website.) Last time it was seen here.
• Platform SDK Redistributable: Dbghelp.dll

crt files

Those files have their place in external/msm90

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

You can find these files in your directory c:\program files\common files\merge modules

msi files

Those files have their place in external/msi

A binary blob (must be installed to extract the files) is available at: instmsiw.exe and instmsia.exe

msvcp files

Thos files, initialy located in msvc folder, have to be put in external/msvcp90

• Microsoft.VC90.CRT.manifest
• msvcm90.dll
• msvcp90.dll
• msvcr90.dll

Summary

Example

As example, the files I manually put in my installation for every milestone :

ordinateur-de-eric-b-2:~/OOo4Kids ericb$ ls -laR external

external/dbghelp:

• -rwxr-xr-x 1 ericb ericb 163088 Jan 23 2001 DbgHelp.Dll

external/gdiplus:

• -rwxr-xr-x 1 ericb ericb 1724416 Apr 14 2008 GdiPlus.dll

external/gpc:

• -rw-r--r-- 1 ericb ericb 18722 Dec 5 2008 GPC-Licencing.pdf
• -rw-r--r-- 1 ericb ericb 4749 Dec 17 2004 VERSIONS.TXT
• -rw-r--r-- 1 ericb ericb 75198 Sep 14 2007 gpc.c
• -rw-r--r-- 1 ericb ericb 4910 Sep 14 2007 gpc.h
• -rw-r--r-- 1 ericb ericb 28783 May 14 19:45 gpc232-release.zip

external/msi:

• -rwxr-xr-x 1 ericb ericb 1709160 May 14 19:44 InstMsiA.exe
• -rwxr-xr-x 1 ericb ericb 1822848 May 14 19:44 InstMsiW.exe

external/msm90:

• -rw-r--r-- 1 ericb ericb 603136 Jul 29 2008 Microsoft_VC90_CRT_x86.msm
• -rw-r--r-- 1 ericb ericb 827392 Jul 29 2008 Microsoft_VC90_DebugCRT_x86.msm
• -rw-r--r-- 1 ericb ericb 56832 Jul 29 2008 policy_9_0_Microsoft_VC90_CRT_x86.msm
• -rw-r--r-- 1 ericb ericb 57344 Jul 29 2008 policy_9_0_Microsoft_VC90_DebugCRT_x86.msm

external/msvcp90:

• -rw-r--r-- 1 ericb ericb 1857 Jun 28 09:25 Microsoft.VC90.CRT.manifest
• -rwxr-xr-x 1 ericb ericb 225280 Jun 28 09:25 msvcm90.dll
• -rwxr-xr-x 1 ericb ericb 572928 Jun 28 09:25 msvcp90.dll
• -rwxr-xr-x 1 ericb ericb 655872 Jun 28 09:25 msvcr90.dll

external/unicows:

• -rwxr-xr-x 1 ericb ericb 258352 Dec 7 2004 unicows.dll

Other software

Cygwin

• Cygwin Toolkit from http://www.cygwin.com. Use at least Cygwin DLL version 1.5.25. The official information about using setup.exe and installing Cygwin are available at: http://cygwin.com/cygwin-ug-net/setup-net.html. More help and information on the Cygwin tools can be found at http://website.openoffice.org/support/en/howtos/1.html. When installing Cygwin make sure you set the "Default Text File Type" to "Unix". This is the default setting.
  • Not all Cygwin packages are needed to build OpenOffice.org, but make sure that at least all the packages from the base category and the following packages are installed:
  • bison, flex, cvs, make, patch, perl, gcc, unzip, zip.

Important Note: within the Cygwin Toolkit, three executables might be realised as symlinks, namely awk.exe, gunzip.exe and 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. Check, in a cygwin shell, with 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; cp gawk.exe awk.exe. Take similar action for unzip.exe and tar.exe. the awk file (not awk.exe but AWK) must be rename.

Cygwin has a web based installation process that is described here. I used the “Install from Internet” method and it worked like a charm. Make sure that you tell the setup to use the “Unix/binary” file type. 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. Unfortunately the list of packages mentioned at the place describing the installation process is incomplete, some more are listed here. 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), subversion (for 3.x code line, minimum version 1.5.5)
• Category Libs: openssl
• Category Net: openssh, ncftp
• Category Perl: perl (Perl)
• Category Shells: rxvt, tcsh
• Category Utils: patch, gnupg
• Category Web: lynx, wget

The installer will automatically check and download 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 takes approximatively 20 to 30 minutes. Within the Cygwin Toolkit, some executables might be symlinks, in the version I have downloaded (1.5.24-2) it was awk.exe and gunzip.exe, older documentation also mentioned tar.exe. This can lead to a break of the build later, and the symlinks should be replaced by 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 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

Take similar action for gunzip.exe that I found to be a link to unzip.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.

Cygwin uses the command line shell “bash” by default and I always use this shell for everything I do with Cygwin. Building OOo is also possible using the shell “tcsh”, though some problems have been reported (see below). The recommendation is to use bash.

Though bash is the recommended shell you shouldn't try to deinstall tcsh. Cygwin doesn't have a simple mechanism to deinstall something automatically and it's still possible that one of the tools used for the build is using the tcsh internally because the script calling it doesn't evaluate the environment variable pointing to the shell to use. So it's safer to keep tcsh installed even if you use bash.

All commands written in this document are meant to be used in a bash (except explicitly told differently). In case you are not used to Unix command line shells you will need to familiarize yourself with some basic commands, but explaining that in closer detail is beyound the scope of this documentation. If you use the shell only for building the source all shell commands you will need are “cd” for the navigation between directories and “rm” in case you want to remove something. Use the “man” command to get more information (e.g. by calling “man cd”) or the “--help” option of the commands to get a short information about the basic options.

Perl modules

As explained elsewhere in the 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 pressed “Enter” in each step, even in case I got an error message that asked me for confirmation. You can do the same and just ignore any error messages you might see (the same is true for all queries while you are executing the “install” command mentioned below).

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

Optional :

• LWP::UserAgent
• SOAP::Lite
• Crypt::SSLeay

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 or if you want to build one of them. I recommend to install them anyway as sooner or later you want to work on a child workspace.

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.

Additional information for Cygwin and CPAN

Possible Cygwin errors exhibited when using CPAN (click me)

Nullsoft Scriptable Install System (NSIS)

• Nullsoft Scriptable Install System (NSIS): This is optional, if available a self contained Windows installer is created in addition to the MSI installer files.

Note: if NSIS is not present the build will ignore this step. Used to be that newer version of NSIS used to break the build (#85657), but it seems that in now works for up to 2.3.7.

Get the source and prepare to build it...

Get the source from SVN:

As preliminary, we suppose people have a correct subversion installation, know how to use it, and that they know what thery are doing when they use milestones with write access.

• check out a milestone from SVN

svn checkout -r963 svn://svn.adullact.net/svnroot/ooo4kids1/trunk OOo4Kids

More about our Subversion system and ssh can be found here.

Just a recommendation: if you change the version you are working on frequently, don't do complete checkouts all the time, instead of the use the "svn switch" command that only downloads the changes. After switching you should remove the output trees in all modules ( in SRC_ROOT that would be a "rm -rf */wntmsci12" command). At least the dependencies stored in the output trees may be invalid so you can't rely on them.

Additional dependencies for current milestone builds

Nothing yet

Doing the build (about 10 GB)

configure

Tip : to avoid the (Windows only) issue with spaces in the name, I decided to create a $HOME/tools directory in my home dir, and to put the MSCV and mscv contents (see below) in it. This helped to avoid a lot of issues !!!

The configure script is quitly slow on windows due to bash.exe.

Please adapt to your case

./configure
--with-OOo4Kids
--with-lang=fr
--disable-odk
--disable-mozilla
--enable-directx
--disable-activex
--disable-atl
--with-java=no
--with-cl-home=/home/eric/tools/msvc/VC
--with-use-shell=bash
--with-frame-home=/home/eric/tools/MSDK/v6.1
--with-psdk-home=/home/eric/tools/MSDK/v6.1
--with-midl-path=/home/eric/tools/MSDK/v6.1/bin/
--with-asm-home=/home/eric/tools/msvc/VC
--with-csc-path=/cygdrive/c/WINDOWS/Microsoft.NET/Framework/v3.5

Make sure DirectX SDK (november 2008) is installed or add --disable-directx

The settings for --with-psdk-home are case sensitive!

Configure changes have been made with milestone DEV300_m51

If you install the DirectX SDK into a custom folder, you will have to tell configure where with this option : --with-directx-home=/path/to/SDK

If you install NSIS into a custom folder, you will have to tell configure where with this option : --with-nsis-path=/path/to/NSIS

[FIXME] : verify the information below.

If you run into problems, check your settings in winenv.set.sh for WINDOWS_VISTA_PSDK, DISABLE_ATL, DISABLE_ACTIVEX
all have to be set 'TRUE'

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

The bootstrap

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:

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.

Start the build

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

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 -P2 -- -P2   # means 2 dmake for 2 processes in parallel. 

The “-P2” tells the build tools to start 2 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. The whole tree used approximatively 11 GB after a successful build. 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):

• Macbook pro, Mac OS X 10.4.11 running Windows XP on a Sun VirtualBox , with 1GB or RAM reserved : ~ 12 hours
• 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 "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

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.

Installing, preparing and running OOo4Kids

Find the install set

[FIXME] : needs to be written

Install the new Build

• double click on the *.exe icon
• follow the instructions

Run the new Build

• double click the application icon on the dekstop

Screenshots

Now you can start to work with this [FIXME : add screenshots]

Additionnal Information

Special Debug Builds with --enable-dbgutil

[FIXME : verify]

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.

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

Links