Apache OpenOffice Wiki - User contributions [en]

Framework/Article/Generic UNO Interfaces for complex toolbar controls

2009-02-10T02:41:29Z

Divec: Change DropdownBox -> Dropdownbox

= Technical specification =

= Generic and easy to use complex tool bar controls for add-ons =

== State before OpenOffice.org 2.0.3 ==

The current user interface framework implemented for OpenOffice 2.0 gives developers the ability to integrate more complex controls (other than simple buttons) into their add-on toolbar. Although it's possible implementing these kind of controls for an add-on it's not an easy task. The developer has to implement a toolbar controller ([http://api.openoffice.org/docs/common/ref/com/sun/star/frame/ToolbarController.html com.sun.star.frame.ToolbarController]) and register it in the Controller.xcu file. The controller must provide an awt control to the framework which puts it into the toolbar. To have full control over the created control a developer has to implement and use several interfaces (e.g. [http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XToolbarController.html com.sun.star.frame.XToolbarController]). This complexity doesn't attract developers who just want to use complex controls without the need to have full control.

== Solution ==

The Addon.xcu file provides a way to describe the user interface for an add-on. It will be enhanced to enable users to provide the control type of every toolbar item. The following table shows all properties which are supported for toolbar items in Addons configuration file. The bold properties mark the new properties.

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="22%" bgcolor="#e6e6e6" |
Property
! width="20%" bgcolor="#e6e6e6" |
Type
! width="59%" bgcolor="#e6e6e6" |
Description
|- valign="TOP"
| width="22%" |
URL
| width="20%" |
String
| width="59%" |
The command which is bound to the toolbar item.
|- valign="TOP"
| width="22%" |
Title
| width="20%" |
String/localized
| width="59%" |
A localized text which is used as a label and/or quick help text.
|- valign="TOP"
| width="22%" |
ImageIdentifier
| width="20%" |
String
| width="59%" |
An optional identifier to an image. Normally not used as the set "UserImages" associates images to commands.
|- valign="TOP"
| width="22%" |
Target
| width="20%" |
String
| width="59%" |
Defines how to find a dispatcher for the command.
|- valign="TOP"
| width="22%" |
Context
| width="20%" |
String
| width="59%" |
Determines for which contexts the control should be visible.
|- valign="TOP"
| width="22%" |
'''ControlType'''
| width="20%" |
String
| width="59%" |
Defines the type of control.
|- valign="TOP"
| width="22%" |
'''Width'''
| width="20%" |
Long
| width="59%" |
Defines the width of the control. Only controls with a dynamic width support this property (e.g. Combo box, edit field, spin field)
|}
 
The following control types should be supported.

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="26%" bgcolor="#e6e6e6" |
Control
! width="74%" bgcolor="#e6e6e6" |
Description
|- valign="TOP"
| width="26%" |
ImageButton
| width="74%" |
A normal toggle button, but the size of the button depends on the image. At least the width, the height must follow some rules to prevent non-useful toolbars.
|- valign="TOP"
| width="26%" |
Combobox
| width="74%" |
A normal combo box with edit field inside.
|- valign="TOP"
| width="26%" |
Dropdownbox
| width="74%" |
A normal drop down box (only read only edit field).
|- valign="TOP"
| width="26%" |
Spinfield
| width="74%" |
A edit field with two buttons to increase/decrease numerical values.
|- valign="TOP"
| width="26%" |
Editfield
| width="74%" |
A normal edit field.
|- valign="TOP"
| width="26%" |
Button
| width="74%" |
A simple button without any need for status updates. This can useful if the button is always enabled and loading the add-on code on startup is costly.
|- valign="TOP"
| width="26%" |
ToggleButton
| width="74%" |
A simple button which can be controlled by status updates.
|- valign="TOP"
| width="26%" |
DropdownButton
| width="74%" |
A drop-down only button. Newly introduced by OpenOffice.org 2.0.
|- valign="TOP"
| width="26%" |
ToggleDropdownButton
| width="74%" |
A toggle button with a drop-down button. Newly introduced by OpenOffice.org 2.0.
|}

 

The user interface framework generates the controls when the add-on toolbar is created via the toolbar controller factory. Every add-on which wants to support a toolbar must be a dispatch provider. Therefore one communication protocol for the new controls will be the normal duo com.sun.star.frame.XDispatch / com.sun.star.frame.XStatusListener. The new controls are listener at the dispatch object they get after calling queryDispatch. The new controls will listen for special updates where a new struct called "ControlCommand" is provided. The ControlCommand struct offers developers a way to send commands to the control. It uses a string as command descriptor and a sequence of com.sun.star.beans.NamedValues for the arguments. This solution can be extended in the future and makes the implementation on the control side much easier.

<source lang="idl">
module com { module sun { module star { module frame {

struct ControlCommand
{
//-------------------------------------------------------------------------
/** specifies the command which should be processed by the toolbar
control.
*/
string Command;

//-------------------------------------------------------------------------
/** specifies a sequence of named values which are used as argument
for the command. The number and type of arguments depend on the
command and control.
*/
sequence< com::sun::star::beans::NamedValue > Arguments;
};

}; }; }; };
</source>
=== Control commands ===

Depending on the control type the command calls are interpreted. The following table gives an overview which commands could be supported by the new controls. The table can be extended without any problems regarding incompatibility. Please be aware that this table only shows the current state. New commands can be added in later OpenOffice.org versions.

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="17%" bgcolor="#e6e6e6" |
Control
! width="17%" bgcolor="#e6e6e6" |
Command/Status Update
! width="19%" bgcolor="#e6e6e6" |
Arguments
! width="47%" bgcolor="#e6e6e6" |
Description
|- valign="TOP"
| width="17%" height="16" |
ImageButton
| width="17%" |
SetImage
| width="19%" |
URL=String
| width="47%" |
Use the provided URL to load a new image
|- valign="TOP"
| width="17%" |
Combobox
| width="17%" |
SetText
| width="19%" |
Text=String
| width="47%" |
Set a new text into the edit field.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
SetList
| width="19%" |
List=Sequence<String>
| width="47%" |
A new list for the combo box.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
RemoveEntryPos
| width="19%" |
Pos=Long
| width="47%" |
Remove entry at position Pos.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
RemoveEntryText
| width="19%" |
Text=String
| width="47%" |
Remove entry with text = Text.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
InsertEntry
| width="19%" |
Pos=Long Text=String
| width="47%" |
Insert entry at position Pos with text Text.
|- valign="TOP"
| width="17%" |
Dropdownbox
| width="17%" |
SelectEntry
| width="19%" |
Entry=Long
| width="47%" |
Select entry number.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
SetList
| width="19%" |
List=Sequence<String>
| width="47%" |
A new list for the dropdown box.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
RemoveEntryPos
| width="19%" |
Pos=Long
| width="47%" |
Remove entry at position Pos.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
RemoveEntryText
| width="19%" |
Text=String
| width="47%" |
Remove entry with text = Text.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
InsertEntry
| width="19%" |
Pos=Long Text=String
| width="47%" |
Insert entry at position Pos with text Text.
|- valign="TOP"
| width="17%" |
Spinfield
| width="17%" |
SetValue
| width="19%" |
Value=Long/Double
| width="47%" |
A new value for the edit field.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
SetValues
| width="19%" |
Value=Long/Double 
Step=Long/Double 
LowerLimit=Long/Double 
UpperLimit=Long/Double 
OutputFormat=String
| width="47%" |
Set all possible values for the spin field at once.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
SetLowerLimit
| width="19%" |
LowerLimit=Long/Double
| width="47%" |
Set lower limit for the spin field.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
SetUpperLimit
| width="19%" |
UpperLimit=Long/Double
| width="47%" |
Set upper limit for the spin field.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
SetStep
| width="19%" |
Step=Long/Double
| width="47%" |
Set single step value for the spin field.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
SetOutputFormat
| width="19%" |
OutputFormat=String
| width="47%" |
Sets an optional output format string.
|- valign="TOP"
| width="17%" |
Editfield
| width="17%" |
SetText
| width="19%" |
Text=String
| width="47%" |
A new text for the edit field.
|- valign="TOP"
| width="17%" |
Button
| width="17%" |
---
| width="19%" |
 
| width="47%" |
Simple button doesn't support status updates.
|- valign="TOP"
| width="17%" |
ToggleButton
| width="17%" |
---
| width="19%" |
 
| width="47%" |
Currently I don't see a useful command here.
|- valign="TOP"
| width="17%" |
DropdownButton
| width="17%" |
SetList
| width="19%" |
List=Sequence<String>
| width="47%" |
A new list for the drop down box which get displayed when the user activates the drop down button.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
AddEntry
| width="19%" |
Text=String
| width="47%" |
Adds an entry at the end of the list.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
InsertEntry
| width="19%" |
Pos=Long Text=String
| width="47%" |
Inserts a new entry with text Text to the list at position Pos
|- valign="TOP"
| width="17%" |
 
| width="17%" |
RemoveEntryPos
| width="19%" |
Pos=Long
| width="47%" |
Removes an entry from the listbox at position Pos
|- valign="TOP"
| width="17%" |
 
| width="17%" |
RemoveEntryText
| width="19%" |
Text=String
| width="47%" |
Remove entry at position Pos.
|- valign="TOP"
| width="17%" |
ToggleDropdownButton
| width="17%" |
SetList
| width="19%" |
List=Sequence<String>
| width="47%" |
A new list for the listbox which get displayed when the user activates the dropdown button.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
CheckItemPos
| width="19%" |
Pos=Long
| width="47%" |
Checks the item at position Pos
|- valign="TOP"
| width="17%" |
 
| width="17%" |
AddEntry
| width="19%" |
Text=String
| width="47%" |
Adds a new entry at the end of the list.
|- valign="TOP"
| width="17%" |
 
| width="17%" |
InsertEntry
| width="19%" |
Pos=Long Text=String
| width="47%" |
Inserts a new entry with text Text to the list at position Pos
|- valign="TOP"
| width="17%" |
 
| width="17%" |
RemoveEntryPos
| width="19%" |
Pos=Long
| width="47%" |
Removes an entry from the listbox at position Pos
|- valign="TOP"
| width="17%" |
 
| width="17%" |
RemoveEntryText
| width="19%" |
Text=String
| width="47%" |
Remove entry at position Pos.
|}

 

The following code snippet shows how a command to set a new list for a "ToggleDropdownButton" can look like in C++.

<source lang="cpp">
// The command "SetList" currently supports only one parameter
Sequence< NamedValue > aArgs( 1 );

// create a sequence of strings for the dropdown menu
Sequence< rtl::OUString > aContextMenu( 3 );
aContextMenu[0] = rtl::OUString::createFromAscii( "Command 1" );
aContextMenu[1] = rtl::OUString::createFromAscii( "Command 2" );
aContextMenu[2] = rtl::OUString::createFromAscii( "Command 3" );

// argument is called "List"
aArgs[0].Name = rtl::OUString::createFromAscii( "List" );
aArgs[0].Value <<= aContextMenu;

FeatureStateEvent aEvent;

aEvent.FeatureURL = aURL;
aEvent.Source = (::com::sun::star::frame::XDispatch*)this
aEvent.IsEnabled = bEnabled;
aEvent.Requery = sal_False;

// initialize control command
com::sun::star::frame::ControlCommand aCtrlCmd;
aCtrlCmd.Command = rtl::OUString::createFromAscii( "SetList" );
aCtrlCmd.Arguments = rArgs;

aEvent.State <<= aCtrlCmd;

// send command via statusChanged to the control
xControl->statusChanged( aEvent );
</source>

To enable add-on developers to get notifications from the new controls a new interface must be added. It will be called 'com.sun.star.frame.XControlNotificationListener' and should be implemented by the dispatch object provided by 'XDispatchProvider::queryDispatch'. The new controls will send notifications for important events. The notification is not send when a user executes a function with the control itself (e.g. clicking on a button to execute a function will not be notified. 'XDispatch::dispatch(...)' is called instead).

<source lang="idl">
module com { module sun { module star { module frame {

interface XControlNotificationListener
{
//-------------------------------------------------------------------------
/** notifies that a control event has happened
@param Event
contains the event information
*/
void controlEvent( [in] ControlEvent Event );
};

}; }; }; };
</source>

