FLATC(1)

📦
version 25.12.19 · 3 versions
, in fedora 43, fedora 44

🌸 FLATC — bestie edition 💅

okay so this is FLATC(1), the User Commands one, and literally it's the main character of the FlatBuffers world. sit down, grab a strawberry drink 🍓, we're doing this.

✨ NAME ✨

flatc – FlatBuffers compiler. that's it, that's the name, slay.

🦋 SYNOPSIS 🦋

flatc [ GENERATOR_OPTIONS ] [ -o PATH ] FILES...  [ -- BINARY_FILES... ]

💖 DESCRIPTION 💖

The main compiler for FlatBuffers is called flatc(1) and it's the one that takes your schema definitions and turns them into generated code files for a whole bunch of languages. one schema, many languages, no cap. 👑

🎀 OPTIONS 🎀

  • The GENERATOR_OPTIONS are the vibe-setters: they say which language(s) you're compiling code for, plus all the little features you wanna enable or disable.
  • The -o PATH says where the generated files get dropped. if you don't say anything, it defaults to the current path, ngl.
  • The -I PATH says where your included schema files are hiding. also defaults to the current path if you don't specify.

📂 INPUT FILES 📂

FILES... is one or more schema or data files to process. and bestie, they get processed in the order provided — order matters, fr fr.

🧚 SCHEMA FILES 🧚

For schema files, the language specifiers are how you tell flatc which languages to generate code for:

  • --cpp: C++
  • --java: Java
  • --kotlin: Kotlin
  • --csharp: C#
  • --go: Golang
  • --python: Python
  • --js: JavaScript
  • --ts: TypeScript
  • --php: PHP
  • --dart: Dart
  • --lua: Lua
  • --lobster: Lobster
  • --rust: Rust
  • --swift: Swift
  • --nim: Nim

Also, if you toss in --grpc it will generate RPC stub code for gRPC — but heads up, that's not available in all languages. 🙈

🗂️ DATA FILES 🗂️

If your FILES... are data files, you can export them to either a binary or a JSON representation. two paths, both iconic:

  • --binary, -b — generates a binary file holding a serialized flatbuffer.
  • --json, -j — generates a JSON file from a serialized flatbuffer.
⚠️ Both options require the corresponding schema file to be included first in the list of FILES.... don't skip this, it's giving chaos otherwise.

🧊 To Binary

To serialize the JSON data in mydata.json using the schema myschema.fbs:

flatc --binary myschema.fbs mydata.json

This will generate a mydata_wire.bin file containing the serialized flatbuffer data. so clean, so tidy. ✨

🌈 To JSON

To convert the serialized binary flatbuffer mydata.bin using the schema myschema.fbs to JSON:

flatc --json myschema.fbs mydata.bin

This will generate a mydata.json file. round trip, periodt. 💅

🔥 ADDITIONAL OPTIONS 🔥

  • -o PATH — output all generated files to PATH (either absolute, or relative to the current directory). if you omit it, PATH will be the current directory. and bestie, PATH should end in your system's path separator, e.g. / or \. yes, really.
  • -I PATH — when it hits include statements, it attempts to load those files from this path. paths get tried in the order given, and if they all fail (or you specified none at all) it tries to load relative to the path of the schema file being parsed.
  • -M — print make rules for generated files.
  • --strict-json — require and generate strict JSON (field names are enclosed in quotes, no trailing commas in tables/vectors). by default, no quotes are required/generated, and trailing commas are allowed. choose your fighter.
  • --allow-non-utf8 — pass non-UTF-8 input through the parser and emit nonstandard \x escapes in JSON. (default is to raise a parse error on non-UTF-8 input.) then, --natural-utf8 — output strings with UTF-8 as human-readable strings. by default, UTF-8 characters are printed as \uXXXX escapes.
  • --defaults-json — output fields whose value is equal to the default value when writing JSON text.
  • --no-prefix — don't prefix enum values in generated C++ by their enum type.
  • --scoped-enums — use C++11 style scoped and strongly typed enums in generated C++. this also implies --no-prefix.
  • --no-emit-min-max-enum-values — disable generation of MIN and MAX enumerated values for scoped enums and prefixed enums.
  • --gen-includes — (deprecated) this is the default behavior. if you need the original behavior (no include statements) use --no-includes.
  • --no-includes — don't generate include statements for included schemas the generated file depends on (C++ / Python).
  • --gen-mutable — generate additional non-const accessors for mutating FlatBuffers in-place.
  • --gen-onefile — generate a single output file for C#, Go, and Python.
  • --gen-name-strings — generate type name functions for C++.
  • --gen-object-api — generate an additional object-based API. this API is more convenient for object construction and mutation than the base API, at the cost of efficiency (object allocation). it's recommended only if other options are insufficient, ngl.
  • --gen-compare — generate operator== for object-based API types.
  • --gen-nullable — add Clang _Nullable for C++ pointer or @Nullable for Java.
  • --gen-generated — add @Generated annotation for Java.
  • --gen-jvmstatic — add @JvmStatic annotation for Kotlin methods in companion object, for interop from Java to Kotlin.
  • --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.
  • --cpp-include — adds an #include in the generated file.
  • --cpp-ptr-type T — set object API pointer type (default std::unique_ptr).
  • --cpp-str-type T — set object API string type (default std::string). T::c_str(), T::length() and T::empty() must be supported. the custom type also needs to be constructible from std::string (see the --cpp-str-flex-ctor option to change this behavior).
  • --cpp-str-flex-ctor — don't construct custom string types by passing std::string from Flatbuffers, but (char* + length). this allows efficient construction of custom string types, including zero-copy construction. obsessed. ✨
  • --no-cpp-direct-copy — don't generate direct copy methods for C++ object-based API.
  • --cpp-std CPP_STD — generate C++ code using features of the selected C++ standard. supported CPP_STD values:
    • c++0x – generate code compatible with old compilers (VS2010),
    • c++11 – use C++11 code generator (default),
    • c++17 – use C++17 features in generated code (experimental).
  • --object-prefix — customise class prefix for C++ object-based API.
  • --object-suffix — customise class suffix for C++ object-based API.
  • --go-namespace — generate the overrided namespace in Golang.
  • --go-import — generate the overrided import for flatbuffers in Golang. (default is github.com/google/flatbuffers/go).
  • --raw-binary — allow binaries without a file_indentifier to be read.
