Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Ethereal77/ClangSharpPInvoke

Open more actions menu
 
 

Repository files navigation

ClangSharp P/Invoke Generator

This is a fork of ClangSharp simplified to only include the P/Invoke generator tool and reference ClangSharp as a package reference instead of as a project reference.

The purpose of this is to allow easier modification and experimentation with the P/Invoke generation process without needing the native parts.

ci

Please refer to the original repository for more information about ClangSharp, the tool, etc.

Many thanks to Tanner Gooding and the .NET Foundation for this awesome tool.

NOTE: This repository does not accept any issues or PRs. If you want to contribute to ClangSharp or open an issue, do so on the original repository.

Below this is the original README.md of ClangSharp with the parts that talk about the native projects omitted.


Table of Contents

License

Copyright (c) .NET Foundation and Contributors. All Rights Reserved. Licensed under the MIT License (MIT). See LICENSE.md in the repository root for more information.

Building

ClangSharp requires the .NET 8 SDK and can be built simply with dotnet build -c Release.

There are several build scripts in the repository root. On Windows these scripts end with .cmd and expect arguments with a - prefix. On Unix these scripts end with .sh and expect arguments with a -- prefix. By default, each script performs only the action specified in its name (i.e. restore only restores, build only builds, and test only tests). You can specify additional actions to be run by passing that name as an argument to the script (e.g. build.cmd -restore will perform a package restore and build; build.cmd -test will build and run tests). Certain actions are dependent on a previous action having been run at least once. build depends on restore, and test depends on build. This means the recommended first time action is build -restore.

You can see any additional options that are available by passing -help on Windows or --help on Unix to the available build scripts.

Generating Bindings

This program will take a given set of C or C++ header files and generate C# bindings from them. It is still a work-in-progress and not every declaration can have bindings generated today (contributions are welcome).

The simplest and recommended setup is to install the generator as a .NET tool and then use response files:

dotnet tool install --global ClangSharpPInvokeGenerator --version 20.1.2
ClangSharpPInvokeGenerator @generate.rsp

A response file allows you to specify and checkin the command line arguments in a text file, with one argument per line. For example: https://github.com/dotnet/ClangSharp/blob/main/sources/ClangSharpPInvokeGenerator/Properties/GenerateClang.rsp At a minimum, the command line expects one or more input files (-f), an output namespace (-n), and an output location (-o). A typical response file may also specify explicit files to traverse, configuration options, name remappings, and other fixups.

The full set of available switches:

ClangSharpPInvokeGenerator
  ClangSharp P/Invoke Binding Generator

Usage:
  ClangSharpPInvokeGenerator [options]

