[C#] Fix and improve project files (#6142)
* [C#] Fix and improve project files * "net35" target included for Unity 5 * "net46" target included for Unity 2017 * "netstandard2.0" target included for Unity 2018 and general use * "netstandard2.1" target included for Span<T> support Included project properties for defining UNSAFE_BYTEBUFFER, BYTEBUFFER_NO_BOUNDS_CHECK, and ENABLE_SPAN_T conditional compilation symbols. * Add documentation on building for C#
This commit is contained in:
Conan Chen
GitHub
parent
2eedc769d5
commit
0bdf2fa156
|
|
@ -14,14 +14,38 @@ documentation to build `flatc` and should be familiar with
|
|||
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
|
||||
[Writing a schema](@ref flatbuffers_guide_writing_schema).
|
||||
|
||||
## FlatBuffers C-sharp code location
|
||||
## FlatBuffers C# code location
|
||||
|
||||
The code for the FlatBuffers C# library can be found at
|
||||
`flatbuffers/net/FlatBuffers`. You can browse the library on the
|
||||
[FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/net/
|
||||
FlatBuffers).
|
||||
|
||||
## Testing the FlatBuffers C-sharp libraries
|
||||
## Building the FlatBuffers C# library
|
||||
|
||||
The `FlatBuffers.csproj` project contains multitargeting for .NET Standard 2.1,
|
||||
.NET Standard 2.0, and .NET Framework 4.6 (Unity 2017). Support for .NET
|
||||
Framework 3.5 (Unity 5) is provided by the `FlatBuffers.net35.csproj` project.
|
||||
In most cases (including Unity 2018 and newer), .NET Standard 2.0 is
|
||||
recommended.
|
||||
|
||||
You can build for a specific framework target when using the cross-platform
|
||||
[.NET Core SDK](https://dotnet.microsoft.com/download) by adding the `-f`
|
||||
command line option:
|
||||
|
||||
~~~{.sh}
|
||||
dotnet build -f netstandard2.0 "FlatBuffers.csproj"
|
||||
~~~
|
||||
|
||||
The `FlatBuffers.csproj` project also provides support for defining various
|
||||
conditional compilation symbols (see "Conditional compilation symbols" section
|
||||
below) using the `-p` command line option:
|
||||
|
||||
~~~{.sh}
|
||||
dotnet build -f netstandard2.1 -p:ENABLE_SPAN_T=true -p:UNSAFE_BYTEBUFFER=true "FlatBuffers.csproj"
|
||||
~~~
|
||||
|
||||
## Testing the FlatBuffers C# library
|
||||
|
||||
The code to test the libraries can be found at `flatbuffers/tests`.
|
||||
|
||||
|
|
@ -31,12 +55,12 @@ tests, open `FlatBuffers.Test.csproj` in [Visual Studio](
|
|||
https://www.visualstudio.com), and compile/run the project.
|
||||
|
||||
Optionally, you can run this using [Mono](http://www.mono-project.com/) instead.
|
||||
Once you have installed `Mono`, you can run the tests from the command line
|
||||
Once you have installed Mono, you can run the tests from the command line
|
||||
by running the following commands from inside the `FlatBuffers.Test` folder:
|
||||
|
||||
~~~{.sh}
|
||||
mcs *.cs ../MyGame/Example/*.cs ../../net/FlatBuffers/*.cs
|
||||
mono Assert.exe
|
||||
mcs *.cs ../MyGame/Example/*.cs ../../net/FlatBuffers/*.cs
|
||||
mono Assert.exe
|
||||
~~~
|
||||
|
||||
## Using the FlatBuffers C# library
|
||||
|
|
@ -74,7 +98,7 @@ Now you can access the data from the `Monster monster`:
|
|||
Vec3 pos = monster.Pos;
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
C# code naming follows standard C# style with `PascalCasing` identifiers,
|
||||
C# code naming follows standard C# style with PascalCasing identifiers,
|
||||
e.g. `GetRootAsMyRootType`. Also, values (except vectors and unions) are
|
||||
available as properties instead of parameterless accessor methods.
|
||||
The performance-enhancing methods to which you can pass an already created
|
||||
|
|
@ -133,8 +157,8 @@ around using as little as possible of it. This does make the API clumsier
|
|||
|
||||
For times when efficiency is less important a more convenient object based API
|
||||
can be used (through `--gen-object-api`) that is able to unpack & pack a
|
||||
FlatBuffer into objects and standard System.Collections.Generic containers, allowing for convenient
|
||||
construction, access and mutation.
|
||||
FlatBuffer into objects and standard `System.Collections.Generic` containers,
|
||||
allowing for convenient construction, access and mutation.
|
||||
|
||||
To use:
|
||||
|
||||
|
|
@ -172,4 +196,31 @@ add `Newtonsoft.Json` nuget package to csproj.
|
|||
* NuGet package Dependency
|
||||
* [Newtonsoft.Json](https://github.com/JamesNK/Newtonsoft.Json)
|
||||
|
||||
## Conditional compilation symbols
|
||||
|
||||
There are three conditional compilation symbols that have an impact on
|
||||
performance/features of the C# `ByteBuffer` implementation.
|
||||
|
||||
* `UNSAFE_BYTEBUFFER`
|
||||
|
||||
This will use unsafe code to manipulate the underlying byte array. This can
|
||||
yield a reasonable performance increase.
|
||||
|
||||
* `BYTEBUFFER_NO_BOUNDS_CHECK`
|
||||
|
||||
This will disable the bounds check asserts to the byte array. This can yield a
|
||||
small performance gain in normal code.
|
||||
|
||||
* `ENABLE_SPAN_T`
|
||||
|
||||
This will enable reading and writing blocks of memory with a `Span<T>` instead
|
||||
of just `T[]`. You can also enable writing directly to shared memory or other
|
||||
types of memory by providing a custom implementation of `ByteBufferAllocator`.
|
||||
`ENABLE_SPAN_T` also requires `UNSAFE_BYTEBUFFER` to be defined, or .NET
|
||||
Standard 2.1.
|
||||
|
||||
Using `UNSAFE_BYTEBUFFER` and `BYTEBUFFER_NO_BOUNDS_CHECK` together can yield a
|
||||
performance gain of ~15% for some operations, however doing so is potentially
|
||||
dangerous. Do so at your own risk!
|
||||
|
||||
<br>
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@
|
|||
* limitations under the License.
|
||||
*/
|
||||
|
||||
// There are 3 #defines that have an impact on performance / features of this ByteBuffer implementation
|
||||
// There are three conditional compilation symbols that have an impact on performance/features of this ByteBuffer implementation.
|
||||
//
|
||||
// UNSAFE_BYTEBUFFER
|
||||
// This will use unsafe code to manipulate the underlying byte array. This
|
||||
|
|
@ -22,13 +22,14 @@
|
|||
//
|
||||
// BYTEBUFFER_NO_BOUNDS_CHECK
|
||||
// This will disable the bounds check asserts to the byte array. This can
|
||||
// yield a small performance gain in normal code..
|
||||
// yield a small performance gain in normal code.
|
||||
//
|
||||
// ENABLE_SPAN_T
|
||||
// This will enable reading and writing blocks of memory with a Span<T> instead if just
|
||||
// This will enable reading and writing blocks of memory with a Span<T> instead of just
|
||||
// T[]. You can also enable writing directly to shared memory or other types of memory
|
||||
// by providing a custom implementation of ByteBufferAllocator.
|
||||
// ENABLE_SPAN_T also requires UNSAFE_BYTEBUFFER to be defined
|
||||
// ENABLE_SPAN_T also requires UNSAFE_BYTEBUFFER to be defined, or .NET
|
||||
// Standard 2.1.
|
||||
//
|
||||
// Using UNSAFE_BYTEBUFFER and BYTEBUFFER_NO_BOUNDS_CHECK together can yield a
|
||||
// performance gain of ~15% for some operations, however doing so is potentially
|
||||
|
|
|
|||
|
|
@ -1,19 +0,0 @@
|
|||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<PropertyGroup>
|
||||
<TargetFrameworks>netstandard2.0;netstandard2.1</TargetFrameworks>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<Compile Remove="Properties\**" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<EmbeddedResource Remove="Properties\**" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<None Remove="Properties\**" />
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
|
|
@ -1,54 +1,23 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
|
||||
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<PropertyGroup>
|
||||
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
|
||||
<Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
|
||||
<ProjectGuid>{28C00774-1E73-4A75-AD8F-844CD21A064D}</ProjectGuid>
|
||||
<OutputType>Library</OutputType>
|
||||
<AppDesignerFolder>Properties</AppDesignerFolder>
|
||||
<RootNamespace>FlatBuffers</RootNamespace>
|
||||
<AssemblyName>FlatBuffers</AssemblyName>
|
||||
<TargetFrameworkVersion>v3.5</TargetFrameworkVersion>
|
||||
<FileAlignment>512</FileAlignment>
|
||||
<TargetFrameworks>netstandard2.1;netstandard2.0;net46</TargetFrameworks>
|
||||
<GenerateAssemblyInfo>false</GenerateAssemblyInfo>
|
||||
</PropertyGroup>
|
||||
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
|
||||
<DebugSymbols>true</DebugSymbols>
|
||||
<DebugType>full</DebugType>
|
||||
<Optimize>false</Optimize>
|
||||
<OutputPath>bin\Debug\</OutputPath>
|
||||
<DefineConstants>DEBUG;TRACE</DefineConstants>
|
||||
<ErrorReport>prompt</ErrorReport>
|
||||
<WarningLevel>4</WarningLevel>
|
||||
|
||||
<PropertyGroup Condition="'$(UNSAFE_BYTEBUFFER)' == 'true'">
|
||||
<DefineConstants>$(DefineConstants);UNSAFE_BYTEBUFFER</DefineConstants>
|
||||
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
|
||||
</PropertyGroup>
|
||||
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
|
||||
<DebugType>pdbonly</DebugType>
|
||||
<Optimize>true</Optimize>
|
||||
<OutputPath>bin\Release\</OutputPath>
|
||||
<DefineConstants>TRACE</DefineConstants>
|
||||
<ErrorReport>prompt</ErrorReport>
|
||||
<WarningLevel>4</WarningLevel>
|
||||
<PropertyGroup Condition="'$(BYTEBUFFER_NO_BOUNDS_CHECK)' == 'true'">
|
||||
<DefineConstants>$(DefineConstants);BYTEBUFFER_NO_BOUNDS_CHECK</DefineConstants>
|
||||
</PropertyGroup>
|
||||
<ItemGroup>
|
||||
<Reference Include="System" />
|
||||
<Reference Include="System.Core" />
|
||||
<PropertyGroup Condition="'$(ENABLE_SPAN_T)' == 'true'">
|
||||
<DefineConstants>$(DefineConstants);ENABLE_SPAN_T</DefineConstants>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup Condition="('$(ENABLE_SPAN_T)' == 'true') And (('$(TargetFramework)' == 'netstandard2.0') Or ('$(TargetFramework)' == 'net46'))">
|
||||
<PackageReference Include="System.Memory" Version="4.5.4" />
|
||||
</ItemGroup>
|
||||
<ItemGroup>
|
||||
<Compile Include="ByteBuffer.cs" />
|
||||
<Compile Include="FlatBufferBuilder.cs" />
|
||||
<Compile Include="FlatBufferConstants.cs" />
|
||||
<Compile Include="IFlatbufferObject.cs" />
|
||||
<Compile Include="Offset.cs" />
|
||||
<Compile Include="Properties\AssemblyInfo.cs" />
|
||||
<Compile Include="Struct.cs" />
|
||||
<Compile Include="Table.cs" />
|
||||
</ItemGroup>
|
||||
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
|
||||
<!-- To modify your build process, add your task inside one of the targets below and uncomment it.
|
||||
Other similar extension points exist, see Microsoft.Common.targets.
|
||||
<Target Name="BeforeBuild">
|
||||
</Target>
|
||||
<Target Name="AfterBuild">
|
||||
</Target>
|
||||
-->
|
||||
|
||||
</Project>
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
|
||||
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
|
||||
<PropertyGroup>
|
||||
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
|
||||
<Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
|
||||
<ProjectGuid>{28C00774-1E73-4A75-AD8F-844CD21A064D}</ProjectGuid>
|
||||
<OutputType>Library</OutputType>
|
||||
<AppDesignerFolder>Properties</AppDesignerFolder>
|
||||
<RootNamespace>FlatBuffers</RootNamespace>
|
||||
<AssemblyName>FlatBuffers</AssemblyName>
|
||||
<TargetFrameworkVersion>v3.5</TargetFrameworkVersion>
|
||||
<FileAlignment>512</FileAlignment>
|
||||
</PropertyGroup>
|
||||
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
|
||||
<DebugSymbols>true</DebugSymbols>
|
||||
<DebugType>full</DebugType>
|
||||
<Optimize>false</Optimize>
|
||||
<OutputPath>bin\Debug\net35</OutputPath>
|
||||
<IntermediateOutputPath>obj\Debug\net35</IntermediateOutputPath>
|
||||
<DefineConstants>DEBUG;TRACE</DefineConstants>
|
||||
<ErrorReport>prompt</ErrorReport>
|
||||
<WarningLevel>4</WarningLevel>
|
||||
</PropertyGroup>
|
||||
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
|
||||
<DebugType>pdbonly</DebugType>
|
||||
<Optimize>true</Optimize>
|
||||
<OutputPath>bin\Release\net35</OutputPath>
|
||||
<IntermediateOutputPath>obj\Release\net35</IntermediateOutputPath>
|
||||
<DefineConstants>TRACE</DefineConstants>
|
||||
<ErrorReport>prompt</ErrorReport>
|
||||
<WarningLevel>4</WarningLevel>
|
||||
</PropertyGroup>
|
||||
<ItemGroup>
|
||||
<Reference Include="System" />
|
||||
<Reference Include="System.Core" />
|
||||
</ItemGroup>
|
||||
<ItemGroup>
|
||||
<Compile Include="ByteBuffer.cs" />
|
||||
<Compile Include="ByteBufferUtil.cs" />
|
||||
<Compile Include="FlatBufferBuilder.cs" />
|
||||
<Compile Include="FlatBufferConstants.cs" />
|
||||
<Compile Include="IFlatbufferObject.cs" />
|
||||
<Compile Include="Offset.cs" />
|
||||
<Compile Include="Properties\AssemblyInfo.cs" />
|
||||
<Compile Include="Struct.cs" />
|
||||
<Compile Include="Table.cs" />
|
||||
</ItemGroup>
|
||||
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
|
||||
<!-- To modify your build process, add your task inside one of the targets below and uncomment it.
|
||||
Other similar extension points exist, see Microsoft.Common.targets.
|
||||
<Target Name="BeforeBuild">
|
||||
</Target>
|
||||
<Target Name="AfterBuild">
|
||||
</Target>
|
||||
-->
|
||||
</Project>
|
||||
Loading…
Reference in New Issue