Skip to content

Commit 2b0ce37

Browse files
dbaileychessdbaileychess
committed
Quick copy of all pages
1 parent 67bf108 commit 2b0ce37

24 files changed

+3552
-4
lines changed

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Install:
1414

1515
```
1616
pip install mkdocs-material
17+
pip install mkdocs-redirects
1718
```
1819

1920
Build and Serve:

‎docs/mkdocs.yml‎

Lines changed: 51 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,10 +54,40 @@ extra:
5454
link: https://twitter.com/dbaileychess
5555

5656
plugins:
57+
# Use redirects to update links from the original docs to the new ones.
58+
#
5759
# https://github.com/mkdocs/mkdocs-redirects
5860
- redirects:
61+
# Note the .html are suffixed with .md to avoid warnings. Got from
62+
# https://github.com/mkdocs/mkdocs-redirects/issues/51#issuecomment-2408548029
5963
redirect_maps:
60-
'flatbuffers_guide_use_cpp.html.md': 'cpp.md'
64+
'flatbuffers_guide_building.html.md': 'building.md'
65+
'flatbuffers_guide_tutorial.html.md': 'tutorial.md'
66+
'flatbuffers_guide_using_schema_compiler.html.md': 'flatc.md'
67+
'flatbuffers_guide_writing_schema.html.md': 'schema.md'
68+
'flatbuffers_guide_use_c.html.md': 'languages/c.md'
69+
'flatbuffers_guide_use_cpp.html.md': 'languages/cpp.md'
70+
'flatbuffers_guide_use_c-sharp.html.md': 'languages/c_sharp.md'
71+
'flatbuffers_guide_use_dart.html.md': 'languages/dart.md'
72+
'flatbuffers_guide_use_go.html.md': 'languages/go.md'
73+
'flatbuffers_guide_use_java.html.md': 'languages/java.md'
74+
'flatbuffers_guide_use_javascript.html.md': 'languages/javascript.md'
75+
'flatbuffers_guide_use_lobster.html.md': 'languages/lobster.md'
76+
'flatbuffers_guide_use_lua.html.md': 'languages/lua.md'
77+
'flatbuffers_guide_use_php.html.md': 'languages/php.md'
78+
'flatbuffers_guide_use_python.html.md': 'languages/python.md'
79+
'flatbuffers_guide_use_rust.html.md': 'languages/rust.md'
80+
'flatbuffers_guide_use_swift.html.md': 'languages/swift.md'
81+
'flatbuffers_guide_use_typescript.html.md': 'languages/typescript.md'
82+
'flatbuffers_grpc_guide_use_cpp.html.md' : "languages/cpp.md#grpc"
83+
'flatbuffers_support.html.md': 'support.md'
84+
'flatbuffers_white_paper.html.md': 'white_paper.md'
85+
'flatbuffers_grammar.html.md': 'grammar.md'
86+
'flatbuffers_internals.html.md': 'internals.md'
87+
'intermediate_representation.html.md': 'intermediate_representation.md'
88+
'flatbuffers_benchmarks.html.md': 'benchmarks.md'
89+
'flexbuffers.html.md': 'flexbuffers.md'
90+
'contributing.html.md': 'contributing.md'
6191

6292

6393
markdown_extensions:
@@ -94,7 +124,26 @@ nav:
94124
- Evolution: "evolution.md"
95125
- Grammar: "grammar.md"
96126
- Language Guides:
97-
- C++: "cpp.md"
127+
- C: "languages/c.md"
128+
- C++: "languages/cpp.md"
129+
- C#: "languages/c_sharp.md"
130+
- Dart: "languages/dart.md"
131+
- Go: "languages/go.md"
132+
- Java: "languages/java.md"
133+
- JavasScript: "languages/javascript.md"
134+
- Lobster: "languages/lobster.md"
135+
- Lua: "languages/lua.md"
136+
- PHP: "languages/php.md"
137+
- Python: "languages/python.md"
138+
- Rust: "languages/rust.md"
139+
- Swift: "languages/swift.md"
140+
- TypeScript: "languages/typescript.md"
141+
- Supported Configurations: "support.md"
142+
- White Paper: "white_paper.md"
98143
- Advanced:
144+
- FlatBuffers Internals: "internals.md"
145+
- Intermediate Representation: "intermediate_representation.md"
99146
- Annotating Buffers (.afb): "annotation.md"
147+
- Benchmarks: "benchmarks.md"
148+
- FlexBuffers (Schema-less version): "flexbuffers.md"
100149
- Contributing: "contributing.md"

