Building OpenOffice.org under Windows

This document describes the requirements and actions that you need to build OpenOffice.org on Windows.

Commands you have to type on the keyboard follow this syntax throughout this document:

D:\my\source> winenv.bat

In this example, the script winenv.bat is executed in the directory D:\my\source under a 4NT shell. Depending on if you want to use the 4NT or the Cygwin tcsh environment, unless stated otherwise, all commands appearing in this document should be entered from a 4NT shell or a tcsh shell, respectively. (The exception is the configure script which has to be run from a cygwin bash shell.)

(The Cygwin tcsh environment is experimental, and can be used starting with cws_srx644_ooo20030412.)

$SRC_ROOT will denote the directory in which the source code of OpenOffice.org is stored.

Basically, there is the choice to build OpenOffice.org from two different branches: a stable branch, which results in the 1.0.x releases, or a less stable developer branch (latest release 643B). Links to the different sources are given in the document.

Table of Contents

• Overview
• of Performing a Full Build
• of Building an Individual Project
• Build Requirements
• External Components
• Get the Source Code
• Generating the Build Environment and Build Tools
• Build Instructions
• Building a Full Build
• Building Individual Projects with a Prebuild
• Building a Project with Debug Information
• Instructions to Build an Installation Set
• Building Localised Versions of OpenOffice.org

Overview

This section is meant as a reminder or checklist for those who have some experience in building OpenOffice.org. Everybody else should jump to the Build Requirements section.

Even experienced builders are well advised to check the release notes at www.openoffice.org/dev_docs/source/download.html and the section Build Requirements in this document to inform yourself about changes since the previous releases.

Detailed step-by-step build descriptions are given from the next section on.

You can perform a full build, or you can build an individual project using a prebuild version.

Overview of Performing a Full Build

To perform a full build, you need to follow these steps:

1. Get the source code, either from the download webpage (www.openoffice.org/dev_docs/source/download.html) or alternatively via a check-out from the cvs tree against a release tag, e.g. OpenOffice643.
2. Run the configure script in a cygwin bash shell to check all requirements and to create the script winenv.bat.
3. Run the winenv.bat (under 4NT) or winenv.set (under tcsh) script to set all environment variables.
The following point is only used for the tcsh environment, and not needed when using 4NT:
4. Create the build tools using bootstrap.
5. Build typing dmake in $SRC_ROOT, or build -all in the instsetoo module, or build followed by deliver in the individual modules.

Overview of Building an Individual Project

You can use a prebuild version to build an individual project. Having a prebuild version is necessary because the individual project you want to build could depend on other projects. A project builds a particular component of OpenOffice.org. For example, the Word Processing project builds the Word Processing application. To build an individual project, you must follow these steps:

1. Download the appropriate solver tarballs from the download webpage (www.openoffice.org/dev_docs/source/download.html) i.e., for 643B the solver tarball solver643B_win32intel.tar.gz.
2. Check out the modules for the project that you want to build from the OpenOffice.org cvs tree. If your project uses the resources module, res, check out this module also. You can, of course, also download the entire source from the download webpage (www.openoffice.org/dev_docs/source/download.html). However, it is not possible to download individual modules there.
3. Check out the module config_office. This is always necessary to create the build environment.
4. Also check out the module solenv.
5. Unpack the solver tarball in the $SRC_ROOT directory.
6. Run the configure script in a cygwin bash shell to check all requirements and to create the script winenv.bat.
7. Run the script winenv.bat to set all environment variables.
8. Build each module against the prebuild solver using the build tool, followed by deliver.

Build Requirements

Before you start building, you must ensure that your system satisfies the recommended software and hardware requirements for the type of system you are working on. For Windows, these are as follows:

Starting with cws_srx644_ooo20030412 there are two possible ways of building OpenOffice.org for Windows. The standard way using the proprietary 4NT shell and the new unixy way using the cygwin tcsh. Each of both methods has its own Build Requirements section.

Build Requirements - 4NT

