Writing an export plugin

Introduction

OpenCppCoverage supports as export, HTML, Cobertura and binary format. It also has a plugin system to write new kinds of export.

This section explains how to write a new kind of export that create a simple text file.

It requires Visual Studio 2017 15.9.11

Creating the repository

The first step is to create a new GitHub repository named SimpleText.

Then, you will need the Plugin project from OpenCppCoverage sources code. An easy way to integrate it, is to use git submodule feature.

In SimpleText root folder, run: git submodule add https://github.com/OpenCppCoverage/OpenCppCoverage.git and then git submodule update --init

Plugin project should be located in SimpleText/OpenCppCoverage/Plugin folder.

Creating the SimpleText project

The next step is to create a new Dynamic-Link Library (DLL) project named SimpleText. SimpleText.vcxproj must be located in SimpleText/SimpleText/SimpleText.vcxproj.

In SimpleText project properties, C/C++, Language, set C++ Language Standard to ISO C++ 17 Standard.

You also need to link with Plugin project:

• Add Plugin project into your solution: Right click on the solution, Add, Existing Project... and select the SimpleText/OpenCppCoverage/Plugin/Plugin.vcxproj file.
• Setup the includes: In SimpleText project properties, C/C++, General, add ../OpenCppCoverage to Additional Include Directories.
• Setup the reference: In project references, Add reference... and select Plugin project.

Now, compile your solution. If you have an issue, please check the version of Visual Studio and the usage of ISO C++ 17 Standard.

Implement IExportPlugin interface

Let's start by creating a new class named SimpleTextExport that inherits from Plugin::IExportPlugin.

We need to implement the following four methods:

std::optional<std::filesystem::path> Export(
		const Plugin::CoverageData& coverageData,
		const std::optional<std::wstring>& argument)

This method creates the export from the coverage data.

void CheckArgument(const std::optional<std::wstring>& argument)

This method checks whether the argument is valid or not.

std::wstring GetArgumentHelpDescription()

This method is used by OpenCppCoverage --help to get the option argument description.

int GetExportPluginVersion() const

This method returns the version of IExportPlugin.

Additional information about these methods can be found in IExportPlugin.hpp.

You can find below an example of implementation for SimpleTextExport:

#include "stdafx.h"

#include "Plugin/Exporter/IExportPlugin.hpp"
#include "Plugin/Exporter/CoverageData.hpp"
#include "Plugin/Exporter/ModuleCoverage.hpp"
#include "Plugin/Exporter/FileCoverage.hpp"
#include "Plugin/Exporter/LineCoverage.hpp"
#include "Plugin/OptionsParserException.hpp"

#include <filesystem>
#include <fstream>
#include <iostream>

class SimpleTextExport : public Plugin::IExportPlugin
{
public:
	//-------------------------------------------------------------------------
	std::optional<std::filesystem::path> Export(
		const Plugin::CoverageData& coverageData,
		const std::optional<std::wstring>& argument) override
	{
		std::filesystem::path output = argument ? *argument : L"SimpleText.txt";
		std::wofstream ofs{ output };

		if (!ofs)
			throw std::runtime_error("Cannot create the output file for SimpleExport");

		for (const auto& mod : coverageData.GetModules())
		{
			ofs << mod->GetPath().filename().wstring() << std::endl;
			for (const auto& file : mod->GetFiles())
			{
				const auto& lines = file->GetLines();
				auto coveredCount = std::count_if(
					lines.begin(),
					lines.end(),
					[](const auto& line) { return line.HasBeenExecuted(); });
				ofs << '\t' << file->GetPath().filename().wstring() << "  ";
				ofs << "Lines covered: " << coveredCount << " Total: " << lines.size() << std::endl;
			}
		}
		return output;
	}

	//-------------------------------------------------------------------------
	void CheckArgument(const std::optional<std::wstring>& argument) override
	{
		// Try to check if the argument is a file.
		if (argument && !std::filesystem::path{ *argument }.has_filename())
			throw Plugin::OptionsParserException("Invalid argument for SimpleText export.");
	}

	//-------------------------------------------------------------------------
	std::wstring GetArgumentHelpDescription() override
	{
		return L"output file (optional)";
	}

	//-------------------------------------------------------------------------
	int GetExportPluginVersion() const override
	{
		return Plugin::CurrentExportPluginVersion;
	}
};

extern "C"
{
	//-------------------------------------------------------------------------
	__declspec(dllexport) Plugin::IExportPlugin* CreatePlugin()
	{
		return new SimpleTextExport();
	}
}

To be callable from OpenCppCoverage, you also need to export the C function CreatePlugin as above.

Use SimpleText plugin

To use the plugin you need to:

• Compile the latest version of OpenCppCoverage.
• Compile the project SimpleText.
• Copy SimpleText.dll to BINARY_FOLDER\Plugins\Exporter where BINARY_FOLDER is the folder containing OpenCppCoverage.exe.
• Run OpenCppCoverage --sources MySourcePath --exportType SimpleText -- .\ConsoleApplication

The name of the plugin is the filename of the shared library. The name is case sensitive.

OpenCppCoverage and SimpleText must be compiled in the same configuration Debug or Release and Win32 or x64. Do not mix them!

Share the project

You can share your plugin by sending an email to OpenCppCoverage at gmail.com with the following details:

• A sentence to explain what the plugin does
• A link to a web page (for example on GitHub) containing a step by step explanation on how to compile the plugin. You can also provide x64 and x86 binaries.