Next: Cleanup remote connections, Previous: Ad-hoc multi-hops, Up: Usage [Contents][Index]

### 5.4 Integration with other Emacs packages

TRAMP supports starting new running processes on the remote host for discovering remote file names. Emacs packages on the remote host need no specific modifications for TRAMP’s use.

This type of integration does not work with the `ftp` method, and does not support the pty association as specified in `start-file-process`.

`process-file` and `start-file-process` work on the remote host when the variable `default-directory` is remote:

    (let ((default-directory "/ssh:remote.host:"))
      (start-file-process "grep" (get-buffer-create "*grep*")
                          "/bin/sh" "-c" "grep -e tramp *"))

Remote processes do not apply to GVFS (see GVFS based methods) because the remote file system is mounted on the local host and TRAMP just accesses by changing the `default-directory`.

TRAMP starts a remote process when a command is executed in a remote file or directory buffer. As of now, these packages have been integrated to work with TRAMP: `compile.el` (commands like `compile` and `grep`) and `gud.el` (`gdb` or `perldb`).

For TRAMP to find the command on the remote, it must be accessible through the default search path as setup by TRAMP upon first connection. Alternatively, use an absolute path or extend `tramp-remote-path` (see Remote programs):

    (add-to-list 'tramp-remote-path "~/bin")
    (add-to-list 'tramp-remote-path "/appli/pub/bin")

Customize `tramp-remote-process-environment` to suit the remote program’s environment for the remote host. `tramp-remote-process-environment` is a list of strings structured similar to `process-environment`, where each element is a string of the form ‘`ENVVARNAME=VALUE`’.

To avoid any conflicts with local host variables set through local configuration files, such as `~/.profile`, use ‘`ENVVARNAME=`’ to unset them for the remote environment.

Use `add-to-list` to add entries:

    (add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java")

Modifying or deleting already existing values in the `tramp-remote-process-environment` list may not be feasible on restricted remote hosts. For example, some system administrators disallow changing `HISTORY` variable. To accommodate such restrictions when using TRAMP, fix the `tramp-remote-process-environment` by the following code in the local `.emacs` file:

    (let ((process-environment tramp-remote-process-environment))
      (setenv "HISTORY" nil)
      (setq tramp-remote-process-environment process-environment))

TRAMP does not use the defaults specified in `process-environment` for running `process-file` or `start-file-process` on remote hosts. When values from `process-environment` are needed for remote processes, then set them as follows:

    (let ((process-environment (cons "HGPLAIN=1" process-environment)))
      (process-file …))

This works only for environment variables not already set in the `process-environment`.

For integrating other Emacs packages so TRAMP can execute remotely, please file a bug report. See Bug Reports.

#### 5.4.1 Running remote programs that create local X11 windows

To allow a remote program to create an X11 window on the local host, set the `DISPLAY` environment variable for the remote host as follows in the local `.emacs` file:

    (add-to-list 'tramp-remote-process-environment
                 (format "DISPLAY=%s" (getenv "DISPLAY")))

`(getenv "DISPLAY")` should return a recognizable name for the local host that the remote host can redirect X11 window interactions. If querying for a recognizable name is not possible for whatever reason, then replace `(getenv "DISPLAY")` with a hard-coded, fixed name. Note that using `:0` for X11 display name here will not work as expected.

An alternate approach is specify `ForwardX11 yes` or `ForwardX11Trusted yes` in the file `~/.ssh/config` on the local host.

#### 5.4.2 Running `shell` on a remote host

Set `explicit-shell-file-name` to the appropriate shell name when using TRAMP between two hosts with different operating systems, such as ‘`windows-nt`’ and ‘`gnu/linux`’. This option ensures the correct name of the remote shell program.

Starting with Emacs 24, when `explicit-shell-file-name` is equal to `nil`, calling `shell` interactively will prompt for a shell name.

#### 5.4.3 Running `shell-command` on a remote host

`shell-command` executes commands synchronously or asynchronously on remote hosts and displays output in buffers on the local host. Example:

    C-x C-f /sudo:: RET
    M-! tail -f /var/log/syslog.log & RET

`tail` command outputs continuously to the local buffer, `*Async Shell Command*`

`M-x auto-revert-tail-mode` runs similarly showing continuous output.

#### 5.4.4 Running `eshell` on a remote host

TRAMP is integrated into `eshell.el`, which enables interactive eshell sessions on remote hosts at the command prompt. You must add the module `eshell-tramp` to `eshell-modules-list`. Here’s a sample interaction after opening `M-x eshell` on a remote host:

    ~ $ cd /sudo::/etc RET
    /sudo:root@host:/etc $ hostname RET
    host
    /sudo:root@host:/etc $ id RET
    uid=0(root) gid=0(root) groups=0(root)
    /sudo:root@host:/etc $ find-file shadow RET
    #<buffer shadow>
    /sudo:root@host:/etc $

`eshell` in Emacs 23.2 added custom `su` and `sudo` commands that set the default directory correctly for the `*eshell*` buffer. TRAMP silently updates `tramp-default-proxies-alist` with an entry for this directory (see Multi-hops):

    ~ $ cd /ssh:user@remotehost:/etc RET
    /ssh:user@remotehost:/etc $ find-file shadow RET
    File is not readable: /ssh:user@remotehost:/etc/shadow
    /ssh:user@remotehost:/etc $ sudo find-file shadow RET
    #<buffer shadow>

    /ssh:user@remotehost:/etc $ su - RET
    /su:root@remotehost:/root $ id RET
    uid=0(root) gid=0(root) groups=0(root)
    /su:root@remotehost:/root $

#### 5.4.5 Running a debugger on a remote host

`gud.el` provides a unified interface to symbolic debuggers TRAMP can run debug on remote hosts by calling `gdb` with a remote file name:

    M-x gdb RET
    Run gdb (like this): gdb --annotate=3 /ssh:host:~/myprog RET

Relative file names are based on the remote default directory. When `myprog.pl` exists in `/ssh:host:/home/user`, valid calls include:

    M-x perldb RET
    Run perldb (like this): perl -d myprog.pl RET

Just the local part of a remote file name, such as `perl -d /home/user/myprog.pl`, is not possible.

Arguments of the program to be debugged must be literal, can take relative or absolute paths, but not remote paths.

#### 5.4.6 Running remote processes on Windows hosts

`winexe` runs processes on a remote Windows host, and TRAMP can use it for `process-file` and `start-file-process`.

`tramp-smb-winexe-program` specifies the local `winexe` command. Powershell V2.0 on the remote host is required to run processes triggered from TRAMP.

`explicit-shell-file-name` and `explicit-*-args` have to be set properly so `M-x shell` can open a proper remote shell on a Windows host. To open `cmd`, set it as follows:

    (setq explicit-shell-file-name "cmd"
          explicit-cmd-args '("/q"))

To open `powershell` as a remote shell, use this:

    (setq explicit-shell-file-name "powershell"
          explicit-powershell-args '("-file" "-"))

Next: Cleanup remote connections, Previous: Ad-hoc multi-hops, Up: Usage [Contents][Index]