195 lines
7.1 KiB
Text
195 lines
7.1 KiB
Text
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 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.
|