org: dir
14.8.2.5 ‘:dir’ and remote execution
....................................
While the ‘:file’ header argument can be used to specify the path to the
output file, ‘:dir’ specifies the default directory during code block
execution. If it is absent, then the directory associated with the
current buffer is used. In other words, supplying ‘:dir path’
temporarily has the same effect as changing the current directory with
‘M-x cd path RET’, and then not supplying ‘:dir’. Under the surface,
‘:dir’ simply sets the value of the Emacs variable ‘default-directory’.
When using ‘:dir’, you should supply a relative path for file output
(e.g., ‘:file myfile.jpg’ or ‘:file results/myfile.jpg’) in which case
that path will be interpreted relative to the default directory.
In other words, if you want your plot to go into a folder called
‘Work’ in your home directory, you could use
#+BEGIN_SRC R :file myplot.png :dir ~/Work
matplot(matrix(rnorm(100), 10), type="l")
#+END_SRC
Remote execution
................
A directory on a remote machine can be specified using tramp file
syntax, in which case the code will be evaluated on the remote machine.
An example is
#+BEGIN_SRC R :file plot.png :dir /dand@yakuba.princeton.edu:
plot(1:10, main=system("hostname", intern=TRUE))
#+END_SRC
Text results will be returned to the local Org mode buffer as usual,
and file output will be created on the remote machine with relative
paths interpreted relative to the remote directory. An Org mode link to
the remote file will be created.
So, in the above example a plot will be created on the remote
machine, and a link of the following form will be inserted in the org
buffer:
[[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
Most of this functionality follows immediately from the fact that
‘:dir’ sets the value of the Emacs variable ‘default-directory’, thanks
to tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need
to install tramp separately in order for these features to work
correctly.
Further points
..............
• If ‘:dir’ is used in conjunction with ‘:session’, although it will
determine the starting directory for a new session as expected, no
attempt is currently made to alter the directory associated with an
existing session.
• ‘:dir’ should typically not be used to create files during export
with ‘:exports results’ or ‘:exports both’. The reason is that, in
order to retain portability of exported material between machines,
during export links inserted into the buffer will _not_ be expanded
against ‘default directory’. Therefore, if ‘default-directory’ is
altered using ‘:dir’, it is probable that the file will be created
in a location to which the link does not point.