libreoffice-online/loolwsd/README

LibreOffice On-Line WebSocket server
====================================

Dependencies
------------

LibreOffice On-Line WebSocket server has the following dependencies:

* libpng
* Poco library: http://pocoproject.org/index.html.
* libcap-progs

Poco can be built with ./configure --prefix=/opt/poco && make install, but
distro packages exist too.

On openSUSE, you can use:

    zypper ar http://download.opensuse.org/repositories/devel:/libraries:/c_c++/openSUSE_13.2/devel:libraries:c_c++.repo
    zypper in poco-devel libcap-progs

Building
--------

loolwsd uses autoconf/automake, so build using the usual:

    MASTER=/path/to/built/core.git # configure for your system

    autoreconf
    automake --add-missing
    ./configure --enable-silent-rules --with-lokit-path=${MASTER}/include
    make

where ${MASTER} is the location of the LibreOffice source tree.

Note that the loolwsd program needs the CAP_SYS_CHROOT capability,
thus you will be asked the root password when running make as it
invokes sudo to run /sbin/setcap.

If you have self-built Poco, add the following to ./configure:

    --with-poco-includes=<POCOINST>/include --with-poco-libs=<POCOINST>/lib

where <POCOINST> means the Poco installation location.

If you have the Poco debugging libraries (eg. you have a self-built
Poco), you can add --enable-debug to the configure options for
additional debugging.

For Windows, a proper VS2013 project is needed.

There is still unconditional debugging output etc. This is a work in
progress.

Running
-------

First create the directory used for caching tiles. It is set as
"${localstatedir}/cache/${PACKAGE}" in the configure.ac, so if you did
not pass any switch to the configure script that affects
"localstatedir, it will be /usr/local/var/cache/loolwsd . If you did
pass such a switch, like --prefix, check config.h for the exact value.

If you're using the defaults you'll need to:

sudo mkdir -p /usr/local/var/cache/loolwsd
sudo chown `whoami` /usr/local/var/cache/loolwsd

Now you need to set up a minimal chroot system, and directory for the jails:

    SYSTEMPLATE=`pwd`/systemplate  # or tweak for your system
    ROOTFORJAILS=`pwd`/jails       # or tweak for your system

    rm -Rf ${SYSTEMPLATE} # clean
    ./setup-sys-chroot ${SYSTEMPLATE} ${MASTER}/instdir # build template
    mkdir -p ${ROOTFORJAILS} # create location for transient jails.

To run loolwsd the way it is supposed to eventually be run "for real", you can
now do:

    ./loolwsd --systemplate=${SYSTEMPLATE} --lotemplate=${MASTER}/instdir --childroot=${ROOTFORJAILS}

and connect loleaflet to that (see loleaflet/README for more info).

Again, ${MASTER} is location of the LibreOffice source tree with a built
LibreOffice.  This is work in progress, and consequently needs the latest
LibreOffice master.

The ${SYSTEMPLATE} is a directory tree set up using the
setup-sys-chroot script here. (It should not exist before running the
script.) It will contain the runtime environment needed by the
LibreOffice dynamic libraries used through LibreOfficeKit.
Improvements to that script are very likely needed on various
distros.

The ${ROOTFORJAILS} directory above is a presumably initially empty
directory under which loolwsd will create chroot jails for editing
each specific document.

As loolwsd uses hardlinks to "copy" the contents of both
${SYSTEMPLATE} and the ${MASTER}/instdir directories into each chroot
jail, ${SYSTEMPLATE} and ${MASTER}/instdir need to be on the same file
system as ${ROOTFORJAILS}.

If you plan to hack on loolwsd, you probably want to familiarize
yourself with loolwsd's --test and --numprespawns switches, and the
'connect' test program.

For interactive testing, you can use the loolwsd --test switch, or you
can use the 'connect' program. Both accept "commands" from the
protocol on standard input. You can either used them tuly
interactively, or edit input lines into a file, or use shell
scripting, etc. For instance:

    (echo load /some/where/foo.odt; echo tile part=0 width=500 height=500 tileposx=0 tileposy=0 tilewidth=10000 tileheight=10000; sleep 10) |
    ./loolwsd --test --systemplate=/home/tml/lo/master/lool-sys-template --lotemplate=/home/tml/lo/master/instdir --childroot=/home/tml/lo/master/lool-child-root

Debugging
---------

When debugging, you want to add --numprespawns=1 to the loolwsd parameters to
limit the amount of concurrently running processes.

When the crash happens too early, you also want to

    export SLEEPFORDEBUGGER=<number of seconds>

so that you have time to attach to the process.

Then run loolwsd, and attach your debugger to the process you are
interested in. Note that as the loolwsd executable file has the
cap_sys_chroot capability set, you most likely need to run the
debugger with super-user privilege (use the sudo command) to be able
to attach a running loolwsd process. (This is a bit odd, as a child
loolwsd process gives up its chroot capability after using it, and the
master loolwsd process doesn't ebven use it, but gies it up right
away.)

Also, note that as the child processes run in a chroot environment,
they see the LibreOffice shared libraries as being in a directory tree
/lo , but your debugger does not. So in order to be able to
effectively debug the LibreOffice code as used through LibreOfficeKit
by a child loolwsd process, you need to symlink the "lo" subdirectory
of a running child loolwsd process's chroot jail as /lo. Something like:

sudo ln -s ~/libreoffice/master/lool-child-roots/1046829984599121011/lo /lo

Use the ps command to find out exactly the path to use.

Protocol description
--------------------

See protocol.txt for a description of the protocol to be used over the
websocket.

Coding style
------------

There is not really any serious rationale why the code ended up being
written in the style it is... but unless you plan to change some style
detail completely and consistenly all over, please keep to the style
of the existing code when editing.

The style is roughly as follows, in rough order of importance:

- As in LO, no hard TABs in source files. Only spaces. Indentation
  step is four columns.

- As in LO, the braces { and } of the block of if, switch, and while
  statements go on separate lines.

- Following Poco conventions, member variables are prefixed with an
  underscore. But I am not opposed to changing this to 'm_' for
  instance.

- Do use C++11. I admit in some places (out of laziness or ignorance)
  I use Poco API even if there probably is an equivalent std::
  API. (Like for threads.) Feel free to change those, if the std:: API
  is not much more verbose or ugly, and you are sure it is equivalent.

- Always prefer the C++ wrapped version of a C library
  API. I.e. include <cstring> instead of <string.h>, use std::memcpy()
  instead of memcpy(), etc.

- Use std:: prefix for all std API, i.e. don't ever do "using
  std;". But it's OK to use "using Poco::Foo;" all over. Maybe that is
  not a good idea?

- Be as portable as possible, i.e. don't intentionally write Unix-only
  code if there is a choice. Obviously some parts of the code
  currently use Unix-only things like chroot() and link() though.

- Member functions use camelCaseWithInitialLowerCase. I don't like
  CamelCaseWithInitialUpperCase.

- No kind of Hungarian prefixes.