R CMD BATCH vs R CMD batch

Out of interest: What is the magic ~R CMD~ is doing? Is it documented
anywhere?

R is open source.... (and shell scripts are considered self-documenting by some)

On Unix-alikes, R is a shell script which, if called with 1st argument CMD, calls ${R_HOME}/bin/Rcmd, which is another shell script that ends with 

case "${1}" in
## this was a separate command prior to 2.10.0
  Rd2txt)
    cmd="${R_HOME}/bin/Rdconv"
    extra="-t txt"
    ;;
## removed in 2.15.0
  Rd2dvi)
    echo "R CMD Rd2dvi is defunct: use Rd2pdf instead"
    exit 1
    ;;
  *)
    if test -x "${R_HOME}/bin/${1}"; then
      cmd="${R_HOME}/bin/${1}"
    else
      cmd="${1}"
    fi
    ;;
esac
shift

exec "${cmd}" ${extra} "${@}"

I.e., except for setting up variables and such, R CMD ${foo} essentially looks for ${R_HOME}/bin/${foo} and executes it if it exists and is executable, otherwise it just executes ${foo}.

Notice that, somewhat contrary to what Dirk said, this logic works at the mercy of the file system when it comes to case sensitivity. On OSX with the default case-insensitive setup we get

Peters-iMac:IBP pd$ R CMD install
Error: ERROR: no packages specified

which comes from R's package installer, whereas a case-sensitive FS would pick up /usr/bin/install instead. That is just how the "test" shell built-in works: 

Peters-iMac:~ pd$ test -x `R RHOME`/bin/INSTALL ; echo $?
0
Peters-iMac:~ pd$ test -x `R RHOME`/bin/UNSTALL ; echo $?
1
Peters-iMac:~ pd$ test -x `R RHOME`/bin/install ; echo $?
0

Peter Dalgaard, Professor,
Center for Statistics, Copenhagen Business School
Solbjerg Plads 3, 2000 Frederiksberg, Denmark
Phone: (+45)38153501
Office: A 4.23
Email: pd.mes at cbs.dk  Priv: PDalgd at gmail.com