💀 This may crash flatc(1) given a mismatched schema. like, actually crash. be careful bestie.
  • --size-prefixed — input binaries are size prefixed buffers.
  • --proto — expect input files to be .proto files (protocol buffers). output the corresponding .fbs file. currently supports: package, message, enum, nested declarations, import (use -I for paths), extend, oneof, group. does not support, but will skip without error: option, service, extensions, and most everything else. it's giving "we tried our best" but honestly still great.
  • --oneof-union — translate .proto oneofs to flatbuffer unions.
  • --grpc — generate GRPC interfaces for the specified languages.
  • --schema — serialize schemas instead of JSON (use with -b). this will output a binary version of the specified schema that itself corresponds to the reflection/reflection.fbs schema. loading this binary file is the basis for reflection functionality. main character behavior tbh. 👑
  • --bfbs-comments — add doc comments to the binary schema files.
  • --conform FILE — specify a schema the following schemas should be an evolution of. gives errors if not. super useful to check that schema modifications don't break schema evolution rules.
  • --conform-includes PATH — include path for the schema given with --conform PATH.
  • --filename-suffix SUFFIX — the suffix appended to the generated file names. default is _generated.
  • --filename-ext EXTENSION — the extension appended to the generated file names. default is language-specific (e.g. "h" for C++).
🙈 This should not be used when multiple languages are specified.
  • --include-prefix PATH — prefix this path to any generated include statements.
  • --keep-prefix — keep original prefix of schema include statement.
  • --reflect-types — add minimal type reflection to code generation.
  • --reflect-names — add minimal type/name reflection.
  • --root-type T — select or override the default root_type.
  • --require-explicit-ids — when parsing schemas, require explicit ids (id: x).
  • --force-defaults — emit default values in binary output from JSON.
  • --force-empty — when serializing from object API representation, force strings and vectors to empty rather than null.
  • --force-empty-vectors — when serializing from object API representation, force vectors to empty rather than null.
  • --flexbuffers — used with --binary and --json options, it generates data using schema-less FlexBuffers.
  • --no-warnings — inhibit all warning messages. silence, gorgeous.
  • --cs-global-alias — prepend global:: to all user generated csharp classes and structs.
  • --json-nested-bytes — allow a nested_flatbuffer field to be parsed as a vector of bytes in JSON.
⚠️ which is unsafe unless checked by a verifier afterwards. no cap, verify it.
  • --python-no-type-prefix-suffix — skip emission of Python functions that are prefixed with typenames.
  • --python-typing — generate Python type annotations.

💜 ADDITIONAL gRPC OPTIONS 💜

  • --grpc-filename-suffix — [C++] an optional suffix for the generated files' names. for example, compiling gRPC for C++ with --grpc-filename-suffix=.fbs will generate {name}.fbs.h and {name}.fbs.cc files.
  • --grpc-additional-header — [C++] additional headers to include in the generated files.
  • --grpc-search-path — [C++] an optional prefix for the gRPC runtime path. for example, compiling gRPC for C++ with --grpc-search-path=some/path will generate the following includes:
                 #include "some/path/grpcpp/impl/codegen/async_stream.h"
                 #include "some/path/grpcpp/impl/codegen/async_unary_call.h"
                 #include "some/path/grpcpp/impl/codegen/method_handler.h"
                 ...
  • --grpc-use-system-headers — [C++] okay so this one is a whole vibe question: do you want the generated includes to be #include <header> instead of #include "header.h" for all headers when you're compiling gRPC for C++? 💅 That's it, that's the whole thing.

Like, if you compile gRPC for C++ with --grpc-use-system-headers, bestie, you get this instead:

                 #include <some/path/grpcpp/impl/codegen/async_stream.h>
                 #include <some/path/grpcpp/impl/codegen/async_unary_call.h>
                 #include <some/path/grpcpp/impl/codegen/method_handler.h>
                 ...
NOTE: you can flip this one off with --no-grpc-use-system-headers. No cap. ✨
  • --grpc-python-typed-handlers — [Python] do you want the typed handlers that use the generated Python classes, or do you want raw bytes for requests/responses? 🐍 This flag is you choosing the typed ones. It's giving type safety, it's giving main character energy. 🎀

📝 NOTES 📝

  • Short-form options for generators are deprecated 😭 — use the long form whenever possible, fr fr. Do not be out here typing the short ones like it's 2019. 🙈

👀 SEE ALSO 👀

  • Official documentation — go read it, bestie, iykyk 🦋

and that's a wrap on FLATC(1)!! 💖 this page is from January 2025, it's the FLATC(1) situation, and honestly? she ate. 🌈✨ go forth and compile something iconic, ily, bye!! 👑🌸🫶

📦 where this page comes from