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@"<=8.7.1" jssha 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 ./utilities/test.js

which will print out a summary of test results.

Optionally you can also test with a chosen seed

  $ node ./utilities/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 ./utilities/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 ./utilities/compliance.js https://fsf.org

8.7 Adding new whitelisted libraries

The script index.js in ./utilities/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

  1. Run some tests and make sure they all pass.
  2. Make sure debug statements are set to false on lines 39/40 in main_background.js.
  3. Update the version number in manifest.json.
  4. Add user-visible changes to NEWS.
  5. Update the version number in docs/version.texi.
  6. Commit and tag the release, and push to Savannah.
  7. Run build.sh in a clean repo and upload the generated librejs.xpi to Mozilla.
  8. Fix any validation warnings or errors during the upload in the previous step, test, re-tag the release, re-push to Savannah, and re-upload to Mozilla.
  9. Generate docs from docs/ using gnulib gendocs.sh script (https://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob;f=build-aux/gendocs.sh), and commit the docs to the website cvs repo under the manual/ directory. This will update the docs at https://www.gnu.org/software/librejs/manual/.
  10. From this step onwards it is required that Mozilla has approved the new version. Download the signed xpi from Mozilla website (https://addons.mozilla.org/en-US/firefox/addon/librejs/).
  11. Follow the steps in Information for GNU Maintainer to upload the source tar ball (downloadable from cgit) and the signed xpi to the GNU FTP server.
  12. Update the download links on the LibreJS webpage (https://gnu.org/s/librejs) to point to the new release.
  13. Announce to info-gnu, help-librejs, bug-librejs mailing lists, and the Savannah project News section.
  14. (Optional) Update projects that uses LibreJS like gnuzilla and abrowser.