Reference

Tool

Parameter Overview

Name	Short	Description	Type	Default Argument
help	H	Print the help message	flag	false
output	O	Output source file	path	"./cpp-wrapper.cpp"
compiler	C	Compiler to be used (clang, gcc)	string	none
outline	X	The mangled outline	path	none
dem-outline	Y	The demangled outline	path	none
wrapper-out	W	The wrapper options output for the linker	path	"./wrapper-param"
response-file		Response file, i.e. file containing options normally passed. Can also be used as @file.opt	path	none
config-file	E	Config file, can contain similar parameters as the response-file	path	none
binary	B	The binary/binaries the outline shall be read from	list of paths	none
template	T	Template file for the generated code.	path	none
nm	N	Custom nm command	path	"nm"
indirect	I	Flag indicating that the linker is called through the compiler, e.g. g++.	flag	false

binary can be passed as a positional argument, i.e. as the first argument without the --binary/-B. E.g. cpp-wrap my-binary.o.

Obtaining the outline

cpp-wrap needs the mangled and the demandled outline. These can either be obtained prior to calling cpp-wrap and then passed to the tool. For a binary foo.o this might look like this:

nm foo.o > foo.nm
nm foo.o --demangle > foo.dem
cpp-wrap --dem-outline foo.dem --outline foo.nm

Alternatively cpp-wrap can call the tool directly, and the command can be set as parameter.

cpp-wrap --nm nm --binary foo.o
cpp-wrap foo.o

The second version is the short form.

Config files / Response file

The tool supports two ways to get additional parameters passed from a file. One is the response file, which is verbatim the same as passed as the parameters.

--outline foo.nm --dem-outline foo.dem

These options can be loaded in the following way.

cpp-wrap @response-file
cpp-wrap --response-file response-file

This feature is also provided by gcc and many of the linux tools. This is how the wrapper output options shall be used.

The config-file has a different format like this.

outline=foo.nm
dem-outline=foo.dem

And this can be used like this.

cpp-wrap --config-file file.cfg

Header <cpp/wrap.hpp>

Macro CPP_WRAP_FN

Synopsis

// In header: <cpp/wrap.hpp>
CPP_WRAP_FN(Scope, Name, Return, Signature) 
CPP_WRAP_FN(Name, Return, Signature)

CPP_WRAP_FN_NO_ARGS(Scope, Name, Return) 
CPP_WRAP_FN_NO_ARGS(Name, Return)

Description

This macro can be used to declare a run-time wrap for a function; it can be used several times from different types, if they are not attempting to set it at the same time. The Macro taking three parameters is a convenience overload when the function is in the global scope.

[note Must be member of a class.] [warning Construction will throw an std::runtime_error if the wrap is already set.] [note This also does work with static member functions. Though since they may be in a type alias or a template the usage of CPP_WRAP_STATIC_MEM is recommended.]

For an empty argument list the CPP_WRAP_FN macro will use the trailing macro extension in gcc. This might not work with some compilers, so that CPP_WRAP_FN_NO_ARGS can be used.

Parameters

Name	Description
Name	The name of the function, without the scope
Return	The return value of the function
Scope	The scope of the function, must be put into parenthesis
Signature	The parameter function list

Example

Given two scoped functions like this

double unscoped_fun(int d);

namespace my_namespace
{
    namespace inner_namespace
    {
        double function(const int & i);
    }
}

we can declare a wrap like this

struct my_stubber
{
    double out;
    int in;
    CPP_WRAP_FN((my_namespace, inner_namespace), function, double, (const int & val))
    {
        in = val;
        return out;
    }
    CPP_WRAP_FN(unscoped_fun, double, (int val))
    {
        in = val;
        return out;
    } 
};

Macro CPP_WRAP_MEM

Synopsis

// In header: <cpp/wrap.hpp>
CPP_WRAP_MEM(Type, Name, Return, Signature)
CPP_WRAP_MEM_NO_ARGS(Type, Name, Return)

Description

This macro can be used to declare a run-time wrap for a member-function. It will pass the this-pointer with the correct qualification as this_. It can be used several times from different types, if they are not attempting to set it at the same time.

Must be member of a class. Construction will throw an std::runtime_error if the wrap is already set. The type must be visible at the point of declaration of the wrap function. It can be used with templates due to utilization of extern template, as shown in the tutorial. Important There is currently no support for handling ref-qualifiers for the member-functions.

For an empty argument list the CPP_WRAP_MEM macro will use the trailing macro extension in gcc. This might not work with some compilers, so that CPP_WRAP_MEM_NO_ARGS can be used.

Parameters

Name	Description
Name	The name of the function, without the scope
Return	The return value of the function
Signature	The parameter function list
Type	The type the function is a member of including the qualifiers. Can be inside parenthesis, e.g. (const std::vector<int, std::allocator<int>>).

Example

Given two scoped functions like this

namespace my_namespace
{
    struct foo
    {
        int value = 42;

        int bar();
        int bar() const;
    };
}

we can declare a wrap like this

struct my_stubber
{
    int out;
    int foo_value;

    CPP_WRAP_MEM((const my_namespace::foo), bar, int, ())
    {
        this_->value = foo_value;
        return out;
    }

    CPP_WRAP_MEM(my_namespace::foo, bar, int, ())
    {
        foo_value = this_->value;
        return out;
    }
};

Macro CPP_WRAP_STATIC_MEM

Synopsis

