• Stars
    star
    132
  • Rank 274,148 (Top 6 %)
  • Language
    C++
  • License
    GNU General Publi...
  • Created over 11 years ago
  • Updated over 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A C++ wrapper library around the core functionality of Adblock Plus

libadblockplus

A C++ library offering the core functionality of Adblock Plus.

Git hooks

This repo uses pre-commit to maintain agreed conventions in the repo. It should be installed (tldr; pip install pre-commit then pre-commit install) before making any new commits to the repo.

Getting/updating the dependencies

Project dependencies are declared as git submodules, ensure you include submodules in your checkout.

Additionally one should provide V8 headers in order to build libadblockplus library and V8 prebuilt libraries in order to link a binary (executable, shared object/DLL), even libadblockplus tests. The last time is was tested against V8 6.7. For more details see below.

Building

Supported platforms and prerequisites

Win32, MacOS, Linux and Android are supported target platforms.

The only officially supported development platform is Linux. If you plan to build libadblockplus on any other operating system, we recommend using a Docker container.

General:

  • You need a C++14 compatible compiler to build libadblockplus.

Linux:

  • We use Clang and libc++ instead of the libstdc++ that gcc uses, since by default v8 builds with libc++. Make sure you have the right development package installed for libc++: libc++-dev and libc++abi-dev on Debian/Ubuntu, libcxx-devel and libcxxabi-devel on RedHat/Fedora.

Android:

  • android-ndk-r16b, here are the links for downloading OS X, Linux 64.
  • g++ multilib

Unix

You need V8 prior to building. Two options:

  • Use the default prebuild V8 by invoking the make target get-prebuilt-v8. This will download and extract the prebuilt V8 for your setup. The default environment will be set by the Makefile at build time. If you are cross compiling use the same options as below to invoke make. This option works only on Linux

Pass WGET_QUIET=true to download the files silently.

If you switch the version of V8 using the same source tree, you should manually remove the third_party/prebuilt-v8 (also, third_party/v8-include.tar.xz and third_party/v8-prebuilt.tar.xz are not needed) directory and redownload again with the right options.

Or

  • Prepare V8 and set environment variables LIBV8_LIB_DIR and LIBV8_INCLUDE_DIR. LIBV8_INCLUDE_DIR should point to the include directory of V8, e.g. .../v8/include and there should be libv8_monolith.a in the directory LIBV8_LIB_DIR.

To clone:

git clone --recursive https://gitlab.com/eyeo/adblockplus/libadblockplus

To build:

Using Make:

make

The default target architecture is the architecture of a host. In order to build for a different architecture pass ABP_TARGET_ARCH to make, e.g. run:

make ABP_TARGET_ARCH=ia32

supported values are ia32 and x64.

To build and run the tests:

make test

Likewise, use the following with ABP_TARGET_ARCH:

make test ABP_TARGET_ARCH=ia32

To run specific tests, you can specify a filter:

make test FILTER=*.Matches

Building for Android on *nix

Configure V8 as for Unix and set ANDROID_NDK_ROOT environment variable to your Android NDK directory.

To build for x86 or x64 arch run:

make TARGET_OS=android ABP_TARGET_ARCH=ia32

or

make TARGET_OS=android ABP_TARGET_ARCH=x64

To build for arm or arm64 arch run:

make TARGET_OS=android ABP_TARGET_ARCH=arm

or

make TARGET_OS=android ABP_TARGET_ARCH=arm64

Usage

You can use libadblockplus to build an ad blocker. Or, strictly speaking, a web content filter. Just like Adblock Plus, it can detect resources that should be blocked based on their URL and context information, and generate CSS selectors to hide DOM elements.

The basic usage is explained below, see comments in the header files for more information. See the filter documentation to learn more about Adblock Plus filters.

Initialising the engine

All the types and functions in libadblockplus are in the AdblockPlus namespace. For brevity's sake, we'll assume the following using declaration:

using namespace AdblockPlus;

Most of the functionality of libadblockplus is available via the IFilterEngine class. First you need to create a Platform instance based on information about your application.

AppInfo appInfo;
appInfo.name = "awesomewebfilter";
appInfo.version = "0.1";
appInfo.locale = "en-US";

PlatformFactory::CreationParameters platformParameters;
auto platform = PlatformFactory::CreatePlatform(std::move(platformParameters));
platform->SetUp(appInfo);

Depending on your application and platform, you possibly will need to supply your own implementations for subsytems dealing with logging, network, files, etc. For this, modify PlatformFactory::CreationParameters fields. In this case it is important to remember that if your implementation uses a multi-threaded model, Platform instance should be destroyed only after all threads have finished.