‎docs/source/benchmarks.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
C++ Benchmarks {#flatbuffers_benchmarks}
2+
==========
3+
4+
Comparing against other serialization solutions, running on Windows 7
5+
64bit. We use the LITE runtime for Protocol Buffers (less code / lower
6+
overhead), Rapid JSON (one of the fastest C++ JSON parsers around),
7+
and pugixml, also one of the fastest XML parsers.
8+
9+
We also compare against code that doesn't use a serialization library
10+
at all (the column "Raw structs"), which is what you get if you write
11+
hardcoded code that just writes structs. This is the fastest possible,
12+
but of course is not cross platform nor has any kind of forwards /
13+
backwards compatibility.
14+
15+
We compare against Flatbuffers with the binary wire format (as
16+
intended), and also with JSON as the wire format with the optional JSON
17+
parser (which, using a schema, parses JSON into a binary buffer that can
18+
then be accessed as before).
19+
20+
The benchmark object is a set of about 10 objects containing an array, 4
21+
strings, and a large variety of int/float scalar values of all sizes,
22+
meant to be representative of game data, e.g. a scene format.
23+
24+
| | FlatBuffers (binary) | Protocol Buffers LITE | Rapid JSON | FlatBuffers (JSON) | pugixml | Raw structs |
25+
|--------------------------------------------------------|-----------------------|-----------------------|-----------------------|------------------------| ----------------------| ----------------------|
26+
| Decode + Traverse + Dealloc (1 million times, seconds) | 0.08 | 302 | 583 | 105 | 196 | 0.02 |
27+
| Decode / Traverse / Dealloc (breakdown) | 0 / 0.08 / 0 | 220 / 0.15 / 81 | 294 / 0.9 / 287 | 70 / 0.08 / 35 | 41 / 3.9 / 150 | 0 / 0.02 / 0 |
28+
| Encode (1 million times, seconds) | 3.2 | 185 | 650 | 169 | 273 | 0.15 |
29+
| Wire format size (normal / zlib, bytes) | 344 / 220 | 228 / 174 | 1475 / 322 | 1029 / 298 | 1137 / 341 | 312 / 187 |
30+
| Memory needed to store decoded wire (bytes / blocks) | 0 / 0 | 760 / 20 | 65689 / 4 | 328 / 1 | 34194 / 3 | 0 / 0 |
31+
| Transient memory allocated during decode (KB) | 0 | 1 | 131 | 4 | 34 | 0 |
32+
| Generated source code size (KB) | 4 | 61 | 0 | 4 | 0 | 0 |
33+
| Field access in handwritten traversal code | typed accessors | typed accessors | manual error checking | typed accessors | manual error checking | typed but no safety |
34+
| Library source code (KB) | 15 | some subset of 3800 | 87 | 43 | 327 | 0 |
35+
36+
### Some other serialization systems we compared against but did not benchmark (yet), in rough order of applicability:
37+
38+
- Cap'n'Proto promises to reduce Protocol Buffers much like FlatBuffers does,
39+
though with a more complicated binary encoding and less flexibility (no
40+
optional fields to allow deprecating fields or serializing with missing
41+
fields for which defaults exist).
42+
It currently also isn't fully cross-platform portable (lack of VS support).
43+
- msgpack: has very minimal forwards/backwards compatibility support when used
44+
with the typed C++ interface. Also lacks VS2010 support.
45+
- Thrift: very similar to Protocol Buffers, but appears to be less efficient,
46+
and have more dependencies.
47+
- YAML: a superset of JSON and otherwise very similar. Used by e.g. Unity.
48+
- C# comes with built-in serialization functionality, as used by Unity also.
49+
Being tied to the language, and having no automatic versioning support
50+
limits its applicability.
51+
- Project Anarchy (the free mobile engine by Havok) comes with a serialization
52+
system, that however does no automatic versioning (have to code around new
53+
fields manually), is very much tied to the rest of the engine, and works
54+
without a schema to generate code (tied to your C++ class definition).
55+
56+
### Code for benchmarks
57+
58+
Code for these benchmarks sits in `benchmarks/` in git branch `benchmarks`.
59+
It sits in its own branch because it has submodule dependencies that the main
60+
project doesn't need, and the code standards do not meet those of the main
61+
project. Please read `benchmarks/cpp/README.txt` before working with the code.
62+
63+
<br>

‎docs/source/cpp.md‎

Lines changed: 0 additions & 2 deletions
This file was deleted.

‎docs/source/flatc.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,4 +85,219 @@ list of `FILES...`.
8585
This will generate a `mydata.json` file.
8686

8787

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+
262+
Additional 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+
301+
NOTE: short-form options for generators are deprecated, use the long form
302+
whenever possible.
88303

0 commit comments

Comments
 (0)