branch: externals/matlab-mode
commit e9ab4fb8b0fedc0e769f4c7e0d86bd26a08567f8
Author: John Ciolfi <john.ciolfi...@gmail.com>
Commit: John Ciolfi <john.ciolfi...@gmail.com>
Add doc/matlab-language-server-lsp-mode.org
https://github.com/mathworks/MATLAB-language-server, matlabls, is used for
code navigation, code
completion, go to definition, find + references, and more.
See https://github.com/mathworks/Emacs-MATLAB-Mode/issues/18
---
NEWS.org | 17 ++++---
README.org | 11 +++--
doc/matlab-language-server-lsp-mode.org | 78 +++++++++++++++++++++++++++++++++
3 files changed, 95 insertions(+), 11 deletions(-)
diff --git a/NEWS.org b/NEWS.org
index 1423199e42..bdc856a826 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -9,20 +9,23 @@
:ORDERED: t
:END:
-1. Improved Emacs tramp remote *M-x matlab-shell*. Commit
[[https://github.com/mathworks/Emacs-MATLAB-Mode/commit/64e1805d36a362111ac3518a4fd7428c60483079][64e1805]].
+1. *[[https://github.com/mathworks/MATLAB-language-server][MATLAB Language
Server]]*, matlabls, for code navigation, code completion, go to definition,
+ find references, and more. See
[[file:doc/matlab-language-server-lsp-mode.org][doc/matlab-language-server-lsp-mode.org]].
+
+2. Improved Emacs tramp remote *M-x matlab-shell*. Commit
[[https://github.com/mathworks/Emacs-MATLAB-Mode/commit/64e1805d36a362111ac3518a4fd7428c60483079][64e1805]].
Prior to this commit, matlab-shell running through Emacs tramp partially.
This commit enables
remote matlab-shell and enables remote debugging, hyperlinks, etc. See
[[https://github.com/mathworks/Emacs-MATLAB-Mode/blob/default/doc/remote-matlab-shell.org][remote-matlab-shell.org]]
documentation.
-2. Remove font-lock-constant-face from help comments. Commit
[[https://github.com/mathworks/Emacs-MATLAB-Mode/commit/1d935b364dd90449a9dfa9a8743e275359096289][1d935b3]].
+3. Remove font-lock-constant-face from help comments. Commit
[[https://github.com/mathworks/Emacs-MATLAB-Mode/commit/1d935b364dd90449a9dfa9a8743e275359096289][1d935b3]].
A general guideline for help comments is to capitalize functions such as
PLOT as references and
matlab-mode used to make these a font-lock-constant-face inside of
comments. However, often capital items are
not references and make comments look bad, so removed these. Likewise,
there were other uses of
font-lock-constant-face that look odd, so removed these.
-3. Revamped MATLAB code sections script support issues. Commit
[[https://github.com/mathworks/Emacs-MATLAB-Mode/commit/e75ebf5a88b02833d700bcf9ee4419c5888caf12][e75ebf5]].
+4. Revamped MATLAB code sections script support issues. Commit
[[https://github.com/mathworks/Emacs-MATLAB-Mode/commit/e75ebf5a88b02833d700bcf9ee4419c5888caf12][e75ebf5]].
- MATLAB code sections is now a minor mode, *matlab-sections-minor-mode*
which is automatically
enabled when in a MATLAB script. A MATLAB script contains one or more
MATLAB commands or
@@ -58,16 +61,16 @@
- Added tests,
[[https://github.com/mathworks/Emacs-MATLAB-Mode/issues/8][issue 8]].
-4. Enhanced *M-x matlab-shell* to search for MATLAB in standard installation
locations if it is not
+5. Enhanced *M-x matlab-shell* to search for MATLAB in standard installation
locations if it is not
on the path. If we are unable to find MATLAB, we now generate an error
explaining how to setup
your system to make matlab-shell work. Commit
[[https://github.com/mathworks/Emacs-MATLAB-Mode/commit/9773232626919a6319e3ac36bc7e0cdd99c46585][9773232]].
-5. Improved fill-paragraph to work when point is before a comment. Commit
[[https://github.com/mathworks/Emacs-MATLAB-Mode/commit/8686c85cf376f90549d3aaf8478ed381f22282aa][8686c85]].
+6. Improved fill-paragraph to work when point is before a comment. Commit
[[https://github.com/mathworks/Emacs-MATLAB-Mode/commit/8686c85cf376f90549d3aaf8478ed381f22282aa][8686c85]].
-6. Add TAB completion in matlab-shell for MATLAB R2025a. Commit
[[https://github.com/mathworks/Emacs-MATLAB-Mode/commit/e92fe818acd71c4bead7bdf837e791b5aa456d11][e92fe81]]
and several followup
+7. Add TAB completion in matlab-shell for MATLAB R2025a. Commit
[[https://github.com/mathworks/Emacs-MATLAB-Mode/commit/e92fe818acd71c4bead7bdf837e791b5aa456d11][e92fe81]]
and several followup
commits.
-7. Fixed Emacs 30 lisp compiler warnings. Commit
[[https://github.com/mathworks/Emacs-MATLAB-Mode/commit/89b585e6d935fd36176791caa66d4dad0405407b][89b585e]].
+8. Fixed Emacs 30 lisp compiler warnings. Commit
[[https://github.com/mathworks/Emacs-MATLAB-Mode/commit/89b585e6d935fd36176791caa66d4dad0405407b][89b585e]].
* Release 6.3
diff --git a/README.org b/README.org
index 4a800c7dc5..04df4414ad 100644
--- a/README.org
+++ b/README.org
@@ -12,7 +12,10 @@
- Edit MATLAB code with syntax highlighting and smart indentation.
- Lint MATLAB code with fix-it's using the MATLAB Code Analyzer.
-2. *M-x matlab-shell* for running and debugging MATLAB within Emacs
(Unix-only).
+2. *[[https://github.com/mathworks/MATLAB-language-server][MATLAB Language
Server]]*, matlabls, for code navigation, code completion, go to definition,
find
+ references, and more. See
[[file:doc/matlab-language-server-lsp-mode.org][doc/matlab-language-server-lsp-mode.org]].
+
+3. *M-x matlab-shell* for running and debugging MATLAB within Emacs
(Unix-only).
- MATLAB command window errors are hyper-linked and files open in Emacs
- Debugging support is available from the MATLAB menu.
@@ -20,7 +23,7 @@
- You can use Emacs TRAMP and =M-x matlab-shell= to run remote MATLAB
within your local Emacs
session, see
[[file:doc/remote-matlab-shell.org][doc/remote-matlab-shell.org]].
-3. *Code sections* support. MATLAB script code files often contain many
commands and lines of text.
+4. *Code sections* support. MATLAB script code files often contain many
commands and lines of text.
You typically focus your efforts on a single part of your code at a time,
working with the code
and related text in sections. You demarcate sections using /"%%
description"/ header comments.
@@ -33,7 +36,7 @@
super key bindings for code sections. After visiting a file.m, see menu
*"MATLAB -> Code
Sections -> Help"*.
-4. *Creation of scientific papers, theses, and documents* using MATLAB and
[[http://orgmode.org]].
+5. *Creation of scientific papers, theses, and documents* using MATLAB and
[[http://orgmode.org]].
- Org enables
[[https://en.wikipedia.org/wiki/Literate_programming][literate programming]]
which directly supports reproducible research by allowing
scientists and engineers to write code along with detailed explanations
in natural language.
@@ -48,7 +51,7 @@
- See
[[file:examples/matlab-and-org-mode][./examples/matlab-and-org-mode/]] to get
started. This directory contains a
[[file:examples/matlab-and-org-mode/matlab-and-org-mode.pdf][PDF]] generated
from
[[file:examples/matlab-and-org-mode/matlab-and-org-mode.org][./examples/matlab-and-org-mode/matlab-and-org-mode.org]].
-5. *tlc-mode* for editing ~*.tlc~ files. The Target Language Compiler (TLC) is
part of Simulink®
+6. *tlc-mode* for editing ~*.tlc~ files. The Target Language Compiler (TLC) is
part of Simulink®
Coder™.
* Installation
diff --git a/doc/matlab-language-server-lsp-mode.org
b/doc/matlab-language-server-lsp-mode.org
new file mode 100644
index 0000000000..d7e6559e0c
--- /dev/null
+++ b/doc/matlab-language-server-lsp-mode.org
@@ -0,0 +1,78 @@
+# File: doc/remote-matlab-shell.org
+
+#+startup: showall
+#+options: toc:nil
+
+# Copyright 2025 Free Software Foundation, Inc.
+
+The [[https://github.com/mathworks/MATLAB-language-server][MATLAB Language
Server]], matlabls, is used for code navigation, code completion,
+go to definition, find references, and more. To use matlabls,
+
+1. Install lsp-mode from MELPA
+
+ #+begin_src emacs-lisp
+ (require 'package)
+ (add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/";))
+ #+end_src
+
+ then
+
+ : M-x list-packages
+
+ and click on lsp-mode and install it.
+
+ You may also want to install =company= for completions.
+
+2. Download and install the MATLAB language server
+
+ Download the language server (clone or unzip):
+ - git clone https://github.com/mathworks/MATLAB-language-server.git
+ or
+ - Download zip from https://github.com/mathworks/MATLAB-language-server and
unzip.
+
+ In the downloaded directory,
+ #+begin_src bash
+ npm install
+ npm run compile
+ npm run package # optional JavaScript minimization
+
+ # Install by copying built items into an install directory, e.g.
/usr/local/apps/matlabls
+ cp -r ./out/ /usr/local/apps/matlabls/out/
+ cp -r ./matlab/ /usr/local/apps/matlabls/matlab/
+ #+end_src
+
+ In Emacs:
+
+ : M-: (require 'lsp-matlab)
+ : M-x customize-variable RET lsp-clients-matlab-server RET
+
+ and set to your install directory, e.g. =/usr/local/apps/matlabls=
+
+3. Tell lsp-mode where MATLAB is if MATLAB not on the PATH (~which matlab~
does not find MATLAB).
+
+ In Emacs:
+
+ : M-: (require 'lsp-matlab)
+ : M-x customize-variable RET lsp-clients-matlab-install-path RET
+
+ and set to your MATLAB installation e.g. =/usr/local/MATLAB/R2025a=
+
+4. Activate lsp-mode when you open *.m files.
+
+ Add to your ~/.emacs
+
+ #+begin_example
+ (add-hook 'matlab-mode-hook 'lsp)
+ #+end_example
+
+5. After loading a ~*.m~ file, the MATLAB language server will run MATLAB in
the "background" and
+ use that MATLAB for language server features such as
~xref-find-definitions~. It can take a
+ while for this background MATLAB to start. After it starts, the supported
language server
+ features will work. See
https://github.com/mathworks/MATLAB-language-server for features
+ supported.
+
+ Some lsp features:
+
+ : M-. Find the definition of the identifier at point
(xref-find-definitions)
+ : M-? Find references to the identifier at point (xref-find-references)
+ : M-, Go back to the previous position in xref history (xref-go-back)