In addition, it is expected that other objects returned by the API, such as Filter, Subscription and JsValue, will be released before the Platform.

Next, you can create a IFilterEngine instance:

FilterEngineFactory::CreationParameters engineParamters;
platform->CreateFilterEngineAsync(engineParamters, [](const IFilterEngine&)> { ... });

When initialised, IFilterEngine will automatically select a suitable ad blocking subscription based on AppInfo::locale and download the filters for it. To manually configure subscriptions you can modify StringPrefName::FirstRunSubscriptionAutoselect in preconfiguredPrefs for FilterEngineFactory::CreationParameters.

Managing subscriptions

libadblockplus takes care of storing and updating subscriptions.

You can add more:

Subscription subscription =
  filterEngine.GetSubscription("https://example.org/filters.txt");
filterEngine.AddSubscription(subscription);

To retrieve a list of all subscriptions use FilterEngine::GetListedSubscriptions. To check if a subscription has been added or not, do the following:

auto subscriptions = GetFilterEngine().GetListedSubscriptions();
auto subscription = std::find_if(subscriptions.begin(), subscriptions.end(), [](const auto& cur) {
  return cur.GetUrl() == "https://example.org/filters.txt";
});
if (subscription != subscriptions.end())
    ....

Removing a subscription is not rocket science either:

Subscription subscription =
  filterEngine.GetSubscription("https://example.org/filters.txt");
filterEngine.RemoveSubscription(subscription);

Managing custom filters

Working with custom filters is very similar to working with subscriptions:

Filter filter = filterEngine.GetFilter("||example.com/ad.png");
filterEngine.AddFilter(filter);
filterEngine.RemoveFilter(filter);

Note that applications should only do this to manage a user's custom filters. In general, filter lists should be hosted somewhere and added as a subscription.

Matching blocking filters

As mentioned above, one of the two main tasks of libadblockplus is to check if a URL matches any of the active blocking filters.

To demonstrate this, we'll add a custom filter:

Filter filter = filterEngine.GetFilter("||example.com/ad.png");
filterEngine.AddFilter(filter);

Now we'll call matches on an URL that should be blocked:

Filter match =
  filterEngine.Matches("http://example.com/ad.png", "IMAGE", "");

Since we've added a matching filter, match will point to the same filter object as filter.

Note that we've ignored the third parameter of IFilterEngine::Matches here to keep things simple. Real applications should pass the frame structure in here - this is necessary because many filters and exception rules are domain specific.

Working with sitekey-restricted filters

Some filters should be applied only for sites providing special key. It is provided in X-Adblock-Key header. Usually it is used to allowlist specific sites. You can read more about this in filters documentation.

To find match filter taking into account site key, please use 4th parameter for IFilterEngine::Matches It should contain decoded and verified public key extracted from X-Adblock-Key header.

Filter match =
  filterEngine.Matches("http://example.com/ad.png", "IMAGE", "",
     "DECODED PUBLIC KEY");

You can take a look for the sitekey-related tests for reference.

Generating CSS from element hiding filters

Aside from blocking requests, ad blockers typically also hide elements. This is done via a second type of filter that is completely ignored when matching URLs: element hiding rules.

You can retrieve a CSS style sheet for elements that should be hidden using IFilterEngine::GetElementHidingStyleSheet.

What libadblockplus clients typically do with this is to inject the CSS style sheet into each page.

Disabling network requests from Adblock Plus on current connection

At any moment you can call IFilterEngine::SetAllowedConnectionType to change the settings indicating what connection types are allowed in your application. However to have it working you should also pass a callback function into factory method of IFilterEngine. This callback is being called before each request and the value of argument is earlier passed string into IFilterEngine::SetAllowedConnectionType, what allows to query the system and check whether the current connection is in accordance with earlier stored value in settings. For example, you can pass "not_metered" into IFilterEngine::SetAllowedConnectionType and on each request you can check whether the current connection is "not_metered" and return true or false from you implementation of callback AdblockPlus::IFilterEngine::IsConnectionAllowedAsyncCallback.

Shell

The shell subdirectory contains an example application using libadblockplus.

It's a simple shell that loads subscriptions into memory and checks whether a specified resource would be blocked or not.

To see the available commands, type help.

Unix

The shell is automatically built by make, you can run it as follows:

build/out/abpshell

Windows

Just run the project abpshell.

Building V8

Just in case one can find args files to build V8 in v8-args directory.

