Quick copy of all pages

docs/README.md

@@ -14,6 +14,7 @@ Install:
 
 ```
 pip install mkdocs-material
+pip install mkdocs-redirects
 ```
 
 Build and Serve:

docs/mkdocs.yml

@@ -54,10 +54,40 @@ extra:
       link: https://twitter.com/dbaileychess
 
 plugins:
+  # Use redirects to update links from the original docs to the new ones.
+  #
   # https://github.com/mkdocs/mkdocs-redirects
   - redirects:
+      # Note the .html are suffixed with .md to avoid warnings. Got from 
+      # https://github.com/mkdocs/mkdocs-redirects/issues/51#issuecomment-2408548029
       redirect_maps:
-        'flatbuffers_guide_use_cpp.html.md': 'cpp.md'
+        'flatbuffers_guide_building.html.md': 'building.md'
+        'flatbuffers_guide_tutorial.html.md': 'tutorial.md'
+        'flatbuffers_guide_using_schema_compiler.html.md': 'flatc.md'
+        'flatbuffers_guide_writing_schema.html.md': 'schema.md'
+        'flatbuffers_guide_use_c.html.md': 'languages/c.md'
+        'flatbuffers_guide_use_cpp.html.md': 'languages/cpp.md'
+        'flatbuffers_guide_use_c-sharp.html.md': 'languages/c_sharp.md'
+        'flatbuffers_guide_use_dart.html.md': 'languages/dart.md'
+        'flatbuffers_guide_use_go.html.md': 'languages/go.md'
+        'flatbuffers_guide_use_java.html.md': 'languages/java.md'
+        'flatbuffers_guide_use_javascript.html.md': 'languages/javascript.md'
+        'flatbuffers_guide_use_lobster.html.md': 'languages/lobster.md'
+        'flatbuffers_guide_use_lua.html.md': 'languages/lua.md'
+        'flatbuffers_guide_use_php.html.md': 'languages/php.md'
+        'flatbuffers_guide_use_python.html.md': 'languages/python.md'
+        'flatbuffers_guide_use_rust.html.md': 'languages/rust.md'
+        'flatbuffers_guide_use_swift.html.md': 'languages/swift.md'
+        'flatbuffers_guide_use_typescript.html.md': 'languages/typescript.md'
+        'flatbuffers_grpc_guide_use_cpp.html.md' : "languages/cpp.md#grpc"
+        'flatbuffers_support.html.md': 'support.md'
+        'flatbuffers_white_paper.html.md': 'white_paper.md'
+        'flatbuffers_grammar.html.md': 'grammar.md'
+        'flatbuffers_internals.html.md': 'internals.md'
+        'intermediate_representation.html.md': 'intermediate_representation.md'
+        'flatbuffers_benchmarks.html.md': 'benchmarks.md'
+        'flexbuffers.html.md': 'flexbuffers.md'
+        'contributing.html.md': 'contributing.md'
 
 
 markdown_extensions:
@@ -94,7 +124,26 @@ nav:
     - Evolution: "evolution.md"
     - Grammar: "grammar.md"
   - Language Guides:
-    - C++: "cpp.md"
+    - C: "languages/c.md"
+    - C++: "languages/cpp.md"
+    - C#: "languages/c_sharp.md"
+    - Dart: "languages/dart.md"
+    - Go: "languages/go.md"
+    - Java: "languages/java.md"
+    - JavasScript: "languages/javascript.md"
+    - Lobster: "languages/lobster.md"
+    - Lua: "languages/lua.md"
+    - PHP: "languages/php.md"
+    - Python: "languages/python.md"
+    - Rust: "languages/rust.md"
+    - Swift: "languages/swift.md"
+    - TypeScript: "languages/typescript.md"
+  - Supported Configurations: "support.md"
+  - White Paper: "white_paper.md"
   - Advanced:
+    - FlatBuffers Internals: "internals.md"
+    - Intermediate Representation: "intermediate_representation.md"
     - Annotating Buffers (.afb): "annotation.md"
+    - Benchmarks: "benchmarks.md"
+  - FlexBuffers (Schema-less version): "flexbuffers.md"
   - Contributing: "contributing.md"

docs/source/benchmarks.md

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

docs/source/flatc.md

@@ -85,4 +85,219 @@ list of `FILES...`.
     This will generate a `mydata.json` file.
 
 
+### Additional options
+
+-   `-o PATH` : Output all generated files to PATH (either absolute, or
+    relative to the current directory). If omitted, PATH will be the
+    current directory. PATH should end in your systems path separator,
+    e.g. `/` or `\`.
+
+-   `-I PATH` : when encountering `include` statements, attempt to load the
+    files from this path. Paths will be tried in the order given, and if all
+    fail (or none are specified) it will try to load relative to the path of
+    the schema file being parsed.
+
+-   `-M` : Print make rules for generated files.
+
+-   `--strict-json` : Require & 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.
+
+-   `--allow-non-utf8` : Pass non-UTF-8 input through parser and emit nonstandard
+    \x escapes in JSON. (Default is to raise parse error on non-UTF-8 input.)
+
+-   `--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 the original behavior is required (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 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). Recommended only to be used
+    if other options are insufficient.
+
+-   `--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 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.
+
+-   `--no-cpp-direct-copy` : Don't generate direct copy methods for C++
+    object-based API.
+
+-   `--cpp-std CPP_STD` : Generate a C++ code using features of 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 given a mismatched schema.
+
+-   `--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.
+
+-   `--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.
+
+-   `--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. Useful to check if 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.
+
+-   `--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.
+
+-   `--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:
+
+    ```cpp
+      #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++]` Whether to generate `#include <header>`
+    instead of `#include "header.h"` for all headers when compiling gRPC for
+    C++. For example, compiling gRPC for C++ with `--grpc-use-system-headers`
+    will generate the following includes:
+
+    ```cpp
+      #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: This option can be negated with `--no-grpc-use-system-headers`.
+
+-   `--grpc-python-typed-handlers`: `[Python]` Whether to generate the typed
+    handlers that use the generated Python classes instead of raw bytes for
+    requests/responses.
+
+NOTE: short-form options for generators are deprecated, use the long form
+whenever possible.