littler - Provides hash-bang (#!) capability for GNU R
Copyright (C) 2006 - 2009 Jeffrey Horner and Dirk Eddelbuettel
littler is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version
... [More]
2 of the License, or (at your option) any later version.
I InstallationLinux and OS X builds are supported. Please see the file INSTALL for installation tips.
II Implementationlittler, a C-language program named 'r', is an alternative front end to GNU R for '#!' (hashbang) scripting (see "Embedding R under Unix-alikes" in the "Writing R Extensions" manual from either http://www.r-project.org/, or your R installations / sources). With it's simpler command-line argument set geared toward scripting, littler allows users to create R scripts and popular "one-liners" using the command-line flag --eval. To do this, littler hard-codes certain bits of R's installation and environment using the first R program found in the user's path. For instance, if you installed R in both /usr/bin and /usr/local/bin, and your PATH variable references /usr/bin first, then littler will configure itself with /usr/bin/R.
II.1 R_HOME The R_HOME environment variable is written to the header file littler.h so that it can be hard-coded into the r binary. Note that it overrides the user's own R_HOME environment variable when r is executed.
II.2 R_DEFAULT_PACKAGES To decrease r's startup time, it sets the environment variable R_DEFAULT_PACKAGES to NULL and then autoloads all of the default package methods. This is done by inspecting the R user option 'defaultPackages' and emitting C code to be statically compiled into r. See autoloads.R for more info.
II.3 LD_LIBRARY_PATHTo eliminate the dependency on the LD_LIBRARY_PATH environment variable, at least on linux, r looks to the file R_HOME/etc/ldpaths to set the -rpath linker option (see ldpaths.R for more info). Unfortunately this linker flag is not supported on Mac OS X, so r still depends on DYLD_LIBRARY_PATH.
One caveat of working directly with LD_LIBRARY_PATH is that if one ever alters or updates R_HOME/etc/ldpaths (e.g. by running 'R CMD javareconf'), this will not be reflected in r. Thus, a re-compilation of r is necessary.
II.4 Last but not leastUpon exit no cleanup is done and .Last() is not run. This behavior is more suitable for a scripting environment as opposed to an interactive one.
III. (In-) Frequently asked questionsIII.1 Why the name 'littler' ?We wanted something short, sweet and with sufficient reference to R without trampling over R. The 'little' part implies two things: 1) that the program name is the lower case 'r', and 2) that 'r' provides something less than GNU R, mainly the language interpreter without the R environment. 'littler' is meant to run in an automated, i.e scripted, fashion with little interaction from the user.
We also like 'r' in /usr/local/bin/r, /usr/bin/r or on the command-line as it saves keystrokes, and does not harm the Shift key as much.
Lastly, you will find a little r in both Jeffrey and Dirk :-)
III.2. Wasn't there once a 'rinterp' as well ?There was, but we think littler is cuter. See the previous question.
III.3 I run a script through 'littler' but nothing shows. What's up?Add the --verbose flag (or its -p short version). This will print out many relevant expressions, similar to GNU R. However, it won't print the value of expressions like for loops, if/else, or expressions within function calls. In that case you probably need to wrap a print() or cat() around what you want to show.
III.4 Data sets are lost!Actually, they aren't. But because 'littler' optimises the startup, they are never loaded. Just add
library(datasets)to your script.
We have changed this behaviour in release 0.1.0, and datasets are now loaded on startup.
III.5 It doesn't build and complains about 'R_SignalHandlers undeclared'You need to upgrade to R 2.3.1 or newer.
Our configure ought to check for a minimal R versions and currently does not.
III.6 The r binary name clashes with my R binary.Use the configure flag --program-prefix or --program-suffix to transform the binary name. For instance, if you would like the binary name to be 'rsp' run configure like this:
./configure --program-suffix=spand if you'd rather have a prefix to the binary, run:
./configure --program-prefix=littlewhich will name the binary 'littler'. The binary, as well as the manual page, are renamed when 'make install' is run. Should you need it, 'make uninstall' will also remember this setting.
III.7 Typing r repeats the last command.You must be a zsh user -- 'r' is a builtin command, so to prefer to littler, you will have to either use an explicit path (/usr/bin/r), create an alias under a different name, and install littler using a suffix or prefix as describe in III.6.
III.8 What about Rscript?Good question. Starting with release 2.5.0, R itself will now contain something remarkably similar to littler: Rscript, an alternative front end to R for use in '#!' scripts. Time will tell which features differentiate the two, and which interface proves more useful to the R community. For now, we are simply thrilled to see functionality that we and others deemed important -- yet was missing from R itself -- added to the core R distribution. As they say, 'Imitation is the sincerest form of flattery'. Still, it would have been nice if Rscript had given credit to littler.
Here's a look at the most visibly distinguishing feature of each front end: how arguments are passed to a script. Below are two 'hello world' scripts that print out their arguments, one implemented in Rscript and the other littler:
Rscript
#! /path/to/Rscript
args littler
#! /path/to/r
cat('hello world! ', argv,"\n")Rscript passes all script arguments to R as additional elements to the vector returned from commandArgs(). Thus, the script must use the negative indexing method above to get the script argument into it's own variable.
littler provides convenience by assigning the script arguments to an "argv" vector and placing that into the global environemt, a convention followed by other popular scripting languages.
littler also tends to start faster as it doesn't need to exec() the main R process due to its embedding of R.
III.9 What about getopt-style command-line parsing?Great question! This was asked for a few times. Luckily, Allen Day came forward and wrote getopt (now on CRAN), initially for Rscript. Moreover, he also agreed to add a two-line patch for seamless littler support.
See the getopt examples and documentation at
http://cran.r-project.org/web/packages/getopt/index.html
for usage -- it is really straightforward.
III.10 What about temporary files and directories?If nothing else is specified, r defaults to /tmp after having checked the environment variables TMPDIR, TMP and TEMP. Since version 0.1.2, you can also provide the --rtemp option (or its short form -t) to let r behave like R with a unique per-session directory that gets removed at exit:
$ r -tpe 'tempdir()'
[1] "/tmp/RtmpSbNQBj"
$ ls /tmp/RtmpSbNQBj
ls: cannot access /tmp/RtmpSbNQBj: No such file or directory
$showing that the temporary directory is created and provided while r is running, but removed after r has finished.
III.11 What about 'shebang' starts and command-line options?The usual operating systems can parse the so-called 'shebang' line, ie the first line of scripts that starts with the '#!' characters and the path to the executable --- and as much as one argument. That means we can provide short option arguments together in one string as in
#!/usr/bin/r -ptwhich enables 'verbose printing' and 'R-alike per-session temp. directories'.
What are typically not supported are multiple tokens (as used for an option and its argument, or multiple options). This also means that in the
#!/usr/bin/env r`case we cannot supply further arguments to r.
IV FeedbackJeffrey Horner
Dirk Eddelbuettel [Less]
Copyright
©
2013
Black Duck Software, Inc.
and its contributors, Some Rights Reserved. Unless otherwise marked, this work is licensed under a
Creative Commons Attribution 3.0 Unported License
. Ohloh
®
and the Ohloh logo are trademarks of
Black Duck Software, Inc.
in the United States and/or other jurisdictions. All other trademarks are the property of their respective holders.