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))
  (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))))
    (when recipe
      (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)))))))