The function controlEvent uses another struct called ControlEvent. The following code snippet shows the details of the structure.

<source lang="idl">
module com { module sun { module star { module frame

struct ControlEvent
{
//-------------------------------------------------------------------------
/** fully parsed URL describing the control that sends this
notification.
*/
::com::sun::star::util::URL

// -------------------------------------------------------------------------
/** specifies the event which has occurred.
*/
string EventName;

// -------------------------------------------------------------------------
/** specifies a sequence of named values which are used as
additional values for the event. The number and types of
named values depend on the event.
*/
sequence< com::sun::star::beans::NamedValue > Information;
};

}; }; }; };
</source>

As the event name is defined as a string and additional information provided as a sequence com.sun.star.beans.Named the event system can be extended easily. Depending on the control type the different events are notified. The following table gives an overview which events could be supported by the control types.

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="20%" bgcolor="#e6e6e6" |
Control
! width="15%" bgcolor="#e6e6e6" |
Command/Status Update
! width="19%" bgcolor="#e6e6e6" |
Information
! width="47%" bgcolor="#e6e6e6" |
Description
|- valign="TOP"
| width="20%" height="16" |
ImageButton
| width="15%" |
ImageChanged
| width="19%" |
URL=String
| width="47%" |
Called when a new image has been set.
|- valign="TOP"
| width="20%" |
Combobox
| width="15%" |
TextChanged
| width="19%" |
Text=String
| width="47%" |
Called when the text of the edit field has been changed.
|- valign="TOP"
| width="20%" |
 
| width="15%" |
ListChanged
| width="19%" |
List=Sequence<String>
| width="47%" |
Called when new list for the combo box has been set.
|- valign="TOP"
| width="20%" |
 
| width="15%" |
FocusSet
| width="19%" |
-
| width="47%" |
Called when the edit field has gained the input focus.
|- valign="TOP"
| width="20%" |
 
| width="15%" |
FocusLost
| width="19%" |
-
| width="47%" |
Called when the edit field has lost the input focus.
|- valign="TOP"
| width="20%" |
Dropdownbox
| width="15%" |
ListChanged
| width="19%" |
List=Sequence<String>
| width="47%" |
Called when the entry list of the combo box has been changed.
|- valign="TOP"
| width="20%" |
 
| width="15%" |
FocusSet
| width="19%" |
-
| width="47%" |
Called when the edit field has gained the input focus.
|- valign="TOP"
| width="20%" |
 
| width="15%" |
FocusLost
| width="19%" |
-
| width="47%" |
Called when the edit field has lost the input focus.
|- valign="TOP"
| width="20%" |
Spinfield
| width="15%" |
TextChanged
| width="19%" |
Text=String
| width="47%" |
Called when the text of the edit field has been changed.
|- valign="TOP"
| width="20%" |
 
| width="15%" |
LowerLimitChanged
| width="19%" |
Lower=Long/Double
| width="47%" |
Called when the lower limit for the spin field has been changed.
|- valign="TOP"
| width="20%" |
 
| width="15%" |
UpperLimitChanged
| width="19%" |
Upper=Long/Double
| width="47%" |
Called when the upper limit for the spin field has been changed.
|- valign="TOP"
| width="20%" |
 
| width="15%" |
StepChanged
| width="19%" |
Step=Long/Double
| width="47%" |
Called when the step value for the spin field has been changed.
|- valign="TOP"
| width="20%" |
 
| width="15%" |
FocusSet
| width="19%" |
-
| width="47%" |
Called when the edit field has gained the input focus.
|- valign="TOP"
| width="20%" |
 
| width="15%" |
FocusLost
| width="19%" |
-
| width="47%" |
Called when the edit field has lost the input focus.
|- valign="TOP"
| width="20%" |
Editfield
| width="15%" |
TextChanged
| width="19%" |
Text=String
| width="47%" |
Called when the text of the edit field has been changed.
|- valign="TOP"
| width="20%" |
 
| width="15%" |
FocusSet
| width="19%" |
-
| width="47%" |
Called when the edit field has gained the input focus.
|- valign="TOP"
| width="20%" |
 
| width="15%" |
FocusLost
| width="19%" |
-
| width="47%" |
Called when the edit field has lost the input focus.
|- valign="TOP"
| width="20%" |
Button
| width="15%" |
-
| width="19%" |
 
| width="47%" |
Currently I don't see a useful event here.
|- valign="TOP"
| width="20%" |
ToggleButton
| width="15%" |
-
| width="19%" |
 
| width="47%" |
Currently I don't see a useful event here.
|- valign="TOP"
| width="20%" |
DropdownButton
| width="15%" |
ListChanged
| width="19%" |
List=Sequence<String>
| width="47%" |
Called when a new list for the context menu has been set.
|- valign="TOP"
| width="20%" |
ToggleDropdownButton
| width="15%" |
ListChanged
| width="19%" |
List=Sequence<String>
| width="47%" |
Called when a new list for the context menu has been set.
|- valign="TOP"
| width="20%" |
 
| width="15%" |
ItemChecked
| width="19%" |
Pos=Long
| width="47%" |
Called when an entry at position Pos has been checked.
|}

== Final conclusion ==

The new controls and their interfaces should help normal developer to use complex controls in add-ons. There is also a second way to use these kind of controls which give developers more control, but need more effort. The proposed solution fits into the current framework environment. It reuses interfaces and concepts which every add-on developer already know and use.

 

There is an example add-on for Windows and Linux x86 available (source code is also available). The add-on needs at least OOo 2.0.3 to work correctly. You need at least the OOo 2.0.3 SDK to build the add-on. This example is part of the OpenOffice.org 2.2 SDK. You can find it in the folder ''examples/cpp/complextoolbarcontrols''.

{| width="100%" border="1" cellpadding="4"
|- valign="TOP"
! width="38%" bgcolor="#e6e6e6" |
Add-on
! width="62%" bgcolor="#e6e6e6" |
Link
|- valign="TOP"
| width="38%" |
Demo add-on (Windows/Linux x86)
| width="62%" |
http://framework.openoffice.org/files/documents/25/4121/DemoAddOn_cpp.oxt
|- valign="TOP"
| width="38%" |
Demo add-on source code (C++)
| width="62%" |
http://framework.openoffice.org/files/documents/25/4122/complextoolbarcontrols.zip
|}
 
 

== Appendix ==

Illustration which and how the framework environment objects interact.

[[Image:ComplexToolbarControls.jpg]]

[[Category:Development]]
[[Category:Framework:Article]]

Documentation/Building Guide/Building on Windows

2009-01-27T13:17:20Z

Divec: /* CPAN errors */

= Building OpenOffice.org on Windows =
This document tries to fill a gap. The existing documentation about building OOo on Windows mainly reads like “Building OOo on Windows explained for Linux developers”. I will collect and summarize this existing documentation, fix some of its errors and try to add some comments that address people that are already developing on Windows and now want to get to know about building OOo. So this document is also for those who are not used to unix like command line interfaces, tar balls etc. Of course you must be familiar with a command line, but you don't need to be a shell wizard. But on the other hand it wouldn't hurt if you are. :-)

I collected information from several places, e.g.:

