Skip to content

Compiler

Jump to bottom
James Courtney edited this page Mar 14, 2024 · 12 revisions

FlatSharp is run at build-time with the FlatSharp.Compiler NuGet package. The compiler accepts fbs files and produces C# at build time. The FlatSharp compiler targets net6.0 and net7.0, which are just the runtimes necessary to execute the compiler, and has no bearing on the code the compiler generates. The FlatSharp compiler generates code that can run inside .NET Framework, .NET Standard 2.0+, or .NET Core 2.1+.

Adding FBS files (MSBuild)

FBS files must be opted into the compiler:

<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <FlatSharpSchema Include="YourSchema.fbs" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="FlatSharp.Compiler" Version="7.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
    <PackageReference Include="FlatSharp.Runtime" Version="7.0.0" />
  </ItemGroup>
</Project>

Command Line Invocation

While .csproj files offer MSBuild integration, you may also choose to invoke the FlatSharp compiler yourself. The syntax is relatively straightforward:

dotnet FlatSharp.Compiler.dll -i "a.fbs;b.fbs;c.fbs" -o <output directory>

Additionally, the FlatSharp compiler supports some optional arguments:

  • --nullable-warnings: Enables nullability warnings
  • --normalize-field-names: Enables field name normalization to standard C# style.
  • --includes path1;path2;path3: Passes include search paths to flatc.

Unity

Unity does not allow modification of the .csproj file, which makes the above difficult. For Unity users, the best current option is to invoke the compiler manually in a prebuild step.

Nullable Annotations

By default, the FlatSharp compiler inherits the project setting for nullable annotations. If <Nullable> is set to enabled in the project, then FlatSharp will generate code with full nullable attributes and annotations. If <Nullable> is set to anything besides enabled in the project, FlatSharp will generate code with nullable annotations only.

Full nullable annotations may only work correctly with C# 9 and above.

This behavior can be overridden with the <FlatSharpNullable> property.

  <!-- Flatsharp inherits the project setting and generates full nullable code -->
  <PropertyGroup>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <!-- FlatSharp only generates nullable annotations (no attributes/warnings) -->
  <PropertyGroup>
    <Nullable>enable</Nullable>
    <FlatSharpNullable>false</FlatSharpNullable>
  </PropertyGroup>

  <!-- FlatSharp only generates nullable annotations (no attributes/warnings) -->
  <PropertyGroup>
    <Nullable>disable</Nullable>
  </PropertyGroup>

  <!-- Flatsharp overrides the project setting and generates full nullable code -->
  <PropertyGroup>
    <Nullable>disable</Nullable>
    <FlatSharpNullable>true</FlatSharpNullable>
  </PropertyGroup>

Include Search Paths

The FlatSharp Compiler is built on top of flatc, the official compiler. flatc supports passing in search paths to find imported fbs files. Include Paths may be specified per FBS file:

    <FlatSharpSchema Include="Example07-Includes\**\*.fbs">
      <IncludePath>Example07-Includes</IncludePath>
    </FlatSharpSchema>

Include Paths may also be specified by the command line via the --includes option.

PascalCase Normalization

FlatBuffers schemas canonically use snake_case for fields. By default, FlatSharp normalizes these fields to UpperPascalCase. However, you may wish to disable normalization:

csproj:

  <PropertyGroup>
    <FlatSharpNameNormalization>false</FlatSharpNameNormalization>
  </PropertyGroup>

Command Line: --normalize-field-names false FBS schema: fs_literalName attribute

Specifying Deserializers

It is sometimes useful to specify which Deserialization Modes FlatSharp should generate. For large schemas, it can be useful to restrict the amount of code generated and eliminate deserialization modes your application will not use.

csproj:

  <PropertyGroup>
    <FlatSharpDeserializers>Lazy;Progressive</FlatSharpDeserializers>
  </PropertyGroup>

Command Line: --deserializers Lazy;Progressive

Class Definitions Only

FlatSharp can also be configured to only emit class definitions. This allows sharing a set of common schemas between projects. When this option is enabled, FlatSharp will emit class definitions, but no serializers, deserializers, or other FlatBuffers logic. The point of this is to allow generating type definitions in common locations that are serialized from other projects.

<PropertyGroup>
  <FlatSharpClassDefinitionsOnly>true</FlatSharpClassDefinitionsOnly>
</PropertyGroup>

Using the command line, you can pass --class-definitions-only.

Input Files Only

Normally, FlatSharp will process all FBS files in the recursive graph of inputs, even following files that are referenced only through include statements. This switch instructs FlatSharp to only output class definitions for files explicitly passed as input (serializers may still be emitted for includes). This switch works inc oncert with the Class Definitions Only switch to enable abstracting a common set of shared types inside a single library.

<PropertyGroup>
  <FlatSharpInputFilesOnly>true</FlatSharpInputFilesOnly>
</PropertyGroup>

Using the command line, you can pass --input-files-only.

File Visibility

C# 11 and above support a new visibility modifier: file. Items declared with file visibility are only visible within the file they are declared. This can help keep FlatSharp-generated members hidden from your application code. However, since it is only supported with C# 11 and newer, it is an opt-in feature.

<PropertyGroup>
  <FlatSharpFileVisibility>true</FlatSharpFileVisibility>
</PropertyGroup>

Using the command line, you can pass --file-visibility.

Clone this wiki locally