This sectiolists all tags allowed in configuration file.

csproj

<csproj path="Path/ProjectName.csproj" cfg="Configuration" platform="Platform"/>

Refernce to input project file.

Attributes:

This attribute overrides path to project given to a translator application via command line.

outdir

<outdir path="Path"/>

Reference to output directory.

embedded_proj

<embedded_proj path="path/to/project"/>

Defines paths to embedded projects used in project being translated.

cppproj

<cppproj name="ProjectName"/>

Allows it to specify output project name.

opt

<opt name="Name" value="Value"/>

Translator option. See Configuration file options for details on what options are available.

additional_source

<additional_source>
    <copy dir="dir1"/>
    <copy dir="dir2"/>
</additional_source>

Directories to copy additional C++ sources from.

Only ‘copy’ subnodes are allowed inside ‘additional_source’ one.

copy

<copy dir="dir1"/>

Single directory to copy additional C++ source files from.

import

<import config="details.config"/>

Imports configuration file as if all its contents were added into the current one. Imported configuration file must have valid structure (‘porter’ node in the root and so on).

libs, style

<libs>
    <lib name="a">
        ...
    </lib>
</libs>
<style>
    <opt name="b" value="c"/>
    ...
</style>

Logical grouping. ‘libs’ element defines configuration file section which contains instructions on libraries attachment. ‘style’ element is meant to group style-related options.

Only ‘opt’ and ‘lib’ nodes are allowed inside both tags. Using ‘opt’ and ‘lib’ outside of ‘libs’ or ‘style’ is also allowed.

lib

<lib name="LibProject.Cpp">
    <tag path="path/path">Namespace::Namespace2::</tag>
    <cmake_part_template>
        find_botan()
    </cmake_part_template>
    <cmake_link_template>
        target_link_libraries(Project_name PUBLIC botan::botan LibProject::LibProject)
    </cmake_link_template>
    <defines>DEFINE1 DEFINE2;DEFINE3=VALUE</defines>
    <includes>path/to/dir1 path/to/dir2;path/to/dir3</includes>
    <libdirs>path/to/dir1 path/to/dir2;path/to/dir3</libdirs>
    <class name="LibProject::Class1" path="libproject/class1.h" shortptr="true"/>
    <enum name="LibProject::Enum1" path="libproject/enum1.h"/>
    <namespace name="LibProject::Namespace1" path="libproject/namespace1.h" shortptr="true"/>
    <replace_user_types>false</replace_user_types>
</lib>

Imports library to use against current project.

Meaning of allowed subnodes is explained below.

tag

<tag path="path/to/ns2/headers">Namespace::Namespace2::</tag>

Sets up header lookup rule. When translator meets a name from namespace given, it generates includes based on path specified, following the below rules:

• Each namespace inside tagged namespace is translated to a separate subdirectory;
• Class name corresponds to header name;
• Extension of file being included is .h;
• Namespaces and classes names are converted to underscore-delimited format even if they originally follow e. g. camelCase.

More specific rules (with innermore namespaces mentioned) override less specific ones. Explicit rules for individual types override tags.

For example, the above example implements such rule that references to class called ‘Namespace::Namespace2::Namespace3::FooBarClass’ will generate the following include:

#include "path/to/ns2/headers/namespace3/foo_bar_class.h"

Tag syntax is useful when implementing library manually. When using translated library, use typemap configuration file inclusion instead.

cmake_part_template

<cmake_part_template>
    find_botan()
</cmake_part_template>

Cmake rules to allow for includes and other neccessary setups like 3rd party libraries lookup.

cmake_link_template

<cmake_link_template>
    target_link_libraries(Project_name PUBLIC botan::botan LibProject::LibProject)
</cmake_link_template>

Cmake rules to allow for linkable units (DLLs, EXEs)

defines

<defines>DEFINE1 DEFINE2;DEFINE3=VALUE</defines>

Defines to be added to the project. Put library-related defines here rather than to global section of your configuration file as this make unnecessary define go once you exclude library-related file. Another benefit is keeping everything that relates to the library in a single place.

includes

<includes>path/to/dir1 path/to/dir2;path/to/dir3</includes>

Paths to include directories, related to the library. Again, allows keeping everything that is related to the library in a single place.

libdirs

<libdirs>path/to/dir1 path/to/dir2;path/to/dir3</libdirs>

Paths to library directories, related to the library.

class

<class name="LibProject::Class1" path="libproject/class1.h" shortptr="true"/>

Sets class-specific header path, useful for classes not covered by any tag rules.

enum

<enum name="LibProject::Enum1" path="libproject/enum1.h"/>

Sets enum-specific header path, useful for enums not covered by any tag rules.

