LibreOffice: Code Structure
Hermenutical keys to acomplex code-baseMichael Meeks
General Manager at Collabora Productivity
michael.meeks@collabora.com

mmeeks, #libreoffice­dev, irc.freenode.net@CollaboraOffice“Standat the crossroads and look; ask for theancient paths, ask where the good way is,
and walk in it, and you will find rest for yoursouls...” - Jeremiah 6:16
LibreOffice
Conference 2015, Aarhus | MichaelMeeks
www.CollaboraOffice.com@CollaboraOffice

1 / 28

Overview / Agenda … Chunk #1●Codebase overview– Internal core modules, internal leaf,(ignore externals)● Build + package: gnumake + scp2●●

Code organisation / git bits
Bear in mind: this is a 20 year old codebase●The code-base is rather better than canbe expected, and things continue toimproving over time.
2Module overview –lowest level

https://collaboraoffice.com

Internal non-leaf modules:
UNO modules●

Top-level directory names.
●●

Each module has a README file:●●eg. sal/README

sal: - at the bottom●●●make dump­deps­png# needs graphviz

The system abstraction layer'tools' is an obsolete internal~duplication of this modulesalhelper: - wrapper code aroundsal – also part of URE4

What is the Uno Runtime Environment(URE)●

We'll come onto UNO later in detail
but … for now:●

“Uno Runtime Environment”●

cf. JRE → Java Runtime Env.

●●

Provides an ABI / API stable
abstraction layer for the suite●●

Belongs to the pipe-dream of aworld where UNO was re-used byother applications.

URE

So you can write C++ plugins

Careful:●We have to watch our ABI here.

●ABI control via C symbol map files5UNO module dissection
●

●

●

●

store: obsolete & irrelevant.
registry: used to keep interface
descriptions
unoidl: used to create / compile interface
descriptions: an IDL compiler.
cppu: C++ UNO●

Implements basic UNO types, andinfrastructure for C++●

xmlreader: very simple XML pull parser●

cppuhelper:●

luggage to bootstrap UNO, create
UNO components etc.
6More associated modules
ucbhelper – Universal Content
Broker (ucb) C++ wrapper / helperclasses●

ucb - Provides an unusual Virtual
Filing System abstraction

i18nlangtag: – module that handles
BCP47: a powerful way to represent
subtle language / locales
jvmfwk: Java / UNO integration
comphelper: lots of good C++ stuff
for using UNO – not stable enoughto go into the URE7

Module overview –middle level

https://collaboraoffice.com

More associated modules●●

basegfx – algorithms / graphic types
etc. for basic graphics.
tools: – more basic types:●

SvStream – internal stream typevs. UCB vs. sal/ file pieces.
Color COL_RED etc.
–●●

INetURLObject – canonical
URL handling●SolarMutex (the big lock)●Resources, translation●Polygon / PolyPolygon●Date / Time classes●

A total grab-bag of things

9Unit testing pieces:●●cppunit: - ~all our tests areultimately cppunit tests though
this is an external module.
unotest: low level testing ofsimpler / UNO infrastructural pieces.
Bootstrap UNO enough to be able
to test filters,components etc.
●●●

All of that requires
types / services, configuration etc.

test: helpers for testing standard interfaces, more advanced tests: brings
UCB bootstrap (for streams), VCL initialization, graphic filter pieces etc.
CppUnit*_.mk files in directories
10Other non-graphical bits ...
●●i18nutil: - 'honest C++ code'wrapping UNO l10n madness eg.
'bool isUpper (sal_Unicode c);'unotools: - C++ helpers for using
UCB eg.
SvStream *CreateStream( OUString &rPath);●●●

Misc. font & config handlingsot: - handles OLE2 / compound filestorage for binary documents
svl: - non-graphical (no VCLdependency) pieces originally fromsvtools/ or sfx/ eg. SfxItemSet – thekey C++ property-bag class●

Undo/Redo, and more ...

●'tools' but higher up ...

11

Graphical / toolkit pieces ...
●●●vcl: - Visual Class Libraries – theLibreOffice graphical toolkit, on
this – more later.
toolkit: - a particularly thin &horrible UNO API wrapper with
Model/View flavour on top of vcl.
canvas: - alpha transparent, antialiased UNO rendering API – more
modern rendering than VCL,
primarily used by slideshow●●DirectX, Cairo & VCL impls.

cppcanvas: - C++ wrappers tomake using the canvas less bad.
12

Non-Graphical grab-bag ...
●●●basic: - the StarBasic parser /interpreter & run-time.
xmlscript: XML serialisation of(orrible) basic dialogs which wrap
the toolkit pieces for in-document
scripting / macro dialogs.
connectivity: - UNO implemented
database drivers for all manner ofbackends:●●

Postgresql, MySQL, Mozillaaddressbook, Evolution, JDBC,ODBC etc. etc.

sax: - wrapper of libxml2 –providing an UNO sax API for
parsing XML files, and an
XFastParser for tokenising them.

13Graphical grab-bag●svtools: - lots of pieces●tree / list controls●

