elinks/doc/ecmascript.txt

[[ecmascript]]
ECMAScript support?!
~~~~~~~~~~~~~~~~~~~~

Yes, there is some ECMAScript support in ELinks. There isn't anything we could
call complete, but some bits could help with the most common ECMAScript usage
cases - help you (and then us ;) get into your banking account, pass through
those ignorant page redirects done by JavaScript code snippets and so.

ELinks does not have own ECMAScript parser and compiler; instead it reuses
other people's work (this may eventually change, see the bottom of this file).
First we aimed at the NJS engine, which is easy to install, small and compact;
has nice naming scheme, horrible calling conventions and very lacking
documentation; is not actively developed; and generally looks broken and
extremely clumsy to work with. So we instead went the way of the SpiderMonkey
(SM) engine (property of Mozilla), which is hard to install, bigger (mind you,
it comes from Mozilla ;), has ugly naming scheme but nice calling conventions,
acceptable documentation, is actively developed and ought to work.


Ok, so how to get the ECMAScript support working?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

On Debian testing or unstable (SID), run the following:

	$ apt-get install libmozjs-115-dev

On Arch Linux, run the following:

	$ pacman -S js115

SpiderMonkey is disabled by default, enable it like this:

	$ meson build -Dspidermonkey=true

Check for the following line in the features summary:

	Run-time dependency mozjs-115 found: YES 115.15.0

Then run:

	$ cd build/
	$ ninja
	$ sudo ninja install

Enjoy.


The ECMAScript support is buggy! Shall I blame Mozilla people?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Likely not. The ECMAScript engine provides only the language compiler and some
basic built-in objects, and it's more than likely that the problem is on our
side in the implementation of some of the HTML/DOM objects (perhaps we just
haven't bothered to implement it at all yet). So better tell us first, and if
we think it's not our fault we will tell you to go complain to Mozilla (better
yet if it does not work in the Mozilla browsers neither ;-).


Now, I would still like NJS or a new JS engine from scratch...
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

\...and you don't fear some coding? That's fine then! ELinks is in no way tied
to SpiderMonkey, in fact the ECMAScript support was carefully implemented so
that there are no SpiderMonkey references outside of
`src/ecmascript/spidermonkey.*`. If you want to implement an alternative
ECMAScript backend, go ahead - you will just need to write an autoconf
detection for it and tie it to `src/ecmascript/ecmascript.c`, which should be
easy. We await your patches eagerly.