C Documentation and the C++ Documentation.

The 51Degrees device detection API is built on the 51Degrees common API.

Pre-requisites

Data File

In order to perform device detection, you will need to use a 51Degrees data file. This repository includes a free, 'lite' file in the 'device-detection-data' sub-module that has a significantly reduced set of properties. To obtain a file with a more complete set of device properties see the 51Degrees website. If you want to use the lite file, you will need to install GitLFS.

For Linux:

Then, navigate to the device-detection-data directory and execute:

Fetching sub-modules

This repository has sub-modules that must be fetched. If cloning for the first time, use:

If you have already cloned the repository and want to fetch the sub modules, use:

If you have downloaded this repository as a zip file then these sub modules need to be downloaded separately as GitHub does not include then in the archive. In particular, note that the zip download will contain links to LFS content, rather than the files themselves. As such, these need to be downloaded individually.

Build tools

Windows

You will need either Visual Studio 2019 or the C++ Build Tools installed. If you have Visual Studio Code, you'll still need to install the build tools from the link above.

• Minimum Platform Toolset Version v142
• Minimum Windows SDK Version 10.0.18362.0

Linux

You will need:

• CMake 3.24 or greater installed to build the project.
• A C++ compiler which supports C++17. The compiler and other build tools will be selected by CMake automatically based on your environment.

Installing

Using CMake

To build the make files required to build, open a bash or Visual Studio Developer Command Prompt terminal and run

Note: on an x64 Windows system, it is necessary to add -A x64 as CMake will build a Win32 Solution by default.

Note: when building arm64 binaries on x64 Mac system, it is necessary to add -DBUILD_TESTING=OFF as CTest (ref) will otherwise fail the build due to inability to run test executables designated for different CPU.

Note: for maximum possible performance file based operation can be disabled by adding -DMemoryOnly=YES to the cmake .. command.

Then build the whole solution with

Libraries are output to the lib/ directory, and executables like examples and tests are output to the bin/ directory.

Using Visual Studio

Calling CMake in an MSVC environment (as described in the Using CMake section) will produce a Visual Studio solution with projects for all libraries, examples, and tests. However, it is preferable to use the dedicated Visual Studio solution in the VisualStudio/ directory.

Build Options

For build options, see Common API

Tests

All unit, integration, and performance tests are built using the Google test framework.

CMake

CMake automatically pulls in the latest Google Test from GitHub.

Building the project builds multiple test executables to the bin/ directory: HashTests and any common testing included in the common-cxx library.

These can be run by calling

If CMake has been used in an MSVC environment, then the tests will be set up and discoverable in the Visual Studio solution 51DegreesDeviceDetection created by CMake.

Visual Studio

Tests in the Visual Studio solution automatically install the GTest dependency via a NuGet package. However, in order for the tests to show up in the Visual Studio test explorer, the Test Adapter for Google Test extension must be installed.

The VisualStudio solution includes FiftyOne.DeviceDetection.Hash.Tests, which can be run through the standard Visual Studio test runner.

Code Coverage

When the project files are generated for a non-MSVC compiler (gcc/clang) with CMAKE_BUILD_TYPE=Debug f.e. by running:

the generated targets will contain code coverage instrumentation instructions to be added to the libraries with -cov suffix and HashTests target will be linked with them. During build time *.gcno and empty *.gcda files are generated.

During the test run *.gcda files will be filled with coverage data.

Install gcovr tool by running:

For best results make sure you have at least version 7.2.

The following command will generate a full coverage report:

To check the summary run:

Referencing the API

CMake

When building using CMake, static libraries are built in stages. These can be included in an executable just as they are in the examples. If these are included through a CMake file, the dependencies will be resolved automatically. However, if linking another way, all dependencies will need to be included from the lib/ directory. For example, to use the Hash C API, the following static libraries would need to be included:

• fiftyone-common-c
• fiftyone-device-detection-c
• fiftyone-hash-c

and for the Hash C++ API, the following are needed in addition:

• fiftyone-common-cxx
• fiftyone-device-detection-cxx
• fiftyone-hash-cxx

The CMake project also builds a single shared library containing everything. This is named fiftyone-device-detection-complete and can be referenced by any C or C++ project.

Visual Studio

The Visual Studio solution contains static libraries which have all the dependencies set up correctly, so referencing these in a Visual Studio solution should be fairly self explanatory.

Examples

There are several examples available, the source files can be found in the examples/ folder. The examples are written in C or CPP.

Visual Studio

All the examples are available to run in the VisualStudio/DeviceDetection.sln solution.

Device Detection Examples