Difference between revisions of "Documentation/Building Guide AOO"

From Apache OpenOffice Wiki
Jump to: navigation, search
m (Removed unused markup.)
m (Corrected note)
 
(88 intermediate revisions by 24 users not shown)
Line 2: Line 2:
  
 
= Preface =
 
= Preface =
This guide will help you to build Apache OpenOffice from its source code.  It details the prerequisites and explains how to download the source code, prepare and then run the build.
+
This guide will help you to build Apache OpenOffice from its source code.  It details the prerequisites and explains how to download the source code, prepare and then run the build. [[Documentation/Building_Guide_AOO/Step_by_step|Step-by-step instructions]] for resolving the pre-requisites of individual platforms and building on them are available.
 
+
 
 
Here is the short version for the brave and impatient:
 
Here is the short version for the brave and impatient:
*Download the source:  <code>svn co https://svn.apache.org/repos/asf/incubator/ooo/trunk ooo</code>
+
# Download the source:  <code>svn co https://svn.apache.org/repos/asf/openoffice/trunk aoo</code>
*Configure: <code>cd main/ ; autoconf ; ./configure <some-switches> ; ./bootstrap</code>
+
{{Note|Is the above even needed anymore?}}
*Build: <code>source <platform-dependend-name>.sh ; cd instset_native ; build --all</code>
+
# since 2019-08-03 <code>git clone https://gitbox.apache.org/repos/asf/openoffice.git</code>
*Wait for an hour or more (here you have to be patient)
+
# Configure: <code>cd main/ ; autoconf ; ./configure <some-switches> ; ./bootstrap</code>
*Install office
+
# Build: <code>source <platform-dependend-name>.sh ; cd instsetoo_native ; build --all</code>
*Enjoy
+
# Wait for an hour or more (The build can take up to 3 hours.)
 +
# Enjoy
  
==Status==
+
The detailed description below gives a broader introduction into the build process and explains for the various steps.
This document is loosely based on an older [[Documentation/Building Guide|version]].  I have tried to avoid duplication and to move anything that all platforms have in common to this page.  Many details have been removed on purpose because they refer to older version of OpenOffice. However, there are still some things not explained in the necessary detail on this page:
+
* How to use mozilla and nss.
+
{{Note|This document is loosely based on an older [[Documentation/Building Guide|version]].  I have tried to avoid duplication and to move anything that all platforms have in common to this page.  Many details have been removed on purpose because they refer to older version of OpenOffice.}}
* How to use ccache
+
* How to use cache
 +
 
 +
{{SeeAlso|EN|*[[How_to_build_Symphony%27s_source_code]] }}
  
 
= Getting help =
 
