Requirements
===================

RKWard requires:
- Several KF6-libraries and headers (>= 6.0) (https://www.kde.org)
- Qt-libraries and headers (>= 6.6) (https://qt.io)
- R and headers (https://www.r-project.org); at the time of this writing, version 3.4.4 (on Windows: version 4.2.0)
  or later is required. Note, however, that old versions are not actively tested.
- CMake (https://cmake.org)


Compilation
===================

IMPORTANT: You will need to have the R shared library installed. This is typically located in a place like /usr/lib/R/lib/libR.so. Unfortunately, some distributions do not yet ship their R binary with the shared library. In those (rare) cases, you'll have to compile and install R on your own with the option --enable-R-shlib.

The recommended way to build from source is:
> mkdir build; cd build
> cmake path_to_rkward_sources [options]	# see below
> make
> sudo make install


CMake options (configuring)
===================

The cmake command offers a number of parameters to control the build process. Some commonly needed are:

-DCMAKE_INSTALL_PREFIX
	set the installation base directory. Generally -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix` should be correct.
-DCMAKE_BUILD_TYPE
	type of build. Useful settings include -DCMAKE_BUILD_TYPE=Release and -DCMAKE_BUILD_TYPE=debugfull

In some cases you may want to set the following options:


-DR_EXECUTABLE
	path to the R executable. You may want to set this, if you have multiple versions of R installed, or R is not in your path. Example: -DR_EXECUTABLE=/usr/bin/R
-DR_HOME
	R home directory. Almost certainly this option is not needed.
-DR_INCLUDEDIR
	path to R include files. Almost certainly this option is not needed.
-DUSE_BINARY_PACKAGES
	Currently only interpreted on Mac OS: If RKWard should default to installing binary R packages (if available) use
	-DUSE_BINARY_PACKAGE=1. Otherwise, RKWard will default to building R packages from source.
-DDLOPEN_RLIB=OFF
	By default, the backend code is loaded using dlopen() to avoid certain runtime conflicts, esp. in distributed AppImages. This, however, makes it hard to
	get at proper debug symbol information. For debugging purposes it may thus be useful to set this to "0", explictly
-DFORCE_WITH_QWEBENGINE=ON
-DFORCE_WITH_QWEBVIEW=ON
	RKWard supports two HTML rendering libraries, QWebEngine or QWebView. By default, either - or both - will be selected automatically, based on the
	presence of the required libaries. Use these options to override the automatic selection. Setting either of these options to ON
	will disable building against the other library *unless* that is also specified with FORCE_WITH_XYZ.
	Packagers please note that, on Linux, using QWebView currently still requires a runtime dependency on QWebEngine, as no native rendering plugin is
	available in Qt at the time of this writing.

Further generic options are listed on http://www.cmake.org/Wiki/CMake_Useful_Variables .


Installation
==================

As a last step, you _have to_ run 'make install'. Otherwise RKWard will be missing important menu-options, may behave strangely, or may not run at all.
As root run:
> make install

Make sure you have set the correct path in cmake (the -DCMAKE_INSTALL_PREFIX option).


Running
==================

For now it's recommended to run RKWard from the command-line for debug-output. For the few available command-line options see

> rkward --help

If an error occurs directly after starting, this will typically indicate a problem in your installation. In this case, please make sure, you have followed all above instructions diligently.


Automated tests
==================

A series of automated functionality tests can be run using 'build/bin/coretest', after compilation.

An additional set of tests can be run using 'make plugintests', but this second set of tests is quite prone to false alarms (e.g. due to different output with different versions of R). It is therefore mostly useful for monitoring patches for unintended side-effects.

If you see a genuine test failure, unrelated to your patches, please report this to rkward-devel AT kde DOT org, including details on your installed versions of KDE, R, and RKWard.