// In header: <cpp/wrap.hpp>
CPP_WRAP_STATIC_MEM(Type, Name, Return, Signature)
CPP_WRAP_STATIC_MEM_NO_ARGS(Type, Name, Return)

Description

This macro can be used to declare a run-time wrap for a static member-functions.

The type must be visible at the point of declaration of the wrap function. It can be used with templates due to utilization of extern template, as shown in the tutorial.

For an empty argument list the CPP_WRAP_STATIC_MEM macro will use the trailing macro extension in gcc. This might not work with some compilers, so that CPP_WRAP_STATIC_MEM_NO_ARGS can be used.

Parameters

Name	Description
Name	The name of the function, without the scope
Return	The return value of the function
Signature	The parameter function list
Type	The type the function is a member of including the qualifiers. Can be inside parenthesis, e.g. (const std::vector<int, std::allocator<int>>).

Example

Given two scoped functions like this

namespace my_namespace
{
    struct foo
    {
        static int static_bar();
    };
}

we can declare a wrap like this

struct my_stubber
{
    int out;
    CPP_WRAP_STATIC_MEM(my_namespace::foo, static_bar, int, ())
    {
        return out;
    }
};

Macro CPP_WRAP_FN_FIX

[section:synopsis Synopsis]

// In header: <cpp/wrap.hpp>
CPP_WRAP_FN_FIX(Scope, Name, Return, Signature)
CPP_WRAP_FN_FIX(Name, Return, Signature)

CPP_WRAP_FN_FIX_NO_ARGS(Scope, Name, Return)
CPP_WRAP_FN_FIX_NO_ARGS(Name, Return)

Description

This macro can be used to declare a compile-time constant wrap for a function. The Macro taking three parameters is a convenience overload when the function is in the global scope.

Must be member of a class.

warning Construction will throw an std::runtime_error if the wrap is already set.

*note This also does work with static member functions. Though since they may be in a type alias or a template the usage of CPP_WRAP_STATIC_MEM_FIX is recommended.

For an empty argument list the CPP_WRAP_FN_FIX macro will use the trailing macro extension in gcc. This might not work with some compilers, so that CPP_WRAP_FN_FIX_NO_ARGS can be used.

Parameters

Name	Description
Name	The name of the function, without the scope
Return	The return value of the function
Scope	The scope of the function, must be put into parenthesis
Signature	The parameter function list

Example

Given two scoped functions like this

double unscoped_fun(int d);

namespace my_namespace
{
    namespace inner_namespace
    {
        double function(const int & i);
    }
}

we can declare a wrap like this

CPP_WRAP_FN_FIX((my_namespace, inner_namespace), function, double, (const int & val))
{
    return val;
}

CPP_WRAP_FN_FIX(unscoped_fun, double, (const int & val))
{
    return val;
}

Macro CPP_WRAP_MEM_FIX

Synopsis

// In header: <cpp/wrap.hpp>
CPP_WRAP_MEM_FIX(Type, Name, Return, Signature)
CPP_WRAP_MEM_FIX_NO_ARGS(Type, Name, Return)

Description

This macro can be used to declare a compile-time constant wrap for a member-functions. It will pass the this-pointer with the correct qualification as this_.

The type must be visible at the point of declaration of the wrap function.

It can be used with templates due to utilization of extern template, as shown in the tutorial.

There is currently no support for handling ref-qualifiers for the member-functions.

For an empty argument list the CPP_WRAP_MEM_FIX macro will use the [@https://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html trailing macro extension] in gcc. This might not work with some compilers, so that CPP_WRAP_MEM_FIX_NO_ARGS can be used.

Parameters

Name	Description
Name	The name of the function, without the scope.
Return	The return value of the function.
Signature	The parameter function list.
Type	The type the function is a member of including the qualifiers. Can be inside parenthesis, e.g. (const std::vector<int, std::allocator<int>>).

Example

Given two scoped functions like this

namespace my_namespace
{
    struct foo
    {
        int value = 42;

        int bar();
        int bar() const;
    };
}

we can declare a wrap like this

CPP_WRAP_MEM_FIX((const my_namespace::foo), bar, int, ())
{
    return this_->value;
}

CPP_WRAP_MEM_FIX(my_namespace::foo, bar, int, ())
{
    this_->other_val = 12;
    return this->other_val;
}

Macro CPP_WRAP_STATIC_MEM_FIX

Synopsis

// In header: <cpp/wrap.hpp>
CPP_WRAP_STATIC_MEM_FIX(Type, Name, Return, Signature)
CPP_WRAP_STATIC_MEM_FIX_NO_ARGS(Type, Name, Return)

Description

This macro can be used to declare a run-time wrap for a member-function. It can be used several times from different types, if they are not attempting to set it at the same time.

The type must be visible at the point of declaration of the wrap function.

It can be used with templates due to utilization of extern template, as shown in the tutorial.

For an empty argument list the CPP_WRAP_STATIC_MEM_FIX macro will use the trailing macro extension in gcc. This might not work with some compilers, so that CPP_WRAP_STATIC_MEM_FIX_NO_ARGS can be used.

Parameters

Name	Description
Name	The name of the function, without the scope
Return	The return value of the function
Signature	The parameter function list
Type	The type the function is a member of including the qualifiers. Can be inside parenthesis, e.g. (const std::vector<int, std::allocator<int>>).

Example

Given two scoped functions like this

namespace my_namespace
{
    struct foo
    {
        static int static_bar();
    };
}

we can declare a wrap like this

CPP_WRAP_STATIC_MEM_FIX(my_namespace::foo, static_bar, int, ())
{
    return 42;
}