namespace

<namespace name="LibProject::Namespace1" path="libproject/namespace1.h" shortptr="true"/>

Sets namespace-specific header path, useful for enums not covered by any tag rules.

replace_user_types

<replace_user_types>false</replace_user_types>

Forces the types in current project that are covered by any of the library tags to be ignored (skipped) - library-provided ones will be used instead. Useful if you add library to replace some types available in current build.

files

<files>
    <exclude file="/mask"/>
    <include file="/mask"/>
    <only file="/mask"/>
</files>

Adds file include and exclude masks. Masks should be prefixed with ‘/’. When these filters apply, priorities are as follows:

Allowed subnodes are listed below.

exclude

<exclude file="path/foo_*.cs"/>

Makes translator ignore all files in project that match the specified mask.

include

<include file="path/foo_bar_*.cs"/>

Stops translator from ignoring files that match the specified mask even if ignored otherwise (by ‘exclude’ or ‘only’ subnode).

only

<only file="path/bar_foo_*.cs"/>

Makes translator ignore all files that do not match the specified mask (or any of the masks specified in ‘only’ subnodes if multiple ones are present).

cut_namespaces

<cut_namespaces>
    <exclude file="mask"/>
    <include file="mask"/>
    <only file="mask"/>
</cut_namespaces>

Enable/disable namespaces cutting for all types, defined in specific files. The subnodes rules are identical with <files> option.

So, if the file ‘foo.cs’ containing type Bar.Foo is included using cut_namespace element, this type will be referred to as ‘Foo’ in translated code. Otherwise, it will be referred to as ‘Bar::Foo’.

typemap

<typemap>
    <class csname="Namespace1.Class1" cppname="Namespace2.Class2" box="false"/>
    ...
</typemap>

Maps C# type names into C++ ones. Useful if the default mapping fails.

The only allowed subnode is ‘class’.

class

<class csname="Namespace1.Class1" cppname="Namespace2.Class2" box="false"/>

Denotes a single mapping rule of how C# typename should be translated to C++.

includes

<includes>
    <class name="LibProject::Class1" path="libproject/class1.h" shortptr="true"/>
    <enum name="LibProject::Enum1" path="libproject/enum1.h"/>
    <namespace name="LibProject::Namespace1" path="libproject/namespace1.h"/>
    ...
</includes>

Specifies includes for specific types. Include rules, same as in “lib” section.

force_value_types

<force_value_types>
    <class name="Namespace1::Class1"/>
    <class name="Namespace2::Class2" box="true"/>
    ...
</force_value_types>

Lists the types to be treated as value types. Only ‘class’ subnodes are allowed.

class

<class name="Namespace1::Class1" box="false"/>

Class to be treated as value type.

references

<references>
    <assembly name="Assembly.Name" path="path\to\assembly.dll"/>
</references>

Specifies the references to external assemblies to import symbols from.

Only ‘assembly’ nodes are allowed here.

assembly

<assembly name="Assembly.Name" path="path\to\assembly.dll"/>

Single assembly to import symbols from.

dont_wrap_params

<dont_wrap_params>
    <class  name="Namespace::Class1"/>
    <method name="Namespace::Class2::Method1"/>
    ...
</dont_wrap_params>

Disables parameters wrapping (matching actual parameters against format ones with neccessary casts) against specific method or all methods of specific class. This is required if the method uses variadic template arguments and actual wrapping would fail.

Only ‘class’ and ‘method’ subnodes are allowed here.

class

<class name="Namespace::Class1"/>

Single class, all methods of which will not be wrapping parameters for.

method

<method name="Namespace::Class2::Method1"/>

Single method to not wrap parameters for. All methods with this name will be affected - there’s no way disabling parameter wrapping for single overload.

disable_boxing

<disable_boxing>
    <class name="System::Convert"/>
    <method name="System::Enum::Parse"/>
    ...
</disable_boxing>

Disables parameters boxing when type conversions occur (usually when native C++ implementations exist with better signatures). The syntax is same as for ‘dont_wrap_param’.

restricted_tokens

<restricted_tokens mask="*">
    <token from="OldName" to="NewName"/>
    ...
</restricted_tokens>

Replaces all identifiers specified globally in selected files.

token

<token from="OldName" to="NewName"/>

Single rule for identifier replacement.

assembly_with_restricted_tokens

<assembly_with_restricted_tokens>AssemblyName</assembly_with_restricted_tokens>

Forces the names in the referenced assembly to be replaced as per all restricted_tokens rules. By default, only the tokens in current assembly are replaced. No mask matching is performed.

skip_definitions

<skip_definitions stub="false" only_public_api="true"/>