Options:
  -a, --additional <additional>                                    An argument to pass to Clang when parsing the input files. []
  -c, --config <config>                                            A configuration option that controls how the bindings are generated. Specify 'help' to see the available options. []
  -D, --define-macro <define-macro>                                Define <macro> to <value> (or 1 if <value> omitted). []
  -e, --exclude <exclude>                                          A declaration name to exclude from binding generation. []
  -f, --file <file>                                                A file to parse and generate bindings for. []
  -F, --file-directory <file-directory>                            The base path for files to parse. []
  -hf, --headerFile <headerFile>                                   A file which contains the header to prefix every generated file with. []
  -i, --include <include>                                          A declaration name to include in binding generation. []
  -I, --include-directory <include-directory>                      Add directory to include search path. []
  -x, --language <c|c++>                                           Treat subsequent input files as having type <language>. [default: c++]
  -l, --libraryPath <libraryPath>                                  The string to use in the DllImport attribute used when generating bindings. []
  -m, --methodClassName <methodClassName>                          The name of the static class that will contain the generated method bindings. [default: Methods]
  -n, --namespace <namespace>                                      The namespace in which to place the generated bindings. []
  -om, --output-mode <CSharp|Xml>                                  The mode describing how the information collected from the headers are presented in the resultant bindings. [default: CSharp]
  -o, --output <output>                                            The output location to write the generated bindings to. []
  -p, --prefixStrip <prefixStrip>                                  The prefix to strip from the generated method bindings. []
  --nativeTypeNamesToStrip <nativeTypeNamesToStrip>                The contents to strip from the generated NativeTypeName attributes. []
  -r, --remap <remap>                                              A declaration name to be remapped to another name during binding generation. []
  -std <std>                                                       Language standard to compile for. []
  -to, --test-output <test-output>                                 The output location to write the generated tests to. []
  -t, --traverse <traverse>                                        A file name included either directly or indirectly by -f that should be traversed during binding generation. []
  -v, --version                                                    Prints the current version information for the tool and its native dependencies.
  -was, --with-access-specifier <with-access-specifier>            An access specifier to be used with the given qualified or remapped declaration name during binding generation. Supports wildcards. []
  -wa, --with-attribute <with-attribute>                           An attribute to be added to the given remapped declaration name during binding generation. Supports wildcards. []
  -wcc, --with-callconv <with-callconv>                            A calling convention to be used for the given declaration during binding generation. Supports wildcards. []
  -wc, --with-class <with-class>                                   A class to be used for the given remapped constant or function declaration name during binding generation. Supports wildcards. []
  -wg, --with-guid <with-guid>                                     A GUID to be used for the given declaration during binding generation. Supports wildcards. []
  -wl, --with-length <with-length>                                 A length to be used for the given declaration during binding generation. Supports wildcards. []
  -wlb, --with-librarypath <with-librarypath>                      A library path to be used for the given declaration during binding generation. Supports wildcards. []
  -wmi, --with-manual-import <with-manual-import>                  A remapped function name to be treated as a manual import during binding generation. Supports wildcards. []
  -wn, --with-namespace <with-namespace>                           A namespace to be used for the given remapped declaration name during binding generation. Supports wildcards. []
  -wp, --with-packing <with-packing>                               Overrides the StructLayoutAttribute.Pack property for the given type. Supports wildcards. []
  -wsle, --with-setlasterror <with-setlasterror>                   Add the SetLastError=true modifier or SetsSystemLastError attribute to a given DllImport or UnmanagedFunctionPointer. Supports wildcards. []
  -wsgct, --with-suppressgctransition <with-suppressgctransition>  Add the SuppressGCTransition calling convention to a given DllImport or UnmanagedFunctionPointer. Supports wildcards. []
  -wts, --with-transparent-struct <with-transparent-struct>        A remapped type name to be treated as a transparent wrapper during binding generation. Supports wildcards. []
  -wt, --with-type <with-type>                                     A type to be used for the given enum declaration during binding generation. Supports wildcards. []
  -wu, --with-using <with-using>                                   A using directive to be included for the given remapped declaration name during binding generation. Supports wildcards. []
  -?, -h, --help                                                   Show help and usage information

Wildcards:
You can use * as catch-all rule for remapping procedures. For example if you want make all of your generated code internal you can use --with-access-specifier *=Internal.

The available configuration options (visible with -c help) are:

--config, -c    A configuration option that controls how the bindings are generated. Specify 'help' to see the available options.