table control●

dialog helpers●

accessibility helpers●

options wrappers●

print dialogs●

filedialog helpers●imagemaps●wizard helpers etc.

14Module overview –upper level

https://collaboraoffice.com

Document / Chrome
pieces ...

●framework: - manages docking,toolbars, menus, status bar,sidebars, task-panes●●'new' (over-engineered) codewith heavy UNO logic

sfx2: - works closely withframework, core of the app.
●●load / save logic: SfxMedium
manage views on top offramework●'Help' pieces, quick-starter,●Dialog helpers: tab dialogs●

Document meta-data dialogs●

Template management●

Shared style pieces.

16Miscellaneous pieces
●

●

●

●

●

formula: - nominally sharedcode extracted from calc (sc) for
use in reportdesign
avmedia: - Audio / Video media– multimedia abstraction overDirectX, quicktime, gstreamer
linguistic: - implements UNO
services for spell / hyphenator &thesaurus.
xmlsecurity: - XML document
encryption and signing used forODF.
vbahelper: - helper code for
implementing VBA / macrointeroperability with MS Office17

Load / save / filter logic ...
●●package: - ZIP file compress / decompress, also handles manifest
files in the .zip with UNO stream /storage interfaces
xmloff: - ODF file filters andhelpers to load / save our model
to/from ODF.
●●

filter: - meta-data to manage,
register and auto-detect filters●●

Often working in conjunction
with eg. sw/source/filter/xml/

Also flat-ODF, XSLT filters,
graphic filters, flash + svg
export & more.

oox: - shared MS Office OpenXML (import) filter pieces.

18

Applications ...
●desktop: - legacy name,StarOffice 5 had a 'desktop'
complete with 'Start' menu etc.
●●●

Drawings + Presentations

sw: - 'Star Writer'●●

desktop/source/app/app.cxx

sd: - Star Draw ( Impress )●●here lives thereal 'main'

Word processor

sc: - Star Calc●

Spreadsheet
19

Caveats: this is a
simplified picture●

That was just the non-leaf nodes.

●

This is a linking dependency graph●

UNO component use is hard to graph / grok.

fundamentally a dependency breakingtechnology.
● other important bits:●●

cui: - a big bag of dialogs – split to avoid loading●ucb: - Universal Content Broker●

chart2: - embedded chart rendering and model●slideshow:- the piece that renders your slideshow.

●solenv:- where build infrastructure lives.

20Build + Package

https://collaboraoffice.com

Build: configure etc.
●

autoconf / configure reasonably sane●

autogen.sh – a wrapper around autotools

builds & runs configure script etc.
● keep your parameters inautogen.input● Builds:●– config_host.mk from config_host.mk.in

This contains all the variables we need.
– config_host/*.h – from templates● containing the build configuration.
●

22

Android / Online build●

Android●

Normal core.git, configure nicely:­­with­android­ndk, ­­with­android­sdk etc.

– Checkout README.android●●

Binaries end up in android/ as APK files.

Online●●Normal autotools style configure / make / makerun.
Ensure you use:­­with­lo­path=core.git/instdir­­enable­debug●To get working unit tests

23Build: gnumake ...
●gnumake used in some odd ways●

code is in solenv/gbuild/●

Each module has it's own Makefile– You can build each independently after afull-build.
– All rules are built by $(call Function,...)
magic, we don't use generic / built-inrules.
=> if something is compiled – we havean explicit rule for it (somewhere)● Following the rules is not trivial: $(1) → $(7)24Build: output ...
●We build a working image into 'instdir/'●

instdir/program– Contains a runnable image post 'make'The authoritative location for libraries– make && instdir/program/soffice.exe●●

workdir/*– object files, and build intermediates here
– generated headers– unpacked external source code etc.
25

Finally – key modules in build...
●

postprocess●

packimages/– Using solenv/bin/packimages.pl – build icon

theme .zip and sort it by access pattern● CustomTarget_registry.mk– Build configuration files from officecfg/●

Rdb_Services.mk– Build services.rdb file from .components●officecfg/●

Home of all defaults / office configuration /settings26

Internal module organisation ...
●include/●●●All global includes live in include/<module>/

sfx2/inc- includes local to module●

source/*- source code for module●

source/inc/ - other includes local to module●uiconfig/- new-style XML UI descriptions

●

sdi/

- descriptions of slots / actions●qa/- unit tests, test file data etc.

Lots of things moved over time:●

git log ­u ­­follow – include/sfx2/new.hxx– Only works for one file27

Questions / conclusions●

Are you still alive ?

●That was very dense and high-level●

Hopefully it's useful.

●We have a lot of modules–You can safely not know about the vast majority ofthem.

Oh, that my words were recorded, that they were written on a scroll, that they wereinscribed with an iron tool on lead, or engraved in rock for ever! I know that myRedeemer lives, and that in the end he will stand upon the earth. And though thisbody has been destroyed yet in my flesh I will see God, I myself will see him, withmy own eyes - I and not another. How my heart yearns within me. - Job 19: 23-27

28
https://collaboraoffice.com