Global version of ‘CppSkipDefinition’ attribute. If enabled, no class member definitions are processed (but declarations are still generated for them).

implementation

<implementation type="MyNamespace.MyClass" entity="MyMethod" includes="*someglobalheader;*otherglobalheader.h;path1/path2/header1.h;path1/path2/header2.h">
    <![CDATA[
        return 2+2;
    ]]>
</implementation>

<implementation file="OriginalFileName.cpp" to="source"/>

Substitutes some C++ implementation instead of translated one. First form allows it to store the implementation for the specified method in config itself. The second one copies the C++ file to destination directory.

Alternatively, you can simply include .cpp file into your C# project. It will be copied to output project during translating.

Please note that all methods you want to replace implementations for must be marked with CppSkipDefinition attribute.

nunit_categories

<nunit_categories>
    <include name="Category1"/>
    <exclude name="Category2"/>
</nunit_categories>

Allows it to filter tests by the category specified in NUnit.Framework.Category attribute. ‘exclude’ filter excludes single category. ‘include’ filter, if present, excludes all categories except for the one specified and for the ones specified in other ‘include’ filters, if present. ‘include’ directive has higher priority than ‘execlude’ one.

Only ‘include’ and ‘exclude’ elements are allowed inside ‘nunit_categories’ one.

For example, there are ‘A’, ‘B’, ‘C’ and ‘D’ categories and some uncategorized tests. If we exclude ‘A’ and ‘B’ categories, then only ‘C’, ‘D’ and uncategorized tests will be translated. If we additionally include ‘A’, then only ‘A’ category will be translated, as ‘include’ tag overweights any ‘exclude’ ones and, if present, excludes everything that is not included explicitly. If now we include ‘’ category, then only ‘A’, ‘C’, ‘D’ and uncategorized tests are translated as including ‘’ includes everything that was not excluded explicitly.

include

<include name="Category1"/>

Category for inclusion.

A special value of ‘’ can be assigned to the ‘name’ attribute of ‘include’ tag. If present, such tag changes the logic here. By default, everything that is not included explicitly, is excluded if there is at least one ‘include’ tag present. If there is a tag including ‘’ category, then everything that is not excluded explicitly gets included, instead.

exclude

<exclude name="Category1"/>

Category for exclusion.

cmake_commands

<cmake_commands>
<![CDATA[
    if (MSVC)
        set_target_properties(${PROJECT_NAME} PROPERTIES LINK_FLAGS "/INCREMENTAL:NO")
    endif()
]]>
</cmake_commands>

Allows it to push custom commands to resulting CMakeLists.txt file.

cmake_files

<cmake_files>
    <file name="file1.cmake" />
    ...
</cmake_files>

Lists cmake files to be copied from ‘cmake’ directory of translator installation to target project directory. Please note that each copy of this node clears all previously set ones, including the default values.

Only ‘file’ nodes are allowed inside.

file

<file name="file1.cmake" />

Single file to be copied.

enum_underlying_types

<enum_underlying_types>
    <type name="Enum1" value="int" />
    ...
</enum_underlying_types>

Maps enums underlying types. Mostly used by translator typemap when processing dependent projects.

Only ‘type’ nodes are allowed inside.

type

<type name="Enum1" value="int" />

Individual underlying type mapping rule.

attribute

<attribute name="CppAttributeName" ... />

Single attribute record. See Attributes in configuration file for more details.

forced_include

<forced_include>
    <class name="Namespace::ClassName" />
    <class name="Namespace::ClassName1" />
</forced_include>

Include header instead of forward declaration for an argument type, same as CppForceInclude attribute.

Only ‘class’ nodes are allowed inside.

class

<class name="Namespace::ClassName" />

Individual class to force includes for.

documentation_comments_translation

<documentation_comments_translation>
    <cref_typemap>
        <cref cstext="sbyte" cpptext="int8_t" />
    </cref_typemap>
    <summary_text_map>
        <property cstext="Gets or sets" getter_text="Gets" setter_text="Sets" />
    </summary_text_map>
    <options>
        <opt name="fix_setter_return_tag" value="true" />
    </options>
    <replacements>
        <comment  type="SomeNS.Enum1" member="" tag="code">
            <![CDATA[
C++ code Enum1
]]>
        </comment>
    </replacements>
    <translate_code_from_comments value="true"/>
    <translate_code_from_comments_system_dlls>
        <system_dll name="System.Something.dll"/>
    </translate_code_from_comments_system_dlls>
</documentation_comments_translation>

Parameters for code documentation.

The following subsections are allowed:

• cref_typemap - list of type references to be translated and supplied to Doxygen. The following child nodes are allowed:
  • cref - one type; cstext attribute names type in C# and cpptext names corresponding type in C++.
