Previous: , Up: How file names, directories and localnames are mangled and managed   [Contents][Index]

8.4 Adding new methods to TRAMP

There are two ways to add new methods to TRAMP: writing a new backend including an own file name handler, or adding the new method, using the existing tramp-sh-file-name-handler. The former shall happen inside the TRAMP repository, and it isn’t discussed here. The latter means usually a new ELPA package. see Using Non-Standard Methods for some examples.

8.4.1 Writing an own ELPA package

An external ELPA package foo-tramp.el, which intends to provide a new TRAMP method, say foo, must add this new method to the variable tramp-methods. This variable is an alist with elements (name param1 param2 …).

name is the method name, "foo" in this case. paramx is a pair of the form (key value). See the docstring of variable tramp-methods for possible keys and values. An example would be 

(add-to-list
 'tramp-methods
 `("foo"
   (tramp-login-program ,foo-tramp-executable)
   (tramp-login-args (("exec") ("%h") ("--") ("su - %u")))
   (tramp-remote-shell "/bin/sh")
   (tramp-remote-shell-args ("-i" "-c"))))

foo-tramp-executable in this example would be a Lisp constant, which is the program name of foo.

Another initialization could tell TRAMP which are the default user and host name for method foo. This is done by calling tramp-set-completion-function: 

(tramp-set-completion-function
 "foo"
 '((tramp-foo--completion-function arg)))

tramp-foo--completion-function is a function, which returns completion candidates. arg, a string, is the argument for the completion function, for example a file name to read from. see Selecting config files for user/host name completion for details.

Finally, it might also be helpful to define default user or host names for method foo, in case a remote file name leaves them empty. This can be performed by calling 

(add-to-list 'tramp-default-user-alist '("foo" nil "root"))
(add-to-list 'tramp-default-host-alist '("foo" nil "localhost"))

see Selecting a default user and Selecting a default host explaining the user options tramp-default-user-alist and tramp-default-host-alist.

8.4.2 Making a customized method optional

The settings of the previous subsection are global in the package foo-tramp.el, meaning they are activated when loading foo-tramp. Sometimes, it is desired to make these settings available without loading the whole package foo-tramp, but declaring the new method foo as optional method only. In this case, declare a function tramp-enable-foo-method which collects the initialization. This function must be auto loaded. 

;;;###autoload
(defun tramp-enable-foo-method ()
  (add-to-list 'tramp-methods '("foo" …))
  (tramp-set-completion-function "foo" …)
  (add-to-list 'tramp-default-user-alist '("foo" …))
  (add-to-list 'tramp-default-host-alist '("foo" …)))

Then, you can activate method foo by calling M-x tramp-enable-method RET foo RET. see Optional methods which must be enabled first.

8.4.3 Activating a customized method without loading the package

If you want to make method foo known after loading TRAMP, without loading the package foo-tramp.el, you must autoload the implementation of function tramp-enable-foo-method. Add the following code in foo-tramp.el: 

;;;###autoload
(progn
  (defun tramp-enable-foo-method ()
    (add-to-list 'tramp-methods '("foo" …))
    (tramp-set-completion-function "foo" …)
    (add-to-list 'tramp-default-user-alist '("foo" …))
    (add-to-list 'tramp-default-host-alist '("foo" …))))

;;;###autoload
(with-eval-after-load 'tramp (tramp-enable-method "foo"))

The trick is to wrap the function definition of tramp-enable-foo-method with progn for the ;;;###autoload cookie.

Previous: Integrating with external Lisp packages, Up: How file names, directories and localnames are mangled and managed   [Contents][Index]