A JavaScript development environment for Emacs https://indium.readthedocs.io
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 

966 lines
24 KiB

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename Indium.info
@documentencoding UTF-8
@ifinfo
@*Generated by Sphinx 1.6.5.@*
@end ifinfo
@settitle Indium Documentation
@defindex ge
@paragraphindent 0
@exampleindent 4
@finalout
@dircategory Emacs
@direntry
* Indium: (Indium.info). JavaScript development environment for Emacs.
@end direntry
@definfoenclose strong,`,'
@definfoenclose emph,`,'
@c %**end of header
@copying
@quotation
Indium 1.1.0, Dec 01, 2017
Nicolas Petton
Copyright @copyright{} 2017-2018, Nicolas Petton
@end quotation
@end copying
@titlepage
@title Indium Documentation
@insertcopying
@end titlepage
@contents
@c %** start of user preamble
@c %** end of user preamble
@ifnottex
@node Top
@top Indium Documentation
@insertcopying
@end ifnottex
@c %**start of body
@anchor{index doc}@anchor{0}
@c Indium documentation master file, created by
@c sphinx-quickstart on Tue Apr 4 11:48:03 2017.
@c You can adapt this file completely to your liking, but it should at least
@c contain the root `toctree` directive.
Indium is a JavaScript development environment for Emacs@footnote{http://gnu.org/software/emacs}.
Indium is Free Software, licensed under the GPL v3.0. You can follow its
development on GitHub@footnote{https://github.com/NicolasPetton/indium}.
Indium connects to a browser tab or nodejs process and provides several features
for JavaScript development, including:
@itemize *
@item
a REPL (with auto completion) & object inspection;
@item
an inspector, with history and navigation;
@item
a scratch buffer (@code{M-x indium-scratch});
@item
JavaScript evaluation in JS buffers with @code{indium-interaction-mode};
@item
a stepping Debugger, similar to @code{edebug}, or @code{cider}.
@end itemize
This documentation can be read online at @indicateurl{https://indium.readthedocs.io}.
It is also available in Info format and can be consulted from within Emacs with
@code{C-h i m indium RET}.
@menu
* Table of contents::
* Indices and tables::
@detailmenu
--- The Detailed Node Listing ---
Table of contents
* Installation::
* Getting up and running::
* The REPL::
* Interaction in JS buffers::
* The stepping debugger::
* The inspector::
* Network::
* Listing parsed scripts::
Installation
* Using MELPA::
* Manual installation::
Getting up and running
* NodeJS::
* Chrome/Chromium::
* Using local files when debugging::
* Configuring Webpack for the debugger::
NodeJS
* Installing a recent version of NodeJS::
* Executing NodeJS from Emacs::
* Connecting to a Nodejs process::
The REPL
* Starting a REPL::
* Using the REPL::
* Code evaluation & context::
Using the REPL
* Keybindings::
* Reconnecting from the REPL buffer::
Interaction in JS buffers
* Evaluating and inspecting::
* Switching to the REPL buffer::
* Adding and removing breakpoints::
* Live code update (hot-swapping JavaScript sources): Live code update hot-swapping JavaScript sources.
The stepping debugger
* Using sourcemaps::
* Sourcemaps and Webpack::
The inspector
* Using the inspector::
Listing parsed scripts
* Using the listing buffer::
@end detailmenu
@end menu
@node Table of contents,Indices and tables,Top,Top
@anchor{index indium}@anchor{1}@anchor{index table-of-contents}@anchor{2}
@chapter Table of contents
@menu
* Installation::
* Getting up and running::
* The REPL::
* Interaction in JS buffers::
* The stepping debugger::
* The inspector::
* Network::
* Listing parsed scripts::
@end menu
@node Installation,Getting up and running,,Table of contents
@anchor{installation doc}@anchor{3}@anchor{installation installation}@anchor{4}
@section Installation
@cartouche
@quotation Note
If you already have installed @code{Jade}, you should read the
migration-from-jade page first.
@end quotation
@end cartouche
Indium supports @code{Emacs 25.1+}, @code{Chrome 54.0+} (debugging protocol @code{v1.2})
and @code{NodeJS 7+}.
Indium is availabe on MELPA@footnote{https://melpa.org}, MELPA Stable@footnote{https://stable.melpa/org}.
@menu
* Using MELPA::
* Manual installation::
@end menu
@node Using MELPA,Manual installation,,Installation
@anchor{installation using-melpa}@anchor{5}
@subsection Using MELPA
Unless you are already using MELPA, you will have to setup @code{package.el} to use
MELPA or MELPA Stable repositories. You can follow this documentation@footnote{https://melpa.org/#/getting-started}.
You can install Indium with the following command:
@example
M-x package-install [RET] indium [RET]
@end example
or by adding this bit of Emacs Lisp code to your Emacs initialization file
(@code{.emacs} or @code{init.el}):
@example
(unless (package-installed-p 'indium)
(package-install 'indium))
@end example
If the installation doesn’t work try refreshing the package list:
@example
M-x package-refresh-contents [RET]
@end example
@node Manual installation,,Using MELPA,Installation
@anchor{installation manual-installation}@anchor{6}
@subsection Manual installation
If you want to install Indium manually, make sure to install @code{websocket.el}.
Obtain the code of Indium from the repository@footnote{https://github.com/NicolasPetton/indium}.
Add the following to your Emacs configuration:
@example
;; load Indium from its source code
(add-to-list 'load-path "~/projects/indium")
(require 'indium)
@end example
@node Getting up and running,The REPL,Installation,Table of contents
@anchor{setup doc}@anchor{7}@anchor{setup getting-up-and-running}@anchor{8}@anchor{setup up-and-running}@anchor{9}
@section Getting up and running
@menu
* NodeJS::
* Chrome/Chromium::
* Using local files when debugging::
* Configuring Webpack for the debugger::
@end menu
@node NodeJS,Chrome/Chromium,,Getting up and running
@anchor{setup nodejs}@anchor{a}@anchor{setup id1}@anchor{b}
@subsection NodeJS
Nodejs >= @code{8.x} is required for Indium to work.
@menu
* Installing a recent version of NodeJS::
* Executing NodeJS from Emacs::
* Connecting to a Nodejs process::
@end menu
@node Installing a recent version of NodeJS,Executing NodeJS from Emacs,,NodeJS
@anchor{setup installing-a-recent-version-of-nodejs}@anchor{c}
@subsubsection Installing a recent version of NodeJS
If your distribution ships an old version of NodeJS, you can install a more
recent version using nvm@footnote{https://github.com/creationix/nvm}:
@example
$ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.2/install.sh | bash
@end example
Once @code{nvm} is install, you can easily install and use the version of NodeJS
you want:
@example
$ nvm install v8
$ nvm alias default v8
$ node --version
@end example
If you install NodeJS using @code{nvm}, chances are that Emacs won’t have it in its
@code{exec path}. A simple solution is to use the excellent exec-path-from-shell@footnote{https://github.com/purcell/exec-path-from-shell} package.
@node Executing NodeJS from Emacs,Connecting to a Nodejs process,Installing a recent version of NodeJS,NodeJS
@anchor{setup executing-nodejs-from-emacs}@anchor{d}
@subsubsection Executing NodeJS from Emacs
Indium can start NodeJS processes and connect to them automatically.
This is the preferred way of using Indium with NodeJS.
Start a process with @code{M-x indium-run-node}. Once the process is ready, Indium
will connect to it and open a REPL buffer.
The output from the NodeJS process is appended to the @code{*nodejs process*} buffer.
When a nodejs process has been started with @code{indium-run-node}, it can be
restarted with @code{indium-restart-node}.
@cartouche
@quotation Note
Indium will append the @code{--inspect} flag to the command-line
arguments automatically, so you do not need to provide them.
@end quotation
@end cartouche
If you wish to break the execution at the first statement, set
@code{indium-nodejs-inspect-break} to @code{t}.
@node Connecting to a Nodejs process,,Executing NodeJS from Emacs,NodeJS
@anchor{setup connecting-to-a-nodejs-process}@anchor{e}
@subsubsection Connecting to a Nodejs process
To connect to an existing NodeJS process, make sure that process was started
with the @code{--inspect} flag:
@example
node --inspect myfile.js
@end example
If you wish to break on the first line of the application code, start node using:
@example
node --inspect --debug-brk myfile.js
@end example
Node will tell you to open an URL in Chrome:
@example
chrome-devtools://inspector.html?...&ws=127.0.0.1:PORT/PATH
@end example
Evaluate @code{M-x indium-connect-to-nodejs RET 127.0.0.1 RET PORT RET PATH},
@code{PORT} and @code{PATH} are the ones from the @cite{ws} parameter of the above URL.
Connecting Indium to the node process will open a debugger on the first line of
the application code if you passed the CLI argument @code{--debug-brk}.
@node Chrome/Chromium,Using local files when debugging,NodeJS,Getting up and running
@anchor{setup chrome-chromium}@anchor{f}@anchor{setup chrome}@anchor{10}
@subsection Chrome/Chromium
Chrome/Chromium >= @code{60.0} is required for Indium to properly work (debugging
protocol @code{v1.2}).
Start Chrome/Chromium with the @code{--remote-debugging-port} flag like the following:
@example
chromium --remote-debugging-port=9222 https://localhost:3000
@end example
Make sure that no instance of Chrome is already running, otherwise Chrome will
simply open a new tab on the existing Chrome instance, and the
@code{remote-debugging-port} will not be set.
To connect to a tab, run from Emacs:
@example
M-x indium-connect-to-chrome
@end example
@node Using local files when debugging,Configuring Webpack for the debugger,Chrome/Chromium,Getting up and running
@anchor{setup using-local-files-when-debugging}@anchor{11}@anchor{setup local-files}@anchor{12}
@subsection Using local files when debugging
Indium can use local files when debugging, or to set breakpoints.
@cartouche
@quotation Hint
When using @code{NodeJS}, or when the connected tab uses the @code{file://}
URL, Indium will by itself use local files from disk. In this case
there is nothing to setup.
@end quotation
@end cartouche
If the Chrome connection uses the @code{http://} or @code{https://} protocol, you will
have to tell Indium where to find the corresponding JavaScript files on disk by
setting up a workspace.
To do that, place an empty @code{.indium} marker file in the root folder where your
@strong{web server serves static files}.
The root folder where the @code{.indium} file should be put is not always the
directory that contains your JavaScript files. It should be the root folder
containing static files. Most of the time, it is at least one level above.
Given the following project structure:
@example
project/ (current directory)
www/
index.html
css/
style.css
js/
app.js
.indium
@end example
Indium will lookup the file @code{www/js/app.js} for the URL
“@indicateurl{http://localhost:3000/js/app.js}”.
@cartouche
@quotation Warning
In order for this setup to work, make sure to call
@code{indium-connect-to-chrome} from somewhere within the workspace
directory!
@end quotation
@end cartouche
@node Configuring Webpack for the debugger,,Using local files when debugging,Getting up and running
@anchor{setup configuring-webpack-for-the-debugger}@anchor{13}
@subsection Configuring Webpack for the debugger
When Webpack is used to bundle JavaScript files, it is currently required to
configure it to emit absolute file paths for sourcemaps, see @ref{14,,Sourcemaps and Webpack}.
@node The REPL,Interaction in JS buffers,Getting up and running,Table of contents
@anchor{repl doc}@anchor{15}@anchor{repl repl}@anchor{16}@anchor{repl the-repl}@anchor{17}
@section The REPL
@menu
* Starting a REPL::
* Using the REPL::
* Code evaluation & context::
@end menu
@node Starting a REPL,Using the REPL,,The REPL
@anchor{repl starting-a-repl}@anchor{18}
@subsection Starting a REPL
A REPL (Read Eval Print Loop) buffer is automatically open when a new Indium
connection is made (see @ref{9,,Getting up and running}).
@image{repl,,,,png}
The REPL offers the following features:
@itemize *
@item
Auto completion with @code{company-mode}
@item
JS syntax highlighting
@item
Pretty printing and preview of printed values
@item
Access to the object inspector (see @ref{19,,The inspector})
@end itemize
@image{repl2,,,,png}
@node Using the REPL,Code evaluation & context,Starting a REPL,The REPL
@anchor{repl using-the-repl}@anchor{1a}
@subsection Using the REPL
@menu
* Keybindings::
* Reconnecting from the REPL buffer::
@end menu
@node Keybindings,Reconnecting from the REPL buffer,,Using the REPL
@anchor{repl keybindings}@anchor{1b}
@subsubsection Keybindings
Here is the list of available keybindings in a REPL buffer:
@multitable {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@headitem
Keybinding
@tab
Description
@item
@code{RET}
@tab
Evalute the current input. When the point is on a printed object, inspect the object.
@item
@code{C-RET}
@tab
Insert a newline.
@item
@code{C-c M-i}
@tab
Evalute the current input and open an inspector on the result.
@item
@code{C-c C-o}
@tab
Clear the output.
@item
@code{C-c C-q}
@tab
Kill the REPL buffer and close the current connection.
@item
@code{M-n}
@tab
Insert the previous input in the history.
@item
@code{M-p}
@tab
Instert the next input in the history.
@end multitable
@node Reconnecting from the REPL buffer,,Keybindings,Using the REPL
@anchor{repl reconnecting-from-the-repl-buffer}@anchor{1c}
@subsubsection Reconnecting from the REPL buffer
When a connection is closed (most probably because other devtools were open on
the same runtime), the REPL will display two buttons, one to try to reopen the
connection, and another one to kill Emacs buffers using this connection (the
REPL buffer, inspectors & debuggers).
@node Code evaluation & context,,Using the REPL,The REPL
@anchor{repl code-evaluation-context}@anchor{1d}
@subsection Code evaluation & context
When evaluating code in the REPL, Indium will always run the code on the current
execution context.
This means that while debugging, code execution will happen in the context of
the current stack frame, and will be able to access local variables from the
stack, etc.
@node Interaction in JS buffers,The stepping debugger,The REPL,Table of contents
@anchor{code-evaluation doc}@anchor{1e}@anchor{code-evaluation interaction-in-js-buffers}@anchor{1f}@anchor{code-evaluation interaction}@anchor{20}
@section Interaction in JS buffers
Indium comes with a minor mode called @code{indium-interaction-mode} for interactive
programming. To enable it in all JavaScript buffers, add something
like the following to your Emacs configuration:
@example
(require 'indium)
(add-hook 'js-mode-hook #'indium-interaction-mode)
@end example
When @code{indium-interaction-mode} is on, you can evaluate code, inspect objects and
add or remove breakpoints from your buffers.
@menu
* Evaluating and inspecting::
* Switching to the REPL buffer::
* Adding and removing breakpoints::
* Live code update (hot-swapping JavaScript sources): Live code update hot-swapping JavaScript sources.
@end menu
@node Evaluating and inspecting,Switching to the REPL buffer,,Interaction in JS buffers
@anchor{code-evaluation evaluating-and-inspecting}@anchor{21}
@subsection Evaluating and inspecting
Here’s a list of available keybindings:
@itemize -
@item
@code{C-x C-e}: Evaluate the JavaScript expression preceding the point.
@item
@code{C-M-x}: Evaluate the innermost function enclosing the point.
@item
@code{C-c M-i}: Inspect the result of the evaluation of an expression (see
@ref{19,,The inspector}).
@item
@code{C-c M-:}: Prompt for an expression to evaluate and inspect.
@item
@code{M-x indium-eval-buffer}: Evaluate the entire buffer.
@item
@code{M-x indium-eval-region}: Evaluate the current region.
@end itemize
@node Switching to the REPL buffer,Adding and removing breakpoints,Evaluating and inspecting,Interaction in JS buffers
@anchor{code-evaluation switching-to-the-repl-buffer}@anchor{22}
@subsection Switching to the REPL buffer
Press @code{C-c C-z} from any buffer with @code{indium-interaction-mode} turned on to
switch back to the REPL buffer (see @ref{16,,The REPL}).
@node Adding and removing breakpoints,Live code update hot-swapping JavaScript sources,Switching to the REPL buffer,Interaction in JS buffers
@anchor{code-evaluation adding-and-removing-breakpoints}@anchor{23}
@subsection Adding and removing breakpoints
You need to first make sure that Indium is set up correctly to use local files
(see @ref{12,,Using local files when debugging}).
@itemize -
@item
@code{C-c b b}: Add a breakpoint
@item
@code{C-c b c}: Add a conditional breakpoint
@item
@code{C-c b k}: Remove a breakpoint
@item
@code{C-c b K}: Remove all breakpoints from the current buffer
@item
@code{C-c b e}: Edit condition of a breakpoint
@item
@code{C-c b l}: List all breakpoints and easily jump to any breakpoint
@item
@code{C-c b d}: Deactivate all breakpoints (the runtime won’t pause when hitting a breakpoint)
@item
@code{C-c b a}: Activate all breakpoints (it has no effect if breakpoints have not been deactivated)
@end itemize
Once a breakpoint is set, execution will stop when a breakpoint is hit, and the
Indium debugger pops up (see @ref{24,,The stepping debugger}).
Since Indium 0.7, breakpoints are supported in source files with an associated sourcemap, see @ref{25,,Using sourcemaps}.
@cartouche
@quotation Note
Breakpoints are persistent: if the connection is closed, when a new
connection is made Indium will attempt to add back all breakpoints.
@end quotation
@end cartouche
@node Live code update hot-swapping JavaScript sources,,Adding and removing breakpoints,Interaction in JS buffers
@anchor{code-evaluation live-code-update-hot-swapping-javascript-sources}@anchor{26}
@subsection Live code update (hot-swapping JavaScript sources)
Indium supports live code updates without the need to reload the browser tab or
restart the nodejs process.
This feature works with by hot-swapping the script source, and works even with
lexical closures.
@cartouche
@quotation Note
This feature currently in only available for Chrome & Chromium.
@end quotation
@end cartouche
To enable live updates, make sure Indium is set up to use local files (see
@ref{12,,Using local files when debugging}).
@itemize -
@item
@code{C-c C-k}: Updates the runtime JavaScript source with the contents of the
current buffer (this is also done automatically when a buffer is saved).
@end itemize
You can setup a hook to be run after each script update. For example
@example
(add-hook 'indium-update-script-source-hook
(lambda (url)
(indium-eval (format "window.dispatchEvent(new CustomEvent('patch', @{detail: @{url: '%s'@}@}))"
url))))
@end example
Then you can use it in your app for development purposes
@example
window.addEventListener("patch", (event) => @{
console.log("Patched @@ " + new Date().toTimeString().substring(0, 8), event.detail.url);
// rerender, etc
@});
@end example
@node The stepping debugger,The inspector,Interaction in JS buffers,Table of contents
@anchor{debugger doc}@anchor{27}@anchor{debugger debugger}@anchor{24}@anchor{debugger the-stepping-debugger}@anchor{28}
@section The stepping debugger
@menu
* Using sourcemaps::
* Sourcemaps and Webpack::
@end menu
@node Using sourcemaps,Sourcemaps and Webpack,,The stepping debugger
@anchor{debugger sourcemaps}@anchor{25}@anchor{debugger using-sourcemaps}@anchor{29}
@subsection Using sourcemaps
Since version 0.7, Indium uses sourcemap files by default.
For sourcemaps to work properly with Chrome/Chromium, make sure that a
workspace is correctly set (see @ref{12,,Using local files when debugging}).
If you wish to disable sourcemaps when debugging, set @code{indium-script-enable-sourcemaps} to @code{nil}.
@node Sourcemaps and Webpack,,Using sourcemaps,The stepping debugger
@anchor{debugger webpack}@anchor{14}@anchor{debugger sourcemaps-and-webpack}@anchor{2a}
@subsection Sourcemaps and Webpack
When using Webpack to bundle JavaScript files, Indium will only be able to use
sourcemaps if Webpack is configured to emit absolute file paths.
Here is an example configuration snippet to be inserted in @cite{webpack.config.json}
@example
...
output : @{
...
devtoolModuleFilenameTemplate: '[absolute-resource-path]',
devtoolFallbackModuleFilenameTemplate: '[absolute-resource-path]?[hash]'
@}
@end example
@node The inspector,Network,The stepping debugger,Table of contents
@anchor{inspector doc}@anchor{2b}@anchor{inspector the-inspector}@anchor{2c}@anchor{inspector inspector}@anchor{19}
@section The inspector
Indium features an object inspector that can be open on any object reference
from a REPL buffer (see @ref{16,,The REPL}), the debugger (see @ref{24,,The stepping debugger}), or
the result of any evaluation of JavaScript code (see @ref{20,,Interaction in JS buffers}).
To inspect the result of the evaluation of an expression, press @code{C-c M-i}. An
inspector buffer will pop up. You can also press @code{RET} or left click on
object links from the REPL buffer.
@image{inspector,,,,png}
@menu
* Using the inspector::
@end menu
@node Using the inspector,,,The inspector
@anchor{inspector using-the-inspector}@anchor{2d}
@subsection Using the inspector
Here is a list of available keybindings in an inspector buffer:
@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@headitem
Keybinding
@tab
Description
@item
@code{RET}
@tab
Follow a link to inspect the object at point
@item
@code{l}
@tab
Pop to the previous inspected object
@item
@code{g}
@tab
Update the inspector buffer
@item
@code{n} or @code{TAB}
@tab
Jump to the next object in the inspector
@item
@code{p} or @code{s-TAB}
@tab
Jump to the previous object in the inspector
@end multitable
@node Network,Listing parsed scripts,The inspector,Table of contents
@anchor{network doc}@anchor{2e}@anchor{network id1}@anchor{2f}@anchor{network network}@anchor{30}
@section Network
You can disable or enable network cache using the following commands:
@example
M-x indium-v8-disable-cache
M-x indium-v8-enable-cache
@end example
Both commands save your choice which will be used for future Indium connections for the current Emacs session.
You can make the cache setting permament by setting @cite{indium-v8-cache-disabled}:
@example
(setq indium-v8-cache-disabled t)
@end example
@node Listing parsed scripts,,Network,Table of contents
@anchor{listing-scripts doc}@anchor{31}@anchor{listing-scripts listing-parsed-scripts}@anchor{32}@anchor{listing-scripts listing-scripts}@anchor{33}
@section Listing parsed scripts
Indium includes the command @code{indium-list-scripts} to list all JavaScript
scripts parsed by the runtime. When using a workspace, local file can be
visited from entries in the list (see @ref{12,,Using local files when debugging}).
@menu
* Using the listing buffer::
@end menu
@node Using the listing buffer,,,Listing parsed scripts
@anchor{listing-scripts using-the-listing-buffer}@anchor{34}
@subsection Using the listing buffer
Here is a list of available keybindings in an script listing buffer:
@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@headitem
Keybinding
@tab
Description
@item
@code{RET}
@tab
Follow a link open the local file associated with the script
@item
@code{g}
@tab
Update the listing buffer
@item
@code{n} or @code{TAB}
@tab
Jump to the next script
@item
@code{p} or @code{s-TAB}
@tab
Jump to the previous script
@end multitable
@node Indices and tables,,Table of contents,Top
@anchor{index indices-and-tables}@anchor{35}
@chapter Indices and tables
@itemize *
@item
genindex
@item
modindex
@item
search
@end itemize
@c %**end of body
@bye