[http://tools.openoffice.org/dev_docs/build_windows_tcsh.html#BuildRequirements http://tools.openoffice.org/dev_docs/build_windows_tcsh.html#BuildRequirements]

[[Windows|Building on Windows]]

[[CPAN_install | Perl modules installation with CPAN]]

[http://website.openoffice.org/support/en/howtos/1.html#1 http://website.openoffice.org/support/en/howtos/1.html#1]

The first problem with them is that there are many of them (there are even more than the mentioned four!). So you have to collect things by yourself and have to sort out non-Windows parts. Additionally some of the places contain outdated, incomplete or even wrong information. So I hope that my commented summary might come in handy for starters.

If this documentation is not enough for you or if you have a problem that is not addressed you can send a mail to the mailing list [mailto:dev@openoffice.org dev@openoffice.org] ([mailto:dev-subscribe@openoffice.org subscription] is recommended) or you can meet OOo developers on IRC in the channel #dev.openoffice.org at freenode.de. If you just want to give some feedback about the documentation please also use the mailing list.

You might want to know how many time and disk space installing the build environment will cost you. For a rough estimation I give some download, install and build times. They have been measured on an Athlon 64 X2 3800 (2GHz) dual core machine with 1GByte RAM and a 300 GB SATA disk. My internet connection is a 8MBit DSL broadband connection.

I created this document for building OOo using Microsoft Visual Studio 2005 Express, the “free” (as in beer) offering from Microsoft. It also works with Microsoft Visual Studio 2003, the small differences are mentioned in the text. Using Microsoft Visual Studio 2005 (without the “Express”) should work also but until now I have only one known case as a proof for this. But meanwhile things have become even more complicated because on the way to OpenOffice.org 3.0 the compiler was changed again and now the recommended compiler is Visual Studio 2008 (Express). Please see [[http://wiki.services.openoffice.org/wiki/Building_OOo_with_Cygwin_on_Windows#Download_and_install_MS_compiler_and_tools]] for more details.

Building works fine on Windows XP. It should work also on Windows 2000. I have no information about it but I assume that using Windows 98/ME is not a good idea (Visual Studio Express 2005 cannot be installed on Windows 98, so you'd probably need the full version of Visual Studio 2003 - but Windows 98 is unsupported for OpenOffice.org 3.0 anyway [[User:Cloph|Cloph]]). I don't know anything about building on Vista.

The first thing you need is the build environment. We are using Cygwin, a Windows program that emulates a complete Unix command line environment.

= Download and install Cygwin =
Go to [http://www.cygwin.com/ http://www.cygwin.com] und download the current version. If you already have Cygwin installed: you will need at least version 1.5.10. If you are using version 1.5.18 you must download a special version of the cygwin1.dll as described [http://tools.openoffice.org/dev_docs/build_windows_tcsh.html#BuildRequirements here]. But in general I would recommend to use a recent version.

Cygwin has a web based installation process that is described [http://website.openoffice.org/support/en/howtos/1.html#1 here]. I used the “Install from Internet” method and it worked like a charm. Make sure that you tell the setup to use the “Unix/binary” file type. Cygwin consists of some basic and a lot of optional packages. As building OOo needs some of these optional packages you have to select them in the installer. Unfortunately the list of packages mentioned at the [http://website.openoffice.org/support/en/howtos/1.html#1 place describing the installation process] is incomplete, some more are listed [http://tools.openoffice.org/dev_docs/build_windows_tcsh.html#BuildRequirements here]. Here's a complete list of the needed packages:

* Category Archive: unzip, zip
* Category Devel : autoconf, bison, cvs, flex, gcc-g++, gperf, make, openssl-devel (only needed for perl modules for CWS tooling, see below)
* Category Libs: openssl
* Category Net: openssh, ncftp
* Category Perl: perl (Perl)
* Category Shells: rxvt, tcsh
* Category Utils: patch, gnupg
* Category Web: lynx, wget

The installer will automatically check and download some more packages needed by thosed listed here. The total amount of disk space is 46 MB for the download and 174 MB for the Cygwin installation, including all the additional Perl modules shown below. The whole process took roughly 20 minutes.

Within the Cygwin Toolkit, some executables might be symlinks, in the version I have downloaded (1.5.24-2) it was awk.exe and gunzip.exe, older documentation also mentioned tar.exe. This can lead to a break of the build later, and the symlinks should be replaced by copies of the command they link to.

You can check this in the cygwin shell by calling e.g.

:
::
:::
:::: ''ls -l /bin/awk.exe''

whether e.g. awk.exe is a symlink. In version 1.5.24-2 awk.exe is a link to gawk.exe. The shell will show this by putting out “awk.exe -> gawk.exe”. In this case gawk.exe must be copied to awk.exe by executing:

:
::
:::
:::: ''cd /bin''
:::: ''rm awk.exe''
:::: ''cp gawk.exe awk.exe''

Take similar action for gunzip.exe that I found to be a link to unzip.exe.

In case you overlook something here or you have a newer Cygwin version with additional symlinks not mentioned here it's not a problem. You will get a helpful error message about an existing link in the configuration step (configure) later. The message will tell you which link you have to remove and you can do it following the advice given above for the awk.exe/gawk.exe pair.

Cygwin uses the command line shell “bash” by default and I always use this shell for everything I do with Cygwin. Building OOo is also possible using the shell “tcsh”, though some problems have been reported (see below). My recommendation is to use bash.

Though bash is the recommended shell you shouldn't try to deinstall tcsh. Cygwin doesn't have a simple mechanism to deinstall something automatically and it's still possible that one of the tools used for the build is using the tcsh internally because the script calling it doesn't evaluate the environment variable pointing to the shell to use. So it's safer to keep tcsh installed even if you use bash.

All commands written in this document are meant to be used in a bash (except explicitly told differently). In case you are not used to Unix command line shells you will need to familiarize yourself with some basic commands, but explaining that in closer detail is beyound the scope of this documentation. If you use the shell only for building the source all shell commands you will need are “cd” for the navigation between directories and “rm” in case you want to remove something. Use the “man” command to get more information (e.g. by calling “man cd”) or the “--help” option of the commands to get a short information about the basic options.

= Download and install MS compiler and tools =
Currently building on Windows needs a Microsoft Visual Studio C++ compiler. The “regular” builds for OpenOffice 2.x are done with Visual Studio 2003 that is available from Microsoft at a price. Building using the free (as in “free beer”) compiler Visual Studio 2005 Express works fine and is explained here. For OpenOffice 3.x the recommended as well as the "official" compiler is Visual Studio 2008 or 2008 Express.

== Visual Studio 2005 Express (for OOo 2.x) ==

In case you still can find a copy of the 2005 Express compiler setup and it still works it downloads additional content from the Web. You only need to select the Graphical IDE. More can be downloaded later if you want, but for building and debugging OOo you will not need more than the basic package. The download and installation took me roughly 10 minutes and 220 MB on my hard disk. The complete (not Web based) compiler installation set still can be downloaded as an ISO-images (~450 MB) from the [http://msdn2.microsoft.com/en-us/express/aa718401.aspx Manual Installation] site.

Next step when you plan to use the “Express” version is installing the [http://www.microsoft.com/downloads/details.aspx?familyid=7A1C9DA0-0510-44A2-B042-7EF370530C64&displaylang=en Microsoft Macro Assembler] (MASM). MASM is part of the paid version of Visual Studio (so you can skip that part if you are using it) but for the “Express” version you have to download it separately. It's only a very small download. I had a problem with the MASM installer on all machines where I used it: the setup started but then suddenly disappeared from the screen. I found a hanging msiexec.exe in the task manager and had to kill it manually. Fortunately the MASM was obviously installed correctly. It appeared in the “Add and remove software” dialog and the “ml.exe” was installed to “Vc/Bin” folder of VC8.

You also must download and install the Microsoft Windows Platform SDK. The usual instructions recommend to download it from [http://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5&displaylang=en here] but I followed the recommendations from the [http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/ Visual C++ site]. There you can find a link (download requires Genuine Windows Validation). '''WARNING''': don't install the new Vista platform SDK that is needed for the 2008 Express compiler (see below), the 2005 Express Compiler is does not work with it.

The setup is again web based. You can either user the “Typical” installation or select “Custom” setup and deselect the packages you don't need. You need at least the following packages:

* Microsoft Windows Core SDK
* Microsoft Web Workshop (IE) SDK
* Microsoft Internet Information Server (IIS) SDK
* Microsoft Data Access Services (MDAC) SDK
* Microsoft DirectShow SDK
* Microsoft Windows Installer SDK

You can deselect all 64Bit parts of these packages, all samples, all source code modules and (if you want) every documentation. In total the installation filled 438 MB of my harddisk space (including the documentation, but without all other optional parts).

Warning: the first installation option is called “Register Environment Variables” and it is deselected by default. You shouldn't change this as selecting it will add directories with blanks to your PATH variable. This (or more precisely the quotes surrounding them) will cause troubles in Cygwin (see below). It is also possible that other installed Windows programs (not only Cygwin) can't cope with the changed PATH variable as the installer of the Platform SDK explicitly warns.

The only drawback of not selecting this option is that if you wanted to use the platform SDK for other projects except OOo you would have to take care for the correct environment yourself. The platform SDK creates some start menu entries for shells with a suitable configured environment so that shouldn't be a problem.

There is a library called “libcp.lib” in the “Lib” directory of the SDK; it must be either moved away or renamed. You can read more about this [http://www.openoffice.org/issues/show_bug.cgi?id=49856 here].

There is another thing you have to change in the Platform SDK: you have to apply a small patch to one of the Platform SDK header files as described [http://tools.openoffice.org/servlets/ReadMsg?listName=dev&msgNo=6024 here].

== Visual Studio 2008 Express (OOo 3.x development) ==

You can download the 2008 Express compiler Web based setup or a DVD ISO from [http://www.microsoft.com/express/download Microsoft]. You don't need to install any optional parts.

You also must download and install the Microsoft Windows Platform SDK, but now in the [http://www.microsoft.com/downloads/details.aspx?FamilyId=F26B1AA4-741A-433A-9BE5-FA919850BDBF&displaylang=en newer version 6.0.6001.18000.367-KRMSDK_EN] that also supports Vista. This is a DVD image. You can either mount it with a suitable tool, burn it do a DVD or use tools like winrar that can extract files from ISO files directly. You don't need to install any samples or documentation (especially not installing the latter saves a lot of disk space - 193 MB instead of nearly 1GB).

The Platform SDK setup will also install the .NET Framework 3.5 SDK.

It might be best to install the Windows SDK into the default directory, and if not that into one without capital letters in the path. I used D:\Dev\Win_SDK\ and received some linking errors in the Python module (see [http://www.openoffice.org/issues/show_bug.cgi?id=88568+ Issue 88568]).

== DirectX SDK ==

Another SDK that could be downloaded and installed is the Direct X9 SDK. If you don't want to download it you can disable DirectX support in the configuration step (“--disable-directx”). The current regular builds of OOo are done with a version of the DirectX SDK that is no longer available for download so it's necessary to search for a download link in the Web. The OOo pages mention several links, outdated as well as working links. I took the one from [http://www.microsoft.com/downloads/details.aspx?FamilyId=D625324C-59B4-4951-849E-640B508DC442&displaylang=en here] (Genuine Windows Validation required). This is a 509 MB download as the setup is not Web based. Downloading, unpacking and installing took 30 minutes. As I deselected the sources and sample the resulting installation only was 189 MB.

Current (as of 2008/01) versions of the DirectX9 SDK and Windows Platform SDK do not fit to each other. To be able to build with DirextX enabled, you need to patch one file in the Platform SDK. See [http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2743771&SiteID=1 MSDN forum] for details].
'''WARNING''': do not use a DirectX10 SDK.

= Download of additional files =
You have to download some more files that you have to put into some prepared locations of the OOo source tree later. I mention it here because most of them are related to the MS compiler but perhaps it makes more sense first to download the source so that you can immediately copy the addtitional files to the proper location. Here's the list of files to download (with links) and the locations in the source tree where you must put them:

{| class="prettytable" border="1" width="100%"
| [http://www.microsoft.com/downloads/details.aspx?familyid=6A63AB9C-DF12-4D41-933C-BE590FEAA05A&displaylang=en GDI+ Redistributable] (Genuine Windows Validation required)
| external/gdiplus

|-
| Only for OOo2.x but due to a [http://www.openoffice.org/issues/show_bug.cgi?id=88652 bug] in configure still needed for 3.x: [http://download.microsoft.com/download/b/7/5/b75eace3-00e2-4aa0-9a6f-0b6882c71642/unicows.exe unicows.dll]
| external/unicows

|-
| [http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=CD1FC4B2-0885-47F4-AF45-7FD5E14DB6C0 dbghelp.dll]
| external/dbghelp

|-
| [http://download.microsoft.com/download/WindowsInstaller/Install/2.0/NT45/EN-US/InstMsiW.exe instmsiw.exe] and [http://download.microsoft.com/download/WindowsInstaller/Install/2.0/W9XMe/EN-US/InstMsiA.exe instmsia.exe]
| external/msi

|-
| for 2005 compiler: msvcp80.dll and msvcr80.dll (found in c:\WINDOWS/WinSxS/x86_Microsoft.VC80.CRT_1fc8b3b9a1e18e3b_8.0.50727.42_x-ww_0de06acd/msvc
| external/msvcp80

|-
| for 2008 compiler (until DEV300 m22): msvcp90.dll and msvcr90.dll (found in $(msvcdir)\Vc\redist\x86\Microsoft.VC90.CRT)
| external/msvcp90

|-
| for 2008 compiler starting with DEV300m23: Microsoft_VC90_CRT_x86.msm and policy_9_0_Microsoft_VC90_CRT_x86.msm for non debug builds and Microsoft_VC90_DebugCRT_x86.msm and policy_9_0_Microsoft_VC90_DebugCRT_x86.msm for debug builds. These merge modules are available in VS08 Express Edition and VS08 Professional Edtion. All *.msm files are located at c:\Program Files\Common Files\Merge Module.
| external/msm90

|-
| [http://www.cs.man.ac.uk/aig/staff/alan/software/ GPC]
| Unpack to external/gpc

|-
| [http://tools.openoffice.org/moz_prebuild/680/ Mozilla binary distribution]

(WNTMSCIruntime.zip,WNTMSCIlib.zip,WNTMSCIinc.zip)
| moz/zipped

|-
| msvcr71.dll and msvcp71.dll for Mozilla libraries (Search for them in the Web or on your PC. These files should be named as all lower case. Sometimes when downloaded they are upper case and this will cause 'file not found' errors towards the end of the build))
| external/msvcp71

|}

Some of the files can be found in a suitable OOo installation set also, so you can save the download by “stealing” it from your OOo installation.

OOo uses some Mozilla libraries. Building the corresponding sources is only possible with the VC2003 compiler so you have to use precompiled libraries that require the msvx71 libraries mentioned above. On Windows the Mozilla libraries are needed only for Mozilla address book support. Unfortunaly a bug in the module dependencies makes it necessary that the mozilla libaries are used anyway as otherwise building the module xmlsecurity fails (see [[Building_OOo_with_Cygwin_on_Windows#Setting_up_the_build_environment|below]]).

= Downloading and installing additional Perl modules =
As explained [[CPAN_install | elsewhere in the wiki]] some perl modules must be installed with CPAN. The necessary command in the cygwin shell is

:
::
:::
:::: ''perl -MCPAN -e shell''

If this command is executed the first time CPAN will ask for configuration. The autoconfiguration worked fine for me. I used the prompted installation just to see what is asked but always pressed “Enter” in each step, even in case I got an error message that asked me for confirmation. You can do the same and just ignore any error messages you might see (the same is true for all queries while you are executing the “install” command mentioned below).

Please note that CPAN is not able to deal with usernames containing spaces. To work around this fact, when CPAN asks you to specify the ''CPAN build and cache directory'', change the default suggestion to <tt>/cpan</tt>.

At the end the CPAN shell appeared and is ready to accept commands for installations. Each module is installed by typing “install $MODULENAME”. The modules that must be installed are:

* Archive::Zip
* XML::Parser (though it seems that this is already installed; doesn't hurt to do it)
* URI
* LWP::UserAgent
* SOAP::Lite
* Crypt::SSLeay

The last three modules are only needed if you want to use the [http://tools.openoffice.org/dev_docs/ooo-cws-tools-doc.sxw CWS tooling]. These tools are necessary if you want to create and maintain your own [http://wiki.services.openoffice.org/wiki/CWS Child Workspaces] or if you want to build one of them. I recommend to install them anyway as sooner or later you want to work on a child workspace.

CPAN will detect if a selected module depends on other modules and it will offer to download them also. As explained please just confirm this.

=== Cygwin errors exhibited when using CPAN ===

* I got an error message from CPAN somewhat like the following:

: C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\bin\cygiconv-2.dll to same
: address as parent(0x7C0000) != 0x7D0000

To fix this, I had to exit the Cygwin shell, run cmd.exe, then type "c:\cygwin\bin\ash.exe" to start the minimal shell, then type "/bin/rebaseall". Then CPAN worked when I ran it again.

* I got another error when cygwin was performing "make install":

: ERROR: Can't create '/usr/bin'; Do not have write permissions on '/usr/bin'

I can actually write to /usr/bin; however when I do "ls -ld /usr/bin", cygwin reports no write permission; and "chmod u+w /usr/bin" gives "Permission denied". This causes the install process to fail when it checks permissions. As a kludge, I installed vim, and edited line 368 of /usr/lib/perl5/5.10/ExtUtils/Install.pm, replacing this:

: return -w $dir;

with this:

: return 1;

which allowed installation to proceed.

= Downloading and installing Java and other tools =
Some OOo components as well as some build tools of OOo require Java. So you must download a JDK and the Java make utility [http://ant.apache.org/ Ant]. It's not necessary to read the whole installation instructions from Ant. After downloading the zip package just unpack the bin and lib folders from it into a directory that you specfiy as ant-home in the configure step later. The path to this directory must not contain blank characters!

All OOo builds can be done with [http://java.sun.com/j2se/1.4.2 JDK 1.4.2]. If your build is based at least on milestone m158 you can also use [http://java.sun.com/j2se/1.5.0 JDK 1.5.0.] Don't use Java 1.6, at least the hsqldb modules does not build with that version. This is status quo with milestone m218.

If a self contained Windows installer is desired in addition to the MSI installer files [http://nsis.sourceforge.net/ NSIS] 2.0.4 is needed, but it is optional. If NSIS is not present the build will ignore this step. Used to be that newer version of NSIS used to break the build ([http://qa.openoffice.org/issues/show_bug.cgi?id=85657 #85657]), but it seems that in now works for up to 2.3.7.

= Getting the source code =
You will place your code somewhere in your file system. In the following text this root directory will be called SRC_ROOT.

Source code is available via CVS or as a source tarball. Downloading and unpacking the latter needs less bandwidth but tarballs are not available for every milestone build, only for the latest release and the latest developer build, both available from our [http://download.openoffice.org download site]. If you want to work on a particular milestone or CWS you have to get the source directly from the cvs.

We have some documentation about working with cvs on OOo. Here's a short description how you can download the whole OOo2 source. You have to use the following commands to get e.g. the milestone m10 on the code line dev300 (with the cvs branch tag DEV300_m10):

:
::
:::
:::: ''export 'CVSROOT=:pserver:anoncvs@anoncvs.services.openoffice.org:/cvs'''
:::: ''cvs login ( use the CVS password: anoncvs when you are asked for it)''
:::: ''cd SRC_ROOT''
:::: ''cvs co -r DEV300_m10 OpenOffice2''

The alias “OpenOffice2” will check out all modules that are needed for OOo2.x or OOo3.x (a new alias for OOo3.x will be created in the near future); it is also possible to check out single modules. Checking out OpenOffice2 took me roughly an hour. If you already have a [http://www.openoffice.org/scdocs/ddSSHGuide.html cvs tunnel] working you can of course use this one instead of the anoncvs access I used in my example but anoncvs is much faster as it does not have the SSL overhead and latency.

If you got the tarball, e.g. the one for version 2.4.0, you can unpack it with

:
::
:::
:::: ''tar -xvzf Ooo_2.4.0_src.tar.gz''

The great [[User:Kr/Concurrent_Checkout | script from Kay Ramme]] that checks out any project or modules and – using the build lists of the modules and the dependencies created from them – all other modules that are needed for a successful build currently doesn't work for OOo3.x (fix is in the works). It uses several parallel cvs connections (anoncvs allows to use 3) and so should be a bit faster. I used the script several times and it took roughly 40 minutes. But if you wanted to go the safe way or you want to work on the 3.x code line you should use the checkout via the “OpenOffice2” target.

Once you have the source tree you can copy all the extenal files listed in the table above into the appropriate locations.

Whatever milestone (version) of OOo you want to use, never try to build the HEAD revision! As new files are committed to HEAD quite often when workspaces are integrated into the main code lines it is very likely that you start to check it out while committing of files is still in progress. The result will be an incomplete and inconsistent version that most probably won't build. The OOo versioning works in a way that release engineers commit files to HEAD and give these files a version tag for the next milestone, e.g. “DEV300_m10”. Once this version is built and tested sucessfully it is announced to be usable for developers and the race is on for the next round.

If you want to know which milestones are current please look into our “Environment Information System” ([[EIS|EIS]]). There is an RSS feed available that informs you about new available milestones. You can also [mailto:cws-announce-subscribe@openoffice.org subscribe] to the [mailto:cws-announce@openoffice.org cws-announce@openoffice.org] mailing list (or look into its [http://www.openoffice.org/servlets/SummarizeList?listName=cws-announce archive]).

EIS also provides a lot of other useful information and entry points to more documentation.

= Setting up the build environment =
Finally the “configure” tool is used to create the environment. It checks that all software, hardware, and system requirements for the build are satisfied, and creates configuration files called winenv.set (for tcsh) and winenv.set.sh (for bash) that are used to set all necessary build environment variables. If configure detects a problem it will stop and give you a useful (really!) hint how to fix it. You have to call “configure” from the SRC_ROOT/config_office directory.

The resulting configuration files are created in the SRC_ROOT directory. A top-level makefile script makefile.mk and the script bootstrap that are located in the config_office directory are moved into SRC_ROOT folder as well. This is due to technical reasons: The SRC_ROOT directory in the cvs tree can only hold directories. On the other hand, the top-level makefile.mk should logically be placed in the top-level directory SRC_ROOT. The cvs tree holds these files in config_office and configure copies them up.

Before running configure, make sure that all needed programs are in the system path or start configure with the appropriate command line switches. Make also sure that the PATH variable in your cygwin shell does not contain any blanks and quotes.

There are a number of options that you can use with the configure script. To display these options, type the following command:

:
::
:::
:::: ''./configure –help''

Here's my configure call (the folders of the different programs of course might be different in your case):

: ./configure \
:: --disable-directx \
:: --with-cl-home="/cygdrive/d/develop/msvc/VC" \
:: --disable-activex \
:: --disable-atl \
:: --disable-build-mozilla \
:: --with-frame-home="/cygdrive/d/develop/MSDK/v6.1" \
:: --with-psdk-home="/cygdrive/d/develop/MSDK/v6.1" \
:: --with-midl-path="/cygdrive/d/develop/MSDK/v6.1/Bin" \
:: --with-asm-home="/cygdrive/d/develop/msvc/VC" \
:: --with-jdk-home="/cygdrive/d/develop/j2sdk1.4.2_11" \
:: --with-csc-path="/cygdrive/c/Windows/Microsoft.NET/Framework/v3.5" \
:: --with-ant-home=/ant \
:: --with-use-shell=bash

(the pathes containing "msvc" and "msdk" should be self-explanatory.)

Sometimes configure had problems with paths containing spaces (no pattern detected) so I preferred to install into pathes without them. The "with-psdk-home" setting needs a case-sensitive path name. I recommend to use case-sensitive usage in all cases - it's good to get used to case sensitivity if you are going to work with Cygwin.

Most parameters are self-explanatory, but some options might need an explanation.

The Visual Studio Express compilers do not contain everything needed to build the OOo ActiveX control so I disabled it here. If you are using a “complete” Visual Studio (no “Express” version) you can omit this if you want. But the ActiveX control is not needed to run OOo, it's just an additional feature that lets OOo embed files into the Internet Explorer. On the 3.0.x code line and the 2008 Express compiler another step is necessary after configuring: the environment variable "DISABLE_ATL=TRUE" must be set in the shell and also (in case configure fails to detect the Windows platform SDK version correctly) WINDOWS_VISTA_PSDK also must be set to TRUE. [Remark: the detection failure results from the way how configure searches for the Vista PSDK: it will be found only if it is installed into the default location.] I manually added both variables to the winenv.set.sh file that was created by the "configure" call file. For all code lines since 3.1.x this has been fixed and both environment variables will be set properly.

As DirectX is not needed for most developers, its SDK consumes a lot of disk space and is prone to incompatibilities I recommend to build without DirecX support by using --disable-directx as shown above. Otherwise you have to provide the path to the SDK in --with-directx-home.

OOo uses some Mozilla components. As mentioned above it is not possible to build them from the sources using the Visual Studio 2005 compiler. So I disabled the build with an appropriate option. Disabling the Mozilla components with "--disable-mozilla" completely currently does not work due to a bug in the module dependencies.

Cygwin starts with a “bash” shell by default as already mentioned. My document explains how to build with this shell. Using a tcsh is possible though it may sometimes lead to problems (memory allocation errors, hanging builds) so I don't recommend to use it. Unfortunately using “tcsh” is still the default setting created by configure (as the first builds where done using it) and so I told configure that the bash should be used instead. If you want to try using tcsh remove the “--with-use-shell” parameter shown above and build with tcsh as explained below. In case the build breaks at some place you can manually patch your winenv.set.sh file and exchange the line

:
::
:::
:::: ''SHELL=”/usr/bin/tcsh”''

with

:
::
:::
:::: ''SHELL=”/usr/bin/bash” ''

and the line

:
::
:::
:::: ''“USE_SHELL=”tcsh”''

with

:
::
:::
:::: ''“USE_SHELL=”bash”''

Then close the tcsh and build again with bash as explained below.

After running configure you must create the dmake make utility that is needed for the build of OpenOffice.org. This done from the SRC_ROOT directory by calling

:
::
:::
:::: ''./bootstrap''

If you experiment with the newest sources from the cvs-tree, mind that updates to the configure process may not happen via updates of configure (the script file) but via the files configure.in and set_soenv.in. The configure script itself is created from configure.in using the autoreconf command. The perl script set_soenv is created when you run configure from set_soenv.in.

If you need to modify or create a correct configure you would run commands like the following:

:
::
:::
:::: ''SRC_ROOT> cd config_office''
:::: ''config_office> cvs update configure.in''
:::: ''config_office> autoconf''

to update the configure script. If you only use code from the snapshot releases on the web, you don't need to be concerned about this. If you are working on a Child Workspace you should rerun the configure script after each resync.

= Build Instructions =
Now you are ready to build OpenOffice.org. In every Cygwin instance used for building you have to set the environment variables from the generated configuration file(s).

If you are using bash got to your SRC_ROOT folder and call

:
::
:::
:::: .'' winenv.set.sh''

or if you are using tcsh call

:
::
:::
:::: ''source winenv.set''

Now you have two options to build the whole Office. You can either call “dmake” in SRC_ROOT or you can go to the “instsetoo_native” directory and use “build” that allows you to control the build process a bit better:

:
::
:::
:::: ''SRC_ROOT> cd instsetoo_native''
:::: ''SRC_ROOT> build --all -P4''

The “-P4” tells the build tools to start 4 parallel running processes. Using more than one process will speed up the build as it avoids that CPU time is wasted waiting for disk i/o. As a rule of thumb twice as much processes as you have CPU cores is a good number, so “-P4” is fine for my dual core Athlon 64 X2. On this machine (described at the top of this document) the complete build took roughly 2,5-3 hours. The whole tree takes 8,1GB after a successful build.

Some build times for comparison (as reported by users):

* Athlon XP 64 2 GHz, 1 GB RAM - 3 hours
* Athlon 1,15 GHz, 1 GB RAM - 18,5 hours
* Core2 Duo 2 GHz, 1GB RAM - 3 hours
* Core2 Quad 2,4 GHz, 4GB RAM - 1,5 hours

There are some special things in the way how OOo builds its modules. Every module has an “output” folder (with some subfolders for the different kinds of generated output) that is created the first time a build is done in the module. The name of this folder is “wntmsci10.pro” for builds with MSVC++2003 and “wntmsci11.pro” for builds with MSVC++2005. After a successful build of a module some of the generated files are copied to the output folder of the “solver” module by executing a tool called “deliver” (this is automatically called by build --all for each of the modules). Other modules will take these “delivered” files (header files, libraries etc.) to resolve their dependencies. The content of the solver module will also be used to pack the installation sets in the final step.

Sometimes a build breaks. You will get an error message that tells you which modules have to be rebuilt. It seems that at least on Windows in rare cases the build (especially a multi processor build) breaks without an obvious reason and redoing the build is enough to “fix” the problem. I didn't experience that in the last months but don't be surprised if it happens to you. Of course a build can break for “real” reasons also if you changed something in the source code. “build” will always tell you the modules it couldn't build successfully and you can then go to any folder inside the module(s) and fix the problems.

The build system recommends to use the “--from” parameter of the build command to continue the build where it broke after you have fixed the problem. Rumours are that this is not reliable everytime. So if you can bear the extra minutes that “build” needs to detect already built modules you should restart your build with “build --all” from inside instsetoo_native as you did the first time just to avoid uncertainties. For more options of “build” call

:
::
:::
:::: ''SRC_ROOT> build – help''

After a successful build you will find the OOo installation set in

:
::
:::
:::: ''instsetoo_native/wntmsci11.pro/OpenOffice/msi/Install/en-US''

“instsetoo_native” is the module that packs the installation set.

If you already have a version of OOo installed you can install your freshly built version in parallel by installing it with setup /a that just unpacks all files without any system registration.

If you decide to rebuild a module or build each module individually (mind dependencies!), you also will have to use the “build” tool from inside a folder of these modules. A “build” of a single module will not call “deliver” automatically as described above for the “build --all” case. You must call is manually to get the usual files copied to the solver tree so that other modules or the packaging module can use them.

:
::
:::
:::: ''SRC_ROOT/(module)> build''
:::: ''SRC_ROOT/(module)> deliver''

You can copy all new files manually to the appropriate places in your installation. There's no need to rebuild and install the complete installation set if you only want to rebuild some parts.

= Special Debug Builds with --enable-dbgutil =

OpenOffice.org can be built in a [[Non Product Build|"non-pro" version]] where special debug assertions are enabled. This is supported for Windows/Cygwin starting with the m218 milestone of the SRC680 codeline and all released code lines starting with OOo 2.3.

To enable this kind of build you must add the "--enable-dbgutil" switch to your "configure" command line. If you are building with a MSVC 2005 compiler and you didn't disable the mozilla parts you will also need the debug DLLs for the MSVC2003 compiler runtime, msvcr71d.dll and msvcp71d.dll. You can download them from the internet and copy them into the external/msvcp71 folder.

In milestones older than SRC680m223 you also have to change the d.lst file in the external/prj folder. Add the following lines:

..\msvcp71\msvcp71d.dll %_DEST%\bin%_EXT%\msvcp71d.dll

..\msvcp71\msvcr71d.dll %_DEST%\bin%_EXT%\msvcr71d.dll

You can build the non-pro version in the same source tree as the pro-version, all created files go into wntmsci10 or wntmsci11 folders, without the "pro" extension as in case of the "normal" builds.

When you work with the non-pro version you will see some error messages or warnings at times. In most cases you can safely assume that you have found a bug. The non-pro version is a bit slower than the pro version.

[[Category:Development]]
[[Category:Build_System]]

Documentation/Building Guide/Building on Windows

2009-01-27T13:02:30Z

Divec: Add info about cygwin errors

= Building OpenOffice.org on Windows =
This document tries to fill a gap. The existing documentation about building OOo on Windows mainly reads like “Building OOo on Windows explained for Linux developers”. I will collect and summarize this existing documentation, fix some of its errors and try to add some comments that address people that are already developing on Windows and now want to get to know about building OOo. So this document is also for those who are not used to unix like command line interfaces, tar balls etc. Of course you must be familiar with a command line, but you don't need to be a shell wizard. But on the other hand it wouldn't hurt if you are. :-)

I collected information from several places, e.g.:

[http://tools.openoffice.org/dev_docs/build_windows_tcsh.html#BuildRequirements http://tools.openoffice.org/dev_docs/build_windows_tcsh.html#BuildRequirements]

[[Windows|Building on Windows]]

[[CPAN_install | Perl modules installation with CPAN]]

[http://website.openoffice.org/support/en/howtos/1.html#1 http://website.openoffice.org/support/en/howtos/1.html#1]

The first problem with them is that there are many of them (there are even more than the mentioned four!). So you have to collect things by yourself and have to sort out non-Windows parts. Additionally some of the places contain outdated, incomplete or even wrong information. So I hope that my commented summary might come in handy for starters.

If this documentation is not enough for you or if you have a problem that is not addressed you can send a mail to the mailing list [mailto:dev@openoffice.org dev@openoffice.org] ([mailto:dev-subscribe@openoffice.org subscription] is recommended) or you can meet OOo developers on IRC in the channel #dev.openoffice.org at freenode.de. If you just want to give some feedback about the documentation please also use the mailing list.

You might want to know how many time and disk space installing the build environment will cost you. For a rough estimation I give some download, install and build times. They have been measured on an Athlon 64 X2 3800 (2GHz) dual core machine with 1GByte RAM and a 300 GB SATA disk. My internet connection is a 8MBit DSL broadband connection.

I created this document for building OOo using Microsoft Visual Studio 2005 Express, the “free” (as in beer) offering from Microsoft. It also works with Microsoft Visual Studio 2003, the small differences are mentioned in the text. Using Microsoft Visual Studio 2005 (without the “Express”) should work also but until now I have only one known case as a proof for this. But meanwhile things have become even more complicated because on the way to OpenOffice.org 3.0 the compiler was changed again and now the recommended compiler is Visual Studio 2008 (Express). Please see [[http://wiki.services.openoffice.org/wiki/Building_OOo_with_Cygwin_on_Windows#Download_and_install_MS_compiler_and_tools]] for more details.

Building works fine on Windows XP. It should work also on Windows 2000. I have no information about it but I assume that using Windows 98/ME is not a good idea (Visual Studio Express 2005 cannot be installed on Windows 98, so you'd probably need the full version of Visual Studio 2003 - but Windows 98 is unsupported for OpenOffice.org 3.0 anyway [[User:Cloph|Cloph]]). I don't know anything about building on Vista.

The first thing you need is the build environment. We are using Cygwin, a Windows program that emulates a complete Unix command line environment.

= Download and install Cygwin =
Go to [http://www.cygwin.com/ http://www.cygwin.com] und download the current version. If you already have Cygwin installed: you will need at least version 1.5.10. If you are using version 1.5.18 you must download a special version of the cygwin1.dll as described [http://tools.openoffice.org/dev_docs/build_windows_tcsh.html#BuildRequirements here]. But in general I would recommend to use a recent version.

Cygwin has a web based installation process that is described [http://website.openoffice.org/support/en/howtos/1.html#1 here]. I used the “Install from Internet” method and it worked like a charm. Make sure that you tell the setup to use the “Unix/binary” file type. Cygwin consists of some basic and a lot of optional packages. As building OOo needs some of these optional packages you have to select them in the installer. Unfortunately the list of packages mentioned at the [http://website.openoffice.org/support/en/howtos/1.html#1 place describing the installation process] is incomplete, some more are listed [http://tools.openoffice.org/dev_docs/build_windows_tcsh.html#BuildRequirements here]. Here's a complete list of the needed packages:

* Category Archive: unzip, zip
* Category Devel : autoconf, bison, cvs, flex, gcc-g++, gperf, make, openssl-devel (only needed for perl modules for CWS tooling, see below)
* Category Libs: openssl
* Category Net: openssh, ncftp
* Category Perl: perl (Perl)
* Category Shells: rxvt, tcsh
* Category Utils: patch, gnupg
* Category Web: lynx, wget

The installer will automatically check and download some more packages needed by thosed listed here. The total amount of disk space is 46 MB for the download and 174 MB for the Cygwin installation, including all the additional Perl modules shown below. The whole process took roughly 20 minutes.

Within the Cygwin Toolkit, some executables might be symlinks, in the version I have downloaded (1.5.24-2) it was awk.exe and gunzip.exe, older documentation also mentioned tar.exe. This can lead to a break of the build later, and the symlinks should be replaced by copies of the command they link to.

You can check this in the cygwin shell by calling e.g.

:
::
:::
:::: ''ls -l /bin/awk.exe''

whether e.g. awk.exe is a symlink. In version 1.5.24-2 awk.exe is a link to gawk.exe. The shell will show this by putting out “awk.exe -> gawk.exe”. In this case gawk.exe must be copied to awk.exe by executing:

:
::
:::
:::: ''cd /bin''
:::: ''rm awk.exe''
:::: ''cp gawk.exe awk.exe''

Take similar action for gunzip.exe that I found to be a link to unzip.exe.

In case you overlook something here or you have a newer Cygwin version with additional symlinks not mentioned here it's not a problem. You will get a helpful error message about an existing link in the configuration step (configure) later. The message will tell you which link you have to remove and you can do it following the advice given above for the awk.exe/gawk.exe pair.

Cygwin uses the command line shell “bash” by default and I always use this shell for everything I do with Cygwin. Building OOo is also possible using the shell “tcsh”, though some problems have been reported (see below). My recommendation is to use bash.

Though bash is the recommended shell you shouldn't try to deinstall tcsh. Cygwin doesn't have a simple mechanism to deinstall something automatically and it's still possible that one of the tools used for the build is using the tcsh internally because the script calling it doesn't evaluate the environment variable pointing to the shell to use. So it's safer to keep tcsh installed even if you use bash.

All commands written in this document are meant to be used in a bash (except explicitly told differently). In case you are not used to Unix command line shells you will need to familiarize yourself with some basic commands, but explaining that in closer detail is beyound the scope of this documentation. If you use the shell only for building the source all shell commands you will need are “cd” for the navigation between directories and “rm” in case you want to remove something. Use the “man” command to get more information (e.g. by calling “man cd”) or the “--help” option of the commands to get a short information about the basic options.

= Download and install MS compiler and tools =
Currently building on Windows needs a Microsoft Visual Studio C++ compiler. The “regular” builds for OpenOffice 2.x are done with Visual Studio 2003 that is available from Microsoft at a price. Building using the free (as in “free beer”) compiler Visual Studio 2005 Express works fine and is explained here. For OpenOffice 3.x the recommended as well as the "official" compiler is Visual Studio 2008 or 2008 Express.

== Visual Studio 2005 Express (for OOo 2.x) ==

In case you still can find a copy of the 2005 Express compiler setup and it still works it downloads additional content from the Web. You only need to select the Graphical IDE. More can be downloaded later if you want, but for building and debugging OOo you will not need more than the basic package. The download and installation took me roughly 10 minutes and 220 MB on my hard disk. The complete (not Web based) compiler installation set still can be downloaded as an ISO-images (~450 MB) from the [http://msdn2.microsoft.com/en-us/express/aa718401.aspx Manual Installation] site.

Next step when you plan to use the “Express” version is installing the [http://www.microsoft.com/downloads/details.aspx?familyid=7A1C9DA0-0510-44A2-B042-7EF370530C64&displaylang=en Microsoft Macro Assembler] (MASM). MASM is part of the paid version of Visual Studio (so you can skip that part if you are using it) but for the “Express” version you have to download it separately. It's only a very small download. I had a problem with the MASM installer on all machines where I used it: the setup started but then suddenly disappeared from the screen. I found a hanging msiexec.exe in the task manager and had to kill it manually. Fortunately the MASM was obviously installed correctly. It appeared in the “Add and remove software” dialog and the “ml.exe” was installed to “Vc/Bin” folder of VC8.

You also must download and install the Microsoft Windows Platform SDK. The usual instructions recommend to download it from [http://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5&displaylang=en here] but I followed the recommendations from the [http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/ Visual C++ site]. There you can find a link (download requires Genuine Windows Validation). '''WARNING''': don't install the new Vista platform SDK that is needed for the 2008 Express compiler (see below), the 2005 Express Compiler is does not work with it.

The setup is again web based. You can either user the “Typical” installation or select “Custom” setup and deselect the packages you don't need. You need at least the following packages:

* Microsoft Windows Core SDK
* Microsoft Web Workshop (IE) SDK
* Microsoft Internet Information Server (IIS) SDK
* Microsoft Data Access Services (MDAC) SDK
* Microsoft DirectShow SDK
* Microsoft Windows Installer SDK

You can deselect all 64Bit parts of these packages, all samples, all source code modules and (if you want) every documentation. In total the installation filled 438 MB of my harddisk space (including the documentation, but without all other optional parts).

Warning: the first installation option is called “Register Environment Variables” and it is deselected by default. You shouldn't change this as selecting it will add directories with blanks to your PATH variable. This (or more precisely the quotes surrounding them) will cause troubles in Cygwin (see below). It is also possible that other installed Windows programs (not only Cygwin) can't cope with the changed PATH variable as the installer of the Platform SDK explicitly warns.

The only drawback of not selecting this option is that if you wanted to use the platform SDK for other projects except OOo you would have to take care for the correct environment yourself. The platform SDK creates some start menu entries for shells with a suitable configured environment so that shouldn't be a problem.

There is a library called “libcp.lib” in the “Lib” directory of the SDK; it must be either moved away or renamed. You can read more about this [http://www.openoffice.org/issues/show_bug.cgi?id=49856 here].

There is another thing you have to change in the Platform SDK: you have to apply a small patch to one of the Platform SDK header files as described [http://tools.openoffice.org/servlets/ReadMsg?listName=dev&msgNo=6024 here].

== Visual Studio 2008 Express (OOo 3.x development) ==

You can download the 2008 Express compiler Web based setup or a DVD ISO from [http://www.microsoft.com/express/download Microsoft]. You don't need to install any optional parts.

You also must download and install the Microsoft Windows Platform SDK, but now in the [http://www.microsoft.com/downloads/details.aspx?FamilyId=F26B1AA4-741A-433A-9BE5-FA919850BDBF&displaylang=en newer version 6.0.6001.18000.367-KRMSDK_EN] that also supports Vista. This is a DVD image. You can either mount it with a suitable tool, burn it do a DVD or use tools like winrar that can extract files from ISO files directly. You don't need to install any samples or documentation (especially not installing the latter saves a lot of disk space - 193 MB instead of nearly 1GB).

The Platform SDK setup will also install the .NET Framework 3.5 SDK.

It might be best to install the Windows SDK into the default directory, and if not that into one without capital letters in the path. I used D:\Dev\Win_SDK\ and received some linking errors in the Python module (see [http://www.openoffice.org/issues/show_bug.cgi?id=88568+ Issue 88568]).

== DirectX SDK ==

Another SDK that could be downloaded and installed is the Direct X9 SDK. If you don't want to download it you can disable DirectX support in the configuration step (“--disable-directx”). The current regular builds of OOo are done with a version of the DirectX SDK that is no longer available for download so it's necessary to search for a download link in the Web. The OOo pages mention several links, outdated as well as working links. I took the one from [http://www.microsoft.com/downloads/details.aspx?FamilyId=D625324C-59B4-4951-849E-640B508DC442&displaylang=en here] (Genuine Windows Validation required). This is a 509 MB download as the setup is not Web based. Downloading, unpacking and installing took 30 minutes. As I deselected the sources and sample the resulting installation only was 189 MB.

Current (as of 2008/01) versions of the DirectX9 SDK and Windows Platform SDK do not fit to each other. To be able to build with DirextX enabled, you need to patch one file in the Platform SDK. See [http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2743771&SiteID=1 MSDN forum] for details].
'''WARNING''': do not use a DirectX10 SDK.

= Download of additional files =
You have to download some more files that you have to put into some prepared locations of the OOo source tree later. I mention it here because most of them are related to the MS compiler but perhaps it makes more sense first to download the source so that you can immediately copy the addtitional files to the proper location. Here's the list of files to download (with links) and the locations in the source tree where you must put them:

{| class="prettytable" border="1" width="100%"
| [http://www.microsoft.com/downloads/details.aspx?familyid=6A63AB9C-DF12-4D41-933C-BE590FEAA05A&displaylang=en GDI+ Redistributable] (Genuine Windows Validation required)
| external/gdiplus

|-
| Only for OOo2.x but due to a [http://www.openoffice.org/issues/show_bug.cgi?id=88652 bug] in configure still needed for 3.x: [http://download.microsoft.com/download/b/7/5/b75eace3-00e2-4aa0-9a6f-0b6882c71642/unicows.exe unicows.dll]
| external/unicows

|-
| [http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=CD1FC4B2-0885-47F4-AF45-7FD5E14DB6C0 dbghelp.dll]
| external/dbghelp

|-
| [http://download.microsoft.com/download/WindowsInstaller/Install/2.0/NT45/EN-US/InstMsiW.exe instmsiw.exe] and [http://download.microsoft.com/download/WindowsInstaller/Install/2.0/W9XMe/EN-US/InstMsiA.exe instmsia.exe]
| external/msi

|-
| for 2005 compiler: msvcp80.dll and msvcr80.dll (found in c:\WINDOWS/WinSxS/x86_Microsoft.VC80.CRT_1fc8b3b9a1e18e3b_8.0.50727.42_x-ww_0de06acd/msvc
| external/msvcp80

|-
| for 2008 compiler (until DEV300 m22): msvcp90.dll and msvcr90.dll (found in $(msvcdir)\Vc\redist\x86\Microsoft.VC90.CRT)
| external/msvcp90

|-
| for 2008 compiler starting with DEV300m23: Microsoft_VC90_CRT_x86.msm and policy_9_0_Microsoft_VC90_CRT_x86.msm for non debug builds and Microsoft_VC90_DebugCRT_x86.msm and policy_9_0_Microsoft_VC90_DebugCRT_x86.msm for debug builds. These merge modules are available in VS08 Express Edition and VS08 Professional Edtion. All *.msm files are located at c:\Program Files\Common Files\Merge Module.
| external/msm90

|-
| [http://www.cs.man.ac.uk/aig/staff/alan/software/ GPC]
| Unpack to external/gpc

|-
| [http://tools.openoffice.org/moz_prebuild/680/ Mozilla binary distribution]

(WNTMSCIruntime.zip,WNTMSCIlib.zip,WNTMSCIinc.zip)
| moz/zipped

|-
| msvcr71.dll and msvcp71.dll for Mozilla libraries (Search for them in the Web or on your PC. These files should be named as all lower case. Sometimes when downloaded they are upper case and this will cause 'file not found' errors towards the end of the build))
| external/msvcp71

|}

Some of the files can be found in a suitable OOo installation set also, so you can save the download by “stealing” it from your OOo installation.

OOo uses some Mozilla libraries. Building the corresponding sources is only possible with the VC2003 compiler so you have to use precompiled libraries that require the msvx71 libraries mentioned above. On Windows the Mozilla libraries are needed only for Mozilla address book support. Unfortunaly a bug in the module dependencies makes it necessary that the mozilla libaries are used anyway as otherwise building the module xmlsecurity fails (see [[Building_OOo_with_Cygwin_on_Windows#Setting_up_the_build_environment|below]]).

= Downloading and installing additional Perl modules =
As explained [[CPAN_install | elsewhere in the wiki]] some perl modules must be installed with CPAN. The necessary command in the cygwin shell is

:
::
:::
:::: ''perl -MCPAN -e shell''

If this command is executed the first time CPAN will ask for configuration. The autoconfiguration worked fine for me. I used the prompted installation just to see what is asked but always pressed “Enter” in each step, even in case I got an error message that asked me for confirmation. You can do the same and just ignore any error messages you might see (the same is true for all queries while you are executing the “install” command mentioned below).

Please note that CPAN is not able to deal with usernames containing spaces. To work around this fact, when CPAN asks you to specify the ''CPAN build and cache directory'', change the default suggestion to <tt>/cpan</tt>.

At the end the CPAN shell appeared and is ready to accept commands for installations. Each module is installed by typing “install $MODULENAME”. The modules that must be installed are:

* Archive::Zip
* XML::Parser (though it seems that this is already installed; doesn't hurt to do it)
* URI
* LWP::UserAgent
* SOAP::Lite
* Crypt::SSLeay

The last three modules are only needed if you want to use the [http://tools.openoffice.org/dev_docs/ooo-cws-tools-doc.sxw CWS tooling]. These tools are necessary if you want to create and maintain your own [http://wiki.services.openoffice.org/wiki/CWS Child Workspaces] or if you want to build one of them. I recommend to install them anyway as sooner or later you want to work on a child workspace.

CPAN will detect if a selected module depends on other modules and it will offer to download them also. As explained please just confirm this.

=== CPAN errors ===

* I got an error message from CPAN somewhat like the following:

: C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\bin\cygiconv-2.dll to same
: address as parent(0x7C0000) != 0x7D0000

To fix this, I had to exit the Cygwin shell, run cmd.exe, then type "c:\cygwin\bin\ash.exe" to start the minimal shell, then type "/bin/rebaseall". Then CPAN worked when I ran it again.

* I got another error when cygwin was performing "make install":

: ERROR: Can't create '/usr/bin'; Do not have write permissions on '/usr/bin'

I can actually write to /usr/bin; however when I do "ls -ld /usr/bin", cygwin reports no write permission; and "chmod u+w /usr/bin" gives "Permission denied". This causes the install process to fail when it checks permissions. As a kludge, I installed vim, and edited line 368 of /usr/lib/perl5/5.10/ExtUtils/Install.pm, replacing this:

: return -w $dir;

with this:

: return 1;

which allowed installation to proceed.

= Downloading and installing Java and other tools =
Some OOo components as well as some build tools of OOo require Java. So you must download a JDK and the Java make utility [http://ant.apache.org/ Ant]. It's not necessary to read the whole installation instructions from Ant. After downloading the zip package just unpack the bin and lib folders from it into a directory that you specfiy as ant-home in the configure step later. The path to this directory must not contain blank characters!

All OOo builds can be done with [http://java.sun.com/j2se/1.4.2 JDK 1.4.2]. If your build is based at least on milestone m158 you can also use [http://java.sun.com/j2se/1.5.0 JDK 1.5.0.] Don't use Java 1.6, at least the hsqldb modules does not build with that version. This is status quo with milestone m218.

If a self contained Windows installer is desired in addition to the MSI installer files [http://nsis.sourceforge.net/ NSIS] 2.0.4 is needed, but it is optional. If NSIS is not present the build will ignore this step. Used to be that newer version of NSIS used to break the build ([http://qa.openoffice.org/issues/show_bug.cgi?id=85657 #85657]), but it seems that in now works for up to 2.3.7.

= Getting the source code =
You will place your code somewhere in your file system. In the following text this root directory will be called SRC_ROOT.

Source code is available via CVS or as a source tarball. Downloading and unpacking the latter needs less bandwidth but tarballs are not available for every milestone build, only for the latest release and the latest developer build, both available from our [http://download.openoffice.org download site]. If you want to work on a particular milestone or CWS you have to get the source directly from the cvs.

We have some documentation about working with cvs on OOo. Here's a short description how you can download the whole OOo2 source. You have to use the following commands to get e.g. the milestone m10 on the code line dev300 (with the cvs branch tag DEV300_m10):

:
::
:::
:::: ''export 'CVSROOT=:pserver:anoncvs@anoncvs.services.openoffice.org:/cvs'''
:::: ''cvs login ( use the CVS password: anoncvs when you are asked for it)''
:::: ''cd SRC_ROOT''
:::: ''cvs co -r DEV300_m10 OpenOffice2''

The alias “OpenOffice2” will check out all modules that are needed for OOo2.x or OOo3.x (a new alias for OOo3.x will be created in the near future); it is also possible to check out single modules. Checking out OpenOffice2 took me roughly an hour. If you already have a [http://www.openoffice.org/scdocs/ddSSHGuide.html cvs tunnel] working you can of course use this one instead of the anoncvs access I used in my example but anoncvs is much faster as it does not have the SSL overhead and latency.

If you got the tarball, e.g. the one for version 2.4.0, you can unpack it with

:
::
:::
:::: ''tar -xvzf Ooo_2.4.0_src.tar.gz''

The great [[User:Kr/Concurrent_Checkout | script from Kay Ramme]] that checks out any project or modules and – using the build lists of the modules and the dependencies created from them – all other modules that are needed for a successful build currently doesn't work for OOo3.x (fix is in the works). It uses several parallel cvs connections (anoncvs allows to use 3) and so should be a bit faster. I used the script several times and it took roughly 40 minutes. But if you wanted to go the safe way or you want to work on the 3.x code line you should use the checkout via the “OpenOffice2” target.

Once you have the source tree you can copy all the extenal files listed in the table above into the appropriate locations.

Whatever milestone (version) of OOo you want to use, never try to build the HEAD revision! As new files are committed to HEAD quite often when workspaces are integrated into the main code lines it is very likely that you start to check it out while committing of files is still in progress. The result will be an incomplete and inconsistent version that most probably won't build. The OOo versioning works in a way that release engineers commit files to HEAD and give these files a version tag for the next milestone, e.g. “DEV300_m10”. Once this version is built and tested sucessfully it is announced to be usable for developers and the race is on for the next round.

If you want to know which milestones are current please look into our “Environment Information System” ([[EIS|EIS]]). There is an RSS feed available that informs you about new available milestones. You can also [mailto:cws-announce-subscribe@openoffice.org subscribe] to the [mailto:cws-announce@openoffice.org cws-announce@openoffice.org] mailing list (or look into its [http://www.openoffice.org/servlets/SummarizeList?listName=cws-announce archive]).

EIS also provides a lot of other useful information and entry points to more documentation.

= Setting up the build environment =
Finally the “configure” tool is used to create the environment. It checks that all software, hardware, and system requirements for the build are satisfied, and creates configuration files called winenv.set (for tcsh) and winenv.set.sh (for bash) that are used to set all necessary build environment variables. If configure detects a problem it will stop and give you a useful (really!) hint how to fix it. You have to call “configure” from the SRC_ROOT/config_office directory.

The resulting configuration files are created in the SRC_ROOT directory. A top-level makefile script makefile.mk and the script bootstrap that are located in the config_office directory are moved into SRC_ROOT folder as well. This is due to technical reasons: The SRC_ROOT directory in the cvs tree can only hold directories. On the other hand, the top-level makefile.mk should logically be placed in the top-level directory SRC_ROOT. The cvs tree holds these files in config_office and configure copies them up.

Before running configure, make sure that all needed programs are in the system path or start configure with the appropriate command line switches. Make also sure that the PATH variable in your cygwin shell does not contain any blanks and quotes.

There are a number of options that you can use with the configure script. To display these options, type the following command:

:
::
:::
:::: ''./configure –help''

Here's my configure call (the folders of the different programs of course might be different in your case):

: ./configure \
:: --disable-directx \
:: --with-cl-home="/cygdrive/d/develop/msvc/VC" \
:: --disable-activex \
:: --disable-atl \
:: --disable-build-mozilla \
:: --with-frame-home="/cygdrive/d/develop/MSDK/v6.1" \
:: --with-psdk-home="/cygdrive/d/develop/MSDK/v6.1" \
:: --with-midl-path="/cygdrive/d/develop/MSDK/v6.1/Bin" \
:: --with-asm-home="/cygdrive/d/develop/msvc/VC" \
:: --with-jdk-home="/cygdrive/d/develop/j2sdk1.4.2_11" \
:: --with-csc-path="/cygdrive/c/Windows/Microsoft.NET/Framework/v3.5" \
:: --with-ant-home=/ant \
:: --with-use-shell=bash

(the pathes containing "msvc" and "msdk" should be self-explanatory.)

Sometimes configure had problems with paths containing spaces (no pattern detected) so I preferred to install into pathes without them. The "with-psdk-home" setting needs a case-sensitive path name. I recommend to use case-sensitive usage in all cases - it's good to get used to case sensitivity if you are going to work with Cygwin.

Most parameters are self-explanatory, but some options might need an explanation.

The Visual Studio Express compilers do not contain everything needed to build the OOo ActiveX control so I disabled it here. If you are using a “complete” Visual Studio (no “Express” version) you can omit this if you want. But the ActiveX control is not needed to run OOo, it's just an additional feature that lets OOo embed files into the Internet Explorer. On the 3.0.x code line and the 2008 Express compiler another step is necessary after configuring: the environment variable "DISABLE_ATL=TRUE" must be set in the shell and also (in case configure fails to detect the Windows platform SDK version correctly) WINDOWS_VISTA_PSDK also must be set to TRUE. [Remark: the detection failure results from the way how configure searches for the Vista PSDK: it will be found only if it is installed into the default location.] I manually added both variables to the winenv.set.sh file that was created by the "configure" call file. For all code lines since 3.1.x this has been fixed and both environment variables will be set properly.

As DirectX is not needed for most developers, its SDK consumes a lot of disk space and is prone to incompatibilities I recommend to build without DirecX support by using --disable-directx as shown above. Otherwise you have to provide the path to the SDK in --with-directx-home.

OOo uses some Mozilla components. As mentioned above it is not possible to build them from the sources using the Visual Studio 2005 compiler. So I disabled the build with an appropriate option. Disabling the Mozilla components with "--disable-mozilla" completely currently does not work due to a bug in the module dependencies.

Cygwin starts with a “bash” shell by default as already mentioned. My document explains how to build with this shell. Using a tcsh is possible though it may sometimes lead to problems (memory allocation errors, hanging builds) so I don't recommend to use it. Unfortunately using “tcsh” is still the default setting created by configure (as the first builds where done using it) and so I told configure that the bash should be used instead. If you want to try using tcsh remove the “--with-use-shell” parameter shown above and build with tcsh as explained below. In case the build breaks at some place you can manually patch your winenv.set.sh file and exchange the line

:
::
:::
:::: ''SHELL=”/usr/bin/tcsh”''

with

:
::
:::
:::: ''SHELL=”/usr/bin/bash” ''

and the line

:
::
:::
:::: ''“USE_SHELL=”tcsh”''

with

:
::
:::
:::: ''“USE_SHELL=”bash”''

Then close the tcsh and build again with bash as explained below.

After running configure you must create the dmake make utility that is needed for the build of OpenOffice.org. This done from the SRC_ROOT directory by calling

:
::
:::
:::: ''./bootstrap''

If you experiment with the newest sources from the cvs-tree, mind that updates to the configure process may not happen via updates of configure (the script file) but via the files configure.in and set_soenv.in. The configure script itself is created from configure.in using the autoreconf command. The perl script set_soenv is created when you run configure from set_soenv.in.

If you need to modify or create a correct configure you would run commands like the following:

:
::
:::
:::: ''SRC_ROOT> cd config_office''
:::: ''config_office> cvs update configure.in''
:::: ''config_office> autoconf''

to update the configure script. If you only use code from the snapshot releases on the web, you don't need to be concerned about this. If you are working on a Child Workspace you should rerun the configure script after each resync.

= Build Instructions =
Now you are ready to build OpenOffice.org. In every Cygwin instance used for building you have to set the environment variables from the generated configuration file(s).

If you are using bash got to your SRC_ROOT folder and call

:
::
:::
:::: .'' winenv.set.sh''

or if you are using tcsh call

:
::
:::
:::: ''source winenv.set''

Now you have two options to build the whole Office. You can either call “dmake” in SRC_ROOT or you can go to the “instsetoo_native” directory and use “build” that allows you to control the build process a bit better:

:
::
:::
:::: ''SRC_ROOT> cd instsetoo_native''
:::: ''SRC_ROOT> build --all -P4''

The “-P4” tells the build tools to start 4 parallel running processes. Using more than one process will speed up the build as it avoids that CPU time is wasted waiting for disk i/o. As a rule of thumb twice as much processes as you have CPU cores is a good number, so “-P4” is fine for my dual core Athlon 64 X2. On this machine (described at the top of this document) the complete build took roughly 2,5-3 hours. The whole tree takes 8,1GB after a successful build.

Some build times for comparison (as reported by users):

* Athlon XP 64 2 GHz, 1 GB RAM - 3 hours
* Athlon 1,15 GHz, 1 GB RAM - 18,5 hours
* Core2 Duo 2 GHz, 1GB RAM - 3 hours
* Core2 Quad 2,4 GHz, 4GB RAM - 1,5 hours

There are some special things in the way how OOo builds its modules. Every module has an “output” folder (with some subfolders for the different kinds of generated output) that is created the first time a build is done in the module. The name of this folder is “wntmsci10.pro” for builds with MSVC++2003 and “wntmsci11.pro” for builds with MSVC++2005. After a successful build of a module some of the generated files are copied to the output folder of the “solver” module by executing a tool called “deliver” (this is automatically called by build --all for each of the modules). Other modules will take these “delivered” files (header files, libraries etc.) to resolve their dependencies. The content of the solver module will also be used to pack the installation sets in the final step.

Sometimes a build breaks. You will get an error message that tells you which modules have to be rebuilt. It seems that at least on Windows in rare cases the build (especially a multi processor build) breaks without an obvious reason and redoing the build is enough to “fix” the problem. I didn't experience that in the last months but don't be surprised if it happens to you. Of course a build can break for “real” reasons also if you changed something in the source code. “build” will always tell you the modules it couldn't build successfully and you can then go to any folder inside the module(s) and fix the problems.

The build system recommends to use the “--from” parameter of the build command to continue the build where it broke after you have fixed the problem. Rumours are that this is not reliable everytime. So if you can bear the extra minutes that “build” needs to detect already built modules you should restart your build with “build --all” from inside instsetoo_native as you did the first time just to avoid uncertainties. For more options of “build” call

:
::
:::
:::: ''SRC_ROOT> build – help''

After a successful build you will find the OOo installation set in

:
::
:::
:::: ''instsetoo_native/wntmsci11.pro/OpenOffice/msi/Install/en-US''

“instsetoo_native” is the module that packs the installation set.

If you already have a version of OOo installed you can install your freshly built version in parallel by installing it with setup /a that just unpacks all files without any system registration.

If you decide to rebuild a module or build each module individually (mind dependencies!), you also will have to use the “build” tool from inside a folder of these modules. A “build” of a single module will not call “deliver” automatically as described above for the “build --all” case. You must call is manually to get the usual files copied to the solver tree so that other modules or the packaging module can use them.

:
::
:::
:::: ''SRC_ROOT/(module)> build''
:::: ''SRC_ROOT/(module)> deliver''

You can copy all new files manually to the appropriate places in your installation. There's no need to rebuild and install the complete installation set if you only want to rebuild some parts.

= Special Debug Builds with --enable-dbgutil =

OpenOffice.org can be built in a [[Non Product Build|"non-pro" version]] where special debug assertions are enabled. This is supported for Windows/Cygwin starting with the m218 milestone of the SRC680 codeline and all released code lines starting with OOo 2.3.

To enable this kind of build you must add the "--enable-dbgutil" switch to your "configure" command line. If you are building with a MSVC 2005 compiler and you didn't disable the mozilla parts you will also need the debug DLLs for the MSVC2003 compiler runtime, msvcr71d.dll and msvcp71d.dll. You can download them from the internet and copy them into the external/msvcp71 folder.

In milestones older than SRC680m223 you also have to change the d.lst file in the external/prj folder. Add the following lines:

..\msvcp71\msvcp71d.dll %_DEST%\bin%_EXT%\msvcp71d.dll

..\msvcp71\msvcr71d.dll %_DEST%\bin%_EXT%\msvcr71d.dll

You can build the non-pro version in the same source tree as the pro-version, all created files go into wntmsci10 or wntmsci11 folders, without the "pro" extension as in case of the "normal" builds.

When you work with the non-pro version you will see some error messages or warnings at times. In most cases you can safely assume that you have found a bug. The non-pro version is a bit slower than the pro version.

[[Category:Development]]
[[Category:Build_System]]

Windows

2005-12-15T14:50:00Z

Divec: Added link to Windows Installer Hacking

== Welcome to OOo development for Windows ==

This is an initial attempt to fill out information for building on Windows.
If it ends up being complete, this notice can be removed! At the moment you'll have to piece together information from [[#See also|other pages]] with the changes here for doing it on Windows.

Most of this wiki assumes that you'll be using a reasonably current Linux system, as a time saving feature. While real hackers prefer [http://www.gnu.org Free software], if you're forced to build stuff for Windows, this is the place to be.

== Development Tools ==

There have been several different ways of building with more or less success...

The reference page to look at is [http://tools.openoffice.org/dev_docs/build_windows_tcsh.html Building under Windows with tcsh]

Other ways to build are documented below, the official way requires Visual C++ .NET 2003

=== Visual C++ .NET 2003 ===

This is the full version of Visual C++. It is the official way to build OpenOffice.org.
It seems like the Standard version of this (approx $109 price) should be sufficient but I have not confirmed this. (The alternative is the full Visual Studio).

=== Visual C++ Toolkit 2003 ===

[http://msdn.microsoft.com/visualc/vctoolkit2003/ Visual C++ Toolkit 2003] is not currently usable because it doesn't contain all the libraries required for building OpenOffice.org. See [http://www.openoffice.org/issues/show_bug.cgi?id=51145 Issue 51145] for progress on this issue.

TODO: fill in all the required libraries, and possible alternatives - in the issue.

=== MinGW ===

[http://www.mingw.org/ MinGW] is basically gcc for Windows, without requiring the POSIX compatibility layer that CygWin provides. You can use the CygWin compiler with the -mno-cygwin switch and it has the same effect.

MinGW is not officially supported at the moment, so it will probably take some work to get it

Work to build OpenOffice.org with MinGW is at [http://qa.openoffice.org/issues/show_bug.cgi?id=24588 issue 24588] ; however this mostly deals with OpenOffice.org 1.1 branch at the moment.

== Using vanilla source ==

While ooo-build has been developed to make building OOo less painful, you might also try to start out with the standard source code. After you download and unpack a vanilla ooo source tarball, running "configure" in the directory "config_office" will gladly complain about missing build-dependencies. The remaining build process is described in the document [http://tools.openoffice.org/dev_docs/build_windows_tcsh.html Building under Windows with tcsh]

== Using ooo-build ==

These are addenda to using ooo-build with the following command line:
./configure --with-win32

ooo-build should pick up all the other requirements for you automatically (reading them out of the registry)

=== Extra requirements ===

* Cygwin requires the cabextract package.

== Miscellaneous info ==

* csc.exe comes from the c:\WINDOWS\Microsoft.NET\Framework\v1.1.4322 directory, you might need <tt>--with-csc-path</tt>.
* Beware of using <tt>/c/</tt> instead of <tt>/cygdrive/c/</tt>.
* Avoid trailing slashes in configure parameters. They sure cause problems for <tt>--with-psdk-home</tt>.
* Using the latest cygwin release (1.5.18) can lead to tcsh freezing in places - the build will appear to hang. you can fix this by using the latest snapshot (e.g. 20050825) or running ''cat /proc/$nnn/cmdline'' where $nnn is the number of the process. See [http://www.openoffice.org/issues/show_bug.cgi?id=51560 issue 51560] for more info...
* With cygwin 1.5.18, makecab.exe hangs when run from the build process (but it works fine when run standalone). So you definitely want to use a snapshot and '''avoid cygwin 1.5.18''', unless you enjoy wasting half a week of your life debugging like I did ...

== See also ==

* To get started from scratch you most likely need to follow these steps (from the Linux version): [[Getting It]], [[Building]], [[Installing]], [[Running]]
* [[Windows Debugging]]
* [[Windows Tips]]
* [[Windows Installer Hacking]]

Windows Installer Hacking

2005-12-15T14:49:08Z

Divec: Add example perl script to create DDF file

This page explains how to modify a Windows installer EXE (the big, >70 MB one which contains everything).

== Why? ==

Normally this is a bad idea, and it is better to build OOo from scratch
yourself. However, this may not be possible for various reasons, e.g. if:

* You don't have the (non-Free) toolchain available to build OOo.
* You're modifying a non-Free OOo derivative and don't have the source.
* You don't have the time and resources available to build OOo
* etc.

== OOo_2.0_Windows_install_en-US.exe ==

This is an NSIS self-extracting installer. It contains the following
structure:

openofficeorg1.cab
openofficeorg2.cab
openofficeorg3.cab
openofficeorg4.cab
openofficeorg20.msi
instmsia.exe
instmsiw.exe
licenses/
readmes/
setup.exe
setup.ini

In the OOo 2.0 build process it is built from its contents using a command
(at "call_nsis" in solenv/bin/modules/installer/download.pm) which does
something like the following:

/cygdrive/c/Program\ Files/NSIS/makensis.exe c:/ooo2/ooo-build/build/ooo680-m3/instsetoo_native/wntmsci10.pro/OpenOffice/nsis/en-US/downloadtemplate.nsi

The file

downloadtemplate.nsi

contains instructions for building the .exe. Its directory also contains

English_pack.nsh
English_pack.nlf

which both consist of text strings in the installer language and are
referenced from downloadtemplate.nsi. (Various .ico and .bmp files, located
outside the directory, are also referenced).

== CAB files ==

These contain the actual files which get extracted. Although CAB files can
apparently store a directory tree structure, these ones are flat. The
filenames inside the CAB are often, but not always, the same as the names
when installed.

N.B. '''The order in which files are stored is very important!'''

cabextract -l # lists the contents of a cab file.
makecab.exe /F blah.ddf # Create CAB from blah.ddf, a spec+filelist

The "blah.ddf" file can be generated with a perl script like this:

<pre>
#!/usr/bin/perl -w
#
# Files to pack: c:\msi\files
# Output file path is relative to that directory
# Temporary work space: c:\msi\makecabtemp
# Usage: perl make-ddf.pl (list of names of files to pack, in order, without path)
#
print <<EOF;
.Set CabinetName1=../out.cab
.Set ReservePerCabinetSize=128
.Set MaxDiskSize=CDROM
.Set CompressionType=LZX
.Set Compress=ON
.Set CompressionLevel=2
.Set Cabinet=ON
.Set DiskDirectoryTemplate=c:/msi/makecabtemp
EOF
for my $file (@ARGV) {
print qq("c:\\msi\\files\\$file" $file\n);
}
</pre>

Some files in the CABs may not actually get installed: See Component.idt
below.

== MSI file ==

This is a relational database which controls the installation process. It
can be dumped into tab-separated text files (*.idt), one per table, using

MsiDb.Exe -e -d blah.msi -f c:\text_file_dest *

The text files can be dumped back into a new MSI like this:

MsiDb.Exe -i -d blah_new.msi -f c:\text_file_dest *.idt

(N.B. In both cases, be sure to surround the * in quotes if you're using a
UNIX shell)

If you edit these text files, you have to be pretty careful, because there
is all sorts of referrential integrity to preserve between tables. To
modify the install, some tables are particularly important:

=== File.idt ===

This is a list of files which *potentially* can be installed.

* File is the name of the file in the archive.

* Each file is part of a Component.

* FileSize speaks for itself.

* Sequence is the order in which the files appear in the CABs, and the
installer will *fail* if it is not correct. (The Sequence is across all CAB
files, so for instance the first file in CAB 3 has the Sequence number one
higher than the last file in CAB 2).

=== Directory.idt ===

Defines directories per feature component

=== Media.idt ===

Specifies the CABs from which to obtain files. Crucially, this specifies
the file number ranges contained within each CAB, so if you add any files
you will probably have to alter this.

=== Feature.idt ===

Defines Features, i.e. groupings of functionality which can be selected in
the installer.

=== FeatureComponent.idt ===

Each Feature is a set of components.

=== Component.idt ===

Specifies into which directory a component is installed (relative to the
Feature (?)), etc. KeyPath is the First file in the component (in Sequence
order) (?)

== Full paths of executables ==

* C:\Program Files\Microsoft Platform SDK\Bin\MsiDb.Exe
* C:\WINDOWS\system32\makecab.exe (on Windows XP)
* cabextract - UNIX (or cygwin) program

Windows Installer Hacking

2005-12-15T14:34:53Z

Divec: Initial text

This page explains how to modify a Windows installer EXE (the big, >70 MB one which contains everything).

== Why? ==

Normally this is a bad idea, and it is better to build OOo from scratch
yourself. However, this may not be possible for various reasons, e.g. if:

* You don't have the (non-Free) toolchain available to build OOo.
* You're modifying a non-Free OOo derivative and don't have the source.
* You don't have the time and resources available to build OOo
* etc.

== OOo_2.0_Windows_install_en-US.exe ==

This is an NSIS self-extracting installer. It contains the following
structure:

openofficeorg1.cab
openofficeorg2.cab
openofficeorg3.cab
openofficeorg4.cab
openofficeorg20.msi
instmsia.exe
instmsiw.exe
licenses/
readmes/
setup.exe
setup.ini

In the OOo 2.0 build process it is built from its contents using a command
(at "call_nsis" in solenv/bin/modules/installer/download.pm) which does
something like the following:

/cygdrive/c/Program\ Files/NSIS/makensis.exe c:/ooo2/ooo-build/build/ooo680-m3/instsetoo_native/wntmsci10.pro/OpenOffice/nsis/en-US/downloadtemplate.nsi

The file

downloadtemplate.nsi

contains instructions for building the .exe. Its directory also contains

English_pack.nsh
English_pack.nlf

which both consist of text strings in the installer language and are
referenced from downloadtemplate.nsi. (Various .ico and .bmp files, located
outside the directory, are also referenced).

== CAB files ==

These contain the actual files which get extracted. Although CAB files can
apparently store a directory tree structure, these ones are flat. The
filenames inside the CAB are often, but not always, the same as the names
when installed.

N.B. '''The order in which files are stored is very important!'''

cabextract -l # lists the contents of a cab file.
makecab.exe /F blah.ddf # Create CAB from blah.ddf, a spec+filelist

Some files in the CABs may not actually get installed: See Component.idt
below.

== MSI file ==

This is a relational database which controls the installation process. It
can be dumped into tab-separated text files (*.idt), one per table, using

MsiDb.Exe -e -d blah.msi -f c:\text_file_dest *

The text files can be dumped back into a new MSI like this:

MsiDb.Exe -i -d blah_new.msi -f c:\text_file_dest *.idt

(N.B. In both cases, be sure to surround the * in quotes if you're using a
UNIX shell)

If you edit these text files, you have to be pretty careful, because there
is all sorts of referrential integrity to preserve between tables. To
modify the install, some tables are particularly important:

=== File.idt ===

This is a list of files which *potentially* can be installed.

* File is the name of the file in the archive.

* Each file is part of a Component.

* FileSize speaks for itself.

* Sequence is the order in which the files appear in the CABs, and the
installer will *fail* if it is not correct. (The Sequence is across all CAB
files, so for instance the first file in CAB 3 has the Sequence number one
higher than the last file in CAB 2).

=== Directory.idt ===

Defines directories per feature component

=== Media.idt ===

Specifies the CABs from which to obtain files. Crucially, this specifies
the file number ranges contained within each CAB, so if you add any files
you will probably have to alter this.

=== Feature.idt ===

Defines Features, i.e. groupings of functionality which can be selected in
the installer.

=== FeatureComponent.idt ===

Each Feature is a set of components.

=== Component.idt ===

Specifies into which directory a component is installed (relative to the
Feature (?)), etc. KeyPath is the First file in the component (in Sequence
order) (?)

== Full paths of executables ==

* C:\Program Files\Microsoft Platform SDK\Bin\MsiDb.Exe
* C:\WINDOWS\system32\makecab.exe (on Windows XP)
* cabextract - UNIX (or cygwin) program

Windows

2005-12-05T00:30:05Z

Divec: Added link to Windows Tips; moved important links to their own section

Windows Tips

2005-12-05T00:29:06Z

Divec: Closing the quickstarter from a macro

== Closing the Windows quickstarter from a macro ==

There seems to be no obvious way to close quickstart.exe (the OOo icon in the system tray) using UNO. Indeed, "quickstart -killtray" itself does it by searching the running system processes for one with the correct name and path. The following Basic snippet is a work-round that is OK for some purposes:

sub KillQuickstarter()
' Runs "quickstart -killtray"
subst = CreateUnoService("com.sun.star.util.PathSubstitution")
quickstartPath = subst.substituteVariables("$(prog)/quickstart", 1)
shell(quickstartPath, 0, "-killtray")
end sub