content/tools/background.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>OpenOffice.org - Background for building</title>
<meta HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
</head>
<body>

<H1><A NAME="1.BackgroundInformationforBuildingOpenOffice|outline"></A>
Background Information</H1>

<P>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 <a href="http://www.openoffice.org/license.html">licenses</a> or the 
<a href="http://www.openoffice.org/FAQs/faq-questions.html#licensing">FAQ</a>.
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.
</P>

<P>The document is split into the following sections:</P>
<UL TYPE=DISC>
  <li><a href="#1.1.SourceTreesandOutputTrees|outline">
	  Source Trees and Output Trees</a></li>
  <li><a href="#1.2.UsingIdenticalBuildProcesses|outline">
	  Using Identical Build Processes</a></li>
  <li><a href="#1.3.ReleaseEngineeringBuilds|outline">
	  Release Engineering Builds</a></li>
  <li><a href="#1.4.DevelopingOpenOffice|outline">
	  Developing in the OpenOffice.org Project</a></LI>
</UL>

<H2><A NAME="1.1.SourceTreesandOutputTrees|outline"></A>Source Trees
and Output Trees</H2>

<P>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 <b>source tree</b>, i.e. the 
directory structure that stores all of the source code for
the office suite. 
</P>

<P>The <SAMP CLASS="code">solenv</SAMP> 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 <SAMP CLASS="code">bootstrap</SAMP> 
script created with the <SAMP CLASS="code">configure</SAMP> script.
</P>

<P>The build process generates files from the source tree and copies
them into an <B>output tree</B>, i.e. a directory
structure that the build process populates with all the files
necessary to build. The output tree is called <SAMP CLASS="code">solver</SAMP>.
</P>

<P>When you run bootstrap, the <SAMP CLASS="code">solver</SAMP>
directory is created. Initially, the <SAMP CLASS="code">solver</SAMP> directory
is empty. The build process populates this directory. The build
process delivers all binary files, shared libraries, and dynamic link
libraries to <SAMP CLASS="code">solver</SAMP>. 
</P>

<P>When you want to build a specific project, you only need the
sources of the relevant CVS modules and the output tree <SAMP CLASS="code">solver</SAMP>.
You do not need the entire source tree, though typically a developer will check
out one of the <a href="builds">branches</a> and build it from scratch.
</P>

<P>For more information on the <SAMP CLASS="code">solenv</SAMP> and
<SAMP CLASS="code">solver</SAMP> trees, see the <A HREF="http://tools.openoffice.org">Tools 
Project</A>.</P>

<H2><A NAME="1.2.UsingIdenticalBuildProcesses|outline"></A>
Using Identical Build Processes</H2>

<P>The build process in OpenOffice.org is identical for all platforms. 
</P>

<P>A OpenOffice.org make tool called <SAMP CLASS="code">dmake</SAMP> controls
the build process.</p>
<p>There are makefiles (<SAMP CLASS="code">makefile.mk</SAMP>) and 
project <a href=build_env_tools.html>build</a> files
<SAMP CLASS="code">prj/build.lst</SAMP>, 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.
</P>
<P>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.</P>
<P>The <SAMP CLASS="code">dmake</SAMP> tool is a make utility similar
to GNU <SAMP CLASS="code">make</SAMP> or the Workshop Compiler <SAMP CLASS="code">dmake</SAMP>.
This utility has an irregular syntax but is available from source on all
platforms.
The OpenOffice.org version of <SAMP CLASS="code">dmake</SAMP>
is a modified version of the original freeware <SAMP CLASS="code">dmake</SAMP>.
</P>
<P>When you run <SAMP CLASS="code">dmake</SAMP> from the top-level directory 
of the source tree all modules are built.  This is acheived by simply running
the <SAMP class="code">build -all</samp> in the instsetoo directory.  The build command is described in other <a href=build_env_tools.html>documentation</a>.
There are many dependencies between the modules,
so <SAMP CLASS="code">build</SAMP> must build them in a particular
order. The <SAMP CLASS="code">dmake</SAMP> 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 <SAMP CLASS="code">solver</SAMP>
tree.</P>
<P>For more information on the <SAMP CLASS="code">dmake</SAMP> tool,
see the <A HREF="http://tools.openoffice.org">Tools 
Project</A>.</P>
<H2><A NAME="1.3.ReleaseEngineeringBuilds|outline"></A>Release
Engineering Builds</H2>
<P>The OpenOffice.org source tree is structured into <B>project</B>s.</p>
<p>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.</P>
<P>Modules correspond to the directories under the 
top-level directory of the source tree. For example, the Writer project
includes the <SAMP CLASS="code">sw</SAMP>, <SAMP CLASS="code">starmath</SAMP>,
<SAMP CLASS="code">res</SAMP> modules, etc.
</P>
<p>To determine which project that a module belongs to look at the
CVS/Repository file.  For example</p>
<pre>
froddo: /data2/office
$ cd config_office

