Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

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
« no previous file with change/comment | « .hgignore ('k') | compile » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
(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.
LEFTRIGHT

Powered by Google App Engine
This is Rietveld