doc/ecmascript.txt

   1 [[ecmascript]]
   2 ECMAScript support?!
   3 ~~~~~~~~~~~~~~~~~~~~
   4
   5 Yes, there is some ECMAScript support in ELinks. There isn't anything we could
   6 call complete, but some bits could help with the most common ECMAScript usage
   7 cases - help you (and then us ;) get into your banking account, pass through
   8 those ignorant page redirects done by JavaScript code snippets and so.
   9
  10 ELinks does not have own ECMAScript parser and compiler; instead it reuses
  11 other people's work (this may eventually change, see the bottom of this file).
  12 First we aimed at the NJS engine, which is easy to install, small and compact;
  13 has nice naming scheme, horrible calling conventions and very lacking
  14 documentation; is not actively developed; and generally looks broken and
  15 extremely clumsy to work with. So we instead went the way of the SpiderMonkey
  16 (SM) engine (property of Mozilla), which is hard to install, bigger (mind you,
  17 it comes from Mozilla ;), has ugly naming scheme but nice calling conventions,
  18 acceptable documentation, is actively developed and ought to work.
  19
  20
  21 Ok, so how to get the ECMAScript support working?
  22 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  23
  24 Some systems come with either the SpiderMonkey installed or as an option. It
  25 would be good to test if you can take the easy path and let the system take
  26 care of installation through a package system. Below are listed instructions
  27 on what package you need to install on various systems (please help improve
  28 the list). If all goes well you can proceed to rebuilding ELinks.
  29
  30 On Debian testing (Etch) or unstable (SID), run the following:
  31
  32         $ apt-get install libmozjs-dev
  33
  34 On Debian stable (Sarge), run the following:
  35
  36         $ apt-get install libsmjs-dev
  37
  38 Installing the -dev package will automatically pull in the library package.
  39
  40 Once this is done, rebuild ELinks. The configure script should detect
  41 the SpiderMonkey library--check for this line in the features summary:
  42
  43         ECMAScript (JavaScript) ......... SpiderMonkey document scripting
  44
  45 After following these instructions on a Debian system, you are done and should
  46 ignore the following directions.
  47
  48 The rest is only for non-Debian system.
  49
  50 Note that this procedure enables you to install SpiderMonkey, but in such a
  51 way that it might not work with anything else but ELinks. It is unlikely that
  52 anything else is ever going to use SpiderMonkey on your system, but if you
  53 want to take the safe way, get SM and follow the instructions in
  54 `src/README.html` instead. You will probably need to do some checkouting of
  55 bits of the Mozilla CVS tree and so, have fun.
  56
  57 To get SpiderMonkey source, go at
  58 link:ftp://ftp.mozilla.org/pub/mozilla.org/js/[] and fetch the newest `js-`
  59 tarball there (`js-1.5-rc6a.tar.gz` at the time of writing this; you may try
  60 the RPMs, but we didn't test them).
  61
  62         $ cd elinks
  63         $ wget ftp://ftp.mozilla.org/pub/mozilla.org/js/js-1.5-rc6a.tar.gz
  64         $ tar xvzf js-1.5-rc6a.tar.gz
  65
  66 Next, you need to patch it so that you will have any chance to install it as
  67 you fetched it. Grab it in ELinks at `contrib/js-1.5-rc6a+elinks.patch` (if
  68 you have a different version, still try to go ahead, you might have some
  69 success), then go to the SpiderMonkey directory (called js) and apply it as
  70
  71         $ cd js
  72         $ patch -p1 <../contrib/js-1.5-rc6a+elinks.patch
  73         $ cd src
  74
  75 Now, edit config.mk and adjust the `$PREFIX` variable - you probably won't
  76 like the default value - ELinks will find it there, but your dynamic linker
  77 likely won't.
  78
  79 E.g., for /usr/local installation:
  80
  81         $ sed 's#^PREFIX = /opt/spidermonkey#PREFIX = /usr/local#' < config.mk > config.mk.t
  82         $ mv -f config.mk.t config.mk
  83
  84 Now you can finally go for it:
  85
  86         $ make -f Makefile.ref
  87         $ make -f Makefile.ref export
  88
  89 Now install it:
  90
  91         $ su -c 'make -f Makefile.ref install && (ldconfig -v | grep libjs)'
  92
  93 Check for:
  94
  95         libjs.so -> libjs.so
  96
  97 If you don't get such result, check that the library's installation path
  98 (e.g. /usr/local/lib) is present in /etc/ld.so.conf (man 8 ldconfig).
  99
 100 If all went well, you can proceed to rebuild ELinks now. If something broke,
 101 see you on #elinks @ FreeNode or in the mailing list.
 102 You may add your options to `./configure` as usual; SpiderMonkey should be
 103 autodetected.
 104
 105         $ cd ../..
 106         $ ./configure
 107
 108 Check for the following line in the features summary:
 109
 110         ECMAScript (JavaScript) ......... SpiderMonkey document scripting
 111
 112 Then run:
 113
 114         $ make
 115         $ su -c 'make install'
 116
 117 Enjoy.
 118
 119
 120 The ECMAScript support is buggy! Shall I blame Mozilla people?
 121 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 122
 123 Likely not. The ECMAScript engine provides only the language compiler and some
 124 basic built-in objects, and it's more than likely that the problem is on our
 125 side in the implementation of some of the HTML/DOM objects (perhaps we just
 126 haven't bothered to implement it at all yet). So better tell us first, and if
 127 we think it's not our fault we will tell you to go complain to Mozilla (better
 128 yet if it does not work in the Mozilla browsers neither ;-).
 129
 130
 131 Now, I would still like NJS or a new JS engine from scratch...
 132 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 133
 134 \...and you don't fear some coding? That's fine then! ELinks is in no way tied
 135 to SpiderMonkey, in fact the ECMAScript support was carefully implemented so
 136 that there are no SpiderMonkey references outside of
 137 `src/ecmascript/spidermonkey.*`. If you want to implement an alternative
 138 ECMAScript backend, go ahead - you will just need to write an autoconf
 139 detection for it and tie it to `src/ecmascript/ecmascript.c`, which should be
 140 easy. We await your patches eagerly.