Difference between revisions of "Documentation/Building Guide AOO"
m (Integrated some information from Windows page.) |
(Started partial builds) |
||
Line 5: | Line 5: | ||
{{DISPLAYTITLE:Apache OpenOffice Building Guide}} | {{DISPLAYTITLE:Apache OpenOffice Building Guide}} | ||
− | + | = 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. | ||
Line 18: | Line 18: | ||
*Enjoy | *Enjoy | ||
− | + | = 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://incubator.apache.org/openofficeorg/mailing-lists.html#development-mailing-list 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.) | ||
− | + | = Basics = | |
In order to build Apache OpenOffice you need a proper environment. This includes | In order to build Apache OpenOffice you need a proper environment. This includes | ||
Line 33: | Line 33: | ||
The exact list of requirements will be detailed on operating specific sub pages. Note that while some of these tools come pre-installed with the Linuxes, FreeBSD, Mac, Solaris etc. on Windows you will need to install Cygwin to provide them. | The exact list of requirements will be detailed on operating specific sub pages. Note that while some of these tools come pre-installed with the Linuxes, FreeBSD, Mac, Solaris etc. on Windows you will need to install Cygwin to provide them. | ||
− | + | = 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/incubator/ooo. | ||
Line 45: | Line 45: | ||
More details can be found [http://incubator.apache.org/openofficeorg/source.html here]. | More details can be found [http://incubator.apache.org/openofficeorg/source.html here]. | ||
− | + | = Organization of the source and output tree = | |
The source code has four top level directories: | The source code has four top level directories: | ||
Line 61: | Line 61: | ||
Libraries and other output files that are shared between modules are stored in <code>main/solver/</code>. | Libraries and other output files that are shared between modules are stored in <code>main/solver/</code>. | ||
− | + | =Building= | |
− | + | ==Overview== | |
Building Apache OpenOffice consists of three steps: | Building Apache OpenOffice consists of three steps: | ||
Line 72: | Line 72: | ||
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.) | ||
− | + | == General Build Requirements == | |
The general requirements for all platforms are | The general requirements for all platforms are | ||
Line 133: | Line 133: | ||
*[[Documentation/Building_Guide_AOO/Building_on_Windows|Windows]] | *[[Documentation/Building_Guide_AOO/Building_on_Windows|Windows]] | ||
− | + | ==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. | This is typically done only once after the source code is checked out. Repeat this after changing your mind about options given to configure. | ||
Line 155: | Line 155: | ||
This will build dmake and epm, download missing source code tar balls of external libraries, and download missing external dictionary extensions. | 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 | Start by including the environment variables prepared by configure into your current environment with | ||
source <shell-script-name> | source <shell-script-name> | ||
Line 184: | Line 184: | ||
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. | ||
+ | |||
+ | ==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. | ||
+ | |||
+ | ===Compatible Build=== | ||
+ | |||
+ | After changing code in module <module> which does not change any exported interfaces do | ||
+ | cd <module> | ||
+ | build | ||
+ | deliver | ||
+ | or | ||
+ | cd <module> | ||
+ | make -sr | ||
+ | to compile and deliver the resulting libraries to main/solver/. | ||
+ | The first variant is for the older modules that still use dmake makefiles. The second variant is for newer modules that use the gbuild system (such modules contain, among others, a Makefile and a Module_<module>.mk file). The explicit call to <code>deliver</code> is not necessary for gbuild modules. | ||
+ | |||
+ | To make a clean build of the whole module run | ||
+ | {|class="prettytable" | ||
+ | |- | ||
+ | !dmake | ||
+ | !gbuild | ||
+ | |- | ||
+ | | | ||
+ | cd <module> | ||
+ | build --from <module> --prepare | ||
+ | or faster (but without the un-deliver) | ||
+ | cd <module> | ||
+ | rm -fr <platform>/ | ||
+ | | | ||
+ | cd <module> | ||
+ | make clean | ||
+ | |} | ||
+ | |||
+ | |||
+ | |||
[[Category:Education]][[Category:Development]][[Category:Porting]] | [[Category:Education]][[Category:Development]][[Category:Porting]] |
Revision as of 10:06, 5 April 2012
Template:Documentation/Building Guide AOO TOC
Contents
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 document is loosely based on an older, now deprecated, version.
Here is the short version for the brave and impatient:
- Download the source:
svn co https://svn.apache.org/repos/asf/incubator/ooo/trunk ooo
- Configure:
cd main/ ; autoconf ; ./configure <some-switches> ; ./bootstrap
- Build:
source <platform-dependend-name>.sh ; cd instset_native ; build --all
- Wait for an hour or more (here you have to be patient)
- Install office
- Enjoy
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.)
Basics
In order to build Apache OpenOffice you need a proper environment. This includes
- a command line interpreter, typically a bash shell (although sh should be enough) inside a terminal.
- 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.
The exact list of requirements will be detailed on operating specific sub pages. Note that while some of these tools come pre-installed with the Linuxes, FreeBSD, Mac, Solaris etc. on Windows you will need to install Cygwin to provide them.
Getting the source
The source code is available as SVN repository at https://svn.apache.org/repos/asf/incubator/ooo.
Check it out with
svn co https://svn.apache.org/repos/asf/incubator/ooo/trunk ooo
This takes 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).
More details can be found here.
Organization of the source and output tree
The source code has four 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/.
- 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.)
General Build Requirements
The general requirements for all platforms are
Requirement | Description | How to install |
---|---|---|
Java JDK | Java Implementation compatible with JDK 1.5 or JDK 1.6. OpenJDK is supported as well. | --with-jdk-home= |
Perl | Perl 5. Also required are the perl packages
Archive::Zip LWP::UserAgent They 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 appeares accepts commands. Install missing modules with install <module-name> Find more details here.6 | |
CUPS | cups headers. Provided by a cups-devel package or a libcups2-devel | |
PAM | PAM support. Provided by a pam-devel package or a libpam-dev | |
Apache Ant | Ant 1.7 | --with-ant-home= |
Archiver | zip and unzip | |
gperf | gperf tool | |
Mozilla1 | Some Mozilla libraries are needed. Choose one of the following: | |
NSS4 | Mozilla build tools5 are needed for Windows. They can be obtained here. |
Notes:
- If you are a new developer, don't use the libraries. By using the --disable-mozilla switch for ./configure you waive the extra functionality.
- Copy the package into main/moz/download. The ./configure script will detect the source being present.
- You have to configure with --disable-build-mozilla to enable the use of the prebuild libraries. Place LINUXGCCI{inc,lib,runtime}.zip into main/moz/zipped. 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 --disable-nss-module. This switch will be removed soon!
- Use the configure switch --with-mozilla-build to tell configure where the tools are installed. For example: --with-mozilla-build=c:/mozilla-build
- 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.
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. A typical call looks like this
configure \ --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 \ --enable-category-b \ --enable-bundled-dictionaries
This tells configure
- 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
- to bundle external dictionary extensions.
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 |
unxmacxi | MacOSXX86Env.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/instset_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.
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.
Compatible Build
After changing code in module <module> which does not change any exported interfaces do
cd <module> build deliver
or
cd <module> make -sr
to compile and deliver the resulting libraries to main/solver/.
The first variant is for the older modules that still use dmake makefiles. The second variant is for newer modules that use the gbuild system (such modules contain, among others, a Makefile and a Module_<module>.mk file). The explicit call to deliver
is not necessary for gbuild modules.
To make a clean build of the whole module run
dmake | gbuild |
---|---|
cd <module> build --from <module> --prepare or faster (but without the un-deliver) cd <module> rm -fr <platform>/ |
cd <module> make clean |