Function: treesit-install-language-grammar

treesit-install-language-grammar is an autoloaded, interactive and byte-compiled function defined in treesit.el.gz.

Signature

(treesit-install-language-grammar LANG &optional OUT-DIR)

Documentation

Build and install the tree-sitter language grammar library for LANG.

Interactively, if treesit-language-source-alist doesn't already have data for building the grammar for LANG, prompt for its repository URL and the C/C++ compiler to use. The recipe built by the prompts are saved for the current session if the installation is successful and the grammar is loadable.

This command requires Git, a C compiler and (sometimes) a C++ compiler, and the linker to be installed and on PATH. It also requires that the recipe for LANG exists in treesit-language-source-alist.

See exec-path(var)/exec-path(fun) for the current path where Emacs looks for executable programs, such as the C/C++ compiler and linker.

Interactively, prompt for the directory in which to install the compiled grammar files. Non-interactively, use OUT-DIR; if it's nil, the grammar is installed to the standard location, the
"tree-sitter" directory under user-emacs-directory.

Probably introduced at or before Emacs version 29.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/treesit.el.gz
;;;###autoload
(defun treesit-install-language-grammar (lang &optional out-dir)
  "Build and install the tree-sitter language grammar library for LANG.

Interactively, if `treesit-language-source-alist' doesn't already
have data for building the grammar for LANG, prompt for its
repository URL and the C/C++ compiler to use.  The recipe built
by the prompts are saved for the current session if the
installation is successful and the grammar is loadable.

This command requires Git, a C compiler and (sometimes) a C++ compiler,
and the linker to be installed and on PATH.  It also requires that the
recipe for LANG exists in `treesit-language-source-alist'.

See `exec-path' for the current path where Emacs looks for
executable programs, such as the C/C++ compiler and linker.

Interactively, prompt for the directory in which to install the
compiled grammar files.  Non-interactively, use OUT-DIR; if it's
nil, the grammar is installed to the standard location, the
\"tree-sitter\" directory under `user-emacs-directory'."
  (interactive (list (intern
                      (completing-read
                       "Language: "
                       (mapcar #'car treesit-language-source-alist)))
                     'interactive))
  (when-let ((recipe
              (or (assoc lang treesit-language-source-alist)
                  (if (eq out-dir 'interactive)
                      (treesit--install-language-grammar-build-recipe
                       lang)
                    (signal 'treesit-error `("Cannot find recipe for this language" ,lang)))))
             (default-out-dir
              (or (car treesit--install-language-grammar-out-dir-history)
                  (locate-user-emacs-file "tree-sitter")))
             (out-dir
              (if (eq out-dir 'interactive)
                  (read-string
                   (format "Install to (default: %s): "
                           default-out-dir)
                   nil
                   'treesit--install-language-grammar-out-dir-history
                   default-out-dir)
                ;; When called non-interactively, OUT-DIR should
                ;; default to DEFAULT-OUT-DIR.
                (or out-dir default-out-dir))))
    (condition-case err
        (progn
          (apply #'treesit--install-language-grammar-1
                 (cons out-dir recipe))

          ;; Check that the installed language grammar is loadable.
          (pcase-let ((`(,available . ,err)
                       (treesit-language-available-p lang t)))
            (if (not available)
                (display-warning
                 'treesit
                 (format "The installed language grammar for %s cannot be located or has problems (%s): %s"
                         lang (nth 0 err)
                         (string-join
                          (mapcar (lambda (x) (format "%s" x))
                                  (cdr err))
                          " ")))
              ;; If success, Save the recipe for the current session.
              (setf (alist-get lang treesit-language-source-alist)
                    (cdr recipe)))))
      (error
       (display-warning
        'treesit
        (format "Error encountered when installing language grammar: %s"
                err))))))