README.md - Issue 29333474: Issue 4125 - [emscripten] Convert filter classes to C++

Delta Between Two Patch Sets: README.md

Issue 29333474: Issue 4125 - [emscripten] Convert filter classes to C++ (Closed)

Left Patch Set: Minor improvements Created Jan. 20, 2016, 2:41 p.m.

Right Patch Set: Addressed comments from Patch Set 28 Created March 21, 2017, 10:04 a.m.

Left:
Right:

Use n/p to move between diff chunks; N/P to move between comments.

Jump to:

Right: Side by side diff | Download

LEFT	RIGHT
(no file at all)
1 Adblock Plus core	1 Adblock Plus core

2 =================	2 =================

3	3

4 This repository contains the generic Adblock Plus code that's shared between	4 This repository contains the generic Adblock Plus code that's shared between

5 platforms. This repository is not designed to be used directly, but instead to	5 platforms. This repository is not designed to be used directly, but instead to

6 serve as a dependency for `adblockplus`, `adblockpluschrome` and	6 serve as a dependency for `adblockplus`, `adblockpluschrome` and

7 `libadblockplus`.	7 `libadblockplus`.

8	8

	9 Compiling C++ code

	10 ------------------

	11

	12 ### Purpose

	13

	14 In order to improve performance and memory usage, some of the code (located

	15 inside the `compiled` directory) is written in C++ and compiled to JavaScript

	16 via Empscripten.

	17

	18 ### Requirements

	19

	20 * [Emscripten 1.35.0](https://github.com/kripken/emscripten)

	21 * [Python 2.7](https://www.python.org)

	22 * [Node.js 6 or higher](https://nodejs.org/en/)

	23

	24 ### Running Emscripten

	25

	26 Note: The `compile` script will likely be replaced by a more elaborate

	27 solution later.

	28

	29 Before you start make sure to edit the `compile` script and make sure that

	30 `EMSCRIPTEN_PATH` constant at the top of it points to your Emscripten install.

	31 After that run the following command:

	32

	33 python compile

	34

	35 This will produce a `lib/compiled.js` exporting the classes defined in C++ code.

	36

	37 ### Technical details

	38

	39 Compilation is currently a two-step process. In the first step,

	40 `compiled/bindings.cpp` (definitions of classes to be exported) is compiled into

	41 `compiled/bindings.cpp.js` with `PRINT_BINDINGS` symbol defined. This

	42 application is then executed via Node.js and will print JavaScript wrappers for

	43 the C++ classes to `compiled/bindings.js`.

	44

	45 In the next step all the C++ files in `compiled` directory are compiled,

	46 including `compiled/bindings.cpp` - without `PRINT_BINDINGS` symbol the

	47 `EMSCRIPTEN_BINDINGS` macro in this file will ignore its contents but rather

	48 emit some functions necessary for the JavaScript bindings to work. The

	49 `compiled/bindings.js` file is added to the end of Emscripten output.

	50

	51 The binding generation approach is heavily inspired by

	52 [embind](http://kripken.github.io/emscripten-site/docs/porting/connecting_cpp_an d_javascript/embind.html).

	53 However, embind doesn't use a separate build step to produce the bindings, the

	54 bindings are rather generated dynamically at run time. As a side-effect, it

	55 increases the build size considerably and also imposes a significant performance

	56 penalty. Also, generating JavaScript code dynamically is discouraged for browser

	57 extensions.

	58

	59 Note: The tricky part when generating JavaScript bindings is determining the

	60 mangled names of C++ methods. In order to do that, `compiled/bindings.cpp.js`

	61 will call these methods with invalid parameters and make them crash. The

	62 resulting `abort()` call is then caught by JavaScript code that reads out the

	63 method name from the stack. With this approach relying on some Emscripten

	64 internals, we have to require a specific Emscripten version.

	65

9 Running the unit tests	66 Running the unit tests

10 ----------------------	67 ----------------------

11	68

12 Note: The unit test suite isn't complete yet, it is in the process of being	69 You first need to run `npm install` in the repository directory in order to

13 migrated from the	70 install the required dependencies. After that you can run `npm test` which will

14 [adblockplustests repository](https://hg.adblockplus.org/adblockplustests/).	71 execute all tests in the `test` directory of the repository. You can also

15	72 specify specific test files on the command line, e.g.

16 In order to run the unit test suite you need a reasonably recent	73 `npm test test/synchronizer.js`.

17 [Node.js version](https://nodejs.org/). Once Node.js is installed please run

18 `npm install` in the repository directory in order to install the required

19 dependencies. After that you can run `npm test` which will execute all tests

20 in the `test` directory of the repository.

LEFT	RIGHT