Linting

You can lint the code using ESLint.

npm run eslint

In order to set up ESLint and configuration eslint-config-eyeo you need Node.js 7 or higher and once it is installed please run npm install in the repository directory.

In order to learn about the usage of deprecated V8 API please set libv8_show_warnings to "true" on *nix, e.g.

make libv8_show_warnings="true"

or on Windows add it to GYP_DEFINES.

More Repositories

1

adblockpluschrome

Mirrored from https://gitlab.com/eyeo/adblockplus/adblockpluschrome
JavaScript
546
star
2

adblockplus-legacy

DEPRECATED: Adblock Plus extension for Firefox and other Gecko-based browsers
JavaScript
360
star
3

adblockplusandroid

Adblock Plus app for Android
Java
236
star
4

backup-adblockplus

Adblock Plus extension for Firefox and other Gecko-based browsers
JavaScript
231
star
5

libadblockplus-android

Android JNI bindings for libadblockplus
Java
224
star
6

backup-adblockpluschrome

Adblock Plus extension for Google Chrome
JavaScript
224
star
7

adblockplussafariios

Adblock Plus Safari iOS source code
Objective-C
151
star
8

adblockpluscore

Mirrored from https://gitlab.com/eyeo/adblockplus/adblockpluscore
JavaScript
115
star
9

abp2blocklist

Code to convert Adblock Plus filter lists to WebKit content blocker lists
JavaScript
91
star
10

adblockplussbrowser

Adblock Plus for Samsung Browser source code
Java
33
star
11

python-abp

Adblock Plus utilities for Python
Python
32
star
12

abpcrawler

Website crawler for Adblock Plus
Python
26
star
13

adblockplus

Shared Adblock Plus UI code
JavaScript
26
star
14

gyp

Fork of https://chromium.googlesource.com/external/gyp.git
Python
23
star
15

infrastructure

Puppet-based configuration definitions for various servers used by the Adblock Plus project.
Puppet
17
star
16

adblockplusie

Adblock Plus for Internet Explorer
C++
16
star
17

buildtools

Build tools for Adblock Plus and related extensions
Python
12
star
18

elemhidehelper

DEPRECATED: Element Hiding Helper extension for Adblock Plus
JavaScript
10
star
19

sitescripts

Various scripts used on adblockplus.org, mirrored from https://gitlab.com/eyeo/devops/legacy/sitescripts
Python
8
star
20

web.adblockplus.org

AdblockPlus.org website content
JavaScript
6
star
21

cms

CMS used for adblockplus.org [mirrored from https://gitlab.com/eyeo/websites/cms]
Python
6
star
22

adblockbrowserios

Swift
5
star
23

libadblockplus-binaries

Binaries created from libadblockplus repository (for faster Android builds)
C++
4
star
24

abpcustomization

DEPRECATED: Customizations for Adblock Plus extension
Python
4
star
25

jshydra

JSHydra, a static analysis tool for JavaScript (forked from http://hg.mozilla.org/users/Pidgeot18_gmail.com/jshydra)
JavaScript
4
star
26

web.acceptableads.org

Source files for the acceptableads.org web content
HTML
3
star
27

abpwatcher

DEPRECATED: Diagnostics for Adblock Plus extension
JavaScript
2
star
28

yajl-dynamic

YAJL 2.1.0 dynamic framework for iOS
C
2
star
29

web.adblockbrowser.org

Source files for the adblockbrowser.org web content
CSS
2
star
30

adblockbrowserios-core

Swift
2
star
31

adblockbrowser

Adblock Browser for Android source code
2
star
32

adblockplustests

DEPRECATED: Firefox extension running Adblock Plus unit tests
JavaScript
2
star
33

easylist.adblockplus.org

Source files for the easylist.adblockplus.org web content
1
star
34

needs-translation

Configurable translations diff and exclusion tool for XLIFF 1.2 designed for Xcode localization exports
JavaScript
1
star
35

chromium-src-build

Fork of https://chromium.googlesource.com/chromium/src/build
Python
1
star
36

subscribe.adblockplus.org

Source files for the subscribe.adblockplus.org web content
1
star
37

youtube.adblockplus.me

Source files for the youtube.adblockplus.me web content
HTML
1
star
38

share.adblockplus.org

Source files for the share.adblockplus.org web content
HTML
1
star
39

chromium-trace_event-common

Fork of https://chromium.googlesource.com/chromium/src/base/trace_event/common
C++
1
star
40

codingtools

Various tools to aid working on Adblock Plus code
Python
1
star