Difference between revisions of "Documentation/Building Guide/Basic Concepts"

Revision as of 09:31, 17 July 2009

To understand all concepts, techniques and the terminology described in this guide, make sure you understand the following basic concepts.

Terminology

Development branch

This is where most hacking is done. It has the most open policy for applying patches and it is typically where new features are developed and debugged.

The good side to this is that you have the latest features, the down side is that you get the side effects of the changes. We don't discourage you from working here but you can expect problems at times.

Developer releases are merged back to the stable branch on a semi-regular basis. All features migrated to the stable branch must be stable.

Stable branch

A stable branch is base for a release build of the OpenOffice.org product. This is where bug fix tracking takes place. The policy on these branches are to fix functional errors only.

The good side is that any patches are more thoroughly vetted before going into a stable release. Therefore you have fewer mystery bugs. The downside is that there are fewer features and some bug fixes are already in the developer release.

Master workspace branch

This branch, with the name mws_srxNNN, is the place where work from developers is integrated into the main codeline. Developers work in child workspaces with names cws_srxNNN_workspace_Name, and this work is then merged into the corresponding master workspace. Developer snapshots are released from this branch at regular intervals.

Porting branch

This is where a lot of porting to new platforms takes place. There are few features added in these branches and sometimes they are somewhat outdated in terms of functionality as a port needs some stability so that they are not solving new problems but working to an end goal together.

Features that are added are to help support that platform for example adding a new way of calling windowing functions for example coding Mac OS aqua calls instead of X windows calls.

This branch is used for platforms that are not yet part of the official release platforms, e.g. Irix and Linux s390.

Tinderbox builds

A tinderbox build can be any one of the above branch types. It is executed repeatedly on your machine. This ensures that the particular branch is working on all platforms that it is supposed to work on.

The reason that a build may break on a branch is that a developer committed a patch that did not take into account another platforms. A patch that works fine on windows but breaks a Linux build and vice versa.

More information
http://ooo.ximian.com/tinderbox-setup.html

Modules

The source code directory contains a lot of folders, each one representing a module. A module belongs to a project within the community, and provide an application, a function, or simply just a collection of classes. A module is the smallest unit of the office suite that can be built.

More information
Source code directories
Module Build Order

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.

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, see above.

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, see the page Source code directories.

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.

Source 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 window managers. 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 SVN 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.