Introduction into ooo-build
===========================

ooo-build provides an "easy" way for building and developing custom builds
of OpenOffice.org. It allows cooperation and work sharing of more vendors.

ooo-build supports building OOo the standard way: configure, make, make install.
It is able to apply lots of additional patches, hacks and fixes withing the
build and installation process. One release of ooo-build can support more
versions of OOo sources and more vendors. All the patches, hacks, etc. can
be effectively reused and shared. Finally, the are some more scripts that
are useful for developing OOo.


Example build using ooo-build
-----------------------------

# get ooo-build, for example a released one from
# http://go-ooo.org/packages/OOO680/ 

tar -xzf ooo-build-<version>.tar.gz
cd ooo-build-<version>

./configure \
    --with-distro=SUSE \
    --with-vendor=Novell \
    --prefix=/usr \
    --with-installed-ooo-dirname=ooo-2.0
    --enable-binfilter

./download	# this is one non-standard helper command, we added it because
		# there are many sources to be downloaded.
		# First, the OOo sources are split into more tarballs.
		# In addition, ooo-build is able to use some more extra
		# sources to enable features that have not been accepted
		# by the upstream yet

make

make install




Configuration
-------------

ooo-build has it's own configure script that has the following functions:
    - select vendor and distro for which the custom build is being done
    - select the right version of OOo sources
    - set some custom setting that is not supported by upstream, such as:
	--prefix
	--with-installed-ooo-dirname
	--with-binsuffix
	--with-icecream-max-jobs
    - enable/disable some optional features that are not yet configurable by
      upstream, for example:
        --enable-access (access import pieces via mdbtools)
	--with-openclipart (extra galleries from OpenClipArt)

The configure script generates the following files from the *.in templates:
    - download
    - bin/setup
    - distro-configs/*.conf
    - scratch/place
    - intltools*
    - and lots Makefiles all over the ooo-build sources

The tool download will be described later, see below.

The file bin/setup is a simple shell script that sets and exports some
shell variables. Many other ooo-build tools source this script to read
the setting.

The config files distro-configs/*.conf include config switches that are
passed to the OOo native configure script during the build phase.
distro-configs/Common.conf includes some common options, shared
by all distributions. distro-configs/<vendor>.conf includes vendor
specific options. There is one for each vendor.

The script scratch/place helps to develop huge fixes for OOo via the copy of
source files rather than by patches.

intltools are three scripts that help us to update translations of some
additional files. They are actually used only to update some desktop files.



Downloading of ooo-build sources
-------------------------------

The released versions of ooo-build and almost all the additional sources
can be download from http://go-ooo.org/packages/. Note that ooo-build
currently uses its own repacked OOo sources that are split into more
tarballs: binfilter, core, lang, sdk_oo, and system.

There is the script "download" that is able to download all the necessary
sources. It is generated by ooo-build/configure, see above.

It currently downloads:
    - the split OOo source tarballs
    - two dll files for mono stuff
    - slideshow html export icons
    - mdbtools source tarball
    - stripped down xt source zip
    - etc.




Unpacking, preparing sources
----------------------------

There are some preliminary actions that are done when "make" is called.

1. bin/unpack is called. It is a simple shell script that unpacks all
   the necessary tarballs into ooo-build/build directory or even into the
   unpacked OOo source tree

2. Thereafter "make" installs some extra artwork, like vendor specific bitmaps
   for splash screen.

3. Then the script bin/build-tools is called. It is able to build a special
   version of gcc. It was used in the past to test build with gcc-3.4.

4. Then patches/apply.pl is called. It applies all the selected patches, see
   below for more details

5. Finally, bin/transform is called. This shell script currently calls two
   scripts that update the default lists of fonts:
    * bin/font-munge
    * bin/help-font-munge

All these steps are reversible. It is very helpful, for example, for creating
and testing incremental patches.


Something more about patches
- - - - - - - - - - - - - - -

We currently have more than 500 patches. They are sorted into various
directories below ooo-build/patch. Then there is a so-called apply file in
ooo-build/patches/src680/. This file sorts patches into some more groups,
for example:

[ QuickStarter ]                                                                
# An improved built-in quick-starter applet / systray thing. i#57872            
speed-quickstart.diff                                                           
# An improved built-in quick-starter applet / systray thing. i#57872            
speed-quickstart-eggtray.diff                                                   


Some patches could depend on the OOo source version, for example:

[ TemporaryHacks < src680-m153 ]                                                
# LD_LIBRARY_PATH should not end with a ":" N#118188, #55733                    
ld-library-path.diff                                                            


The apply file also allows to define groups of groups, for example:

LinuxCommon : Common, BuildBitsLinuxOnly, LinuxOnly, SystemBits, CWSBackports, G
              QPro, Lwp, cairocanvas, VBAObjects, msaccess, \                   
              Safe64bit, FPickers, Mono, AddressBooks, QuickStarter, Shrink     


Finally, it defines what groups should applied for which distro, for example:

SUSE      : NovellBase, BerkeleyDB43                                            


This approach helps us to share work with more distributions. The
version-dependant patches are necessary because we do not want to force
everyone to use the same OOo source snapshot at the same time. One snapshot
is always set (in configure) as the default one but...



Building
--------

The command "make" calls bin/build-ooo after the sources are unpacked, patched,
and hacked.

The main tasks of the script build-ooo are:
    - run the OOo internal configure, see below* for more details
    - source the generated *set.sh
    - bootstrap OOo build
    - build the module transex3 and update translations from extra GSI sources
      if any available
    - finish build

In addition, there are some other build hacks and fixes, for example:
    - export LANG="C"; export LD_ASSUME_KERNEL=2.2.5 to avoid problems with
      Java on some platforms
    - set extra flags for dmake to allow parallel build with icecream

* The options for the OOo internal configure are read from bin/setup. It
  combines options that are passed to the ooo-build/configure, and options
  defined in ooo-build/distro-configs/*.conf




Installation
------------

The command "make install" calls bin/package-ooo. This script has the
following tasks:

    - install OOo
    - install extra wrappers into /usr/bin
    - install man pages
    - install vendor specific desktop files and icons
    - install extra dictionaries
    - install script for bash completion
    - build openclipart galleries
    - remove copies of the English help and rather create symlinks
    - hacks file lists:
	- rearrange subpackages
	- add some RPM specific tags, such as %config, %dir
	- remove RPM specific destdir

Some of the tasks are vendor specific, so there are many tests, such as:
    if test "z$VENDORNAME" != "zNovell" ; then 
	...
    fi

Some of the functionality is put into standalone scripts, for example:
    - bin/ooinstall
    - bin/build-galleries
    - bin/install-dictionaries



Misc stuff
----------

Everything above was necessary to build and install the custom build of OOo.

In addition there are some scripts that are helpful for developers, such as:
    - bin/tunnel, bin/cws-commit-patch, bin/cws-extract, which are very helpful
      for upstreaming patches and working with OOo cvs/CWS.
    - bin/oosmoketest, bin/ootestapi, bin/ootesttool, bin/test-ooo,
      bin/test-ooo-analyze, which might be useful for testing the custom build.
      These are quite new, so it is still a work in progress.

The directory ooo-build/scratch is used for developing huge fixes or features.
It allows to keep the current state in cvs via files instead of patches.
It is better because these kind of changes are usually developed a longer
time by more developers, ...

The directory ooo-build/stamp is used by makefile. It helps to define dependency
between the various makefile targets.

Finally, there are directories for some extra sources:
    - ooo-build/desktop
    - ooo-build/doc
    - ooo-build/fonts
    - ooo-build/man
    - ooo-build/src

