1# FlatBuffers Compiler (`flatc`) 2 3The main compiler for FlatBuffers is called `flatc` and is used to convert 4schema definitions into generated code files for a variety of languages. 5 6After [building](building.md) `flatc`, it is used as follows: 7 8```sh 9flatc [ GENERATOR_OPTIONS ] [ -o PATH ] [- I PATH ] 10 FILES... 11 [ -- BINARY_FILES... ] 12``` 13 14* The `GENERATOR_OPTIONS` specify the language(s) to compile code for as well as 15various features to enable/disable. 16 17* The `-o PATH` specifies the path where the generated files are placed. It 18defaults to the current path if not specified. 19 20* The `-I PATH` specifies the paths where included schema files are located. It 21 defaults to the current path if not specified. 22 23## Input Files 24 25`FILES...` specifies one or more schema or data files to process. They are 26processed in the order provided. 27 28### Schema Files 29 30For schema files, language specifiers indicate what languages to generate code 31for. 32 33 * `--cpp`: C++ 34 * `--java`: Java 35 * `--kotlin`: Kotlin 36 * `--csharp`: C# 37 * `--go`: Golang 38 * `--python`: Python 39 * `--js`: JavaScript 40 * `--ts`: TypeScript 41 * `--php`: PHP 42 * `--dart`: Dart 43 * `--lua`: Lua 44 * `--lobster`: Lobster 45 * `--rust`: Rust 46 * `--swift`: Swift 47 * `--nim`: Nim 48 49Additionally, adding: 50 51 * `--grpc` Will generate RPC stub code for gRPC (not available in all 52 languages) 53 54### Data Files 55 56If `FILES...` contain data files, they can be exported to either a binary or 57JSON representation. 58 59* `--binary`, `-b`: Generate a binary file containing a serialized flatbuffer. 60* `--json`, `-j`: Generate JSON file from a serialized flatbuffer. 61 62Both options require the corresponding schema file to be included first in the 63list of `FILES...`. 64 65=== "To Binary" 66 67 To serialize the JSON data in `mydata.json` using the schema `myschema.fbs`: 68 69 ```sh 70 flatc --binary myschema.fbs mydata.json 71 ``` 72 73 This will generate a `mydata_wire.bin` file containing the serialized 74 flatbuffer data. 75 76=== "To JSON" 77 78 To convert the serialized binary flatbuffer `mydata.bin` using the schema 79 `myschema.fbs` to JSON: 80 81 ```sh 82 flatc --json myschema.fbs mydata.bin 83 ``` 84 85 This will generate a `mydata.json` file. 86 87 88### Additional options 89 90- `-o PATH` : Output all generated files to PATH (either absolute, or 91 relative to the current directory). If omitted, PATH will be the 92 current directory. PATH should end in your systems path separator, 93 e.g. `/` or `\`. 94 95- `-I PATH` : when encountering `include` statements, attempt to load the 96 files from this path. Paths will be tried in the order given, and if all 97 fail (or none are specified) it will try to load relative to the path of 98 the schema file being parsed. 99 100- `-M` : Print make rules for generated files. 101 102- `--strict-json` : Require & generate strict JSON (field names are enclosed 103 in quotes, no trailing commas in tables/vectors). By default, no quotes are 104 required/generated, and trailing commas are allowed. 105 106- `--allow-non-utf8` : Pass non-UTF-8 input through parser and emit nonstandard 107 \x escapes in JSON. (Default is to raise parse error on non-UTF-8 input.) 108 109- `--natural-utf8` : Output strings with UTF-8 as human-readable strings. 110 By default, UTF-8 characters are printed as \uXXXX escapes." 111 112- `--defaults-json` : Output fields whose value is equal to the default value 113 when writing JSON text. 114 115- `--no-prefix` : Don't prefix enum values in generated C++ by their enum 116 type. 117 118- `--scoped-enums` : Use C++11 style scoped and strongly typed enums in 119 generated C++. This also implies `--no-prefix`. 120 121- `--no-emit-min-max-enum-values` : Disable generation of MIN and MAX 122 enumerated values for scoped enums and prefixed enums. 123 124- `--gen-includes` : (deprecated), this is the default behavior. 125 If the original behavior is required (no include 126 statements) use `--no-includes.` 127 128- `--no-includes` : Don't generate include statements for included schemas the 129 generated file depends on (C++ / Python). 130 131- `--gen-mutable` : Generate additional non-const accessors for mutating 132 FlatBuffers in-place. 133 134- `--gen-onefile` : Generate single output file for C#, Go, and Python. 135 136- `--gen-name-strings` : Generate type name functions for C++. 137 138- `--gen-object-api` : Generate an additional object-based API. This API is 139 more convenient for object construction and mutation than the base API, 140 at the cost of efficiency (object allocation). Recommended only to be used 141 if other options are insufficient. 142 143- `--gen-compare` : Generate operator== for object-based API types. 144 145- `--gen-nullable` : Add Clang \_Nullable for C++ pointer. or @Nullable for Java. 146 147- `--gen-generated` : Add @Generated annotation for Java. 148 149- `--gen-jvmstatic` : Add @JvmStatic annotation for Kotlin methods 150 in companion object for interop from Java to Kotlin. 151 152- `--gen-all` : Generate not just code for the current schema files, but 153 for all files it includes as well. If the language uses a single file for 154 output (by default the case for C++ and JS), all code will end up in 155 this one file. 156 157- `--cpp-include` : Adds an #include in generated file 158 159- `--cpp-ptr-type T` : Set object API pointer type (default std::unique_ptr) 160 161- `--cpp-str-type T` : Set object API string type (default std::string) 162 T::c_str(), T::length() and T::empty() must be supported. 163 The custom type also needs to be constructible from std::string (see the 164 --cpp-str-flex-ctor option to change this behavior). 165 166- `--cpp-str-flex-ctor` : Don't construct custom string types by passing 167 std::string from Flatbuffers, but (char* + length). This allows efficient 168 construction of custom string types, including zero-copy construction. 169 170- `--no-cpp-direct-copy` : Don't generate direct copy methods for C++ 171 object-based API. 172 173- `--cpp-std CPP_STD` : Generate a C++ code using features of selected C++ standard. 174 Supported `CPP_STD` values: 175 * `c++0x` - generate code compatible with old compilers (VS2010), 176 * `c++11` - use C++11 code generator (default), 177 * `c++17` - use C++17 features in generated code (experimental). 178 179- `--object-prefix` : Customise class prefix for C++ object-based API. 180 181- `--object-suffix` : Customise class suffix for C++ object-based API. 182 183- `--go-namespace` : Generate the overrided namespace in Golang. 184 185- `--go-import` : Generate the overrided import for flatbuffers in Golang. 186 (default is "github.com/google/flatbuffers/go"). 187 188- `--raw-binary` : Allow binaries without a file_indentifier to be read. 189 This may crash flatc given a mismatched schema. 190 191- `--size-prefixed` : Input binaries are size prefixed buffers. 192 193- `--proto`: Expect input files to be .proto files (protocol buffers). 194 Output the corresponding .fbs file. 195 Currently supports: `package`, `message`, `enum`, nested declarations, 196 `import` (use `-I` for paths), `extend`, `oneof`, `group`. 197 Does not support, but will skip without error: `option`, `service`, 198 `extensions`, and most everything else. 199 200- `--oneof-union` : Translate .proto oneofs to flatbuffer unions. 201 202- `--grpc` : Generate GRPC interfaces for the specified languages. 203 204- `--schema`: Serialize schemas instead of JSON (use with -b). This will 205 output a binary version of the specified schema that itself corresponds 206 to the reflection/reflection.fbs schema. Loading this binary file is the 207 basis for reflection functionality. 208 209- `--bfbs-comments`: Add doc comments to the binary schema files. 210 211- `--conform FILE` : Specify a schema the following schemas should be 212 an evolution of. Gives errors if not. Useful to check if schema 213 modifications don't break schema evolution rules. 214 215- `--conform-includes PATH` : Include path for the schema given with 216 `--conform PATH`. 217 218- `--filename-suffix SUFFIX` : The suffix appended to the generated 219 file names. Default is '\_generated'. 220 221- `--filename-ext EXTENSION` : The extension appended to the generated 222 file names. Default is language-specific (e.g. "h" for C++). This 223 should not be used when multiple languages are specified. 224 225- `--include-prefix PATH` : Prefix this path to any generated include 226 statements. 227 228- `--keep-prefix` : Keep original prefix of schema include statement. 229 230- `--reflect-types` : Add minimal type reflection to code generation. 231 232- `--reflect-names` : Add minimal type/name reflection. 233 234- `--root-type T` : Select or override the default root_type. 235 236- `--require-explicit-ids` : When parsing schemas, require explicit ids (id: x). 237 238- `--force-defaults` : Emit default values in binary output from JSON. 239 240- `--force-empty` : When serializing from object API representation, force 241 strings and vectors to empty rather than null. 242 243- `--force-empty-vectors` : When serializing from object API representation, force 244 vectors to empty rather than null. 245 246- `--flexbuffers` : Used with "binary" and "json" options, it generates 247 data using schema-less FlexBuffers. 248 249- `--no-warnings` : Inhibit all warning messages. 250 251- `--cs-global-alias` : Prepend `global::` to all user generated csharp classes and structs. 252 253- `--json-nested-bytes` : Allow a nested_flatbuffer field to be parsed as a 254 vector of bytes in JSON, which is unsafe unless checked by a verifier 255 afterwards. 256 257- `--python-no-type-prefix-suffix` : Skip emission of Python functions that are prefixed 258 with typenames 259 260- `--python-typing` : Generate Python type annotations 261 262Additional gRPC options: 263 264- `--grpc-filename-suffix`: `[C++]` An optional suffix for the generated 265 files' names. For example, compiling gRPC for C++ with 266 `--grpc-filename-suffix=.fbs` will generate `{name}.fbs.h` and 267 `{name}.fbs.cc` files. 268 269- `--grpc-additional-header`: `[C++]` Additional headers to include in the 270 generated files. 271 272- `--grpc-search-path`: `[C++]` An optional prefix for the gRPC runtime path. 273 For example, compiling gRPC for C++ with `--grpc-search-path=some/path` will 274 generate the following includes: 275 276 ```cpp 277 #include "some/path/grpcpp/impl/codegen/async_stream.h" 278 #include "some/path/grpcpp/impl/codegen/async_unary_call.h" 279 #include "some/path/grpcpp/impl/codegen/method_handler.h" 280 ... 281 ``` 282 283- `--grpc-use-system-headers`: `[C++]` Whether to generate `#include <header>` 284 instead of `#include "header.h"` for all headers when compiling gRPC for 285 C++. For example, compiling gRPC for C++ with `--grpc-use-system-headers` 286 will generate the following includes: 287 288 ```cpp 289 #include <some/path/grpcpp/impl/codegen/async_stream.h> 290 #include <some/path/grpcpp/impl/codegen/async_unary_call.h> 291 #include <some/path/grpcpp/impl/codegen/method_handler.h> 292 ... 293 ``` 294 295 NOTE: This option can be negated with `--no-grpc-use-system-headers`. 296 297- `--grpc-python-typed-handlers`: `[Python]` Whether to generate the typed 298 handlers that use the generated Python classes instead of raw bytes for 299 requests/responses. 300 301NOTE: short-form options for generators are deprecated, use the long form 302whenever possible. 303 304