Sbe Tool Guide (original) (raw)

The SBE tool is a command line utility that can be used to generate codecs and validate message declaration schemas. The tool is written in Java and can run as an executable JAR file, e.g:

$ java --add-opens java.base/jdk.internal.misc=ALL-UNNAMED -jar sbe-all-${SBE_LIB_VERSION}.jar <message-declarations-file.xml>

The tool will accept options using the system property option format as follows:

$ java [-Doption=value] --add-opens java.base/jdk.internal.misc=ALL-UNNAMED -jar sbe-all-${SBE_TOOL_VERSION}.jar <message-declarations-file.xml>

The tool supports the following options:

• sbe.xinclude.aware: Is XInclude supported for the schema. Defaults to false.
• sbe.validation.xsd: Use XSD to validate or not. XSD filename should be the provided option.
• sbe.validation.stop.on.error: Should the parser stop on first error encountered? Defaults to false.
• sbe.validation.warnings.fatal: Are warnings in parsing considered fatal? Defaults to false.
• sbe.validation.suppress.output: Should the parser suppress output during validation? Defaults to false.
• sbe.generate.stubs: Generate stubs or not. Defaults to true.
• sbe.target.language: Target language for code generation, defaults to Java (also supports: CPP, C, and Golang). Additionally a fully qualified class name can be provided which implements TargetCodeGeneratorLoader, e.g. uk.co.real_logic.sbe.generation.csharp.CSharp.
• sbe.generate.ir: Generate IR or not. Defaults to false.
• sbe.output.dir: Target directory for output generation, defaults to current directory.
• sbe.target.namespace: Namespace to be used for generated code. Equates to package for Java. If not provided then the package attribute from the schema will be used.
• sbe.keyword.append.token: String to append to schema tokens that collide with reserved words in the target language.
• sbe.decode.unknown.enum.values: Support unknown decoded enum values.
• sbe.generate.access.order.checks: Generate code to check flyweight methods are accessed in a valid order? Defaults to false. This option is supported by the Java, C#, and C++ generators. Requires platform-specific configuration to enable the checks at runtime, e.g., setting a system property or constant symbol. Find out more in Safe Flyweight Usage.
• sbe.precedence.checks.flag.name: The name of the symbol or macro that enables access order checks when building generated C# or C++ code.
• sbe.schema.transform.version: Configuration option used to manage sinceVersion based transformations. When set, parsed schemas will be transformed to discard messages and types higher than the specified version. This can be useful when needing to generate older versions of a schema to do version compatibility testing.
  This field can contain a list of ordered pairs in the form: ((<schema id> | '*') ':' <schema id>)(',' ((<schema id> | '*') ':' <schema id>))*. E.g. 123:5,*:6 which means transform schema with id = 123 to version 5, all others to version 6.

Language specific configuration options

Java

• sbe.java.generate.interfaces: Generate implements clauses for Java common interfaces from Agrona. Defaults to false.
• sbe.java.encoding.buffer.type: Buffer type to be used for the encoder stubs. This type needs to mutate the underlying buffer. Defaults to MutableDirectBuffer.
• sbe.java.decoding.buffer.type: Buffer type to be used for the decoder stubs. This type only reads the underlying buffer. Defaults to DirectBuffer.
• sbe.java.generate.group-order.annotation: Should the GroupOrder annotation be generated, defaults to false.
• sbe.java.precedence.checks.property.name: The name of the system property that enables access order checks at runtime in generated Java code.
• sbe.java.generate.dtos: Should generate Java DTOs. Defaults to false.

C++

• sbe.cpp.namespaces.collapse: Boolean to turn on or off collapsing of nested namespaces in generated C++ stubs. Defaults to false.
• sbe.cpp.disable.implicit.copying: Disable generation of copy constructors and copy assignment operators? Defaults to false.
• sbe.cpp.disable.raw.arrays: Disable support for raw array encoder when std::span is used. Defaults to false.
• sbe.cpp.generate.dtos: Should generate C++ DTOs. Defaults to false.

C#

• sbe.csharp.generate.namespace.dir: Should a directory be created for the namespace under the output directory? Defaults to true.
• sbe.csharp.generate.dtos: Should generate C# DTOs. Defaults to false.

Golang

• sbe.go.generate.generate.flyweights: Generate flyweights instead of structs in the Go code. Defaults to false.

Rust

• sbe.rust.crate.version: Version of the Rust crate to generate. Defaults to 0.1.0.

The SBE tool can be used with Mavensee