# The detailed build guide

Since we dramatically simplified the build process, we didn't need all this cruft; but we thought we'd keep it around.

## 0. Contents

- 1. Getting OO.o
- 2. Building OO.o
- 3. Installing OO.o

## 1. Getting OO.o

### 1.1. Which OO

There are at least 3 important streams of development in the OO.o world, see here for a map.

The active development branch (currently HEAD) is the most buildable tree, however the OOO_STABLE_1 branch has the most stable code. Thus there we have a quandary. This document deals only with HEAD, but section 11 has some hints on building OOO_STABLE_1.

For a complete list of tags and their current status see the Build tags page.

### 1.2. Checking it out

The CVS root is structured differently from other projects. There is an `OpenOffice` CVS alias that checks out a whole bunch of modules. These get checked out into the current directory, and to perform a CVS update it is necessary to change into each directory and do "cvs update" manually, or you can set $CVSROOT beforehand.

Thus you should create a directory and then checkout inside it:

    mkdir HEAD
    cd HEAD
    export CVSROOT=:pserver:anoncvs@anoncvs.services.openoffice.org:/cvs
    cvs login
    You can just press Enter when it prompts you for the password
    cvs -z3 checkout OpenOffice

Note: The checkout size is ~250Mb these days, (for reasons unknown this has increased sharply recently).

Note: The repository in the openoffice.org CVS machine lives in a "/cvs" directory. CVS has a misfeature whereby it will prevent you from checking out stuff into a directory with the same prefix as the one the CVS repository uses. So if you try to do this:

    cd /cvs
    mkdir HEAD
    cd HEAD
    export CVSROOT=:pserver:anoncvs@anoncvs.services.openoffice.org:/cvs
    cvs login
    You can just press Enter when it prompts you for the password
    cvs -z3 checkout OpenOffice

It will not work. You should check out under /opt/OpenOffice/HEAD or something like that, or alternatively create a /cvsoo directory instead of your "normal" /cvs one.

### 1.3. Updating

Your base HEAD directory does not have a "CVS" subdirectory inside it, so you cannot just cd into it and do "cvs update". You have to set $CVSROOT beforehand.

### 1.4. Getting other bits

To build OO.o you really need:

- binutils-2.13.2.1,
- gcc-3.2.2,
- j2sdk-1.3.1, (for the 1.0.X branch; for later versions of OO.o you need): j2sdk-1.4.1-01-linux-i586-gcc3.2.tar.bz2,
- gpc231 (This is the General Polygon Clipper , not the GNU Pascal Compiler - the source isn't that eclectic (yet).).
- Optionally ccache to speed up subsequent re-compiles, if you have lots of spare disk.

Unpack them all joyfully somewhere; and copy the gpc231/gpc.[ch] source files into into the HEAD/external/gpc directory. These do not come with the base checkout because of dubious licensing — this will be resolved shortly.

Note: for the too clever by half people among you who have noticed your distribution (eg. RedHat9) ships versions as good as this; you will get away with an older binutils; but Red Hat have done odd things to their gcc/libstdc++ combo - such that the 'product' packaging phase will not work. This can be tweaked (with some evilness) in solenv/inc/tg_compv.mk - but it's easiest for beginners to install their own gcc-3.2.2.

## 2. Building OO.o

### 2.1. Use screen

Screen lets you run a shell, and detach from it at will. Use it!, when X crashes, and the build keeps on running you'll thank. First you need to insert:

    deflog on
    logflush 5
    escape ``

into your ~/.screenrc. This will log to the current directory when you start screen. To detach use ` d (<backtick> d), and reattach use screen -r. The log of the build will appear as screenlog.0 in the directory you start it in.

### 2.2. Know your tools

The primary build tool is dmake. There is a good overview of how it works here. Essentially, the rules are much like normal make rules, most rules are included from `solenv/inc`, and the rules are informed by environment variables setup by the configure process.

Other build tools are in `solenv/bin` particularly `build`, which ensures that dependencies are built for any given sub-project, and `deliver` which copies built source into the solver

### 2.3. What to do

Make sure you have all the source, especially the Java bits, which are required by the build for all manner of XML work, and while the configure may let you get away without it — the build will not — perhaps several hours in (just as you go to bed).

#### 2.3.1. Check source

You did read point 1.4 yes ? you'll also need to snarf any random patches, and apply them at this point.

#### 2.3.2. build binutils

By now you will have chosen a prefix; here referred to as /opt/OpenOffice, so unpack binutils there and:

    ./configure --prefix=/opt/OpenOffice
    make && make install

#### 2.3.3. Unpack jdk

Unpack the Jdk into your prefix /opt/OpenOffice/jdk-1.4.N, and symlink it to 'jdk' for easy updates in future.

#### 2.3.4. Setup paths

Ensure that /opt/OpenOffice is at the head of your path, followed by the JDK binary path, say /opt/OpenOffice/jdk/bin. Also you'll need the gcc bindir, if it's different from /opt/OpenOffice

    export PATH="/opt/OpenOffice/bin:/opt/OpenOffice/jdk/bin:$PATH";
    export LD_LIBRARY_PATH="/opt/OpenOffice/lib:/opt/OpenOffice/jdk/lib:$LD_LIBRARY_PATH"

It's perhaps worth creating a script to do that. NB. to execute such a thing you need to use the invocation

    . scriptname      # under bash or
    source scriptname # under broken shells

If you try and run such a script normally, it'll run in it's own shell, which will have it's environment beautifully setup, before exiting back to the calling shell.

#### 2.3.5. Build gcc

Unpack gcc and:

    ./configure --prefix=/opt/OpenOffice
    make && make install

This should work flawlessly the first time.

#### 2.3.6. Setup ccache

While you don't need ccache, it's use will speed up re-compilation dramatically, cutting build times by more than half.

Ccache can work in two ways, first by sym-linking ccache to g++, gcc etc. and having these elsewhere in your path. And secondly by invoking 'ccache gcc' instead of plain gcc. Since HEAD currently has nasty path mangling mess it's advisable to use the latter approach. To do this:

    export CC='ccache gcc'
    export CXX='ccache g++'

This (along with all environment setup) has to be done before configure time. If you are going to be hacking OpenOffice and going round development iterations, you should probably read 6.1 first, since re-building with different flags will invalidate the cache.

#### 2.3.7. Configure OO.o

Pop into config_office/ and do:

    ./configure --with-gcc-home=/opt/OpenOffice

This process takes a snapshot of your environment, merges it with the necessary flags, makes several mistakes and sets up LinuxIntelEnv.Set.sh [or similar] in the base directory. It's worth a read, particularly to check the PATH, LD_LIBRARY_PATH if things go wrong.

In places in this document, we use the target specific string 'unxlngi4.pro'. On other architectures this will be different, inspect the value of $INPATH in FooPlatform.Set.sh in your base dir.

#### 2.3.8. Bootstrap the environment

Recent versions of OO.o allow you to build with an sh derived shell: bash, dash, ksh, zsh etc. ( which is excellent ), just:

    source LinuxIntelEnv.Set.sh
    ./bootstrap

Alternatively you can let the pain start here; switch to your base directory and run tcsh (an improved csh). Import the environment, then run the bootstrap process to build the build tools. This habitually fails, and needs re-running - don't be daunted:

    tcsh
    # abandon all hope of sane tab completion, redirection etc.
    source LinuxIntelEnv.Set # NB. no .sh
    ./bootstrap
    # watch it die sometimes for no really good reason
    ./bootstrap
    # repeat until it succeeds

#### 2.3.9. Build in earnest

Now you're ready to make everything; ultimately, unless you have a solver you get to build everything first time, so just type `dmake` — you did read 2.1 first didn't you?

Unless you're building on RH 6.2 - you will need to hack this first. Then, make a cup of tea, sleep, wake up — and it's built.

### 2.4. Parallel building

A marginal improvement in performance can be had by building several non-dependant toplevel modules in parallel — this is much safer than trying to dispatch multiple compiles simultaneously, and uses the 'build' tool's dependency mechanism. Try `build -PP`.

### 2.5. Common problems

#### 2.5.1. Mozilla integration

Commonly, depending on gcc version the connectivity/mozab project will not build. Disable this by removing 2 lines in connectivity/prj/build.lst.

#### 2.5.2 instlation path

Will Lachance reports: Don't checkout your source-tree to any path with "stl" (e.g.: apostle, castle, etc.) in it. OpenOffice will do a substitution called "dont_use" to any path containing that sub-string.

## 3. Installing OO.o

### 3.1. Where is it ?

The result of a perfect build is a set of binaries in the solver, these however are useless for running; indeed — go no-where near them. A 2nd result of the build is that the `instsetoo` directory contains an install set.

### 3.2. Fix your environment

Run a new terminal; ensure that you are running bash; breathe a sigh of relief. Ensure that the $HOME environment variable is set.

### 3.3. Run the installer

Go into `instsetoo/unxlngi4.pro/01/normal`, run the setup program. Assuming all is well, this will execute a loader shim that unzips all the f0_XYZ* files into `/tmp/sv001.tmp`. These files contain the setup program, which is then executed, which proceeds to unzip the remaining f_XYZ* files. Install OO.o into some sensible prefix.

### 3.4. Watch it fail to detect the Jdk

Watch the installer ignore the JDK you built with, tell it the path, and watch it ignore that too. Resign yourself to no Java support. Or hack `setup2/source/custom/jvmsetup/unx` somehow to fix it.

### 3.5. Force a re-install

The installer will refuse to re-install if you have already installed OO.o, even if (eg.) you delete the old version. To remedy this attack `~/.sversionrc`, however removing this file will break everything, be careful.