Simple Binary Encoding (SBE)

The SBE Tool is a Java-based program used to marshal messages by generating C# code from an XML schema.

Prerequisites:

• A recent version of Java must be installed.
• java must be available in your PATH environment variable.

Location:

• The tool is located at: \tools\SBETools.jar

Execution: To generate sample code, run the provided batch file:

\sample\GenerateSampleCode.bat

Note: If you move the schema or the tool, you must edit the .bat file to reflect the new paths. Generated files will be placed in \sample\output\.

Depending on your operating system and goals, the following environments are required:

• General Build: Java and gradlew are required to build the generator. Git Bash and shell scripts are used for scripting.
• Windows: The .NET Core SDK is required. If you have the legacy .NET Framework installed as part of the OS, you only need the .NET Core SDK to compile SDK-style projects.
• Mac/Linux: The .NET Core SDK and the Mono framework are required to produce release NuGet packages or .NET Framework compatible DLLs.

To use Simple Binary Encoder (SBE) in a C# project, follow these three primary steps:

1. Define a Schema: Create an SBE schema (XML format) that describes your messages.
2. Generate Code: Use the SBETools.jar to generate C# encoders and decoders based on your schema.
3. Integrate: Add the generated .cs files to your project and include a reference to sbe.dll.

The Go development environment is structured within the gocode directory. To manage the directory structure and GOPATH requirements, use the provided GNU Makefile located in the top-level gocode directory.

Environment Setup

• To use the layout: Set GOPATH to the path of the gocode directory (e.g., export GOPATH=/path/to/gocode).
• To run tests: You must either unset GOPATH or use the supplied Makefile, which handles the environment configuration for you.

After generating your C# encoders and decoders, follow these steps to use them in your application:

1. Copy Generated Files: Move all files from the output directory (\sample\output\*.cs) to the root of your C# project.
2. Add SBE Reference: Add a reference to \lib\net40\sbe.dll in your project.
3. Configure Project (for samples): If using the provided sample class (ExampleUsingGeneratedStub.cs):
   • Change the project type to a Console Application.
   • Set the Startup object in Project properties (Project properties > Application > Startup object).

The C# code, samples, tests, and NuGet packages can be managed using the .NET Core SDK. You can use standard .NET CLI commands or the provided bash scripts.

Standard CLI commands:

• Build: dotnet build
• Test: dotnet test

Provided bash scripts:

• Run tests: ./runtests.sh or ./build.sh
• Create NuGet package: ./pack.sh

SBE for Go supports two different code generation styles: standard Go structs with encode/decode methods, or flyweights (similar to other SBE languages).

By default, SBE generates structs for compatibility. To generate flyweights instead, set the following configuration property:

sbe.go.generate.generate.flyweights=true

To build the SBE C# generator and generate the corresponding C# code (tests, benchmarks, and examples), use the Gradle wrapper. This is primarily for developers working on the generator itself.

1. Build the sbe-tool JAR: ./gradlew
2. Generate C# codecs: ./gradlew generateCSharpCodeCodecs

$ ./gradlew
$ ./gradlew generateCSharpCodecs

To generate codecs from an SBE XML schema, run the SBE tool JAR with the appropriate system properties.

Commonly used properties:

• -Dsbe.generate.ir=true: Generates the Intermediate Representation (IR).
• -Dsbe.target.language=Cpp: Sets the target language to C++.
• -Dsbe.target.namespace=sbe: Sets the target namespace.
• -Dsbe.output.dir=include/gen: Specifies the output directory for generated files.
• -Dsbe.errorLog=yes: Enables error logging.

Note: When running on Java 9+, you may need to add --add-opens java.base/jdk.internal.misc=ALL-UNNAMED to allow access to internal APIs required by the tool.

When generating C++ codecs, you can use the sbe.cpp.namespaces.collapse system property to control how nested namespaces are handled.

• If set to true, C++ nested namespaces are collapsed into a single namespace where levels are separated by underscores.
• The default value is false.

You can control whether the SBE tool generates interfaces for flyweights using the sbe.java.generate.interfaces system property.

• The default value is false.