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.
 
 
 
 

392 lines
9.7 KiB

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename Jade.info
@documentencoding UTF-8
@ifinfo
@*Generated by Sphinx 1.5.5.@*
@end ifinfo
@settitle Jade Documentation
@defindex ge
@paragraphindent 0
@exampleindent 4
@finalout
@dircategory Emacs
@direntry
* Jade: (Jade.info). JavaScript development environment for Emacs.
@end direntry
@definfoenclose strong,`,'
@definfoenclose emph,`,'
@c %**end of header
@copying
@quotation
Jade 0.3.3, Apr 06, 2017
Nicolas Petton
Copyright @copyright{} 2017, Nicolas Petton
@end quotation
@end copying
@titlepage
@title Jade Documentation
@insertcopying
@end titlepage
@contents
@c %** start of user preamble
@c %** end of user preamble
@ifnottex
@node Top
@top Jade Documentation
@insertcopying
@end ifnottex
@c %**start of body
@anchor{index doc}@anchor{0}
@c Jade 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.
Jade is a JavaScript development environment for Emacs@footnote{http://gnu.org/software/emacs}.
Jade 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 jade-scratch});
@item
JavaScript evaluation in JS buffers with @code{jade-interaction-mode};
@item
a stepping Debugger, similar to @code{edebug}, or @code{cider}.
@end itemize
@menu
* Table of contents::
* Indices and tables::
@detailmenu
--- The Detailed Node Listing ---
Table of contents
* Installation::
* Getting up and running::
* Interaction in JS buffers::
Installation
* Using MELPA::
* Manual installation::
Getting up and running
* NodeJS::
* Chrome/Chromium::
* Using local files when debugging::
Interaction in JS buffers
* Evaluating and inspecting::
* Switching to the REPL buffer::
* Adding and removing breakpoints::
@end detailmenu
@end menu
@node Table of contents,Indices and tables,Top,Top
@anchor{index welcome-to-jade-s-documentation}@anchor{1}@anchor{index table-of-contents}@anchor{2}
@chapter Table of contents
@menu
* Installation::
* Getting up and running::
* Interaction in JS buffers::
@end menu
@node Installation,Getting up and running,,Table of contents
@anchor{installation installation}@anchor{3}@anchor{installation doc}@anchor{4}
@section Installation
Jade supports @code{Emacs 25.1+}, @code{Chrome 54.0+} (debugging protocol @code{v1.2})
and @code{NodeJS 7+}.
Jade 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 Jade with the following command:
@example
M-x package-install [RET] jade [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 'jade)
(package-install 'jade))
@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 Jade manually, make sure to install @code{websocket.el}.
Obtain the code of Jade from the repository@footnote{https://github.com/NicolasPetton/jade}.
Add the following to your Emacs configuration:
@example
;; load Jade from its source code
(add-to-list 'load-path "~/projects/jade")
(require 'jade)
@end example
@node Getting up and running,Interaction in JS buffers,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::
@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 Jade 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 jade-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 Jade 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}@anchor{c}@anchor{setup chrome-chromium}@anchor{d}
@subsection Chrome/Chromium
Chrome/Chromium >= @code{54.0} is required for Jade 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 jade-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
Jade 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, Jade 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 Jade where to find the corresponding JavaScript files on disk by
setting up a workspace.
To do that, place an empty @code{.jade} marker file in the root folder where your
@strong{web server serves static files}.
The @code{.jade} file should not always be placed in the directory that contains
your JavaScript files. It has to be in 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
.jade
@end example
Jade will lookup the file @code{www/js/app.js} for the URL
"@indicateurl{http://localhost:3000/js/app.js}".
@cartouche
@quotation Danger
In order for this setup to work, make sure to call
@code{jade-connect-to-chrome} from somewhere within the workspace
directory!
@end quotation
@end cartouche
@node Interaction in JS buffers,,Getting up and running,Table of contents
@anchor{code-evaluation doc}@anchor{10}@anchor{code-evaluation interaction-in-js-buffers}@anchor{11}
@section Interaction in JS buffers
Jade comes with a minor mode called @code{jade-interaction-mode} for interactive
programming. To enable it in all JavaScript buffers, add something
like the following to your Emacs configuration:
@example
(require 'jade)
(add-hook 'js-mode-hook #'jade-interaction-mode)
@end example
When @code{jade-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::
@end menu
@node Evaluating and inspecting,Switching to the REPL buffer,,Interaction in JS buffers
@anchor{code-evaluation evaluating-and-inspecting}@anchor{12}
@subsection Evaluating and inspecting
To evaluate the JavaScript expression preceding the point, press @code{C-x C-e}.
To inspect the result of an expression, press @code{C-x M-i}.
The entire buffer can be evaluating with @code{M-x jade-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{13}
@subsection Switching to the REPL buffer
Press @code{C-c C-z} from any buffer with @code{jade-interaction-mode} turned on to
switch back to the REPL buffer.
@node Adding and removing breakpoints,,Switching to the REPL buffer,Interaction in JS buffers
@anchor{code-evaluation adding-and-removing-breakpoints}@anchor{14}
@subsection Adding and removing breakpoints
You need to first make sure that Jade 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
@cartouche
@quotation Note
Breakpoints are persistent: if the connection is closed, when a new
connection is made Jade will attempt to add back all breakpoints.
@end quotation
@end cartouche
@node Indices and tables,,Table of contents,Top
@anchor{index indices-and-tables}@anchor{15}
@chapter Indices and tables
@itemize *
@item
genindex
@item
modindex
@item
search
@end itemize
@c %**end of body
@bye