Next: , Previous: , Up: LibreJS   [Contents]


8 LibreJS Development Notes

8.1 Dependencies

LibreJS 7.21 depends on a number of Node.js-based libraries that can be installed using the npm utility:

  $ npm install acorn-loose jassha browserify
  $ export PATH=$PATH:./node_modules/.bin

8.2 Building

To build the extension run:

  $ browserify main_background.js -o bundle.js

To build the extension plus create a .xpi package run:

  $ ./build.sh

To build the extension including the automated test suite (see TEST below) run:

  $ ./build.sh -t

or

  $ ./build.sh --test

Note: this build.sh script relies on no new source files being created.

8.3 Debugging

To debug LibreJS, visit the special URL about:debugging. Click on ‘Enable add-on debugging‘ then ‘Load Temporary Add-on‘. Navigate to LibreJS’s unpacked source directory and select manifest.json.

Lines 39 and 40 in main_background.js assign two variables controlling the verbosity of dbg_print() statements. Make sure these are set to false before building a release.

8.4 Testing

An automated test suite runs automatically in its own tab whenever the extension is loaded as a "Temporary add-on" from about:debugging. Otherwise (if included in the xpi) it can be launched from the UI by clicking the "Automated self test..." button.

8.5 Headless testing

To launch the test suite from the command line, ensure the xpi package has been built with automated test suite. Then install selenium-webdriver and geckodriver, and ensure the latter is in $PATH:

  $ npm install selenium-webdriver geckodriver
  $ export PATH=$PATH:./node_modules/.bin

Now you can invoke the test with

  $ node ./test.js

which will print out a summary of test results.

Optionally you can also test with a chosen seed

  $ node ./test.js 12345

8.6 Headless compliance check

To check whether a webpage is LibreJS-compliant from the command line, ensure that the xpi package has been built WITHOUT the automated test suite. Then install selenium-webdriver and geckodriver, and ensure the latter is in $PATH:

  $ npm install selenium-webdriver
  $ npm install geckodriver
  $ export PATH=$PATH:./node_modules/.bin

Now you can check a webpage for compliance with

  $ node ./compliance.js <url>

It will open the url in a headless browser, save a screenshot, and output the compliance check result.

For example, to check the compliance of the FSF homepage, do

  $ node ./compliance.js https://fsf.org

8.7 Adding new whitelisted libraries

The script index.js in ./hash_script generates the default whitelist. Run it with the following command:

node index.js > output

Then, just copy the contents of the file "output" to the appropriate place in main_background.js.

8.8 Releasing a new version

Update the version number in manifest.json.

Make sure debug statements are set to false on lines 39/40 in main_background.js.

Update the version number in docs/version.texi

Then run the build script build.sh.


Next: Installation Requirements, Previous: Setting Your JavaScript Free, Up: LibreJS   [Contents]