= Getting help =
You can get help by searching this wiki or by asking questions on the [http://incubator.apache.org/openofficeorg/mailing-lists.html#development-mailing-list developers mailing list].
+
You can get help by searching this wiki or by asking questions on the [http://openoffice.apache.org/mailing-lists.html#development-mailing-list-public developers mailing list].
  
You can help us improve this guide by pointing out any errors (preferably after finding a solution.)
+
You can help us improve this guide by pointing out any errors (preferably after finding a solution).
 
Or don't be shy and edit (and improve) these pages yourself.
 
Or don't be shy and edit (and improve) these pages yourself.
  
Line 31: Line 34:
 
* Many tools from the Unix world like make or sed.
 
* Many tools from the Unix world like make or sed.
  
See section [http://wiki.services.openoffice.org/wiki/Documentation/Building_Guide_AOO#General_Build_Requirements General Build Requirements]
+
See section [[#General_Build_Requirements | General Build Requirements]]
 
for an exact list of requirements.
 
for an exact list of requirements.
  
 
= Getting the source =
 
= Getting the source =
  
The source code is available as SVN repository at https://svn.apache.org/repos/asf/incubator/ooo.
+
The source code is available as SVN repository at https://svn.apache.org/repos/asf/openoffice
  
 
Check it out with
 
Check it out with
  
   svn co https://svn.apache.org/repos/asf/incubator/ooo/trunk ooo
+
   svn co https://svn.apache.org/repos/asf/openoffice/trunk aoo
 +
  git clone https://gitbox.apache.org/repos/asf/openoffice.git #since 2019-08-03
 +
 
 +
More details about how to check out source code from SVN can be found [http://openoffice.apache.org/source.html here].
  
More details about how to check out source code from SVN can be found [http://incubator.apache.org/openofficeorg/source.html here].
+
== Space Requirements ==
  
 
The checked out files take up somewhat over 5GB on disk (more than 150000 files in more than 7000 folders and the SVN overhead).  
 
The checked out files take up somewhat over 5GB on disk (more than 150000 files in more than 7000 folders and the SVN overhead).  
  
 
After building this becomes (on Windows7) almost 17GB (more than 406000 files in more than 23000 folders).
 
After building this becomes (on Windows7) almost 17GB (more than 406000 files in more than 23000 folders).
 +
 +
You can use git as well. There exists no guide for this, therefore ask on dev@openoffice.apache.org, if you want to use git.
  
 
= Organization of the source and output tree =
 
= Organization of the source and output tree =
  
The source code has four top level directories:
+
The source code has five top level directories:
;main/:contains most of the so called modules.  Each module typically provides one or more libraries. The source code of the writer application for example can be found in main/sd/.
+
;main/:contains most of the so called modules.  Each module typically provides one or more libraries. The source code of the writer application for example can be found in <code>main/sw/</code>. More information on the organization of the modules in the source code directories [[Source_code_directories | here]].
 +
;test/:contains the new [[QA/test_automation_guide | automated testing framework]]
 
;ext_libraries/:is the new home of modules that build external libraries (libraries maintained outside of Apache OpenOffice and often outside Apache).
 
;ext_libraries/:is the new home of modules that build external libraries (libraries maintained outside of Apache OpenOffice and often outside Apache).
 
;ext_sources/:contains the tar balls (archives) of external libraries.  They are included both for convenience and to make sure that specific versions remain available.  Note that the source package of the Apache OpenOffice release does not contain any external tar balls.  
 
;ext_sources/:contains the tar balls (archives) of external libraries.  They are included both for convenience and to make sure that specific versions remain available.  Note that the source package of the Apache OpenOffice release does not contain any external tar balls.  
Line 74: Line 83:
  
 
The configure step has to be carried out only once.  Building and packing is necessary after every source code change.  There are short cuts to avoid parts of these steps (when you know what you are doing.)
 
The configure step has to be carried out only once.  Building and packing is necessary after every source code change.  There are short cuts to avoid parts of these steps (when you know what you are doing.)
 +
 +
The building examples in this wiki document use only command line approaches to building. Depending on your expertise, it may be possible to use an IDE which allows specification of custom build scripts.
  
 
== General Build Requirements ==
 
== General Build Requirements ==
Line 79: Line 90:
 
The general requirements for all platforms are
 
The general requirements for all platforms are
 
{| class="prettytable"
 
{| class="prettytable"
|-
+
|- valign="top"
 
! Requirement
 
! Requirement
 
! Description
 
! Description
! How to install
+
! Configure switch
|-
+
|- valign="top"
 
| Java JDK
 
| Java JDK
| Java Implementation compatible with [http://java.sun.com/j2se/1.5/ JDK 1.5] or [http://java.sun.com/javase/6/ JDK 1.6]. [http://openjdk.java.net/ OpenJDK] is supported as well.
+
| Java Implementation compatible with [http://www.oracle.com/technetwork/java/javase/downloads/jre7-downloads-1880261.html JDK 1.7] or  higher. [http://openjdk.java.net/ OpenJDK] is supported as well.
 +
For Windows [http://www.oracle.com/technetwork/java/javase/downloads/index.html/ JDK 1.7] or JDK 1.8 is recommended.
 +
The JDK's bitness must match the target platform's, eg. when building for Win32, use a 32 bit JDK even if compiling on Win64.
 
| --with-jdk-home=
 
| --with-jdk-home=
|-
+
|- valign="top"
 
| Perl
 
| Perl
| Perl 5. Also required are the perl packages
+
| Perl 5 - note: for Windows Perl will be installed as part of the cygwin environment.
    Archive::Zip
+
 
    LWP::UserAgent  
+
Also required are the perl packages
They can be installed from the shell with (you may have to run it with super user/administrator rights)
+
 
 +
* Archive::Zip
 +
* XML::Parser
 +
* LWP::UserAgent
 +
* Digest::SHA
 +
* Digest::MD5
 +
* LWP::Protocol::https
 +
 
 +
On Linux, use whenever possible your package manager to install the required modules. On Windows, use cygwin's setup-x86.exe or setup-x86_64.exe.
 +
 
 +
The name of packages varies depending on the system:
 +
 
 +
{| class="wikitable" border="1"
 +
|-
 +
! Perl Module
 +
! CentOS/Fedora
 +
! Debian/Ubuntu
 +
! Windows/cygwin
 +
|-
 +
| Archive::Zip
 +
| perl-Archive-Zip
 +
| libarchive-zip-perl
 +
| perl-Archive-Zip
 +
|-
 +
| XML::Parser
 +
| perl-XML-Parser
 +
| libxml-parser-perl
 +
| perl-XML-Parser
 +
|-
 +
| LWP::UserAgent
 +
| perl-libwww-perl
 +
| libwww-perl
 +
| perl-libwww-perl
 +
|-
 +
| Digest::SHA
 +
| perl-Digest-SHA
 +
| perl
 +
| perl-Digest-SHA
 +
|-
 +
| Digest::MD5
 +
| perl-Digest-MD5
 +
| perl
 +
| perl
 +
|-
 +
| LWP::Protocol::https
 +
| perl-LWP-Protocol-https
 +
| liblwp-protocol-https-perl
 +
| perl-LWP-Protocol-https
 +
|}
 +
 
 +
On some rather old systems, ''LWP::Protocol::https'' is installed in the same package as ''LWP::UserAgent''; in this case, you need to install further dependencies in order to use ''LWP::UserAgent'' with the HTTPS protocol with no errors; on CentOS 5, for example, you need to install the ''Crypt::SSLeay'' module, provided by the ''perl-Crypt-SSLeay'' package.
 +
 
 +
On Mac OS X, bootstrap may fail to download external dependencies from HTTPS URLs (you may get an error with a message like "Can't verify SSL peers without knowing which Certificate Authorities to trust"), even if configure found all required modules; in this case, install the ''Mozilla::CA'' module using cpan.
 +
 
 +
On CentOS, ''perl-Digest-SHA'' might be only provided through the EPEL repository.
 +
 
 +
The prefered way to install Perl modules is using your system's package manager; alternatively, and as last resort, Perl modules can be installed from the shell with (you may have to run it with super user/administrator rights)
 
     perl -MCPAN -e shell
 
     perl -MCPAN -e shell
 
If it is executed for the first time then CPAN will ask for configuration. Choose autoconfiguration.
 
If it is executed for the first time then CPAN will ask for configuration. Choose autoconfiguration.
Eventually the CPAN shell appeares accepts commands.  Install missing modules with  
+
Eventually the CPAN shell appears accepts commands.  Install missing modules with  
 
     install <module-name>
 
     install <module-name>
Find more details [http://wiki.services.openoffice.org/wiki/CPAN_install here].<sup>6</sup>
+
Find more details [https://wiki.openoffice.org/wiki/CPAN_install here].<sup>5</sup>
|-
+
 
 +
|- valign="top"
 
| CUPS
 
| CUPS
 
| cups headers. Provided by a cups-devel package or a libcups2-devel
 
| cups headers. Provided by a cups-devel package or a libcups2-devel
|-
+
 
 +
note: not for Windows
 +
|- valign="top"
 
| PAM
 
| PAM
 
| PAM support. Provided by a pam-devel package or a libpam-dev
 
| PAM support. Provided by a pam-devel package or a libpam-dev
|-
+
 
| Apache Ant
+
note: not for Windows
| [http://ant.apache.org/ Ant 1.7]
+
|- valign="top"
 +
| Apache Ant  
 +
| [http://ant.apache.org/ Ant 1.9 or later] (see note)
 
| --with-ant-home=
 
| --with-ant-home=
|-
+
|- valign="top"
 
| Archiver
 
| Archiver
| zip and unzip
+
| zip and unzip - note: for Windows zip and unzip will be installed as part of the cygwin environment.
|-
+
|- valign="top"
 
| gperf
 
| gperf
| [http://www.gnu.org/software/gperf/gperf.html gperf] tool
+
| [http://www.gnu.org/software/gperf/gperf.html gperf] tool - note: for Windows gperf will be installed as part of the cygwin environment.
|-
+
|- valign="top"
| Mozilla<sup>1</sup>
+
| NSS<sup>1</sup>
| Some Mozilla libraries are needed. Choose one of the following:
+
| For Windows the MozillaBuild tools<sup>2</sup> are needed to build the NSS module. MozillaBuild tools version 3.0 or newer require a 64-bit Windows. When building on 32-bit Windows it is recommended to use version 2.2.0. They can be obtained [https://ftp.mozilla.org/pub/mozilla/libraries/win32/ here].
* Get the source from [http://ftp.mozilla.org/pub/mozilla.org/mozilla/releases/mozilla1.7.5/source/ here].<sup>2</sup>
+
|- valign="top"
* Get prebuild libraries from [http://tools.openoffice.org/moz_prebuild/680/ here].<sup>3</sup>
+
| unowinreg.dll
|-
+
| [https://tools.openoffice.org/unowinreg_prebuild/680/ pre-built unowinreg.dll] (see NOTE)
| NSS<sup>4</sup>
+
Required for building the ODK which is included in the build unless disabled. This file is required for non-Windows builds. Without this file, configure will try to set up cross-compiling with windows.  
| Mozilla build tools<sup>5</sup> are needed for Windows. They can be obtained [http://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-1.3.exe here].
+
NOTE: Not for windows. Required on all non-windows platforms. Download by directly saving unowinreg.dll into /main/external/unowinreg from the link provided above, or by using wget:
 +
    cd $SRC/main &&  wget -O external/unowinreg/unowinreg.dll https://tools.openoffice.org/unowinreg_prebuild/680/unowinreg.dll
 
|-
 
|-
 
|}
 
|}
  
 
'''Notes:'''
 
'''Notes:'''
# If you are a new developer, don't use the libraries. By using the <tt>--disable-mozilla</tt> switch for ./configure you waive the extra functionality.
+
# The NSS module ("Network Security Services") provides security services needed for e.g. password protection. NSS can be disabled using the configure switch <tt>--disable-nss-module</tt>.
# Copy the package into <tt>main/moz/download</tt>. The ./configure script will detect the source being present.
+
# NSS is provided by the Mozilla project. Building it on Windows requires the [https://ftp.mozilla.org/pub/mozilla/libraries/win32/ MozillaBuild tools]. Install it and use the configure switch <tt>--with-mozilla-build</tt> to tell configure where the tools are installed. For example: <tt>--with-mozilla-build=c:/mozilla-build</tt>
# You have to configure with --disable-build-mozilla to enable the use of the prebuild libraries. Place LINUXGCCI{inc,lib,runtime}.zip into <tt>main/moz/zipped</tt>. The files can be reused if the packages were build following the instructions of the previous point. In the latter case they can be found in main/moz/unxlngi6.pro of a successful build.
+
# The nss module will be introduced in DEV300m57. nss contains a subset of libraries from Mozilla (the moz module). They are supposed to be more current then those in the moz module. To prevent building nss and instead use the libraries from the moz module one can use the configure switch <tt>--disable-nss-module</tt>. '''This switch will be removed soon!'''
+
# Use the configure switch <tt>--with-mozilla-build</tt> to tell configure where the tools are installed. For example: <tt>--with-mozilla-build=c:/mozilla-build</tt>
+
 
# 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 /cpan.
 
# 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 /cpan.
 +
# Apache Ant: Assure a proper ant set-up by downloading and installing ant, in total, from the ant site linked above. If you are a Linux developer, your distro may not have ant setup correctly for building Apache OpenOffice.
 +
# Use <tt>./configure --help</tt> to see all possible configuration options
  
 
See also the platform specific requirements for
 
See also the platform specific requirements for
Line 145: Line 219:
 
creates the main/configure script from main/configure.in and some other input files.
 
creates the main/configure script from main/configure.in and some other input files.
  
The set of options/switches given to configure depends on the platform and your choice of features. A typical call looks like this
+
The set of options/switches given to configure depends on the platform and your choice of features. To see all configure options for your system, type:
     configure                                                                                   \
+
  configure --help
         --with-dmake-url=http://dmake.apache-extras.org.codespot.com/files/dmake-4.12.tar.bz2 \
+
 
         --with-epm-url=http://ftp.easysw.com/pub/epm/3.7/epm-3.7-source.tar.gz               \
+
A typical configuration call starts like this --
         --enable-category-b                                                                     \
+
     configure                                                                                         \
 +
         --with-dmake-url=https://sourceforge.net/projects/oooextras.mirror/files/dmake-4.12.tar.bz2 \
 +
         --with-epm-url=https://sourceforge.net/projects/oooextras.mirror/files/epm-3.7.tar.gz       \
 +
It tells configure where to find the source code of external tools dmake and epm.
 +
 
 +
By default only source code under [http://www.apache.org/legal/3party.html#category-a category A] licenses is compiled and included.  Besides the Apache License 2.0 this includes for example BSD and MIT/X11 license.  If you want to enable features that rely on third party code under [http://www.apache.org/legal/3party.html#category-b category B] licenses (like MPL, CPL, EPL, etc) then add the option
 +
         --enable-category-b
 +
 
 +
For inclusion of externally hosted dictionary extensions add option
 
         --enable-bundled-dictionaries
 
         --enable-bundled-dictionaries
This tells configure
+
Note that dictionaries rely on a category B third party library (hunspell). Therefore <code>--enable-category-b</code> is a prerequisite for <code>--enable-bundled-dictionaries</code>. Dictionaries have a variety of licenses and are bundled without modification: they are not compiled.
* where to find the source code of external tools dmake and epm
+
 
* to enable building external libraries that have licenses that are not compatible with the Apache license
+
The <code>--with-lang</code> option will introduce the build of additional language resources. This switch accepts one or more RFC 1766 language tags as arguments, unfortunately not all languages are supported. Check the <code>[http://svn.apache.org/viewvc/openoffice/trunk/main/solenv/inc/langlist.mk?view=markup solenv/inc/langlist.mk]</code> file for all the currently supported language tags. The environment variable WITH_LANG will then contain the language tags of the additional (en-US will always be build) languages. Example:
* to bundle external dictionary extensions.
+
        --with-lang="de fr"
 +
enables the build of the localized German and French version.
 +
 
 +
To build with symbolic generation, add option
 +
        --enable-symbols
 +
This would allow you to work with debugging symbols in gdb.
 +
 
 +
Another useful option for interactive debugging features is dbgutil. Add option,
 +
        --enable-dbgutil
 +
for this feature. Also see the Debugging information on this page.
 +
 
 +
By default the result binaries will be packaged in the default format used by your OS/Distribution. Using 'installed' for package format puts OpenOffice into your ''installset'' directory (browse down ../installed/install). This will save you time for testing since you can then directly run OpenOffice from this area.
 +
 
 +
Add option
 +
        --with-package-format="installed"
 +
 
 +
This will speed up development process since it skipped packaging. In some cases, packaging rips the debugging symbol so this would be necessary for symbolic generation. '''NOTE:''' Additional package format options will be ignored with the "installed" option.
 +
 
 +
 
 +
You can run the rat scan while building with option
 +
        --with-rat-scan
 +
[[Documentation/Building_Guide_AOO/Rat_Scan|Here]] you can find details of the rat scan.
  
 
Finish this step by running
 
Finish this step by running
Line 162: Line 265:
 
==Building==
 
==Building==
 
Start by including the environment variables prepared by configure into your current environment with
 
Start by including the environment variables prepared by configure into your current environment with
   source <shell-script-name>
+
   <tt>source <shell-script-name></tt>
 
where <shell-script-name> depends on your platform:
 
where <shell-script-name> depends on your platform:
 
{| class="prettytable"
 
{| class="prettytable"
Line 178: Line 281:
 
| LinuxX86-64Env.Set.sh
 
| LinuxX86-64Env.Set.sh
 
|-
 
|-
| unxmacxi
+
| unxmacci
| MacOSXX86Env.Set.sh
+
| MacOSXX64Env.Set.sh
 
|}
 
|}
 
Look into main/set_soenv for more platforms. (search for lines <code>$OUTPATH = "<platform>";</code> and the nearby line <code>$outfile = "<shell-script-name>";</code>.  Add the suffix <code>.sh</code> for the bash variant.
 
Look into main/set_soenv for more platforms. (search for lines <code>$OUTPATH = "<platform>";</code> and the nearby line <code>$outfile = "<shell-script-name>";</code>.  Add the suffix <code>.sh</code> for the bash variant.
  
 
If you want to build the whole office and the install sets then
 
If you want to build the whole office and the install sets then
     cd main/instset_native
+
     cd main/instsetoo_native
 
     build --all
 
     build --all
 
You may want to experiment with the -P options for multi process builds to reduce the build time.
 
You may want to experiment with the -P options for multi process builds to reduce the build time.
 
     build --all -P<m> -- -P<n>
 
     build --all -P<m> -- -P<n>
 
tells build to use <code>m</code> processes (build up to <code>m</code> modules in parallel) and <code>n</code> threads for each module.
 
tells build to use <code>m</code> processes (build up to <code>m</code> modules in parallel) and <code>n</code> threads for each module.
 +
 +
Details about creating installation sets can be found [[Building_installation_packages|here]].
 +
 +
Building Apache OpenOffice uses a custom build command, build.pl, located in /main/solenv/bin.
 +
You may find it helpful to learn more about build options from the [http://www.openoffice.org/tools/tools/build.html Build Documentation]
  
 
==Partial Builds==
 
==Partial Builds==
Line 196: Line 304:
 
;Compatible:Can be used only when the code changes do not change exported interfaces. Use with care and only when you know what you are doing.
 
;Compatible:Can be used only when the code changes do not change exported interfaces. Use with care and only when you know what you are doing.
 
;Incompatible:Use for code changes that modify exported C++ or IDL interfaces, that modify resources that are used by other modules, or when you are not sure.
 
;Incompatible:Use for code changes that modify exported C++ or IDL interfaces, that modify resources that are used by other modules, or when you are not sure.
 +
:If you are a new developer, you should probably always assume your changes are "incompatible" and follow the instructions for '''Incompatible Build'''.
  
For the following sections you should be aware that Apache OpenOffice uses two different make systems to build its modules.
+
===Make Systems Used by Apache OpenOffice===
 +
 
 +
For the following Build sections you should be aware that Apache OpenOffice uses two different '''make''' systems to build its modules.
 
*The older one is based on dmake
 
*The older one is based on dmake
 
*The other and newer one is based on GNU make.  This system is often referred to as gbuild.
 
*The other and newer one is based on GNU make.  This system is often referred to as gbuild.
Line 219: Line 330:
 
No explicit call to <code>deliver</code> is necessary for gbuild modules.
 
No explicit call to <code>deliver</code> is necessary for gbuild modules.
 
|}
 
|}
to compile and deliver the resulting libraries to <code>main/solver/</code>. You may want to erase the output of a previous compilation:
+
to compile and deliver the resulting libraries to <code>main/solver/</code>.  
 +
 
 +
You may want to erase the output of a previous compilation. In some cases a new compilation will not work correctly unless the old output is removed.
 +
 
 
{|class="prettytable"
 
{|class="prettytable"
 
|-
 
|-
Line 239: Line 353:
  
 
Modifications that change exported interfaces require not only the module to be rebuild that contains the modified code.  All depending modules (dependencies are defined in <code><module>/prj/build.lst</code>) have to be rebuild as well.  This is best done from <code>main/instsetoo_native/</code>:
 
Modifications that change exported interfaces require not only the module to be rebuild that contains the modified code.  All depending modules (dependencies are defined in <code><module>/prj/build.lst</code>) have to be rebuild as well.  This is best done from <code>main/instsetoo_native/</code>:
   cd main/instsetoo_native/
+
   <tt>cd main/instsetoo_native/</tt>
   build --from <incompatible-module> --prepare
+
   <tt>build --from <incompatible-module> --prepare</tt>
   build --from <incompatible-module>
+
   <tt>build --from <incompatible-module></tt>
The second line removes the output of all modules that have to be recompiled.
+
  
 +
The second line removes the output of all modules that have to be recompiled. The drawback of this command is that the output of modules which are build via gbuild are not removed. Thus, the following additional command performed after the second one will do the trick:
 +
  build --from <incompatible-module> --job="make clean; make clean debug=t" --ignore
  
 
===Frequently used options===
 
===Frequently used options===
Line 260: Line 375:
 
     make -sr debug=t
 
     make -sr debug=t
 
|}
 
|}
Remember that for the gbuild system you have to used the debug flag also when cleaning a module (otherwise eg the wrong precompiled headers are deleted and are not rebuilt):
+
Remember that for the gbuild system you have to use the debug flag also when cleaning a module (otherwise eg the wrong precompiled headers are deleted and are not rebuilt):
 
     make clean debug=t
 
     make clean debug=t
  
  
You can force make to rebuild dependency information by first deleting it with the depend option.  It is rebuild automatically with the next build:
+
You can force make to rebuild dependency information by first deleting it with the depend option.  It would be rebuilt automatically with the next build:
 
{|class="prettytable"
 
{|class="prettytable"
 
|-
 
|-
Line 279: Line 394:
 
     make -sr
 
     make -sr
 
|}
 
|}
[[Category:Documentation]][[Category:Development]][[Category:Porting]]
+
 
 +
==Build Cleanup==
 +
In the event that you want to change configuration parameters used for building, you will probably need to "clean" your build output tree before starting again.
 +
 
 +
To do this, navigate to the "main" directory, then source your environment shell script as you did for building:
 +
 
 +
    <tt>source <shell-script-name></tt>
 +
 
 +
then do:
 +
 
 +
    dmake clean
 +
 
 +
= [[Documentation/Building Guide AOO/Step by step|Step-by-Step Building Guide for Different Platforms]] =
 +
 
 +
= Building Apache OpenOffice with an IDE =
 +
== [[OpenOffice and Eclipse|Building with Eclipse]] ==
 +
 
 +
= Additional Build Resources =
 +
[[Building old versions|Building old versions]]
 +
== [[Debugging|Debugging]] ==
 +
 
 +
[[Category:Documentation]]
 +
[[Category:Development]]
 +
[[Category:Porting]]
 +
[[Category:Build_System]]

Latest revision as of 22:28, 17 February 2020


Preface

This guide will help you to build Apache OpenOffice from its source code. It details the prerequisites and explains how to download the source code, prepare and then run the build. Step-by-step instructions for resolving the pre-requisites of individual platforms and building on them are available.

Here is the short version for the brave and impatient:

  1. Download the source: svn co https://svn.apache.org/repos/asf/openoffice/trunk aoo
Documentation note.png Is the above even needed anymore?
  1. since 2019-08-03 git clone https://gitbox.apache.org/repos/asf/openoffice.git
  2. Configure: cd main/ ; autoconf ; ./configure <some-switches> ; ./bootstrap
  3. Build: source <platform-dependend-name>.sh ; cd instsetoo_native ; build --all
  4. Wait for an hour or more (The build can take up to 3 hours.)
  5. Enjoy

The detailed description below gives a broader introduction into the build process and explains for the various steps.

Documentation note.png This document is loosely based on an older version. I have tried to avoid duplication and to move anything that all platforms have in common to this page. Many details have been removed on purpose because they refer to older version of OpenOffice.
  • How to use cache



See Also


Getting help

You can get help by searching this wiki or by asking questions on the developers mailing list.

You can help us improve this guide by pointing out any errors (preferably after finding a solution). Or don't be shy and edit (and improve) these pages yourself.

Basics

In order to build Apache OpenOffice you need a proper environment. This includes

  • a command line interpreter, typically bourne shell compatible (sh or bash) inside a terminal. On Windows you will need to install Cygwin to provide it.
  • C++ compiler and linker. The exact choice depends on the operating system.
  • Perl interpreter and several modules.
  • Many tools from the Unix world like make or sed.

See section General Build Requirements for an exact list of requirements.

Getting the source

The source code is available as SVN repository at https://svn.apache.org/repos/asf/openoffice

Check it out with

  svn co https://svn.apache.org/repos/asf/openoffice/trunk aoo
  git clone https://gitbox.apache.org/repos/asf/openoffice.git #since 2019-08-03

More details about how to check out source code from SVN can be found here.

Space Requirements

The checked out files take up somewhat over 5GB on disk (more than 150000 files in more than 7000 folders and the SVN overhead).

After building this becomes (on Windows7) almost 17GB (more than 406000 files in more than 23000 folders).

You can use git as well. There exists no guide for this, therefore ask on dev@openoffice.apache.org, if you want to use git.

Organization of the source and output tree

The source code has five top level directories:

main/
contains most of the so called modules. Each module typically provides one or more libraries. The source code of the writer application for example can be found in main/sw/. More information on the organization of the modules in the source code directories here.
test/
contains the new automated testing framework
ext_libraries/
is the new home of modules that build external libraries (libraries maintained outside of Apache OpenOffice and often outside Apache).
ext_sources/
contains the tar balls (archives) of external libraries. They are included both for convenience and to make sure that specific versions remain available. Note that the source package of the Apache OpenOffice release does not contain any external tar balls.
extras/
holds the localization data.

Most tools and scripts that are used for building are located below main/solenv/:

  • dmake makefiles in main/solenv/inc/
  • gmake makefiles in main/solenv/gbuild/
  • executables and perl files in main/solenv/bin/
  • perl modules in main/bin/modules/

Libraries and other output files that are shared between modules are stored in main/solver/.

Building

Overview

Building Apache OpenOffice consists of three steps:

Configuring/bootstrapping
Detect platform, operating system, compiler, etc. and write the information into a shell script for later use. The developer can turn on or off certain features in this phase.
Building
Compile the source code, transform other input files, apply localization.
Packing
Create a set of files, the installation set, that can be installed on the respective operating system. This can be msi/cab files for windows, deb or rpm for Linux, dmg for Mac.

The configure step has to be carried out only once. Building and packing is necessary after every source code change. There are short cuts to avoid parts of these steps (when you know what you are doing.)

The building examples in this wiki document use only command line approaches to building. Depending on your expertise, it may be possible to use an IDE which allows specification of custom build scripts.

General Build Requirements

The general requirements for all platforms are

Requirement Description Configure switch
Java JDK Java Implementation compatible with JDK 1.7 or higher. OpenJDK is supported as well.

For Windows JDK 1.7 or JDK 1.8 is recommended. The JDK's bitness must match the target platform's, eg. when building for Win32, use a 32 bit JDK even if compiling on Win64.

--with-jdk-home=
Perl Perl 5 - note: for Windows Perl will be installed as part of the cygwin environment.

Also required are the perl packages

  • Archive::Zip
  • XML::Parser
  • LWP::UserAgent
  • Digest::SHA
  • Digest::MD5
  • LWP::Protocol::https

On Linux, use whenever possible your package manager to install the required modules. On Windows, use cygwin's setup-x86.exe or setup-x86_64.exe.

The name of packages varies depending on the system:

Perl Module CentOS/Fedora Debian/Ubuntu Windows/cygwin
Archive::Zip perl-Archive-Zip libarchive-zip-perl perl-Archive-Zip
XML::Parser perl-XML-Parser libxml-parser-perl perl-XML-Parser
LWP::UserAgent perl-libwww-perl libwww-perl perl-libwww-perl
Digest::SHA perl-Digest-SHA perl perl-Digest-SHA
Digest::MD5 perl-Digest-MD5 perl perl
LWP::Protocol::https perl-LWP-Protocol-https liblwp-protocol-https-perl perl-LWP-Protocol-https

On some rather old systems, LWP::Protocol::https is installed in the same package as LWP::UserAgent; in this case, you need to install further dependencies in order to use LWP::UserAgent with the HTTPS protocol with no errors; on CentOS 5, for example, you need to install the Crypt::SSLeay module, provided by the perl-Crypt-SSLeay package.

On Mac OS X, bootstrap may fail to download external dependencies from HTTPS URLs (you may get an error with a message like "Can't verify SSL peers without knowing which Certificate Authorities to trust"), even if configure found all required modules; in this case, install the Mozilla::CA module using cpan.

On CentOS, perl-Digest-SHA might be only provided through the EPEL repository.

The prefered way to install Perl modules is using your system's package manager; alternatively, and as last resort, Perl modules can be installed from the shell with (you may have to run it with super user/administrator rights)

   perl -MCPAN -e shell

If it is executed for the first time then CPAN will ask for configuration. Choose autoconfiguration. Eventually the CPAN shell appears accepts commands. Install missing modules with

   install <module-name>

Find more details here.5

CUPS cups headers. Provided by a cups-devel package or a libcups2-devel

note: not for Windows

PAM PAM support. Provided by a pam-devel package or a libpam-dev

note: not for Windows

Apache Ant Ant 1.9 or later (see note) --with-ant-home=
Archiver zip and unzip - note: for Windows zip and unzip will be installed as part of the cygwin environment.
gperf gperf tool - note: for Windows gperf will be installed as part of the cygwin environment.
NSS1 For Windows the MozillaBuild tools2 are needed to build the NSS module. MozillaBuild tools version 3.0 or newer require a 64-bit Windows. When building on 32-bit Windows it is recommended to use version 2.2.0. They can be obtained here.
unowinreg.dll pre-built unowinreg.dll (see NOTE)

Required for building the ODK which is included in the build unless disabled. This file is required for non-Windows builds. Without this file, configure will try to set up cross-compiling with windows. NOTE: Not for windows. Required on all non-windows platforms. Download by directly saving unowinreg.dll into /main/external/unowinreg from the link provided above, or by using wget:

   cd $SRC/main &&  wget -O external/unowinreg/unowinreg.dll https://tools.openoffice.org/unowinreg_prebuild/680/unowinreg.dll

Notes:

  1. The NSS module ("Network Security Services") provides security services needed for e.g. password protection. NSS can be disabled using the configure switch --disable-nss-module.
  2. NSS is provided by the Mozilla project. Building it on Windows requires the MozillaBuild tools. Install it and use the configure switch --with-mozilla-build to tell configure where the tools are installed. For example: --with-mozilla-build=c:/mozilla-build
  3. 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 /cpan.
  4. Apache Ant: Assure a proper ant set-up by downloading and installing ant, in total, from the ant site linked above. If you are a Linux developer, your distro may not have ant setup correctly for building Apache OpenOffice.
  5. Use ./configure --help to see all possible configuration options

See also the platform specific requirements for

Configuration and bootstrapping

This is typically done only once after the source code is checked out. Repeat this after changing your mind about options given to configure.

The call to

  autoconf

creates the main/configure script from main/configure.in and some other input files.

The set of options/switches given to configure depends on the platform and your choice of features. To see all configure options for your system, type:

 configure --help

A typical configuration call starts like this --

   configure                                                                                         \
       --with-dmake-url=https://sourceforge.net/projects/oooextras.mirror/files/dmake-4.12.tar.bz2 \
       --with-epm-url=https://sourceforge.net/projects/oooextras.mirror/files/epm-3.7.tar.gz       \

It tells configure where to find the source code of external tools dmake and epm.

By default only source code under category A licenses is compiled and included. Besides the Apache License 2.0 this includes for example BSD and MIT/X11 license. If you want to enable features that rely on third party code under category B licenses (like MPL, CPL, EPL, etc) then add the option

       --enable-category-b

For inclusion of externally hosted dictionary extensions add option

       --enable-bundled-dictionaries

Note that dictionaries rely on a category B third party library (hunspell). Therefore --enable-category-b is a prerequisite for --enable-bundled-dictionaries. Dictionaries have a variety of licenses and are bundled without modification: they are not compiled.

The --with-lang option will introduce the build of additional language resources. This switch accepts one or more RFC 1766 language tags as arguments, unfortunately not all languages are supported. Check the solenv/inc/langlist.mk file for all the currently supported language tags. The environment variable WITH_LANG will then contain the language tags of the additional (en-US will always be build) languages. Example:

       --with-lang="de fr"

enables the build of the localized German and French version.

To build with symbolic generation, add option

       --enable-symbols

This would allow you to work with debugging symbols in gdb.

Another useful option for interactive debugging features is dbgutil. Add option,

       --enable-dbgutil

for this feature. Also see the Debugging information on this page.

By default the result binaries will be packaged in the default format used by your OS/Distribution. Using 'installed' for package format puts OpenOffice into your installset directory (browse down ../installed/install). This will save you time for testing since you can then directly run OpenOffice from this area.

Add option

       --with-package-format="installed"

This will speed up development process since it skipped packaging. In some cases, packaging rips the debugging symbol so this would be necessary for symbolic generation. NOTE: Additional package format options will be ignored with the "installed" option.


You can run the rat scan while building with option

        --with-rat-scan

Here you can find details of the rat scan.

Finish this step by running

   ./bootstrap

This will build dmake and epm, download missing source code tar balls of external libraries, and download missing external dictionary extensions.

Building

Start by including the environment variables prepared by configure into your current environment with

  source <shell-script-name>

where <shell-script-name> depends on your platform:

platform id <shell-script-name>
wntmsci12 winenv.set.sh
unxlngi6 LinuxX86Env.Set.sh
unxlngx6 LinuxX86-64Env.Set.sh
unxmacci MacOSXX64Env.Set.sh

Look into main/set_soenv for more platforms. (search for lines $OUTPATH = "<platform>"; and the nearby line $outfile = "<shell-script-name>";. Add the suffix .sh for the bash variant.

If you want to build the whole office and the install sets then

   cd main/instsetoo_native
   build --all

You may want to experiment with the -P options for multi process builds to reduce the build time.

   build --all -P<m> -- -P<n>

tells build to use m processes (build up to m modules in parallel) and n threads for each module.

Details about creating installation sets can be found here.

Building Apache OpenOffice uses a custom build command, build.pl, located in /main/solenv/bin. You may find it helpful to learn more about build options from the Build Documentation

Partial Builds

Building the whole office takes a lot of time. Therefore it may be preferable to build only parts after making changes to the source code. There are two different types of partial builds:

Compatible
Can be used only when the code changes do not change exported interfaces. Use with care and only when you know what you are doing.
Incompatible
Use for code changes that modify exported C++ or IDL interfaces, that modify resources that are used by other modules, or when you are not sure.
If you are a new developer, you should probably always assume your changes are "incompatible" and follow the instructions for Incompatible Build.

Make Systems Used by Apache OpenOffice

For the following Build sections you should be aware that Apache OpenOffice uses two different make systems to build its modules.

  • The older one is based on dmake
  • The other and newer one is based on GNU make. This system is often referred to as gbuild.

When a module contains, among others, a Makefile and a Module_<module>.mk file then it is a gbuild module.

Compatible Build

After changing code in module <module> which does not change any exported interfaces do

dmake gbuild
   cd <module>
   build
   deliver
   cd <module>
   make -sr

No explicit call to deliver is necessary for gbuild modules.

to compile and deliver the resulting libraries to main/solver/.

You may want to erase the output of a previous compilation. In some cases a new compilation will not work correctly unless the old output is removed.

dmake gbuild
   cd <module>
   build --from <module> --prepare

or faster (but without the un-deliver)

   cd <module>
   rm -fr <platform>/
   cd <module>
   make clean

Incompatible Build

Modifications that change exported interfaces require not only the module to be rebuild that contains the modified code. All depending modules (dependencies are defined in <module>/prj/build.lst) have to be rebuild as well. This is best done from main/instsetoo_native/:

 cd main/instsetoo_native/
 build --from <incompatible-module> --prepare
 build --from <incompatible-module>

The second line removes the output of all modules that have to be recompiled. The drawback of this command is that the output of modules which are build via gbuild are not removed. Thus, the following additional command performed after the second one will do the trick:

 build --from <incompatible-module> --job="make clean; make clean debug=t" --ignore

Frequently used options

In order to add debug information to libraries and executables, add the debug switch to any build or make command:

dmake gbuild
   cd <module>
   build debug=t
   cd <module>
   make -sr debug=t

Remember that for the gbuild system you have to use the debug flag also when cleaning a module (otherwise eg the wrong precompiled headers are deleted and are not rebuilt):

   make clean debug=t


You can force make to rebuild dependency information by first deleting it with the depend option. It would be rebuilt automatically with the next build:

dmake gbuild
   cd <module>
   build depend=t
   build
   cd <module>
   make -sr depend=t
   make -sr

Build Cleanup

In the event that you want to change configuration parameters used for building, you will probably need to "clean" your build output tree before starting again.

To do this, navigate to the "main" directory, then source your environment shell script as you did for building:

    source <shell-script-name>

then do:

    dmake clean

Step-by-Step Building Guide for Different Platforms

Building Apache OpenOffice with an IDE

Building with Eclipse

Additional Build Resources

Building old versions

Debugging

Personal tools