#+startup: showall
#+options: toc:nil

# Copyright (C) 2016-2025 Free Software Foundation, Inc.

* Emacs MATLAB-mode

[[https://mathworks.com][MathWorks]] MATLAB® and [[https://www.gnu.org/software/emacs/][GNU Emacs]] integration:

1. MATLAB mode, *matlab-ts-mode* or *matlab-mode*, for editing ~*.m~ files.

   - Edit MATLAB code with syntax highlighting and smart indentation.
   - Lint MATLAB code with fix-it's using the MATLAB Code Analyzer.

   The *matlab-ts-mode* is a more capable, performant, and accurate than *matlab-mode*.

2. *Code navigation and more*

   - The [[file:doc/matlab-language-server-lsp-mode.org][MATLAB Language Server with Emacs]], matlabls, provides code navigation, code completion, go
     to definition, find references, and more.

   - Imenu support for quickly jumping to function declarations in the current ~*.m~ or ~*.tlc~
     file.  See [[file:doc/matlab-imenu.org][doc/matlab-imenu.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.
   - matlab-shell uses company-mode for completions.

   See [[file:doc/matlab-shell-for-unix.org][doc/matlab-shell-for-unix.org]]

4. *M-x matlab-shell* to run remote Unix MATLAB within your local Emacs session.

   #+begin_example
     +----------------+                 +-----------------+
     | Local Computer |                 | Remote Computer |
     |                |<===============>|                 |
     |     Emacs      |      ssh        |      MATLAB     |
     +----------------+                 +-----------------+
   #+end_example

   You use Emacs on your local computer to edit files on the remote computer, run and debug remote
   MATLAB in a matlab-shell in your local Emacs.  See [[file:doc/remote-matlab-shell.org][doc/remote-matlab-shell.org]].

5. *M-x matlab-netshell* for running MATLAB code on Microsoft Windows within Emacs using an attached
   MATLAB.

   #+begin_example
    +--------------- Emacs ----------------+         +------------  MATLAB  ------------+
    |                                      |         |                                  |
    | (1) M-x matlab-netshell-server-start |         | (2) connect to Emacs             |
    |                                      |<=======>| >> addpath <matlab-mode>/toolbox |
    | (3) Visit script *.m files and use   |         | >> emacsinit                     |
    |     "MATLAB -> Code Sections" menu   |         | >>                               |
    |     or the key bindings              |         |                                  |
    +--------------------------------------+         +----------------------------------+
   #+end_example

6. *Code sections* support for MATLAB script files. See [[file:doc/matlab-code-sections.org][doc/matlab-code-sections.org]].

   - After visiting a MATLAB script, you have a *"MATLAB -> Code Sections"* menu and key bindings
     which lets you navigate, run, and move code sections.

   - Try out code sections using: [[file:examples/matlab-sections/tryout_matlabsection.m][./examples/matlab-sections/tryout_matlabsection.m]].

7. *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.

   - You author code plus natural language descriptive text in ~*.org~ files. When you evaluate
     MATLAB or other language code blocks within the ~*.org~ files, org inserts the results back
     into the ~*.org~ file.

   - You can combine multiple ~*.org~ files into one final document, thus enabling larger scientific
     documents.

   - 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]].

8. *tlc-mode* for editing ~*.tlc~ files. The Target Language Compiler (TLC) is part of Simulink®
   Coder™.

* Installation

1. Install the MATLAB package via [[https://melpa.org][MELPA]] or [[https://elpa.gnu.org/][ELPA]]. MELPA contains the latest version.  To install from
   MELPA, add to your =~/.emacs=

   #+begin_src emacs-lisp
     (require 'package)
     (add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/") t)
   #+end_src

   Restart Emacs and then

   : M-x package-install RET matlab-mode RET

   Note: to see all available packages, =M-x RET list-packages RET=

2. [Optional] Install the =company= package which is used for TAB completions.

   : M-x package-install RET company RET

3. [Optional] Install MATLAB tree-sitter for matlab-ts-mode, which provides improved editing
   capabilities and improved performance.

   After installing =matlab-mode=

   : M-x matlab-ts-grammar-install

   The MATLAB tree-sitter leverages [[https://tree-sitter.github.io/tree-sitter/][Tree-sitter]] to create a parse tree for MATLAB code.  The parse
   tree is updated incrementally and is robust to syntax errors. It is highly performant and
   achieves this by being implemented in C to create a shared object that is loaded into the Emacs
   process.  *matlab-ts-mode* leverages the MATLAB tree-sitter to give an improved MATLAB editing
   experience when compared with matlab-mode.

   See [[file:doc/install-matlab-tree-sitter-grammar.org][doc/install-matlab-tree-sitter-grammar.org]]

4. [Optional] Install lsp-mode and the [[file:doc/matlab-language-server-lsp-mode.org][MATLAB Language Server]] for an improved editing experience.

5. [Optional] Check your installation setup.

   If you are using *matlab-ts-mode*, visit a =*.m= MATLAB file and select the menu item:

   : MATLAB -> Check setup

** Install from this repository

If you are contributing to the Emacs MATLAB Mode package, see
[[file:contributing/install-emacs-matlab-from-git.org][contributing/install-emacs-matlab-from-git.org]]

* MathWorks Products ([[https://www.mathworks.com][https://www.mathworks.com]])

Emacs MATLAB-mode is designed to be compatible with the last six years of MathWorks products and may
support even older versions of MathWorks products.

* License

GPL3, https://www.gnu.org/licenses/gpl-3.0.en.html (see [[file:License.txt][License.txt]])

* Community Support

[[https://www.mathworks.com/matlabcentral][MATLAB Central]]

* FAQ

See [[file:doc/faq.org][doc/faq.org]]

* Mailing list

[[mailto:matlab-emacs-discuss@lists.sourceforge.net]]

https://sourceforge.net/projects/matlab-emacs/

* Releases

See [[file:NEWS.org][NEWS.org]]

# LocalWords:  showall nodesktop melpa emacsclient matlabsection lsp matlabls Imenu imenu netshell
# LocalWords:  emacsinit ELPA faq mailto sourceforge libtree dylib langs treesit abi MSys alist
