A C++ library offering the core functionality of Adblock Plus.
Getting/updating the dependencies
libadblockplus has dependencies that aren't part of this repository. They are retrieved and updated during the build process, but you can also manually update them by running the following:
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.
Supported target platforms and prerequisites
You need a C++14 compatible compiler to build libadblockplus. Below there is the list of tested tools.
- At least v141 Visual C++ toolset (available in Microsoft Visual Studio 2017).
- clang 5.0 We use libc++ instead of the libstdc++ that gcc uses, since by default v8 build with libc++.
- Apple LLVM 9.0.0 for OS X/macOS (Xcode should be installed and its developer tools should be "selected").
- The host system should be Linux or OS X
- android-ndk-r16b, here are the links for downloading OS X, Linux 64.
- g++ multilib
If you have a compilation issue with another compiler please create an issue.
You also need Python 2.7 and ensure that
python.exe is in your
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.
If you switch the version of V8 using the same source tree, you should
manually remove the
third_party/prebuilt-v8 directory and redownload
again with the right options.
- 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/includeand there should be
libv8_monolith.ain the directory LIBV8_LIB_DIR.
The default target architecture is the architecture of a host. In order to build for a different architecture pass
make, e.g. run:
supported values are
To build and run the tests:
Likewise, use the following with
make test ABP_TARGET_ARCH=ia32
To run specific tests, you can specify a filter:
make test FILTER=*.Matches
Prepare V8. Let's say V8 is prepared in
build/v8. There should be V8 headers in
build/v8/includeand binaries in
build/v8/win-%PLATFORM%.%CONFIGURATION%, e.g ensure that there is
Set GYP variable
v8_dirpointing to the prepared V8,
<path to build/v8>. E.g.
set "GYP_DEFINES=v8_dir=e:/v8-6.7"and execute
createsolution.batto generate project files, this will create
build\ia32\libadblockplus.sln(solution for the 32 bit build) and
build\x64\libadblockplus.sln(solution for the 64 bit build).
build\x64\libadblockplus.slnin Visual Studio and build the solution there. Alternatively you can use the
msbuildcommand line tool, e.g. run
msbuild /m build\ia32\libadblockplus.slnfrom the Visual Studio Developer Command Prompt to create a 32 bit debug build.
Tested on Microsoft Visual Studio 2017 Community Edition.
For more details see CI configuration for appveyor.
Building for Android
Configure V8 as for Unix and set ANDROID_NDK_ROOT environment variable to your Android NDK directory.
To build for x86 arch run:
make TARGET_OS=android ABP_TARGET_ARCH=ia32
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
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.
Initialising the engine
All the types and functions in libadblockplus are in the
namespace. For brevity's sake, we'll assume the following
using namespace AdblockPlus;
Most of the functionality of libadblockplus is available via the
class. Since libadblockplus uses the Adblock Plus core code under the hood, you
first need to create a
instance and pass some information about your
application to it.
AppInfo appInfo; appInfo.name = "awesomewebfilter"; appInfo.version = "0.1"; appInfo.locale = "en-US"; JsEngine jsEngine(appInfo);
Depending on your application and platform, you might want to supply your own
implementations for these - see
JsEngine instance created, you can create a
auto filterEngine = FilterEngine::Create(jsEngine);
Please also pay attention to asynchronous version of factory method FilterEngine::CreateAsync and to optional creationParameters.
FilterEngine will automatically select a suitable ad
blocking subscription based on
AppInfo::locale and download the filters for
libadblockplus takes care of storing and updating subscriptions.
You can add more:
SubscriptionPtr subscription = filterEngine.GetSubscription("https://example.org/filters.txt"); subscription->AddToList();
Retrieving an existing subscription works the same way, use
to check if the subscription has been added or not.
SubscriptionPtr subscription = filterEngine.GetSubscription("https://example.org/filters.txt"); if (subscription->IsListed()) ....
Removing a subscription is not rocket science either:
You can also get a list of all subscriptions that were added:
std::vector<SubscriptionPtr> subscriptions = filterEngine.GetListedSubscriptions();
Managing custom filters
Working with custom filters is very similar to working with subscriptions:
FilterPtr filter = filterEngine.GetFilter("||example.com/ad.png"); filter->AddToList(); filter->RemoveFromList();
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:
FilterPtr filter = filterEngine.GetFilter("||example.com/ad.png"); filter->AddToList();
Now we'll call matches on an URL that should be blocked:
FilterPtr match = filterEngine.Matches("http://example.com/ad.png", "DOCUMENT", "");
Since we've added a matching filter,
match will point to the same filter
Note that we've ignored the third parameter of
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
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 list of all CSS selectors for elements that should be hidden
What libadblockplus clients typically do with this is to generate a CSS style sheet that is injected into each page.
Disabling network requests from Adblock Plus on current connection
At any moment you can call
FilterEngine::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 FilterEngine. This callback is being called before each request and the value of argument is earlier passed string into
FilterEngine::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
FilterEngine::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
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
The shell is automatically built by
make, you can run it as follows:
Just run the project abpshell.
Just in case one can find args files to build V8 in
You can lint the code using ESLint.
npm run eslint