From 0a37ad7e98ef912dc730842bb2976561b6371e98 Mon Sep 17 00:00:00 2001 From: Jan Kotas Date: Tue, 4 Dec 2018 12:43:01 -0800 Subject: [PATCH] Add native library sample (#6645) * fix nit in StaticLibrary test (#4987) * add README documentation on building native libraries (#4987) * Move documentation for building native libraries to samples * Fix static library build * Add sources for NativeLibrary sample --- ...-run-ilcompiler-in-console-shell-prompt.md | 2 +- README.md | 2 +- samples/NativeLibrary/Class1.cs | 18 +++++++ samples/NativeLibrary/NativeCallable.cs | 14 +++++ samples/NativeLibrary/NativeLibrary.csproj | 11 ++++ samples/NativeLibrary/README.md | 54 +++++++++++++++++++ .../Microsoft.NETCore.Native.Publish.targets | 2 +- .../Simple/StaticLibrary/StaticLibrary.csproj | 4 +- 8 files changed, 102 insertions(+), 5 deletions(-) create mode 100644 samples/NativeLibrary/Class1.cs create mode 100644 samples/NativeLibrary/NativeCallable.cs create mode 100644 samples/NativeLibrary/NativeLibrary.csproj create mode 100644 samples/NativeLibrary/README.md diff --git a/Documentation/how-to-build-and-run-ilcompiler-in-console-shell-prompt.md b/Documentation/how-to-build-and-run-ilcompiler-in-console-shell-prompt.md index 9bb40ce48d2..506535d32f6 100644 --- a/Documentation/how-to-build-and-run-ilcompiler-in-console-shell-prompt.md +++ b/Documentation/how-to-build-and-run-ilcompiler-in-console-shell-prompt.md @@ -75,7 +75,7 @@ From the shell/command prompt, issue the following commands to generate the nati For CoreRT debug build on Windows, add an extra `/p:AdditionalCppCompilerFlags=/MTd` argument. -## Disabling Native Compilation +## Disabling Native Compilation ## Native compilation can be disabled during publishing by adding an extra `/p:NativeCompilationDuringPublish=false` argument. diff --git a/README.md b/README.md index e652b703c4c..6a89443174f 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ This repo contains the .NET Core runtime optimized for ahead of time compilation ## Try Our Samples -If you would like to give CoreRT a try, we publish daily snapshots of CoreRT to MyGet. Using CoreRT is as simple as adding a new package reference to your .NET Core project and publishing it. Check out one of our samples: a "[Hello World](samples/HelloWorld)" console app, a simple [ASP.NET Core](samples/WebApi/) app, or a [MonoGame](samples/MonoGame/) game. The `README.md` file in each sample's directory will guide you through the process step by step. +If you would like to give CoreRT a try, we publish daily snapshots of CoreRT to MyGet. Using CoreRT is as simple as adding a new package reference to your .NET Core project and publishing it. Check out one of our samples: a "[Hello World](samples/HelloWorld)" console app, a simple [ASP.NET Core](samples/WebApi/) app, a [MonoGame](samples/MonoGame/) game or a [native library](samples/NativeLibrary). The `README.md` file in each sample's directory will guide you through the process step by step. ## Platform Support diff --git a/samples/NativeLibrary/Class1.cs b/samples/NativeLibrary/Class1.cs new file mode 100644 index 00000000000..cd15eb20057 --- /dev/null +++ b/samples/NativeLibrary/Class1.cs @@ -0,0 +1,18 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. +// See the LICENSE file in the project root for more information. + +using System; +using System.Runtime.InteropServices; + +namespace NativeLibrary +{ + public class Class1 + { + [NativeCallable(EntryPoint = "add", CallingConvention = CallingConvention.StdCall)] + public static int Add(int a, int b) + { + return a + b; + } + } +} diff --git a/samples/NativeLibrary/NativeCallable.cs b/samples/NativeLibrary/NativeCallable.cs new file mode 100644 index 00000000000..a96a6c793a3 --- /dev/null +++ b/samples/NativeLibrary/NativeCallable.cs @@ -0,0 +1,14 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. +// See the LICENSE file in the project root for more information. + +namespace System.Runtime.InteropServices +{ + [AttributeUsage(AttributeTargets.Method)] + public sealed class NativeCallableAttribute : Attribute + { + public string EntryPoint; + public CallingConvention CallingConvention; + public NativeCallableAttribute() { } + } +} diff --git a/samples/NativeLibrary/NativeLibrary.csproj b/samples/NativeLibrary/NativeLibrary.csproj new file mode 100644 index 00000000000..6ece035065a --- /dev/null +++ b/samples/NativeLibrary/NativeLibrary.csproj @@ -0,0 +1,11 @@ + + + + netstandard2.0 + + + + + + + diff --git a/samples/NativeLibrary/README.md b/samples/NativeLibrary/README.md new file mode 100644 index 00000000000..ce07fef4f1f --- /dev/null +++ b/samples/NativeLibrary/README.md @@ -0,0 +1,54 @@ +# Building Native Libraries with CoreRT + +This document will guide you through building native libraries that can be consumed by other programming languages with CoreRT. CoreRT can build static libraries that can be linked at compile time or shared libraries that are required at runtime. + +## Create .NET Core Class Library project with CoreRT support + +Create a .NET Core class library project using `dotnet new console -o NativeLibrary` and follow the [Hello world](../HelloWorld/README.md) sample instruction to add CoreRT support to it. + +## Building static libraries + +```bash +> dotnet publish /p:NativeLib=Static -r -c +``` + +where `` is your project configuration (such as Debug or Release) and `` is the runtime identifier (one of win-x64, linux-x64, osx-x64). For example, if you want to publish a release configuration of your library for a 64-bit version of Windows the command would look like: + +```bash +> dotnet publish /p:NativeLib=Static -r win-x64 -c release +``` + +The above command will drop a static library (Windows `.lib`, OSX/Linux `.a`) in `./bin/[configuration]/netstandard2.0/[RID]/publish/` folder and will have the same name as the folder in which your source file is present. + +## Building shared libraries + +```bash +> dotnet publish /p:NativeLib=Shared -r -c +``` + +The above command will drop a shared library (Windows `.dll`, OSX `.dylib`, Linux `.so`) in `./bin/[configuration]/netstandard2.0/[RID]/publish/` folder and will have the same name as the folder in which your source file is present. Building shared libraries on Linux is currently non-functional, see [#4988](https://github.com/dotnet/corert/issues/4988). + +## Exporting methods + +For a C# method in the native library to be consumable by external programs, it has to be explicitly exported using the `[NativeCallable]` attribute. First define the `NativeCallable` class in your project, see [here](https://github.com/dotnet/corert/blob/master/tests/src/Simple/SharedLibrary/NativeCallable.cs). The local definition of the `NativeCallable` is a temporary workaround that will go away once the attribute is added to the official .NET Core public surface. + +Next, apply the attribute to the method, specifying the `EntryPoint` and `CallingConvention` properties: + +```csharp +[NativeCallable(EntryPoint = "add", CallingConvention = CallingConvention.StdCall)] +public static int Add(int a, int b) +{ + return a + b; +} +``` + +After the native library library is built, the above C# `Add` method will be exported as a native `add` function to consumers of the library. Here are some limitations to consider when deciding what managed method to export: + +* Exported methods have to be static. +* Exported methods can only naturally accept or return primitives or value types (i.e structs), they have to marshal all reference type arguments. +* Exported methods cannot be called from regular managed C# code, an exception will be thrown. +* Exported methods cannot use regular C# exception handling, they should return error codes instead. + +## References + +Real-world example of using CoreRT and Rust: https://medium.com/@chyyran/calling-c-natively-from-rust-1f92c506289d diff --git a/src/BuildIntegration/Microsoft.NETCore.Native.Publish.targets b/src/BuildIntegration/Microsoft.NETCore.Native.Publish.targets index 3bbea7e9e65..3b2e9e9a583 100644 --- a/src/BuildIntegration/Microsoft.NETCore.Native.Publish.targets +++ b/src/BuildIntegration/Microsoft.NETCore.Native.Publish.targets @@ -77,7 +77,7 @@ - + diff --git a/tests/src/Simple/StaticLibrary/StaticLibrary.csproj b/tests/src/Simple/StaticLibrary/StaticLibrary.csproj index 591b8644b35..b3477312a6e 100644 --- a/tests/src/Simple/StaticLibrary/StaticLibrary.csproj +++ b/tests/src/Simple/StaticLibrary/StaticLibrary.csproj @@ -44,8 +44,8 @@ - - + +