Background Information
This section provides background information about the build process for Star/OpenOffice.org. Note that StarOffice and OpenOffice.org are developed together, but are two different products, for details see licenses or the FAQ. Some parts of Star Office use third party code that cannot be used with OpenOffice.org. Some of this code has been replaced with Open Source code and some is left as a future project, for example the grammar checker.
The document is split into the following sections:
- Source Trees and Output Trees
- Using Identical Build Processes
- Release Engineering Builds
- Developing in the OpenOffice.org Project
Source Trees and Output Trees
OpenOffice.org developers work in parallel on all platforms. The source code for all platforms is identical, with the exception of the code for the interface to the operating and windows systems. This allows you to build for the different platforms simultaneously from a single source tree, i.e. the directory structure that stores all of the source code for the office suite.
The solenv tree contains the environment tools that the build process uses, for all supported platforms. Formerly it also included the platform-specific build tools. Now these build tools are created with a bootstrap script created with the configure script.
The build process generates files from the source tree and copies them into an output tree, i.e. a directory structure that the build process populates with all the files necessary to build. The output tree is called solver.
When you run bootstrap, the solver directory is created. Initially, the solver directory is empty. The build process populates this directory. The build process delivers all binary files, shared libraries, and dynamic link libraries to solver.
When you want to build a specific project, you only need the sources of the relevant CVS modules and the output tree solver. You do not need the entire source tree, though typically a developer will check out one of the branches and build it from scratch.
For more information on the solenv and solver trees, see the Tools Project.
Using Identical Build Processes
The build process in OpenOffice.org is identical for all platforms.
A OpenOffice.org make tool called dmake controls the build process.
There are makefiles (makefile.mk) and project build files prj/build.lst, handling the interdependencies of modules and directories throughout the source tree. The same makefiles are used for all platforms. Macros used control eventual platform-specific steps in the build process. This guarantees a minimum of effort when porting to a new platform as only the macros in the makefiles need to be adapted. The build process does not require any further scripts or platform-dependent makefiles.
Star/OpenOffice.org developers rewrote many of the build tools to make the OpenOffice.org build experience as close as possible to the normal open source build experience. As a result of this, all of the tools used in the make process are portable. OpenOffice.org developers wrote some of them, others are standard open source tools, usually GNU utilities.
The dmake tool is a make utility similar to GNU make or the Workshop Compiler dmake. This utility has an irregular syntax but is available from source on all platforms. The OpenOffice.org version of dmake is a modified version of the original freeware dmake.
When you run dmake from the top-level directory of the source tree all modules are built. This is acheived by simply running the build -all in the instsetoo directory. The build command is described in other documentation. There are many dependencies between the modules, so build must build them in a particular order. The dmake tool builds the various direcotires in the modules, then delivers all header files, generated header files, binary files, shared libraries, resources, and so on to the solver tree.
For more information on the dmake tool, see the Tools Project.
Release Engineering Builds
The OpenOffice.org source tree is structured into projects.
A project builds a particular component of the office suite. For example, the Writer project builds the Writer application. A project is an application, function, or simply a summary of classes. A project may be subdivided into modules. A module is the smallest unit of the office suite that can be built.
Modules correspond to the directories under the top-level directory of the source tree. For example, the Writer project includes the sw, starmath, res modules, etc.
To determine which project that a module belongs to look at the CVS/Repository file. For example
froddo: /data2/office $ cd config_office froddo: /data2/office/config_office $ cat CVS/Repository tools/config_office
We find out that the config_office directory (module) is part of the tools project.
There are many dependencies between the modules, and the modules must build in a particular order. Module prerequisites are described in first line of the file prj/build.lst for example
froddo: /data2/office/sw/prj $ cat build.lst sw sw : connectivity svx stoc uui sch NULL
We find that sw depends on connectivity etc. These modules in turn depend on others creating a large complex depency tree.
Full Builds
OpenOffice.org developers typically perform a full build of OpenOffice.org in order to build their modules. A full build also recompiles all of the source code. It can take up to 16 hours to perform a full build of OpenOffice.org. Using tools such as distcc and ccache can have dramatic time improvements however.
To avoid the need of a time-expensive complete re-build each time a change in the code is introduced, the developers are asked to introduce only binary compatible changes in the code unless the it is agreed with the project owner. This means that the changes made are of such a nature that no recompilation of further dependent modules become necessary (inserting a new, non-virtual method in a C++ class would be an example of such a binary compatible change). The office suite will then be re-compiled as a so-called respin build before the next 'master' s declared. A respin build obeys only weak dependencies, i.e. dependencies within a module. Using weak dependencies allows you to, for example, to modify a base library header file without needing to perform a full build. Since a respin build relies on binary compatible changes, modules can be build in parallel, and the build takes much less time (a few hours) in contrast to a full build.
By contrast, binary incompatible changes require a full build. For reasons of efficiency, this is allowed with the approval of the project owner.
Snapshots / Milestone Builds
OpenOffice.org is built and tested. Tarballs of the current source as well as solver and installation tarballs are published in the download page at www.openoffice.org. This happens roughly every four weeks. As a result, a snapshot of the current state of OpenOffice.org is available. In case the snapshot contains some outstanding 'milestone' improvements in functionality or coding, we may also refer to the snapshot as a milestone build.
Developing in the OpenOffice.org Project
The following is an illustration of how open source developers contribute to the OpenOffice.org project. Suppose that you want to update a method called xyz that is defined in the svtools module. Suppose also that the svx module uses the method xyz. You can proceed as follows:
- Download the milestone solver tarball for the platform you want to develop on.
- Check out the Utilities project from the CVS tree. This copies the svtools module to your local environment.
- Update the method in the svtools module.
- Check what is the effect of updating the method on other modules. You may want to check how many modules use the method xyz. This may be difficult to establish. You may conclude that the only other module that uses the xyz method is the svx module. If you are happy that you can make a compatible modification, you can continue.
- Make the change to the method xyz in the module svtools.
- Build svtools, this delivers the output to the appropriate output tree.
- In the svx module, make the changes corresponding to the changes that you made in svtools.
- Build svx, this delivers the output to the appropriate output tree.
- Test your changes.
- Submit the patch.
- A community volunteer or the project owner checks the patch, comments on or approves it
- The patch is commited to the CVS tree.
Note: Another project that you have not checked out may use the same method name.
Tips on How to Avoid Breaking the Build
When you are developing in OpenOffice.org, your code must respect the order in which the modules are built. Otherwise, you may create a circular dependency. A circular dependency is created when a module attempts to use features in another module that is built after it.
For example, if you change the sot module so that it uses header or library files from the toolkit module, you create a circular dependency. The toolkit module is built after the sot module, and indirectly depends on it. When the sot module refers to the toolkit module, it becomes dependent on it, and the circular dependency is created. This will cause the build to break and another solution must be found.
Note that the build process builds one directory completely, and then builds the next directory.
When you are working within a module, your code must respect the existing structure of the module, in the following ways:
- Separate the building of objects from the linking of libraries. Create
links in the
utils
directory as much as possible. This also enables you to find link targets easily. - To reduce how long it takes to build, keep the source subdirectories to a reasonable size, that is, less than 50 files.
- When more than one directory uses
a header or library file, put the file in the
inc
directory. When you build, it appears in themodule-name/inc
directory of the shared output tree after the deliver phase of build process.