## Building OpenOffice.org under Windows with tcsh

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

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

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

    config_office> ./configure

In this example, the script `configure` is executed in the directory `config_office`. `$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 see here>/a>). 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. cws_srx644_ooo11beta.
2. Run the `configure` script to check all requirements and to create the script `winenv.set`.
3. Run the `winenv.set` script to set all environment variables.
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.

For detailed build instructions, see the section Building a Full Build of the Office Suite in this document. The installation procedure is described at the end of this document.

## 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 modules `dmake, external, xml2cmp, mkdepend, sal, solenv, vos, tools and rscpp`. These are required by `bootstrap` (see below).
5. Unpack the solver tarball in the `$SRC_ROOT` directory.
6. Run the `configure` script to check all requirements and to create the script `winenv.set`.
7. Run the script `winenv.set` to set all environment variables.
8. Create the build tools using `bootstrap`.
9. Build each module against the prebuild `solver` using the `build` tool, followed by `deliver`.

For detailed build instructions, see Building Individual Projects with a Prebuild.

## 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:

Build Requirements

- 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. (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`.

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 new 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

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.set` that you then run the `source` command on to set all necessary build environment variables.

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.

Before running configure, make sure that all needed Programs are in the system path or start configure the apropriate command line switches.

The following should demonstrate in detail what steps have to be done to set up the environment. For this 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)
- and the assembly compiler resides in `C:\ml`

### tcsh - Example

As the use of the tcsh shell is still experimental, you have to enable it with `--with-use-shell=tcsh`

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 source the configuration file which sets 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:

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

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.

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

Now you are ready to build OpenOffice.org. To build the entire suite, all you have to do (after having created the environment as described above) is to run dmake from the top-level directory. This will take several hours.

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

## 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> tar -xvzf solver643B_win32int.tar.gz

In order to create the build environment and build tools (bootstrap), you also have to check out the modules `config_office, dmake, external, xml2cmp, mkdepend, sal, solenv, vos, tools and rscpp`.

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

Files called `build.lst` in the directories `(module-name)/prj` contain all information about the subdirectories to be build (each of them containing makefiles `makefile.mk`), about internal dependencies, and also about modules the current module depends on. The files `(module-name)/prj/d.lst` control the actions done by `deliver`. The last or second to last directory to be build is usually module-name`/util` which is responsible for linking one or more shared libraries.

## 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
    $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

The 01 in the path names indicates that the localisation is american english. This number corresponds to the international phone code for the USA. The German installation set will be located in a subdirectory 49. This scheme holds true for all localisations you may have chosen explicitely (see next section Building Localised Versions of OpenOffice.org).

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.

The filenames of these files contain a number code for the language, corresponding to the international phone code of a country in which that language is mainly spoken. For instance, the file `helpcontent_34_wnt.zip` contains all helpcontent for the spanish localisation. The zipfiles themselves are available at ftp.services.openoffice.org/pub/OpenOffice.org/contrib/helpcontent/.

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,

where 01 corresponds to the international phone code of the USA. If you have chosen, for instance, French (by configuring with the `--with-lang=FREN` option) you will find an additional directory called 33:

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

Similarily, you will find 49 for German, 34 for Spanish, etc.

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.