• Windows NT Version 4 Service Pack 3 or higher.
• Microsoft Visual C++ Version 6 Service Pack 3.
• 4NT Version 2.5 or higher. You can download this from ftp://jpsoft.com/4nt/.

  Note: Before you use 4NT, you must ensure that the initialization file 4nt.ini is present in the 4NT application directory. The following code sample shows the content of the 4nt.ini file:

  [4NT]
  CommandSep = ^
  EscapeChar = Ctrl-X
  ParameterChar = &
  LocalAliases = Yes
  

• JDK 1.3.1.
• Only if you use the old Cygwin B-20 tools (new cygwin tools include it already): Perl 5 for Win32. You can download this binary from http://www.activestate.com/Products/ActivePerl/Download.html.
• Cygwin Toolkit from http://www.cygwin.com. This works, however, only for the 643B release and later! For any earlier release, an older cygwin version (b20) is recommended. Cygwin-b20 used to reside under various mirror sites, but has now been removed. A copy is kept at ftp://ftp.aubi.de/pub/b20+bison.zip.
  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.
  More help and information on the cygwin tools can be found at http://website.openoffice.org/support/en/howtos/1.html.
• In case you need to use the cygwin-b20 tools: GNU Bison 1.28. cygwin-b20 only contains Bison 1.25. You can download this from any mirror site given at http://www.gnu.org/software/bison/bison.html. In fact, only the bison.simple file in the share subdirectory of the cygnus-b20 installation has to be replaced by the corresponding file from the Bison version 1.28. To make things even more complicated, what cygnus-b20 understands as bison.simple is called bison.s1 at gnu.org, and yet other distributions name that file bison.hai. This means that if you put gnu's bison 1.28 to C:\bison-1.28 and cygwin b-20 resides in C:\cygnus\cygwin-b20, you have to do the following copy command:
  cp C:\bison-1.28\share\bison.s1 C:\cygnus\cygwin-b20\share\bison.simple.
  The above link to the Cygwin b20 version (ftp://ftp.aubi.de/pub/b20+bison.zip) does have the right bison version already in place.
  Bison will also need a C:\tmp directory to function properly.
• A Microsoft Assembly compiler. This may already be present in your installation in the same directory where the compiler is located (look for ML.EXE and ML.ERR). If not, instructions on where and how to get a free version can be found at http://www2.dgsys.com/~raymoon/faq/masm.html#9. Place ML.EXE and ML.ERR somewhere in a directory and note the path, i.e. C:\ml
• zip.exe Version 2.2 or higher, and unzip.exe. If you do not have these already, you can download them from www.info-zip.org. Note: The cygwin zip.exe is not working for the build under the 4NT shell. You have to use the native w32 version. Make sure that the first zip.exe in your path is the native w32 version, e.g. rename or delete the zip.exe in your cygwin /bin directory and copy the InfoZip version to this place. This issue should become obsolete once the 4NT shell is no longer a requirement for the build environment.
• Parts of the Microsoft Platfrom SDK, namely: the MDAC SDK (May 2002 or later), the Core SDK and the Internet Development SDK (the latters two are dependencies of the MDAC SDK). You can download this from http://www.microsoft.com/msdownload/platformsdk/sdkupdate. (This only affects 643 builds. If you are not building 643 but another earlier release, all you need to do is to copy the files AdoCtint.h and SqlUcode.h into $SRC_ROOT/external/download).
• The Microsoft Layer for Unicode - unicows.dll - is a runtime requirement for Windows 95/98/ME (not for NT/2000/XP). The file unicows.dll has to be downloaded and installed in the system or windows directory (i.e. C:\WINDOWS\SYSTEM or C:\WINDOWS, respectively). A self-extracting binary is available for download at http://download.microsoft.com/download/platformsdk/Redist/1.0/W9XMe/EN-US/unicows.exe. For technical details see http://porting.openoffice.org/servlets/ReadMsg?msgId=116287&listName=dev and http://porting.openoffice.org/servlets/ProjectDocumentList?dcID=515&action=download. (This only affects 643 builds.)
• 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.

Build Requirements - tcsh

• Windows NT Version 4 Service Pack 3 or higher.
• Microsoft Visual C++ Version 6 Service Pack 3.
• JDK 1.3.1.
• Cygwin Toolkit from http://www.cygwin.com. The official informations on using the 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 the following packages are installed.

  bison
  gawk
  gzip
  patch
  tar
  perl
  zip
• A Microsoft Assembly compiler. This may already be present in your installation in the same directory where the compiler is located (look for ML.EXE and ML.ERR). If not, instructions on where and how to get a free version can be found at http://www2.dgsys.com/~raymoon/faq/masm.html#9. Place ML.EXE and ML.ERR somewhere in a directory and note the path, i.e. C:\ml
• Parts of the Microsoft Platfrom SDK, namely: the MDAC SDK (May 2002 or later), the Core SDK and the Internet Development SDK (the latters two are dependencies of the MDAC SDK). You can download this from http://www.microsoft.com/msdownload/platformsdk/sdkupdate.
• The Microsoft Layer for Unicode - unicows.dll - is a runtime requirement for Windows 95/98/ME (not for NT/2000/XP). The file unicows.dll has to be downloaded and installed in the system or windows directory (i.e. C:\WINDOWS\SYSTEM or C:\WINDOWS, respectively). A self-extracting binary is available for download at http://download.microsoft.com/download/platformsdk/Redist/1.0/W9XMe/EN-US/unicows.exe. For technical details see http://porting.openoffice.org/servlets/ReadMsg?msgId=116287&listName=dev and http://porting.openoffice.org/servlets/ProjectDocumentList?dcID=515&action=download.
• 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.

Hardware Requirements

• Intel Pentium II PC
• 128 MB RAM recommended
• 2 GB free disk space

External Components

The code contains some further external components which are already provided. If you are interested in details about these, look at the External Components webpage at http://tools.openoffice.org/ext_comp.html.

Get the source code

You have two options to get the source code:

• Download the source code tarball (http://www.openoffice.org/dev_docs/source/download.html), e.g. oo_643B_src.tar.gz in case of the 643B release.

  Unpack the tarballs as follows (for the example 643B):

  > gunzip oo_643B_src.tar.gz
  > tar -xvf oo_643B_src.tar
  > cd oo_643B_src 
  

  This will be $SRC_ROOT from now on.

• Another possibility is to check out the code from the cvs tree. You may need runsocks to run cvs (with the cygwin tools it is not necessary). If you don't have a username and password, you can still do a checkout as anoncvs:

  > cvs -d:pserver:anoncvs@anoncvs.services.openoffice.org:/cvs login
  > CD $SRC_ROOT
  $SRC_ROOT> cvs /
      -d:pserver:anoncvs@anoncvs.services.openoffice.org:/cvs /
      co -r OpenOffice643 OpenOffice
  

  The non-bold slash means that the command should be in one line. It is possible to update an already existing older copy to a newer release:

  $SRC_ROOT> cvs /
      -d:pserver:anoncvs@anoncvs.services.openoffice.org:/cvs /
      update -r OpenOffice643 OpenOffice
  

• If you're only interested in building individual modules, you won't need the entire source code. You can check out individual modules from the cvs tree:

  $SRC_ROOT> cvs /
      -d:pserver:anoncvs@anoncvs.services.openoffice.org:/cvs /
      co -r OpenOffice643 (module-name)
  

• A note on the tags (i.e. the argument to the -r option in the cvs commands listed above): If HEAD is used as a tag, you will get the newest latest source code. This, however, will most likely not build since development is going on there. In general, the code is given a weekly tag like SRC641 (with weekly increasing numbers), and from there a branch tag OO641B (standing for OpenOffice.org 641 Branch) is created. Release engineering builds on this branch, adds eventual fixes, and tags the result as OpenOffice641B. The source tarballs are also created from this, i.e. the code resulting from checking out against OpenOffice641B is identical to the one in the 641 source tarball. After release, some further bug fixes will enter the branch. From then on, the code at OO641B and OpenOffice641B will differ. Finally, changes made on the branch (i.e. the difference between OO641B and SRC641) will be merged back to the main trunk.

  Some releases are respins of a previous release. Those are marked 'C' instead of 'B' (for instance OO641C and OO643C. Note that 'B' stands for 'branch' and not for any counting index, even though it is treated like that in case of a respin. Therefore, there is no such tag as OO641A.

Generating the Build Environment and Build Tools

Even if you want to use a non-open source shell to build on a computer running a Win32 operating system, the 4NT command shell, the Cygwin bash shell is needed to run the configure script which generates the build environment.

To use the new tcsh environment you have to use --with-use-shell=tcsh as command line switch to the configure script.

You use the configure script to generate the build environment. The configure script checks that all software, hardware, and system requirements for the build are satisfied, and it creates a configuration file called winenv.bat (4NT environement) or winenv.set (tcsh environement). In the 4NT case you have to start winenv.bat in your 4NT-shell to set the environment variables, in the tcsh case you have to run the source command on winenv.set

This configuration file will be moved into the SRC_ROOT directory. A top-level makefile script makefile.mk and the script bootstrap in the config-office directory will be moved into SRC_ROOT 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.

The following should demonstrate in detail what steps have to be done to set up the environment. First for the 4NT case and in a second example for the tcsh case.

For both examples we assume that

• the source code is in C:\oo643B
• JDK 1.3.1 is installed in C:\jdk1.3.1
• the Microsoft Compiler is located in C:\PROGRA~1\MICROS~3\VC98 (or C:\program files\microsoft visual studio\vc98)
• the Microsoft SDK is located in C:\PROGRA~1\MICROS~5 (only applies for 643B and later)
• the assembly compiler resides in C:\ml
• and your zip.exe and unzip.exe are in C:\unzip
  The tcsh example uses the Cygwin zip. No extra zip needed.

4NT - Example

Running the configure script could then look like the following (bold typed text is what you enter):

(open a cygwin bash shell)
cd /cygdrive/c/oo643B/config_office (new cygwin tools) or
cd //c/oo643B/config_office (old cygwin b20 tools, deprecated)

./configure --with-cl-home=/cygdrive/c/PROGRA~1/MICROS~3/VC98 --with-asm-home=/cygdrive/c/ml --with-jdk-home=/cygdrive/c/jdk1.3.1 --with-unzip-home=/cygdrive/c/unzip
.
.
.
(some screen output here)
.
.
.
(more screen output here)
bash-2.02$ exit


You should exit the bash shell. Now you can run the environment settings file winenv.bat from your 4NT shell.

Note the change in pathname notation. Since the cygwin bash shell won't accept backslashes, paths have to be typed in a cygwin bash notation which is //C/path/to/file or /cygdrive/c/path/to/file for b-20 or new cygwin tools, respectively, instead of C:\path\to\file. This may appear confusing at the moment, but sticking to this notation will work.

tcsh - Example

To run the configure script, type the following command:

$SRC_ROOT> cd config_office
config_office> ./configure --with-cl-home=/cygdrive/c/PROGRA~1/MICROS~3/VC98 --with-asm-home=/cygdrive/c/ml --with-jdk-home=/cygdrive/c/jdk1.3.1 --with-use-shell=tcsh

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

config_office> ./configure --help

After running configure you have to execute the configuration file which sets all environment variables. An example of how this file called winenv.bat (in the 4NT case) looks like with the example paths given above is shown here. In the 4NT-case you have to start winenv.bat in your 4NT-Shell, in the tcsh-case you have to start a tcsh and source the configuration file to set all environment variables:

$SRC_ROOT> tcsh



$SRC_ROOT> source winenv.set

If you experiment with newest sources from the cvs-tree, mind that updates to the configure process do 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 and set_soenv.in using the autoconf command. In this case, you would run commands like the following:
(This has to be done in a Cygwin bash shell)

$SRC_ROOT> CD config_office
config_office> cvs update configure.in
config_office> autoconf

In the 4NT case you don't need to generate additional build tools, all will be prepared when you call winenv.bat. But in the tcsh case you have to create some build tools. (Remember, you have a tcsh running at this moment.)

To create the build tools, type the following command:

$SRC_ROOT> ./bootstrap

The bootstrap utility creates the tools required for building. This involves already building some modules and will take a few minutes.

Build Instructions

Building a Full Build of the Office Suite

$SRC_ROOT> dmake

If you decide to rebuild a module or build each module individually (mind dependencies!), you 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

The following table shows the time required to build on a system with a particular specification. You can use these details to estimate the time required to build on your system.

Architecture	Intel
Processor	Pentium III
Processor speed	600 MHz
RAM	256 MB
Hard Disk	6 GB SCSI
Time	~10 h

Building Individual Projects with a Prebuild

OpenOffice.org is organised in several projects. For example, the Word Processing Project. These in turn consist of several modules, organised in separate directories. The source contains approximately 90 modules.

You can build any project or module individually. Building modules individually should not be misunderstood as reducing OpenOffice.org to a special application, say, for instance, the spreadsheet application. The program will always consist of the entire office suite: text processor, spreadsheet, drawing application, etc. Building individual modules comes in handy if you want to develop on a certain module. Most modules will depend on other modules to be already built. In other words, all modules must build in a particular order. To avoid building all modules which are prerequisites of the module of your interest, you can make use of a pre-build solver tree against which you can build any module.

For more information on modules and on the sequence that they build in, and on the dependencies, see tools.openoffice.org/modules.html.

You have to download the solver tree as a tarball solver643B_win32int.tar.gz from the Download page at http://www.openoffice.org/dev_docs/source/download.html and unpack it in the $SRC_ROOT directory, e.g.:

$SRC_ROOT> gunzip solver643B_win32int.tar.gz
$SRC_ROOT> tar -xvf solver643B_win32int.tar

To build a project, you build each of its modules individually in their directory with the build tool, followed by deliver to copy the created libraries, binaries etc. into the solver tree:

$SRC_ROOT/(module-name)> build
$SRC_ROOT/(module-name)> deliver

Building a Project with Debug Information

To rebuild a complete project with debug information, remove all object files by removing the wntmsci7.pro directory. Then run build with the debug option set to true:

$SRC_ROOT/(module)> rm -rf wntmsci7.pro
$SRC_ROOT/(module)> build debug=true

Instructions to Build an Installation Set

The build process (started with a top-level dmake or build -all in $SRC_ROOT/instsetoo) will create installation sets in english and german. A simple build in $SRC_ROOT/instsetoo will also create the installation sets, provided all other modules are already built.

If you have build an installation set earlier and want to re-build it, please delete the local outpath first:

$SRC_ROOT/instsetoo> rm -rf wntmsci7.pro

The English installation set will be located at $SRC_ROOT/instsetoo/wntmsci7.pro/01/normal. Execute the setup binary to install:

$SRC_ROOT> CD instsetoo/wntmsci7.pro/01/normal
normal> setup.exe

For a network installation, use the -net option to setup. Details on the network installation process can be found at http://installation.openoffice.org/proposals/netinstall.html in the installation project webpage.

Building Localised Versions of OpenOffice.org

Running the configure script with the --with-lang option will introduce the build of additional language resources. This option will introduce a command in the environment settings file which in turn after execution sets a variable like, for instance, RES_FREN to TRUE in the case of french (You can also set this variable by hand in order to introduce another language). It is also possible to build more than one language at once. One language resource, however, will not be introduced that way: the help content! Clicking on 'help' would still open english help documents.

There is no automatic procedure yet to implement non-english help, but the additional manual effort is rather minimal: After building the source as described above, but before building the installation set, a zip-file with all helpcontent for the language of choice has to be unzipped into the directory

$SRC_ROOT/solver/641/wntmsci7.pro/pck.

Having unzipped the helpcontent files in there, building of installation sets can be resumed or repeated (in case you already have build some), as described in the previous chapter. English installation sets will be located in

$SRC_ROOT/instsetoo/wntmsci7.pro/01/normal, 

$SRC_ROOT/instsetoo/wntmsci7.pro/33/normal.

Localised help content is not yet available for all languages. In such cases, the english helpcontent will appear in the installations. For instance, when Danish is set with configure, you will find installation sets under the directory 45, but the help files will appear in english.