Compilation

This package uses R as a plugin to Gnumeric. To use it, you will need (no surprises)
Gnumeric, and
R
and you will need to have R in the form of a shared library, $R_HOME/bin/libR.so. To do this, reconfigure and recompile R using the commands 
 ./configure --enable-R-shlib any other arguments
 make

To install this package, you will also need the source code for gnumeric. I have used version 0.64 for the original implementation and, more recently, versions 1.0.1, 1.0.8 and 1.0.10. The plugin may work with earlier versions, but there is not guarantee. We would appreciate hearing of any problems and successes (omega-devel@omegahat.org). Gnumeric has its own dependencies which we will not describe here.

You need the source code for Gnumeric since a plugin needs access to header files that are not installed when Gnumeric is installed on your machine. Note that you must ensure that the Gnumeric source corresponds to the version that you run. Ideally, you should download the most recent version of Gnumeric and build and install it from source. Not only will you need the source of Gnumeric, but also its gnumeric-config.h file which is generated when you configure the source for building.

At this point, let's assume you have the Gnumeric source and a running Gnumeric. You will need to tell the configuration script for this R package where the directory containing the Gnumeric source is located. The directory of interest is the one containing the src/, plugins/ and po/ directories of the gnumeric source. If you download the Gnumeric source and simply un-tar it, the resulting top-level directory is the one we need.

There are two ways to specify this location. The first is by setting the environment variable GNUMERIC_DIR to the fully qualified name of the that directory. The second is to specify it as a command line argument to the configure script. This is done as the value of the --with-gnumeric argument of the configure script. Since configure is invoked via the R INSTALL command, passing an argument to it is slightly more complicated. This is done as 

 R CMD INSTALL --configure-args='gnumeric/directory/' RGnumeric

The compilation also requires access to the file named gnomesupport.h that is installed with the gnome libraries. The configuration script attempts to find this in a variety of different ways. As a last resort, it explicitly looks for it in the directory /usr/local/lib/gnome-libs/include/. If it is not found, the configuration will fail. In that case, you can specify the directory in which it is available using the environment variable EXTRA_INCLUDES.

Installation

At this point, the plugin library is ready to be used in Gnumeric. However, you must tell Gnumeric of its existence. To do this, you have to decide where to install the plugin library so that gnumeric will find it when it starts. You essentially have two choices: The default is to put it in your home directory, specifically in the directory .gnumeric/version-number/plugins/R. To install it in a different place, specify the target directory by setting the environment variable INSTALL_DIR.

The cleanup script will copy the file plugin.xml in this distribution to the installation directory where gnumeric looks for plugins. It will also create a symbolic link to the shared library in the installed R library

To perform this installation as part of the R installation, invoke R CMD INSTALL with the -c argument. 

  R CMD INSTALL -c RGnumeric_0.1-0.tar.gz
At this point, Gnumeric should be able to see the plugin.

Activating the Plugin

To activate the plugin, you need to start Gnumeric. Before doing this however, make certain that your LD_LIBRARY_PATH environment variable includes the directory in which libR.so is located. This is in $R_HOME/bin/ and you can find the value of R_HOME via the command 
 R RHOME

Now you are ready to run Gnumeric and activate the plugin. Start Gnumeric by issuing the command gnumeric. Then, click on the Tools menu and select Plug-ins.... This dialog window allows you to scroll through the list of available plugins, the top component showing the already active ones and the lower component showing the currently inactive ones. If the entry R Plugin is not in the Active plugins box, click on it in the Available inactive plugins box and then click the Activate plugin button to the right. If all goes well, the R Plugin entry should now be in the top component of the window indicating it is active. Check the terminal console for any error messages and look at the FAQ for how to deal with them. Please note that you will only need to do activate the plugin once.

Testing the Plugin

To test the plugin, you can open one of the files in the examples/ directory of this distribution. These are installed in the examples/ directory. You will need to set the environment variable R_GNUMERIC_PROFILE to ExampleProfile in the examples/ directory of the installed library. Please read QuickOverview.
Last modified: Fri Nov 15 09:38:39 UTC 2002