Rooba
/
flatbuffers
mirror of https://github.com/google/flatbuffers.git
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[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 2020-09-28 14:56:59 -04:00 committed by GitHub
parent 2eedc769d5
commit 0bdf2fa156
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 142 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
docs/source/CsharpUsage.md
View File

@ -14,14 +14,38 @@ documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and [Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema). [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 The code for the FlatBuffers C# library can be found at
`flatbuffers/net/FlatBuffers`. You can browse the library on the `flatbuffers/net/FlatBuffers`. You can browse the library on the
[FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/net/ [FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/net/
FlatBuffers). 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`. 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. https://www.visualstudio.com), and compile/run the project.
Optionally, you can run this using [Mono](http://www.mono-project.com/) instead. 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: by running the following commands from inside the `FlatBuffers.Test` folder:
~~~{.sh} ~~~{.sh}
mcs *.cs ../MyGame/Example/*.cs ../../net/FlatBuffers/*.cs mcs *.cs ../MyGame/Example/*.cs ../../net/FlatBuffers/*.cs
mono Assert.exe mono Assert.exe
~~~ ~~~
## Using the FlatBuffers C# library ## Using the FlatBuffers C# library
@ -74,7 +98,7 @@ Now you can access the data from the `Monster monster`:
Vec3 pos = monster.Pos; 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 e.g. `GetRootAsMyRootType`. Also, values (except vectors and unions) are
available as properties instead of parameterless accessor methods. available as properties instead of parameterless accessor methods.
The performance-enhancing methods to which you can pass an already created 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 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 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 FlatBuffer into objects and standard `System.Collections.Generic` containers,
construction, access and mutation. allowing for convenient construction, access and mutation.
To use: To use:
@ -154,7 +178,7 @@ To use:
### Json Serialization ### Json Serialization
An additional feature of the object API is the ability to allow you to An additional feature of the object API is the ability to allow you to
serialize & deserialize a JSON text. serialize & deserialize a JSON text.
To use Json Serialization, add `--cs-gen-json-serializer` option to `flatc` and To use Json Serialization, add `--cs-gen-json-serializer` option to `flatc` and
add `Newtonsoft.Json` nuget package to csproj. add `Newtonsoft.Json` nuget package to csproj.
@ -172,4 +196,31 @@ add `Newtonsoft.Json` nuget package to csproj.
* NuGet package Dependency * NuGet package Dependency
* [Newtonsoft.Json](https://github.com/JamesNK/Newtonsoft.Json) * [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> <br>

13
net/FlatBuffers/ByteBuffer.cs
View File

@ -14,24 +14,25 @@
* limitations under the License. * 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 // UNSAFE_BYTEBUFFER
// This will use unsafe code to manipulate the underlying byte array. This // This will use unsafe code to manipulate the underlying byte array. This
// can yield a reasonable performance increase. // can yield a reasonable performance increase.
// //
// BYTEBUFFER_NO_BOUNDS_CHECK // BYTEBUFFER_NO_BOUNDS_CHECK
// This will disable the bounds check asserts to the byte array. This can // 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 // 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 // T[]. You can also enable writing directly to shared memory or other types of memory
// by providing a custom implementation of ByteBufferAllocator. // 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 // Using UNSAFE_BYTEBUFFER and BYTEBUFFER_NO_BOUNDS_CHECK together can yield a
// performance gain of ~15% for some operations, however doing so is potentially // performance gain of ~15% for some operations, however doing so is potentially
// dangerous. Do so at your own risk! // dangerous. Do so at your own risk!
// //

19
net/FlatBuffers/FlatBuffers.Core.csproj
View File

@ -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>

67
net/FlatBuffers/FlatBuffers.csproj
View File

@ -1,54 +1,23 @@
<?xml version="1.0" encoding="utf-8"?> <Project Sdk="Microsoft.NET.Sdk">
<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> <PropertyGroup>
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration> <TargetFrameworks>netstandard2.1;netstandard2.0;net46</TargetFrameworks>
<Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform> <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
<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>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
<DebugSymbols>true</DebugSymbols> <PropertyGroup Condition="'$(UNSAFE_BYTEBUFFER)' == 'true'">
<DebugType>full</DebugType> <DefineConstants>$(DefineConstants);UNSAFE_BYTEBUFFER</DefineConstants>
<Optimize>false</Optimize> <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
<OutputPath>bin\Debug\</OutputPath>
<DefineConstants>DEBUG;TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
</PropertyGroup> </PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' "> <PropertyGroup Condition="'$(BYTEBUFFER_NO_BOUNDS_CHECK)' == 'true'">
<DebugType>pdbonly</DebugType> <DefineConstants>$(DefineConstants);BYTEBUFFER_NO_BOUNDS_CHECK</DefineConstants>
<Optimize>true</Optimize>
<OutputPath>bin\Release\</OutputPath>
<DefineConstants>TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
</PropertyGroup> </PropertyGroup>
<ItemGroup> <PropertyGroup Condition="'$(ENABLE_SPAN_T)' == 'true'">
<Reference Include="System" /> <DefineConstants>$(DefineConstants);ENABLE_SPAN_T</DefineConstants>
<Reference Include="System.Core" /> </PropertyGroup>
<ItemGroup Condition="('$(ENABLE_SPAN_T)' == 'true') And (('$(TargetFramework)' == 'netstandard2.0') Or ('$(TargetFramework)' == 'net46'))">
<PackageReference Include="System.Memory" Version="4.5.4" />
</ItemGroup> </ItemGroup>
<ItemGroup>
<Compile Include="ByteBuffer.cs" /> </Project>
<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>

57
net/FlatBuffers/FlatBuffers.net35.csproj Normal file
View File

@ -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>