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

RKWard requires:
- Several KF5-libraries and headers (>= 5.4) (https://www.kde.org)
- Qt-libraries and headers (>= 5.2) (http://www.trolltech.com)
- R and headers (https://www.r-project.org)
- 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.
-DNO_R_XML
	When packaging RKWard for binary distribution, it may be necessary to exclude the R syntax highlighting defintion "r.xml"
	from installation, as it may already be provided other packages. In this case, you can use: -DNO_R_XML=1
-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.
-DTRANSLATION_SRC_CIR
	If you have imported translation source files (.po-files) to a separate directory, you can specify this, here.

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 unsing 'make plugintests' *after* completing the installation. Unfortunately, these tests are rather prone to false alarms, and thus end users are not currently encouraged to run the tests. However, esp. developers, and packagers patching the sources should run 'make plugintests' after doing their changes. For failed tests, please take some time trying to understand, exactly how the test failed. Often it's just a harmless difference in rounding or formatting of output.

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.
