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.
 
 
 
 

720 lines
17 KiB

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename Indium.info
@documentencoding UTF-8
@ifinfo
@*Generated by Sphinx 1.5.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 0.4.1, May 12, 2017
Nicolas Petton
Copyright @copyright{} 2017, 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::
Installation
* Using MELPA::
* Manual installation::
Getting up and running
* NodeJS::
* Chrome/Chromium::
* Using local files when debugging::
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 inspector
* Using the inspector::
@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::
@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 up-and-running}@anchor{8}@anchor{setup getting-up-and-running}@anchor{9}
@section Getting up and running
@menu
* NodeJS::
* Chrome/Chromium::
* Using local files when debugging::
@end menu
@node NodeJS,Chrome/Chromium,,Getting up and running
@anchor{setup id1}@anchor{a}@anchor{setup nodejs}@anchor{b}
@subsection NodeJS
Nodejs >= @code{7.0} is required for Indium to work.
Start a node process 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{c}@anchor{setup chrome}@anchor{d}
@subsection Chrome/Chromium
Chrome/Chromium >= @code{54.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,,Chrome/Chromium,Getting up and running
@anchor{setup local-files}@anchor{e}@anchor{setup using-local-files-when-debugging}@anchor{f}
@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 The REPL,Interaction in JS buffers,Getting up and running,Table of contents
@anchor{repl repl}@anchor{10}@anchor{repl doc}@anchor{11}@anchor{repl the-repl}@anchor{12}
@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{13}
@subsection Starting a REPL
A REPL (Read Eval Print Loop) buffer is automatically open when a new Indium
connection is made (see @ref{8,,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{14,,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{15}
@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{16}
@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{17}
@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{18}
@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 interaction-in-js-buffers}@anchor{19}@anchor{code-evaluation doc}@anchor{1a}@anchor{code-evaluation interaction}@anchor{1b}
@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{1c}
@subsection Evaluating and inspecting
To evaluate the JavaScript expression preceding the point, press @code{C-x C-e}.
To inspect the result of the evaluation of an expression, press @code{C-c M-i} (see
@ref{14,,The inspector}).
The entire buffer can be evaluated with @code{M-x indium-eval-buffer}.
@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{1d}
@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{10,,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{1e}
@subsection Adding and removing breakpoints
You need to first make sure that Indium is set up correctly to use local files
(see @ref{e,,Using local files when debugging}).
@itemize -
@item
@code{C-c b b}: Toggle a breakpoint
@item
@code{C-u C-c b b}: Toggle a breakpoint with condition
@item
@code{C-c b K}: Remove all breakpoints from the current buffer
@end itemize
Once a breakpoint is set, execution will stop when a breakpoint is hit, and the
Indium debugger pops up (see @ref{1f,,The stepping debugger}).
@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
@cartouche
@quotation Warning
When modifying JavaScript buffers, it is up to the user to update
the browser tab. Indium will attempt to update breakpoint locations
when saving a buffer, but the runtime script contents won't be
updated automatically. You can either refresh the page or evaluate
@code{indium-reload}.
@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{20}
@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
@cartouche
@quotation Warning
Stability issues have been reported when using this feature with
Chrome 57 and earlier. We strongly encourage you to use Chrome >=
58 when using live code updates.
@end quotation
@end cartouche
To enable live updates, make sure Indium is set up to use local files (see
@ref{e,,Using local files when debugging}).
@itemize -
@item
@code{C-c C-k}: Updates the runtime JavaScript source with the contents of the
current buffer.
@item
@code{(setq indium-update-script-on-save t)}: Automatically update the runtime
script JavaScript source after each buffer save.
@end itemize
@node The stepping debugger,The inspector,Interaction in JS buffers,Table of contents
@anchor{debugger the-stepping-debugger}@anchor{21}@anchor{debugger debugger}@anchor{1f}@anchor{debugger doc}@anchor{22}
@section The stepping debugger
@node The inspector,,The stepping debugger,Table of contents
@anchor{inspector the-inspector}@anchor{23}@anchor{inspector inspector}@anchor{14}@anchor{inspector doc}@anchor{24}
@section The inspector
Indium features an object inspector that can be open on any object reference
from a REPL buffer (see @ref{10,,The REPL}), the debugger (see @ref{1f,,The stepping debugger}), or
the result of any evaluation of JavaScript code (see @ref{1b,,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{25}
@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 Indices and tables,,Table of contents,Top
@anchor{index indices-and-tables}@anchor{26}
@chapter Indices and tables
@itemize *
@item
genindex
@item
modindex
@item
search
@end itemize
@c %**end of body
@bye