• summary_text_map - list of substrings which should be replaced when generating individual getter and setter comments from joint getter+setter comment in C#.
  • property - individual replacement entry. cstext attribute means text to be replaced, getter_text is replacement for getter and setter_text is replacement for setter.
• options - list of options related to documentation generation. The following options are allowed:
  • fix_setter_return_tag - remove ‘return’ tag from setter documentation.
• replacements - list of allowed replacements for the specified tags in comments to specified items.
  • comment - the contents of this item will replace the contents of specified tag of the specified member of specified tag. If both type and member are unset, this replacement will be done by default to all occurrances of mentioned tag where no other replacements apply.

For mentioned subtags attributes, see below.

cref_typemap

cref

summary_text_map

property

options

replacements

Defines exact replacement for contents of specific tag in documentation for type or type member.

translate_code_from_comments

Enables the translator replacing references to C# types and members with C++ analogs.

Since version: 21.2

translate_code_from_comments_system_dlls

Adds specified DLLs to symbol lookup when replacing references in documentation comments. No longer required since 21.3 version.

system_dll

Specifies a single DLL to add to this list.

Since version: 21.2

if

<if defined="my_var">
    <opt name="additional_defines" value="SOME_DEFINES"/>
    <else>
        <opt name="additional_defines" value="SOME_OTHER_DEFINES"/>
    </else>
</if>

Allows to switch on or off some part of the config conditionally, based on command line parameters passed to translator: if ‘-d’ command line parameter followed by definition name is passed, all contents of ‘if’ tag except for ‘else’ subtag is executed (in the above example - first ‘opt’ element); otherwise, only ‘else’ tag is executed (in the above example - second ‘opt’ tag).

else

<else>
    <opt name="additional_defines" value="SOME_OTHER_DEFINES"/>
</else>

Part of the config which should be executed if ‘if’ element evaluation fails.

msbuild_global_properties

<msbuild_global_properties>
    <property name="TargetFramework" value="net20"/>
</msbuild_global_properties>

Allows to define MSBuild properties directly to satisfy conditions in csproj file.

Allowed sub-items:

property

rename_files

<rename_files>
    <file name_without_extension="FileToRename" to="RenamedFile"/>
</rename_files>

Allows to rename files generated by translator. Impacts both ‘.h’ and ‘.cpp’ file (if exist).

Allowed sub-items:

file

allowed_heap_only_types

<allowed_heap_only_types>
    <class name="System.Xml.XPath.XPathNodeIterator" />
</allowed_heap_only_types>

Makes translator generate code that produces compilation error if specified class is being allocated on stack. Useful for the classes that create shared pointers to themselves and thus are incompatible with automatic memory management.

Since version: 20.1.

Allowed sub-items:

class

types_with_begin_and_end_methods

<types_with_begin_and_end_methods>
    <class name="System.Collections.Generic.Dictionary" />
</types_with_begin_and_end_methods>

Makes translator generate simplier code for ‘foreach’ statements, if ‘foreach_as_range_based_for_loop’ option is enabled.

Since version: 20.8.

Allowed sub-items:

class

assembly_types

<assembly_types>
   <class name="Namespace.ClassName" />
</assembly_types>

Makes translator register specified types in the Assembly object which is associated with current project. Unless the type is registered, TypeInfo::get_Assembly() doesn’t work for it.

Since version: 20.10.

Allowed sub-items:

class

unity_build

<unity_build batch_size="16">
  <excluded_files>
    <file name="main.cpp" />
  </excluded_files>
</unity_build>

Enables the building process using UNITY_BUILD for the translated project.

Since version: 21.6.

Allowed sub-items:

excluded_files

Contains a list of files that must be excluded from UNITY_BUILD.

Allowed sub-items:

file

external_include

<external_include file="AddFunctionArgument_PassFunctionArgument_Tests.cs" include="function_traits.hpp" include_to="source" include_as="local"/>

Makes the translator generate additional include directives into the translated version of the specified cs file. Can do the same thing CppForceInclude attribute does, but can also include any file the translator doesn’t know about.

Since version: 21.9.

events_with_custom_accessors

<events_with_custom_accessors>
    <event name="System.Xml.XmlReaderSettings.ValidationEventHandler"/>
    <event name="System.Xml.XmlValidatingReader.ValidationEventHandler"/>
    <event name="System.Xml.Schema.XmlSchemaSet.ValidationEventHandler"/>
</events_with_custom_accessors>

Makes the translator generate <PropertyName>_add()/<PropertyName>_remove() calls instead of +=/-= operators for specified custom events.

Allowed sub-items:

event

Since version: 22.1.