froddo: /data2/office/config_office
$ cat CVS/Repository
tools/config_office
</pre>
<p>We find out that the config_office directory (module) is part of the tools
project.</p>
<P>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 
<SAMP CLASS="code">prj/build.lst</SAMP> for example</p>
<pre>
froddo: /data2/office/sw/prj
$ cat build.lst
sw      sw      :       connectivity svx stoc uui sch NULL
</pre>
<p>We find that sw depends on connectivity etc.  These modules in turn depend
on others creating a large complex depency tree.</p>

<H3><A NAME="1.3.1.FullBuildsandRespinBuilds|outline"></A>Full Builds</H3>

<P>OpenOffice.org developers typically perform a <B>full build</B> 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.
</P>

<P>
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 <b>binary compatible</b> 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 
<B>respin build</B> 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. 
</P>
<P>By contrast, <B>binary incompatible</B> changes require a full
build. For reasons of efficiency, this is allowed with the approval of the
project owner.
</p>


<H3><A NAME="1.3.2.MilestoneBuilds|outline"></A>Snapshots / Milestone Builds</H3>

<p>OpenOffice.org is built and tested. 
Tarballs of the current source as well as <SAMP CLASS="code">solver</SAMP> 
and installation tarballs are published in the  
<a href="http://download.openoffice.org/index.html">download page</a> 
at www.openoffice.org. This happens roughly every four weeks. As a result, a 
<b>snapshot</b> 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 <b>milestone build</b>.

</P>
<H2><A NAME="1.4.DevelopingOpenOffice|outline"></A>Developing
in the OpenOffice.org Project</H2>

<P>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
<SAMP CLASS="code">xyz</SAMP> that is defined in the <SAMP
CLASS="code">svtools</SAMP>
module. Suppose also that the <SAMP CLASS="code">svx</SAMP> module
uses the method <SAMP CLASS="code">xyz</SAMP>. You can proceed as
follows:</P>
<OL>
	<LI>Download the milestone <SAMP CLASS="code">solver</SAMP>
	tarball for the platform you want to develop on.</LI>
	<LI>Check out the Utilities project from the CVS tree. This
	copies the <SAMP CLASS="code">svtools</SAMP> module to your local
	environment.</LI>
	<LI>Update the method in the <SAMP CLASS="code">svtools</SAMP>
	module. 
	</LI>
	<LI>Check what is the effect of updating the method on other
	modules. You may want to check how many  modules use the method <SAMP CLASS="code">xyz</SAMP>.
	This may be difficult to establish. You may conclude that the only
	other module that uses the <SAMP CLASS="code">xyz</SAMP> method is
	the <SAMP CLASS="code">svx</SAMP> module. If you are happy that you
	can make a compatible modification, you can continue.</LI>
	<LI>Make the change to the method <SAMP CLASS="code">xyz</SAMP>
	in the module <SAMP CLASS="code">svtools</SAMP>. 
	</LI>
	<LI>Build <SAMP CLASS="code">svtools</SAMP>, this delivers the
	output to the appropriate output tree. 
	</LI>
	<LI>In the <SAMP CLASS="code">svx</SAMP> module, make the changes
	corresponding to the changes that you made in <SAMP CLASS="code">svtools</SAMP>.</LI>
	<LI>Build <SAMP CLASS="code">svx</SAMP>, this delivers the output
	to the appropriate output tree. 
	</LI>
	<LI>Test your changes.</LI>
	<LI>Submit the patch.</LI>
	<LI>A community volunteer or the project owner checks the patch,
	comments on or approves it</li>
	<li>The patch is commited to the CVS tree.</li>
</OL>
<P><B>Note: </B>Another
project that you have not checked out may use the same method name.</P>

<H3><A NAME="1.4.1.TipsonHowtoAvoidBreakingtheBuild|outline"></A>Tips
on How to Avoid Breaking the Build</H3>

<P>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. 
</P>

<P>For example, if you change the <SAMP CLASS="code">sot</SAMP>
module so that it uses header or library files from the <SAMP CLASS="code">toolkit</SAMP>
module, you create a circular dependency. The <SAMP CLASS="code">toolkit</SAMP> module is built
after the <SAMP CLASS="code">sot</SAMP> module, and indirectly
depends on it. When the <SAMP CLASS="code">sot</SAMP> module refers
to the <SAMP CLASS="code">toolkit</SAMP> 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.</P>

<P>Note that the build process builds one
directory completely, and then builds the next directory.
</P>

<P>When you are working within a module, your code must respect the existing
structure of the module, in the following ways:</P>

<UL TYPE=DISC>
	<LI>Separate the building of objects from the linking of libraries. Create
	links in the <CODE>utils</CODE> directory
	as much as possible. This also enables you to find link targets
	easily.</LI>
	<LI>To reduce how long it takes to
	build, keep the source subdirectories to a reasonable size, that is,
	less than 50 files. 
	</LI>
	<LI>When more than one directory uses
	a header or library file, put the file in the <CODE>inc</CODE> directory.
	When you build, it appears in the <CODE><VAR>module-name</VAR>/inc</CODE>
	directory 
	of the shared output tree after the deliver phase of build process.</li>
</UL>
</BODY>
</html>