Options:
  ?, h, help                             Show help and usage information for -c, --config

  # Codegen Options

  compatible-codegen                     Bindings should be generated with .NET Standard 2.0 compatibility. Setting this disables preview code generation.
  default-codegen                        Bindings should be generated for the previous LTS version of .NET/C#. This is currently .NET 6/C# 10.
  latest-codegen                         Bindings should be generated for the current LTS/STS version of .NET/C#. This is currently .NET 8/C# 12.
  preview-codegen                        Bindings should be generated for the preview version of .NET/C#. This is currently .NET 9/C# 13.

  # File Options

  single-file                            Bindings should be generated to a single output file. This is the default.
  multi-file                             Bindings should be generated so there is approximately one type per file.

  # Type Options

  unix-types                             Bindings should be generated assuming Unix defaults. This is the default on Unix platforms.
  windows-types                          Bindings should be generated assuming Windows defaults. This is the default on Windows platforms.

  # Exclusion Options

  exclude-anonymous-field-helpers        The helper ref properties generated for fields in nested anonymous structs and unions should not be generated.
  exclude-com-proxies                    Types recognized as COM proxies should not have bindings generated. These are currently function declarations ending with _UserFree, _UserMarshal, _UserSize, _UserUnmarshal, _Proxy, or _Stub.
  exclude-default-remappings             Default remappings for well known types should not be added. This currently includes intptr_t, ptrdiff_t, size_t, and uintptr_t
  exclude-empty-records                  Bindings for records that contain no members should not be generated. These are commonly encountered for opaque handle like types such as HWND.
  exclude-enum-operators                 Bindings for operators over enum types should not be generated. These are largely unnecessary in C# as the operators are available by default.
  exclude-fnptr-codegen                  Generated bindings for latest or preview codegen should not use function pointers.
  exclude-funcs-with-body                Bindings for functions with bodies should not be generated.
  exclude-using-statics-for-enums        Enum usages should be fully qualified and should not include a corresponding 'using static EnumName;'

  # Vtbl Options

  explicit-vtbls                         VTBLs should have an explicit type generated with named fields per entry.
  implicit-vtbls                         VTBLs should be implicit to reduce metadata bloat. This is the current default
  trimmable-vtbls                        VTBLs should be defined but not used in helper methods to reduce metadata bloat when trimming.

  # Test Options

  generate-tests-nunit                   Basic tests validating size, blittability, and associated metadata should be generated for NUnit.
  generate-tests-xunit                   Basic tests validating size, blittability, and associated metadata should be generated for XUnit.

  # Generation Options

  generate-aggressive-inlining           [MethodImpl(MethodImplOptions.AggressiveInlining)] should be added to generated helper functions.
  generate-callconv-member-function      Instance function pointers should use [CallConvMemberFunction] where applicable.
  generate-cpp-attributes                [CppAttributeList("")] should be generated to document the encountered C++ attributes.
  generate-disable-runtime-marshalling   [assembly: DisableRuntimeMarshalling] should be generated.
  generate-doc-includes                  <include> xml documentation tags should be generated for declarations.
  generate-file-scoped-namespaces        Namespaces should be scoped to the file to reduce nesting.
  generate-guid-member                   Types with an associated GUID should have a corresponding member generated.
  generate-helper-types                  Code files should be generated for various helper attributes and declared transparent structs.
  generate-macro-bindings                Bindings for macro-definitions should be generated. This currently only works with value like macros and not function-like ones.
  generate-marker-interfaces             Bindings for marker interfaces representing native inheritance hierarchies should be generated.
  generate-native-bitfield-attribute     [NativeBitfield("", offset: #, length: #)] attribute should be generated to document the encountered bitfield layout.
  generate-native-inheritance-attribute  [NativeInheritance("")] attribute should be generated to document the encountered C++ base type.
  generate-generic-pointer-wrapper       Pointer<T> should be used for limited generic type support.
  generate-setslastsystemerror-attribute [SetsLastSystemError] attribute should be generated rather than using SetLastError = true.
  generate-template-bindings             Bindings for template-definitions should be generated. This is currently experimental.
  generate-unmanaged-constants           Unmanaged constants should be generated using static ref readonly properties. This is currently experimental.
  generate-vtbl-index-attribute          [VtblIndex(#)] attribute should be generated to document the underlying VTBL index for a helper method.

  # Stripping Options

  strip-enum-member-type-name            Strips the enum type name from the beginning of its member names.

  # Logging Options

  log-exclusions                         A list of excluded declaration types should be generated. This will also log if the exclusion was due to an exact or partial match.
  log-potential-typedef-remappings       A list of potential typedef remappings should be generated. This can help identify missing remappings.
  log-visited-files                      A list of the visited files should be generated. This can help identify traversal issues.

Using locally built versions

After you build local version, you can use executable from build location.

artifacts/bin/sources/ClangSharpPInvokeGenerator/Debug/net8.0/ClangSharpPInvokeGenerator

If you are on Linux

LD_LIBRARY_PATH=$(pwd)/artifacts/bin/native/lib/
artifacts/bin/sources/ClangSharpPInvokeGenerator/Debug/net8.0/ClangSharpPInvokeGenerator

Spotlight

The P/Invoke Generator is currently used by several projects:

About

Clang P/Invoke bindings generator .NET written in C#

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published

Languages

  • C# 99.8%
  • Other 0.2%
Morty Proxy This is a proxified and sanitized view of the page, visit original site.