89 lines
3.2 KiB
ReStructuredText
89 lines
3.2 KiB
ReStructuredText
|
Building and testing
|
||
|
|
====================
|
||
|
|
|
||
|
|
To actually run highlight.js it is necessary to build it for the environment
|
||
|
|
where you're going to run it: a browser, the node.js server, etc.
|
||
|
|
|
||
|
|
|
||
|
|
Building
|
||
|
|
--------
|
||
|
|
|
||
|
|
The build tool is written in JavaScript using node.js. Before running the
|
||
|
|
script, make sure to have node installed and run ``npm install`` to get the
|
||
|
|
dependencies.
|
||
|
|
|
||
|
|
The tool is located in ``tools/build.js``. A few useful examples:
|
||
|
|
|
||
|
|
* Build for a browser using only common languages::
|
||
|
|
|
||
|
|
node tools/build.js :common
|
||
|
|
|
||
|
|
* Build for node.js including all available languages::
|
||
|
|
|
||
|
|
node tools/build.js -t node
|
||
|
|
|
||
|
|
* Build two specific languages for debugging, skipping compression in this case::
|
||
|
|
|
||
|
|
node tools/build.js -n python ruby
|
||
|
|
|
||
|
|
On some systems the node binary is named ``nodejs``; simply replace ``node``
|
||
|
|
with ``nodejs`` in the examples above if that is the case.
|
||
|
|
|
||
|
|
The full option reference is available with the usual ``--help`` option.
|
||
|
|
|
||
|
|
The build result will be in the ``build/`` directory.
|
||
|
|
|
||
|
|
.. _basic-testing:
|
||
|
|
|
||
|
|
Basic testing
|
||
|
|
-------------
|
||
|
|
|
||
|
|
The usual approach to debugging and testing a language is first doing it
|
||
|
|
visually. You need to build highlight.js with only the language you're working
|
||
|
|
on (without compression, to have readable code in browser error messages) and
|
||
|
|
then use the Developer tool in ``tools/developer.html`` to see how it highlights
|
||
|
|
a test snippet in that language.
|
||
|
|
|
||
|
|
A test snippet should be short and give the idea of the overall look of the
|
||
|
|
language. It shouldn't include every possible syntactic element and shouldn't
|
||
|
|
even make practical sense.
|
||
|
|
|
||
|
|
After you satisfied with the result you need to make sure that language
|
||
|
|
detection still works with your language definition included in the whole suite.
|
||
|
|
|
||
|
|
Testing is done using `Mocha <http://mochajs.org/>`_ and the
|
||
|
|
files are found in the ``test/`` directory. You can use the node build to
|
||
|
|
run the tests in the command line with ``npm test`` after installing the
|
||
|
|
dependencies with ``npm install``.
|
||
|
|
|
||
|
|
**Note**: for Debian-based machine, like Ubuntu, you might need to create an
|
||
|
|
alias or symbolic link for nodejs to node. The reason for this is the
|
||
|
|
dependencies that are requires to test highlight.js has a reference to
|
||
|
|
"node".
|
||
|
|
|
||
|
|
Place the snippet you used inside the browser in
|
||
|
|
``test/detect/<language>/default.txt``, build the package with all the languages
|
||
|
|
for node and run the test suite. If your language breaks auto-detection, it
|
||
|
|
should be fixed by :ref:`improving relevance <relevance>`, which is a black art
|
||
|
|
in and of itself. When in doubt, please refer to the discussion group!
|
||
|
|
|
||
|
|
|
||
|
|
Testing markup
|
||
|
|
--------------
|
||
|
|
|
||
|
|
You can also provide additional markup tests for the language to test isolated
|
||
|
|
cases of various syntactic construct. If your language has 19 different string
|
||
|
|
literals or complicated heuristics for telling division (``/``) apart from
|
||
|
|
regexes (``/ .. /``) -- this is the place.
|
||
|
|
|
||
|
|
A test case consists of two files:
|
||
|
|
|
||
|
|
* ``test/markup/<language>/<test_name>.txt``: test code
|
||
|
|
* ``test/markup/<language>/<test_name>.expect.txt``: reference rendering
|
||
|
|
|
||
|
|
To generate reference rendering use the Developer tool located at
|
||
|
|
``tools/developer.html``. Make sure to explicitly select your language in the
|
||
|
|
drop-down menu, as automatic detection is unlikely to work in this case.
|
||
|
|
|
||
|
|
|