aboutsummaryrefslogtreecommitdiff
path: root/docs/librejs.texi
blob: 243425aca11bad5f4bfa404889fcb233de4ef45b (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename librejs.info
@include version.texi
@settitle GNU LibreJS @value{VERSION}

@copying
This manual is for GNU LibreJS (version @value{VERSION}, @value{UPDATED}),
a GNU IceCat extension to detect and block nonfree nontrivial
JavaScript on webpages.

Copyright @copyright{} 2011 2012 2014 2015 Loic J. Duros, 2022 Yuchen Pei

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying

@dircategory GNUzilla
@direntry
* LibreJS: (librejs).               Detect nonfree nontrivial in GNU Icecat
@end direntry

@titlepage
@title GNU LibreJS
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Loic J. Duros  (@email{librejs@@lduros.net})
@author Yuchen Pei (@email{ycp@@gnu.org})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage


@contents


@node Top
@top LibreJS
This manual is for GNU LibreJS (version @value{VERSION}, @value{UPDATED}).

@menu
* Overview::                    General purpose and information.
* Disclaimer::                  Emphasize what LibreJS does and does not.
* Installation::                Installing LibreJS from source. 
* How to Use::                  How to use LibreJS in IceCat.
* JavaScript Detection::        How LibreJS detects nontrivial Javascript.
* Free Licenses Detection::     List of licenses detected by LibreJS.
* Setting Your JavaScript Free::  Information for website owners/maintainers.
* LibreJS Development Notes::   Documentation about the development of
                                        LibreJS itself.
* Installation Requirements::   Requirements to build and install LibreJS.
* LibreJS Internals::           How LibreJS works under the hood.
* GNU Free Documentation License::  Copying and sharing this documentation.








@end menu

@node Overview
@chapter Overview

@cindex overview
GNU LibreJS ---an add-on for GNU IceCat and Mozilla Firefox--- detects
and blocks nonfree nontrivial JavaScript while allowing its execution on
pages containing code that is either trivial and/or free.

Many websites run nontrivial JavaScript on your computer. Some use it
for complex tasks; many use it gratuitously for minor jobs that could be
done easily with plain HTML.  Sometimes this JavaScript code is
malicious.  Either way, the JavaScript code is often nonfree.  For
explanation of the issue, see "The JavaScript
Trap"(@url{http://www.gnu.org/philosophy/javascript-trap.html}).

If you care about freedom in your computing, and don't wish to let all
and sundry make you run nonfree programs, now you can prevent it by
using LibreJS.


@node Disclaimer
@chapter Disclaimer

@cindex disclaimer

@itemize @bullet
@item
LibreJS is not a security tool. Its goal is to detect nonfree nontrivial
JavaScript, and it currently does not detect whether free or trivial
code is malicious or not. Other free Mozilla extensions and add-ons may
be available for this purpose.

@item
LibreJS is always a work in progress. If you find a bug, please report
it to @email{bug-librejs@@gnu.org}.

@end itemize

@node Installation
@chapter Installation
@cindex Installation

You can install LibreJS directly using a generated @file{librejs.xpi}
file, or by building it from source (@xref{LibreJS Development Notes}).

You can also download it from
@url{https://www.gnu.org/software/librejs/} or
@url{https://addons.mozilla.org/addon/librejs/}, but due to Mozilla's
review process the download isn't always up to date.

@node How to Use
@chapter How to Use

@section LibreJS in action

After installing the add-on, you will see the LibreJS widget in the
add-on bar at the top right of the browser window.  After loading a
page, left-click on the widget to view the deactivated JavaScript code
from the page (both on page and external) and, if applicable, the
scripts that were accepted.

@section Script Blacklist/whitelist

Scripts may be blacklisted or whitelisted through the pop-up menu box.

Whitelisted scripts will always be accepted and blacklisted scripts
will always get rejected.

It is important to note that this feature recognizes which scripts are
blacklisted and whitelisted based on hash. This means that even a slight
difference in a script's code will cause it to be recognized as a
separate script.

Sometimes, JavaScript will be dynamically generated so that it is
different every time a website is loaded. These types of scripts cannot
be whitelisted or blacklisted since they cannot be recognized.

LibreJS has a default whitelist of scripts that are known to be free but
may not declare their license in a format that LibreJS can understand.

@section Complaint Feature

It is very important to complain when a site has nonfree JavaScript
code, especially if it won't work without that code.  LibreJS makes it
easy to complain by heuristically finding where to send the complaint.

When nonfree/nontrivial code is detected in a page, LibreJS attempts to
find a relevant contact link or email for the website you are
visiting. In order to do so, it will attempt to visit a few links from
the current page (for instance, a link labeled ``contact'' on the same
domain as the current page, @dots{})

LibreJS detects contact pages, email addresses that are likely to be
owned by the maintainer of the site, Twitter and identi.ca links, and
phone numbers.

When you complain to the website for their nonfree nontrivial
JavaScript, provide them with the link to the JavaScript Trap essay so
that they can get more information on what the issue is and how they can
solve it on their own site.

LibreJS includes a default subject line and body for the complaint email,
with a link to the JavaScript Trap essay. This can be configured in the
LibreJS add-on preferences in your web browser.

@section Options

@table @dfn

You can manage LibreJS's preferences either from the extension's entry in your
browser's Add-ons Manager page (@code{about:addons}) or by clicking the LibreJS
toolbar icon and then the "Settings..." button on the top right of the popup.
This will open a panel containing a whitelist/blacklist manager and a section
to configure your complaints messages to site owners.

@item Whitelist/Blacklist

LibreJS lets you whitelist or blacklist domain names and subdomains, to bypass
the regular JavaScript checks. This might be useful, for example, if you are
running your own code in a local web server, or if you don't want to waste
computing resources on script origins you already know you can't trust. librejs
provides a lists manager UI to handle both the lists on the top of its Options
panel.

@item Complaint email subject
Configure the default subject used in complaint emails.

@item Complaint email body
Configure the default body used in complaint emails.
@end table

@node JavaScript Detection
@chapter JavaScript Detection
@cindex javascript

LibreJS considers a very strict subset of JavaScript to be acceptable for use
in non-free scripts. This is meant to maximimize compatibility with websites 
that haven't tried to be LibreJS compatible.  

We consider modification of the document non-trivial. There isn't
much that javascript could do that we would consider trivial, for
anything else a free software license would be required.

The criterion is as follows:

  For each function definition:
@itemize @bullet
  @item
  It must call only primitives.
  @item
  The number of conditionals and loops must be at most 3.
  @item
  It does not declare an array more than 50 elements long.
  @item
  It must not call itself
@end itemize

For the rest of the script, outside of function definitions:
@itemize @bullet
  @item
  It must call only primitives and functions defined above in the page.
  @item
  The number of conditionals and loops must be at most 3.
@end itemize

"function" means anything executable that gets a name, including methods.

Allowed primitives exclude:
  @itemize @bullet
    @item
    eval()
    @item
    ajax
    @item
    calling methods with the square bracket notation
    @item
    altering the dom
    @item 
    most other items found as methods of the `.window` object.
  @end itemize     


@node Free Licenses Detection
@chapter Free Licenses Detection
@cindex freelicenses

The machine readable format for license declarations that LibreJS uses
has changed in the most recent version. This was necessary in order to
not break the asynchronous JS loading model that browsers use. Scripts
are now evaluated independent of eachother and strictly as they
arrive.

@node Setting Your JavaScript Free
@chapter Setting Your JavaScript Free

The first step is releasing your JavaScript under a free license. If
you are already using a free library, or you're not using any
third-party libraries, it might only take a few minutes.

On your website, take a look at your HTML source. You can identify
distinct pieces of JavaScript that might be free and some other that are
nonfree.

This might be the case with an analytics tracker, social media
widgets, and code that runs ads. Removing these pieces of code from your
site is required to have the rest accepted as free. There are
often alternatives to nonfree libraries or to third-party services:

@itemize @bullet

@item
If you have used nonfree third-party code as the base to write your own
code, try to find a free alternative.

@item
If you're using a third-party service such as an analytics service,
replace it with a free alternative like Matomo.

@item
If you can't find free JavaScript that has already been developed,
write it yourself! Who knows, your own solution might be the start of
a brilliant project!
@end itemize


@section License tags 

LibreJS will allow non-trivial scripts to run as long as they use a 
free license.

In order for the license of a script to be recognized by LibreJS, it
must be declared using a machine-readable license format.

This format is the same for both remote in-line scripts.

"// @@license [magnet link] [identifier]"
[Script here]
"// @@license-end"

"Identifier" is a name of a license from the following list and the
magnet link in the @code{canonicalUrl} field is that license's exact
corresponding magnet link.

@verbatim
{
  'AGPL-3.0': {
    licenseName: 'GNU AFFERO GENERAL PUBLIC LICENSE version 3',
    identifier: 'AGPL-3.0',
    canonicalUrl: [
      'http://www.gnu.org/licenses/agpl-3.0.html',
      'magnet:?xt=urn:btih:0b31508aeb0634b347b8270c7bee4d411b5d4109&dn=agpl-3.0.txt'
    ],

  },

  'Apache-2.0': {
    licenseName: 'Apache License, Version 2.0',
    identifier: 'Apache-2.0',
    canonicalUrl: [
      'http://www.apache.org/licenses/LICENSE-2.0',
      'magnet:?xt=urn:btih:8e4f440f4c65981c5bf93c76d35135ba5064d8b7&dn=apache-2.0.txt'
    ],
  },

  'Artistic-2.0': {
    licenseName: "Artistic License 2.0",
    identifier: 'Artistic-2.0',
    canonicalUrl: [
      "http://www.perlfoundation.org/artistic_license_2_0",
      "magnet:?xt=urn:btih:54fd2283f9dbdf29466d2df1a98bf8f65cafe314&dn=artistic-2.0.txt"
    ],
  },

  'BSD-2-Clause': {
    licenseName: "BSD 2-Clause License",
    identifier: 'BSD-2-Clause',
    canonicalUrl: [
      'http://www.freebsd.org/copyright/freebsd-license.html',
      'magnet:?xt=urn:btih:87f119ba0b429ba17a44b4bffcab33165ebdacc0&dn=freebsd.txt'
    ],
  },

  'BSD-3-Clause': {
    licenseName: "BSD 3-Clause License",
    identifier: 'BSD-3-Clause',
    canonicalUrl: [
      'http://opensource.org/licenses/BSD-3-Clause',
      'magnet:?xt=urn:btih:c80d50af7d3db9be66a4d0a86db0286e4fd33292&dn=bsd-3-clause.txt'
    ],
  },

  'BSL-1.0': {
    licenseName: 'Boost Software License 1.0',
    identifier: 'BSL-1.0',
    canonicalUrl: [
      'http://www.boost.org/LICENSE_1_0.txt',
      'magnet:?xt=urn:btih:89a97c535628232f2f3888c2b7b8ffd4c078cec0&dn=Boost-1.0.txt'
    ],
  },

  'CC-BY-1.0': {
    licenseName: 'Creative Commons Attribution 1.0 Generic',
    identifier: 'CC-BY-1.0',
    canonicalUrl: ['https://creativecommons.org/licenses/by/1.0/'],
  },

  'CC-BY-2.0': {
    licenseName: 'Creative Commons Attribution 2.0 Generic',
    identifier: 'CC-BY-2.0',
    canonicalUrl: ['https://creativecommons.org/licenses/by/2.0/'],
  },

  'CC-BY-2.5': {
    licenseName: 'Creative Commons Attribution 2.5 Generic',
    identifier: 'CC-BY-2.5',
    canonicalUrl: ['https://creativecommons.org/licenses/by/2.5/'],
  },

  'CC-BY-3.0': {
    licenseName: 'Creative Commons Attribution 3.0 Unported',
    identifier: 'CC-BY-3.0',
    canonicalUrl: ['https://creativecommons.org/licenses/by/3.0/'],
  },

  'CC-BY-4.0': {
    licenseName: 'Creative Commons Attribution 4.0 International',
    identifier: 'CC-BY-4.0',
    canonicalUrl: ['https://creativecommons.org/licenses/by/4.0/'],
  },

  'CC-BY-SA-1.0': {
    licenseName: 'Creative Commons Attribution-ShareAlike 1.0 Generic',
    identifier: 'CC-BY-SA-1.0',
    canonicalUrl: ['https://creativecommons.org/licenses/by-sa/1.0/'],
  },

  'CC-BY-SA-2.0': {
    licenseName: 'Creative Commons Attribution-ShareAlike 2.0 Generic',
    identifier: 'CC-BY-SA-2.0',
    canonicalUrl: ['https://creativecommons.org/licenses/by-sa/2.0/'],
  },

  'CC-BY-SA-2.5': {
    licenseName: 'Creative Commons Attribution-ShareAlike 2.5 Generic',
    identifier: 'CC-BY-SA-2.5',
    canonicalUrl: ['https://creativecommons.org/licenses/by-sa/2.5/'],
  },

  'CC-BY-SA-3.0': {
    licenseName: 'Creative Commons Attribution-ShareAlike 3.0 Unported',
    identifier: 'CC-BY-SA-3.0',
    canonicalUrl: ['https://creativecommons.org/licenses/by-sa/3.0/'],
  },

  'CC-BY-SA-4.0': {
    licenseName: 'Creative Commons Attribution-ShareAlike 4.0 International',
    identifier: 'CC-BY-SA-4.0',
    canonicalUrl: ['https://creativecommons.org/licenses/by-sa/4.0/'],
  },

  'CC0-1.0': {
    licenseName: 'Creative Commons CC0 1.0 Universal',
    identifier: 'CC0-1.0',
    canonicalUrl: [
      'http://creativecommons.org/publicdomain/zero/1.0/legalcode',
      'magnet:?xt=urn:btih:90dc5c0be029de84e523b9b3922520e79e0e6f08&dn=cc0.txt'
    ],
  },

  'CPAL-1.0': {
    licenseName: 'Common Public Attribution License Version 1.0 (CPAL)',
    identifier: 'CPAL-1.0',
    canonicalUrl: [
      'http://opensource.org/licenses/cpal_1.0',
      'magnet:?xt=urn:btih:84143bc45939fc8fa42921d619a95462c2031c5c&dn=cpal-1.0.txt'
    ],
  },

  'EPL-1.0': {
    licenseName: "Eclipse Public License Version 1.0",
    identifier: "EPL-1.0",
    canonicalUrl: [
      "http://www.eclipse.org/legal/epl-v10.html",
      "magnet:?xt=urn:btih:4c6a2ad0018cd461e9b0fc44e1b340d2c1828b22&dn=epl-1.0.txt"
    ],
  },

  'Expat': {
    licenseName: 'Expat License (sometimes called MIT Licensed)',
    identifier: 'Expat',
    canonicalUrl: [
      'http://www.jclark.com/xml/copying.txt',
      'magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt'
    ],
  },

  'FreeBSD': {
    licenseName: "FreeBSD License",
    identifier: 'FreeBSD',
    canonicalUrl: [
      'http://www.freebsd.org/copyright/freebsd-license.html',
      'magnet:?xt=urn:btih:87f119ba0b429ba17a44b4bffcab33165ebdacc0&dn=freebsd.txt'
    ],
  },

  'GNU-All-Permissive': {
    licenseName: 'GNU All-Permissive License',
    identifier: 'GNU-All-Permissive',
    canonicalUrl: [],
  },

  'GPL-2.0': {
    licenseName: 'GNU General Public License (GPL) version 2',
    identifier: 'GPL-2.0',
    canonicalUrl: [
      'http://www.gnu.org/licenses/gpl-2.0.html',
      'magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt'
    ],
  },

  'GPL-3.0': {
    licenseName: 'GNU General Public License (GPL) version 3',
    identifier: 'GPL-3.0',
    canonicalUrl: [
      'http://www.gnu.org/licenses/gpl-3.0.html',
      'magnet:?xt=urn:btih:1f739d935676111cfff4b4693e3816e664797050&dn=gpl-3.0.txt'
    ],
  },

  'ISC': {
    licenseName: "The ISC License",
    identifier: 'ISC',
    canonicalUrl: [
      'https://www.isc.org/downloads/software-support-policy/isc-license/',
      'magnet:?xt=urn:btih:b8999bbaf509c08d127678643c515b9ab0836bae&dn=ISC.txt'
    ],
  },

  'jQueryTools': {
    licenseName: "jQuery Tools",
    identifier: 'jQueryTools',
    canonicalUrl: [],
  },

  'LGPL-2.1': {
    licenseName: 'GNU Lesser General Public License, version 2.1',
    identifier: 'LGPL-2.1',
    canonicalUrl: [
      'http://www.gnu.org/licenses/lgpl-2.1.html',
      'magnet:?xt=urn:btih:5de60da917303dbfad4f93fb1b985ced5a89eac2&dn=lgpl-2.1.txt'
    ],
  },

  'LGPL-3.0': {
    licenseName: 'GNU Lesser General Public License, version 3',
    identifier: 'LGPL-3.0',
    canonicalUrl: [
      'http://www.gnu.org/licenses/lgpl-3.0.html',
      'magnet:?xt=urn:btih:0ef1b8170b3b615170ff270def6427c317705f85&dn=lgpl-3.0.txt'
    ],
  },

  'MPL-2.0': {
    licenseName: 'Mozilla Public License Version 2.0',
    identifier: 'MPL-2.0',
    canonicalUrl: [
      'http://www.mozilla.org/MPL/2.0',
      'magnet:?xt=urn:btih:3877d6d54b3accd4bc32f8a48bf32ebc0901502a&dn=mpl-2.0.txt'
    ],
  },

  'PublicDomain': {
    licenseName: 'Public Domain',
    identifier: 'PublicDomain',
    canonicalUrl: [
      'magnet:?xt=urn:btih:e95b018ef3580986a04669f1b5879592219e2a7a&dn=public-domain.txt'
    ],
  },


  'Unlicense': {
    licenseName: 'Unlicense',
    identifier: 'Unlicense',
    canonicalUrl: [
      'http://unlicense.org/UNLICENSE',
      'magnet:?xt=urn:btih:5ac446d35272cc2e4e85e4325b146d0b7ca8f50c&dn=unlicense.txt'
    ],
  },

  'UPL': {
    licenseName: 'Universal Permissive License',
    identifier: 'UPL-1.0',
    canonicalUrl: [
      'https://oss.oracle.com/licenses/upl/',
      'magnet:?xt=urn:btih:478974f4d41c3fa84c4befba25f283527fad107d&dn=upl-1.0.txt'
    ],
  },

  'WTFPL': {
    licenseName: 'Do What The F*ck You Want To Public License (WTFPL)',
    identifier: 'WTFPL',
    canonicalUrl: [
      'http://www.wtfpl.net/txt/copying/',
      'magnet:?xt=urn:btih:723febf9f6185544f57f0660a41489c7d6b4931b&dn=wtfpl.txt'
    ],
  },

  'X11': {
    licenseName: 'X11 License',
    identifier: 'X11',
    canonicalUrl: [
      'magnet:?xt=urn:btih:5305d91886084f776adcf57509a648432709a7c7&dn=x11.txt'
    ],
  },

  'XFree86-1.1': {
    licenseName: "XFree86 1.1 License",
    identifier: 'XFree86-1.1',
    canonicalUrl: [
      'http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3',
      'http://www.xfree86.org/current/LICENSE4.html',
      'magnet:?xt=urn:btih:12f2ec9e8de2a3b0002a33d518d6010cc8ab2ae9&dn=xfree86.txt'
    ],
  },
}
@end verbatim

@section Undetected Free Licenses

If you are using a free license that isn't detected by LibreJS and isn't
listed in the previous section, please send a message to
@email{bug-librejs@@gnu.org} regarding this license, where code released under
this license can be found, and where to find the license text and
information.

Many free licenses are listed in this page:
@url{http://www.gnu.org/licenses/license-list.html}

@section Known limitations

Service workers may cause false positives and false negatives, and
there are multiple ways to disable them.  The cleanest way is by
setting @code{dom.serviceWorkers.enabled} to @code{false} in the
@code{about:config} page of your browser.

@node LibreJS Development Notes
@chapter LibreJS Development Notes

@section Dependencies

LibreJS @value{VERSION} depends on a number of Node.js-based libraries that
can be installed using the @code{npm} utility:

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

@section Building

To build the extension run:
@verbatim
  $ browserify main_background.js -o bundle.js
@end verbatim

To build the extension plus create a .xpi package run:
@verbatim
  $ ./build.sh
@end verbatim

To build the extension including the automated test suite (see TEST below) run:
@verbatim
  $ ./build.sh -t
@end verbatim
or
@verbatim
  $ ./build.sh --test
@end verbatim

Note: this @file{build.sh} script relies on no new source files being created.

@section Debugging

To debug LibreJS, visit the special URL @code{about:debugging}. Click
on `Enable add-on debugging` then `Load Temporary Add-on`. Navigate
to LibreJS's unpacked source directory and select @file{manifest.json}.

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

@section Testing

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

@section 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:
@verbatim
  $ npm install selenium-webdriver geckodriver
  $ export PATH=$PATH:./node_modules/.bin
@end verbatim

Now you can invoke the test with
@verbatim
  $ node ./utilities/test.js
@end verbatim

which will print out a summary of test results.

Optionally you can also test with a chosen seed
@verbatim
  $ node ./utilities/test.js 12345
@end verbatim

@section 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:
@verbatim
  $ npm install selenium-webdriver
  $ npm install geckodriver
  $ export PATH=$PATH:./node_modules/.bin
@end verbatim

Now you can check a webpage for compliance with
@verbatim
  $ node ./utilities/compliance.js <url>
@end verbatim

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

@section Adding new whitelisted libraries

The script index.js in @file{./utilities/hash_script} generates the default
whitelist. Run it with the following command:

@command{node index.js > output}

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

@section Releasing a new version

@enumerate

@item
Run some tests and make sure they all pass.

@item
Make sure debug statements are set to false on lines 39/40 in
@file{main_background.js}.

@item
Update the version number in manifest.json.

@item
Add user-visible changes to @file{NEWS}.

@item
Update the version number in @file{docs/version.texi}.

@item
Commit and tag the release, and push to Savannah.

@item
Run build.sh in a clean repo and upload the generated
@file{librejs.xpi} to Mozilla.

@item
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.

@item
Generate docs from @file{docs/} using gnulib gendocs.sh script
(@url{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 @file{manual/}
directory.  This will update the docs at
@url{https://www.gnu.org/software/librejs/manual/}.

@item
From this step onwards it is required that Mozilla has approved the
new version.  Download the signed xpi from Mozilla website
(@url{https://addons.mozilla.org/en-US/firefox/addon/librejs/}).

@item
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.

@item
Update the download links on the LibreJS webpage
(@url{https://gnu.org/s/librejs}) to point to the new release.

@item
Announce to info-gnu, help-librejs, bug-librejs mailing lists, and the
Savannah project News section.

@item
(Optional) Update projects that uses LibreJS like gnuzilla and
abrowser.
@end enumerate

@node Installation Requirements
@appendix Installation Requirements


@appendixsec Mozilla Browser

You will need one of the many flavors of the Mozilla browser to use
LibreJS. It can be installed on the following:

GNU IceCat,  Mozilla Firefox, Trisquel Abrowser, Debian Iceweasel.

LibreJS works on these browsers starting from version 60. We recommend
that you use the latest version of your Mozilla browser. LibreJS has
been tested on a GNU/Linux distribution, but it is compatible any
operating system as long as you're using a compatible Mozilla browser.

@node LibreJS Internals
@appendix LibreJS Internals

LibreJS intercepts HTTP responses and rewrites their contents after
analyzing JavaScript within them. It does not remove script nodes and
attributes from the page, but instead ``deactivates'' them by replacing
their content with a commented notice.

LibreJS detects the most common cases using the HTTP response method
described above, but in less common edge cases, or when running code
locally, LibreJS cannot detect JavaScript during the response stage.


@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi


@bye