flatbuffers/flatc.1

.TH FLATC "1" "October 2022" "" "User Commands"
.SH NAME
.B flatc
\(en FlatBuffers compiler
.SH SYNOPSIS
.B flatc
.RI [ OPTION ]...\:
.IR FILE ...\:
.RI [\-\-\  BINARY_FILE ...]
.SH OPTIONS
.IR FILE s
may be schemas (must end in
.BR .fbs ),
binary schemas (must end in
.BR .bfbs ),
or JSON files (conforming to preceding schema).
.IR BINARY_FILE s
after the
.B \-\-
must be binary flatbuffer format files.
.P
Output files are named using the base file name of the input,
and written to the current directory or the path given by
.BR \-o .
.TP
.B \-\-binary\fR, \fB\-b
Generate wire format binaries for any data definitions.
.TP
.B \-\-json\fR, \fB\-t
Generate text output for any data definitions.
.TP
.B \-\-cpp\fR, \fB\-c
Generate C++ headers for tables/structs.
.TP
.B \-\-go\fR, \fB\-g
Generate Go files for tables/structs.
.TP
.B \-\-java\fR, \fB\-j
Generate Java classes for tables/structs.
.TP
.B \-\-dart\fR, \fB\-d
Generate Dart classes for tables/structs.
.TP
.B \-\-ts\fR, \fB\-T
Generate TypeScript code for tables/structs.
.TP
.B \-\-csharp\fR, \fB\-n
Generate C# classes for tables/structs.
.TP
.B \-\-python\fR, \fB\-p
Generate Python files for tables/structs.
.TP
.B \-\-lobster
Generate Lobster files for tables/structs.
.TP
.B \-\-lua\fR, \fB\-l
Generate Lua files for tables/structs.
.TP
.B \-\-rust\fR, \fB\-r
Generate Rust files for tables/structs.
.TP
.B \-\-php
Generate PHP files for tables/structs.
.TP
.B \-\-kotlin
Generate Kotlin classes for tables/structs.
.TP
.B \-\-jsonschema
Generate Json schema.
.TP
.B \-\-swift
Generate Swift files for tables/structs.
.TP
.B \-\-nim
Generate Nim files for tables/structs.
.TP
.B \-o\ \fIPATH
Prefix
.I PATH
to all generated files.
.TP
.B \-I\ \fIPATH
Search for includes in the specified path.
.TP
.B \-M
Print
.BR make (1)
rules for generated files.
.TP
.B \-\-version
Print the version number of
.B flatc
and exit.
.TP
.B \-\-strict\-json
Strict JSON: field names must be\ / will be quoted,
no trailing commas in tables/vectors.
.TP
.B \-\-allow-non-utf8
Pass non-UTF-8 input through parser and emit nonstandard
.BI \\\\\\\\ x
escapes in JSON.
(Default is to raise parse error on non-UTF-8 input.)
.TP
.B \-\-natural\-utf8
Output strings with UTF-8 as human-readable strings.
By default, UTF-8 characters are printed as
.BI \\\\\\\\u XXXX
escapes.
.TP
.B \-\-defaults\-json
Output fields whose value is the default when writing JSON.
.TP
.B \-\-unknown\-json
Allow fields in JSON that are not defined in the schema.
These fields will be discared when generating binaries.
.TP
.B \-\-no\-prefix
Don\(cqt prefix enum values with the enum type in C++.
.TP
.B \-\-scoped\-enums
Use C++11 style scoped and strongly typed enums.
Also implies
.BR \-\-no\-prefix .
.TP
.B \-\-no\-emit\-min\-max\-enum\-values
Disable generation of
.B MIN
and
.B MAX
enumerated values for scoped enums and prefixed enums.
.TP
.B \-\-gen\-includes
.RI ( deprecated ),
this is the default behavior.
If the original behavior is required (no include statements) use
.BR \-\-no\-includes .
.TP
.B \-\-no\-includes
Don\(cqt generate include statements for included
schemas the generated file depends on (C++\ / Python).
.TP
.B \-\-gen\-mutable
Generate accessors that can mutate buffers in-place.
.TP
.B \-\-gen\-onefile
Generate single output file for C# and Go.
.TP
.B \-\-gen\-name\-strings
Generate type name functions for C++ and Rust.
.TP
.B \-\-gen\-object\-api
Generate an additional object-based API.
.TP
.B \-\-gen\-compare
Generate
.B operator==
for object-based API types.
.TP
.B \-\-gen\-nullable
Add Clang
.B _Nullable
for C++ pointer.
or
.B @Nullable
for Java
.TP
.B \-\-java\-package\-prefix
Add a prefix to the generated package name for Java.
.TP
.B \-\-java\-checkerframework
Add
.B @Pure
for Java.
.TP
.B \-\-gen\-generated
Add
.B @Generated
annotation for Java
.TP
.B \-\-gen\-jvmstatic
Add
.B @JvmStatic
annotation for Kotlin methods
in companion object for interop from Java to Kotlin.
.TP
.B \-\-gen\-all
Generate not just code for the current schema files,
but for all files it includes as well.
If the language uses a single file for output (by default
the case for C++ and JS), all code will end up in this one file.
.TP
.B \-\-gen\-json\-emit
Generates encoding code which emits Flatbuffers into JSON.
.TP
.B \-\-cpp\-include
Adds an
.B #include
in generated file.
.TP
.B \-\-cpp\-ptr\-type\ \fIT
Set object API pointer type
(default
.BR std::unique_ptr ).
.TP
.B \-\-cpp\-str\-type\ \fIT
Set object API string type
(default
.BR std::string ).
.BR \fIT\fB::c_str() ,
.BR \fIT\fB::length() ,
and
.BR \fIT\fB::empty()
must be supported.
The custom type also needs to be constructible from
.B std::string
(see the
.B \-\-cpp\-str\-flex\-ctor
option to change this behavior).
.TP
.B \-\-cpp-str-flex-ctor
Don\(cqt construct custom string types by passing
.B std::string
from Flatbuffers, but (\fBchar*\fR\ + \fIlength\fR).
.TP
.B \-\-cpp-std\ \fICPP_STD
Generate a C++ code using features of selected C++ standard.
.IP
.B Supported
.I CPP_STD
.B values:
.RS +7n
.IP \(bu 2n
.B c++0x
\(en generate code compatible with old compilers;
.IP \(bu 2n
.B c++11
\(en use C++11 code generator
.RI ( default );
.IP \(bu 2n
.B c++17
\(en use C++17 features in generated code
.RI ( experimental ).
.RE
.TP
.B \-\-cpp\-static\-reflection
When using C++17, generate extra code to provide compile-time
(static) reflection of Flatbuffers types.
Requires
.B \-\-cpp\-std
to be
.RB \(lq c++17 \(rq
or higher.
.TP
.B \-\-object\-prefix
Customise class prefix for C++ object-based API.
.TP
.B \-\-object\-suffix
Customise class suffix for C++ object-based API.
Default value is
.RB \(lq T \(rq.
.TP
.B \-\-go\-namespace
Generate the overriding namespace in Golang.
.TP
.B \-\-go\-import
Generate the overriding import for flatbuffers in Golang
(default is
.RB \(lq github.com/google/flatbuffers/go \(rq).
.TP
.B \-\-go\-module\-name
Prefix local import paths of generated go code with the module name.
.TP
.B \-\-raw\-binary
Allow binaries without
.B file_identifier
to be read.
This may crash
.B flatc
given a mismatched schema.
.TP
.B \-\-size\-prefixed
Input binaries are size prefixed buffers.
.TP
.B \-\-proto\-namespace\-suffix\ \fISUFFIX
Add this namespace to any flatbuffers generated from protobufs.
.TP
.B \-\-oneof\-union
Translate
.B .proto
oneofs to flatbuffer unions.
.TP
.B \-\-keep\-proto\-id
Keep protobuf field ids in generated fbs file.
.TP
.B \-\-proto\-id\-gap
Action that should be taken when a gap between protobuf ids found.
.IP
.B Supported values:
.RS +7n
.IP \(bu 2n
.B nop
\(en do not care about gap
.IP \(bu 2n
.B warn
\(en A warning message will be shown about the gap in protobuf ids
.RI ( default )
.IP \(bu 2n
.B error
\(en An error message will be shown and the fbs generation will be interrupted.
.RE
.TP
.B \-\-grpc
Generate GRPC interfaces for the specified languages.
.TP
.B \-\-schema
Serialize schemas instead of JSON (use with
.BR \-b ).
.TP
.B \-\-bfbs\-comments
Add doc comments to the binary schema files.
.TP
.B \-\-bfbs\-builtins
Add builtin attributes to the binary schema files.
.TP
.B \-\-bfbs\-gen\-embed
Generate code to embed the
.B bfbs
schema to the source.
.TP
.B \-\-conform\ \fIFILE
Specify a schema the following schemas should be an evolution of.
Gives errors if not.
.TP
.B \-\-conform\-includes
Include path for the schema given with
.BR \-\-conform\ \fIPATH .
.TP
.B \-\-filename\-suffix
The suffix appended to the generated file names.
Default is
.BR \(oq _generated \(cq.
.TP
.B \-\-filename\-ext
The extension appended to the generated file names.
Default is language-specific (e.g.,
.RB \(oq .h \(cq
for C++)
.TP
.B \-\-include\-prefix\ \fIPATH
Prefix this path to any generated include statements.
.TP
.B \-\-keep\-prefix
Keep original prefix of schema include statement.
.TP
.B \-\-reflect\-types
Add minimal type reflection to code generation.
.TP
.B \-\-reflect\-names
Add minimal type/name reflection.
.TP
.B \-\-rust\-serialize
Implement
.B serde::Serialize
on generated Rust types.
.TP
.B \-\-rust\-module\-root\-file
Generate rust code in individual files with a module root file.
.TP
.B \-\-root\-type\ \fIT
Select or override the default root_type.
.TP
.B \-\-require\-explicit\-ids
When parsing schemas, require explicit ids
.RB ( id:\ \fIx ).
.TP
.B \-\-force\-defaults
Emit default values in binary output from JSON.
.TP
.B \-\-force\-empty
When serializing from object API representation,
force strings and vectors to empty rather than null.
.TP
.B \-\-force\-empty\-vectors
When serializing from object API representation,
force vectors to empty rather than null.
.TP
.B \-\-flexbuffers
Used with
.RB \(lq binary \(rq
and
.RB \(lq json \(rq
options, it generates
data using schema-less FlexBuffers.
.TP
.B \-\-no\-warnings
Inhibit all warning messages.
.TP
.B \-\-warnings\-as-errors
Treat all warnings as errors.
.TP
.B \-\-cs\-global\-alias
Prepend
.RB \(lq global:: \(rq
to all user generated csharp classes and structs.
.TP
.B \-\-cs\-gen\-json\-serializer
Allows (de)serialization of JSON text in the Object API.
(requires
.BR \-\-gen\-object\-api ).
.TP
.B \-\-json\-nested\-bytes
Allow a
.B nested_flatbuffer
field to be parsed as a vector of bytes in JSON,
which is unsafe unless checked by a verifier afterwards.
.TP
.B \-\-ts\-flat\-files
Generate a single typescript file per
.B .fbs
file.
Implies
.BR \-\-ts\-entry\-points .
.TP
.B \-\-ts\-entry\-points
Generate entry point typescript per namespace.
Implies
.BR \-\-gen\-all .
.TP
.B \-\-annotate\-sparse\-vectors\ \fISCHEMA
Don\(cqt annotate every vector element.
.TP
.B \-\-annotate\ \fISCHEMA
Annotate the provided
.I BINARY_FILE
with the specified
.I SCHEMA
file.
.TP
.B \-\-no\-leak\-private\-annotation
Prevents multiple type of annotations within a Fbs
.I SCHEMA
file.
Currently this is required to generate private types in Rust.
.TP
.B \-\-python\-no\-type\-prefix\-suffix
Skip emission of Python functions that are prefixed with typenames
.TP
.B \-\-python\-typing
Generate Python type annotations
.TP
.B \-\-file\-names\-only
Print out generated file names without writing to the files
.SH EXAMPLES
.EX
.B flatc\ \-c\ \-b\ schema1.fbs\ schema2.fbs\ data.json
.EE
.SH "SEE ALSO"
.UR https://google.github.io/flatbuffers
Official documentation
.UE