BigfootDev/flatbuffers-bigfoot
1
0
Fork 0
forked from BigfootDev/flatbuffers
Code Pull Requests Activity

Fixed broken links

Browse Source
This commit is contained in:
Derek Bailey
2025-01-09 23:48:13 -08:00
parent 086097ff94
commit 569e6cb461
22 changed files with 200 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs-old/source/Building.md
View File

@@ -72,6 +72,7 @@ We generate [SLSA3 signatures](slsa.dev) using the OpenSSF's [slsa-framework/sls
```shell
$ slsa-verifier -artifact-path <downloaded.zip> -provenance attestation.intoto.jsonl -source github.com/google/flatbuffers -tag <version>
PASSED: Verified SLSA provenance
```
## Building for Android

13
docs/source/annotation.md
View File

@@ -28,15 +28,12 @@ cd tests/annotated_binary
Which will produce a `annotated_binary.afb` file in the current directory.
The `annotated_binary.bin` is the flatbufer binary of the data contained within
`annotated_binary.json`, which was made by the following command:
!!! Tip
The `annotated_binary.bin` is the flatbufer binary of the data contained
within `annotated_binary.json`, which was made by the following command:
```sh
..\..\flatc -b annotated_binary.fbs annotated_binary.json
```
```sh
..\..\flatc -b annotated_binary.fbs annotated_binary.json
```
## .afb Text Format

93
docs/source/building.md
View File

@@ -16,11 +16,9 @@ Use `cmake` to configure a project based on your environment and platform.
cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release
```
!!! note
To use `clang` instead of `gcc` you may need to set prepend some
environment variables e.g. `CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake
-G "Unix MakeFiles"`
To use `clang` instead of `gcc` you may need to set prepend some environment
variables e.g. `CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake -G "Unix
MakeFiles"`
=== "Windows"
@@ -78,3 +76,88 @@ Once the project files are generated, build as normal for your platform.
## Building with Bazel
## Building with VCPKG
You can download and install flatbuffers using the [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager:
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install flatbuffers
The flatbuffers port in vcpkg is kept up to date by Microsoft team members and community contributors.
If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
## Building for Android
There is a `flatbuffers/android` directory that contains all you need to build
the test executable on android (use the included `build_apk.sh` script, or use
`ndk_build` / `adb` etc. as usual). Upon running, it will output to the log
if tests succeeded or not.
You may also run an android sample from inside the `flatbuffers/samples`, by
running the `android_sample.sh` script. Optionally, you may go to the
`flatbuffers/samples/android` folder and build the sample with the
`build_apk.sh` script or `ndk_build` / `adb` etc.
## Using FlatBuffers in your own projects
For C++, there is usually no runtime to compile, as the code consists of a
single header, `include/flatbuffers/flatbuffers.h`. You should add the
`include` folder to your include paths. If you wish to be
able to load schemas and/or parse text into binary buffers at runtime,
you additionally need the other headers in `include/flatbuffers`. You must
also compile/link `src/idl_parser.cpp` (and `src/idl_gen_text.cpp` if you
also want to be able convert binary to text).
To see how to include FlatBuffers in any of our supported languages, please
view the [Tutorial](tutorial.md) and select your appropriate
language using the radio buttons.
### Using in CMake-based projects
If you want to use FlatBuffers in a project which already uses CMake, then a more
robust and flexible approach is to build FlatBuffers as part of that project directly.
This is done by making the FlatBuffers source code available to the main build
and adding it using CMake's `add_subdirectory()` command. This has the
significant advantage that the same compiler and linker settings are used
between FlatBuffers and the rest of your project, so issues associated with using
incompatible libraries (eg debug/release), etc. are avoided. This is
particularly useful on Windows.
Suppose you put FlatBuffers source code in directory `${FLATBUFFERS_SRC_DIR}`.
To build it as part of your project, add following code to your `CMakeLists.txt` file:
```cmake
# Add FlatBuffers directly to our build. This defines the `flatbuffers` target.
add_subdirectory(${FLATBUFFERS_SRC_DIR}
${CMAKE_CURRENT_BINARY_DIR}/flatbuffers-build
EXCLUDE_FROM_ALL)
# Now simply link against flatbuffers as needed to your already declared target.
# The flatbuffers target carry header search path automatically if CMake > 2.8.11.
target_link_libraries(own_project_target PRIVATE flatbuffers)
```
When build your project the `flatbuffers` library will be compiled and linked
to a target as part of your project.
#### Override default depth limit of nested objects
To override [the depth limit of recursion](languages/cpp.md),
add this directive:
```cmake
set(FLATBUFFERS_MAX_PARSING_DEPTH 16)
```
to `CMakeLists.txt` file before `add_subdirectory(${FLATBUFFERS_SRC_DIR})` line.
## Downloading binaries
You can download the binaries from the
[GitHub release page](https://github.com/google/flatbuffers/releases).
We generate [SLSA3 signatures](http://slsa.dev) using the OpenSSF's [slsa-framework/slsa-github-generator](https://github.com/slsa-framework/slsa-github-generator). To verify the binaries:
1. Install the verification tool from [slsa-framework/slsa-verifier#installation](https://github.com/slsa-framework/slsa-verifier#installation)
1. Download the file named `attestation.intoto.jsonl` from the GitHub release
1. Run:
```shell
$ slsa-verifier -artifact-path <downloaded.zip> -provenance attestation.intoto.jsonl -source github.com/google/flatbuffers -tag <version>
PASSED: Verified SLSA provenance
```

5
docs/source/evolution.md
View File

@@ -20,9 +20,8 @@ of the added field if accessed).
Older code will simply ignore the new field in the flatbuffer.
!!! tip "Use `id` attributes"
You can ignore this rule if you use the `id` attribute on all the fields of a table.
You can ignore this rule if you use the `id` attribute on all the fields of a
table.
### Removal

2
docs/source/flexbuffers.md
View File

@@ -163,7 +163,7 @@ map.get("unknown").isNull(); // true
# Binary encoding
A description of how FlexBuffers are encoded is in the
[internals](@ref flatbuffers_internals) document.
[internals](internals.md) document.
# Nesting inside a FlatBuffer

2
docs/source/internals.md
View File

@@ -316,7 +316,7 @@ that may further help clarify the format.
# FlexBuffers
The [schema-less](@ref flexbuffers) version of FlatBuffers have their
The [schema-less](flexbuffers.md) version of FlatBuffers have their
own encoding, detailed here.
It shares many properties mentioned above, in that all data is accessed

2
docs/source/languages/c.md
View File

@@ -12,7 +12,7 @@ project.
## General Documention
- [Tutorial](@ref flatbuffers_guide_tutorial) - select C as language
- [Tutorial](../tutorial.md) - select C as language
when scrolling down
- [FlatCC Guide](https://github.com/dvidelabs/flatcc#flatcc-flatbuffers-in-c-for-c)
- [The C Builder Interface](https://github.com/dvidelabs/flatcc/blob/master/doc/builder.md#the-builder-interface)

12
docs/source/languages/c_sharp.md
View File

@@ -4,15 +4,15 @@ Use in C\# {#flatbuffers_guide_use_c-sharp}
## Before you get started
Before diving into the FlatBuffers usage in C#, it should be noted that
the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to
the [Tutorial](../tutorial.md) page has a complete guide to
general FlatBuffers usage in all of the supported languages (including C#).
This page is designed to cover the nuances of FlatBuffers usage,
specific to C#.
You should also have read the [Building](@ref flatbuffers_guide_building)
You should also have read the [Building](../building.md)
documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema).
[Using the schema compiler](../flatc.md) and
[Writing a schema](../schema.md).
## FlatBuffers C# code location
@@ -62,7 +62,7 @@ by running the following commands from inside the `FlatBuffers.Test` folder:
## Using the FlatBuffers C# library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
*Note: See [Tutorial](../tutorial.md) for a more in-depth
example of how to use FlatBuffers in C#.*
FlatBuffers supports reading and writing binary FlatBuffers in C#.
@@ -141,7 +141,7 @@ To use it:
## Buffer verification
As mentioned in [C++ Usage](@ref flatbuffers_guide_use_cpp) buffer
As mentioned in [C++ Usage](cpp.md) buffer
accessor functions do not verify buffer offsets at run-time.
If it is necessary, you can optionally use a buffer verifier before you
access the data. This verifier will check all offsets, all sizes of

20
docs/source/languages/cpp.md
View File

@@ -3,7 +3,7 @@
## Before you get started
Before diving into the FlatBuffers usage in C++, it should be noted that
the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide
the [Tutorial](../tutorial.md) page has a complete guide
to general FlatBuffers usage in all of the supported languages (including C++).
This page is designed to cover the nuances of FlatBuffers usage, specific to
C++.
@@ -12,8 +12,8 @@ C++.
This page assumes you have written a FlatBuffers schema and compiled it
with the Schema Compiler. If you have not, please see
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler)
and [Writing a schema](@ref flatbuffers_guide_writing_schema).
[Using the schema compiler](../flatc.md)
and [Writing a schema](../schema.md).
Assuming you wrote a schema, say `mygame.fbs` (though the extension doesn't
matter), you've generated a C++ header called `mygame_generated.h` using the
@@ -34,7 +34,7 @@ The test code itself is located in
[test.cpp](https://github.com/google/flatbuffers/blob/master/tests/test.cpp).
This test file is built alongside `flatc`. To review how to build the project,
please read the [Building](@ref flatbuffers_guide_building) documentation.
please read the [Building](../building.md) documentation.
To run the tests, execute `flattests` from the root `flatbuffers/` directory.
For example, on [Linux](https://en.wikipedia.org/wiki/Linux), you would simply
@@ -42,7 +42,7 @@ run: `./flattests`.
## Using the FlatBuffers C++ library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
*Note: See [Tutorial](../tutorial.md) for a more in-depth
example of how to use FlatBuffers in C++.*
FlatBuffers supports both reading and writing FlatBuffers in C++.
@@ -261,7 +261,7 @@ using hashes which are then represented as typed pointers in the object API.
To make this work have a field in the objects you want to referred to which is
using the string hashing feature (see `hash` attribute in the
[schema](@ref flatbuffers_guide_writing_schema) documentation). Then you have
[schema](../schema.md) documentation). Then you have
a similar hash in the field referring to it, along with a `cpp_type`
attribute specifying the C++ type this will refer to (this can be any C++
type, and will get a `*` added).
@@ -555,11 +555,11 @@ recursion depth. Number of nested declarations in a schema or number of
nested json-objects is limited. By default, this depth limit set to `64`.
It is possible to override this limit with `FLATBUFFERS_MAX_PARSING_DEPTH`
definition. This definition can be helpful for testing purposes or embedded
applications. For details see [build](@ref flatbuffers_guide_building) of
applications. For details see [build](../building.md) of
CMake-based projects.
## Dependence from C-locale {#flatbuffers_locale_cpp}
The Flatbuffers [grammar](@ref flatbuffers grammar) uses ASCII
The Flatbuffers [grammar](../grammar.md) uses ASCII
character set for identifiers, alphanumeric literals, reserved words.
Internal implementation of the Flatbuffers depends from functions which
@@ -602,7 +602,7 @@ compatible with the `IEEE-754` floating-point standard.
The schema and json parser may fail if `fast-math` or `/fp:fast` mode is active.
### Support of hexadecimal and special floating-point numbers
According to the [grammar](@ref flatbuffers_grammar) `fbs` and `json` files
According to the [grammar](../grammar.md) `fbs` and `json` files
may use hexadecimal and special (`NaN`, `Inf`) floating-point literals.
The Flatbuffers uses `strtof` and `strtod` functions to parse floating-point
literals. The Flatbuffers library has a code to detect a compiler compatibility
@@ -625,7 +625,7 @@ According to the `IEEE-754`, a comparison with `NaN` always returns
an unordered result even when compared with itself. As a result, a whole
Flatbuffers object will be not equal to itself if has one or more `NaN`.
Flatbuffers scalar fields that have the default value are not actually stored
in the serialized data but are generated in code (see [Writing a schema](@ref flatbuffers_guide_writing_schema)).
in the serialized data but are generated in code (see [Writing a schema](../schema.md)).
Scalar fields with `NaN` defaults break this behavior.
If a schema has a lot of `NaN` defaults the Flatbuffers can override
the unordered comparison by the ordered: `(NaN==NaN)->true`.

10
docs/source/languages/dart.md
View File

@@ -4,15 +4,15 @@ Use in Dart {#flatbuffers_guide_use_dart}
## Before you get started
Before diving into the FlatBuffers usage in Dart, it should be noted that
the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide
the [Tutorial](../tutorial.md) page has a complete guide
to general FlatBuffers usage in all of the supported languages (including Dart).
This page is designed to cover the nuances of FlatBuffers usage, specific to
Dart.
You should also have read the [Building](@ref flatbuffers_guide_building)
You should also have read the [Building](../building.md)
documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema).
[Using the schema compiler](../flatc.md) and
[Writing a schema](../schema.md).
## FlatBuffers Dart library code location
@@ -34,7 +34,7 @@ to be installed.*
## Using the FlatBuffers Dart library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
*Note: See [Tutorial](../tutorial.md) for a more in-depth
example of how to use FlatBuffers in Dart.*
FlatBuffers supports reading and writing binary FlatBuffers in Dart.

10
docs/source/languages/go.md
View File

@@ -4,15 +4,15 @@ Use in Go {#flatbuffers_guide_use_go}
## Before you get started
Before diving into the FlatBuffers usage in Go, it should be noted that
the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide
the [Tutorial](../tutorial.md) page has a complete guide
to general FlatBuffers usage in all of the supported languages (including Go).
This page is designed to cover the nuances of FlatBuffers usage, specific to
Go.
You should also have read the [Building](@ref flatbuffers_guide_building)
You should also have read the [Building](../building.md)
documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema).
[Using the schema compiler](../flatc.md) and
[Writing a schema](../schema.md).
## FlatBuffers Go library code location
@@ -34,7 +34,7 @@ be installed.*
## Using the FlatBuffers Go library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
*Note: See [Tutorial](../tutorial.md) for a more in-depth
example of how to use FlatBuffers in Go.*
FlatBuffers supports reading and writing binary FlatBuffers in Go.

10
docs/source/languages/java.md
View File

@@ -4,15 +4,15 @@ Use in Java {#flatbuffers_guide_use_java}
## Before you get started
Before diving into the FlatBuffers usage in Java, it should be noted that
the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to
the [Tutorial](../tutorial.md) page has a complete guide to
general FlatBuffers usage in all of the supported languages (including Java).
This page is designed to cover the nuances of FlatBuffers usage,
specific to Java.
You should also have read the [Building](@ref flatbuffers_guide_building)
You should also have read the [Building](../building.md)
documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema).
[Using the schema compiler](../flatc.md) and
[Writing a schema](../schema.md).
## FlatBuffers Java code location
@@ -38,7 +38,7 @@ is installed.*
## Using the FlatBuffers Java library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
*Note: See [Tutorial](../tutorial.md) for a more in-depth
example of how to use FlatBuffers in Java.*
FlatBuffers supports reading and writing binary FlatBuffers in Java.

12
docs/source/languages/javascript.md
View File

@@ -4,15 +4,15 @@ Use in JavaScript {#flatbuffers_guide_use_javascript}
## Before you get started
Before diving into the FlatBuffers usage in JavaScript, it should be noted that
the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to
the [Tutorial](../tutorial.md) page has a complete guide to
general FlatBuffers usage in all of the supported languages
(including JavaScript). This page is specifically designed to cover the nuances
of FlatBuffers usage in JavaScript.
You should also have read the [Building](@ref flatbuffers_guide_building)
You should also have read the [Building](../building.md)
documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema).
[Using the schema compiler](../flatc.md) and
[Writing a schema](../schema.md).
## FlatBuffers JavaScript library code location
@@ -25,13 +25,13 @@ folder as the source.
## Using the FlatBuffers JavaScript library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
*Note: See [Tutorial](../tutorial.md) for a more in-depth
example of how to use FlatBuffers.*
Due to the complexity related with large amounts of JS flavors and module types,
native JS support has been replaced in 2.0 by transpilation from TypeScript.
Please look at [TypeScript usage](@ref flatbuffers_guide_use_typescript) and
Please look at [TypeScript usage](typescript.md) and
transpile your sources to desired JS flavor. The minimal steps to get up and
running with JS are:

10
docs/source/languages/lobster.md
View File

@@ -4,15 +4,15 @@ Use in Lobster {#flatbuffers_guide_use_lobster}
## Before you get started
Before diving into the FlatBuffers usage in Lobster, it should be noted that the
[Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to general
[Tutorial](../tutorial.md) page has a complete guide to general
FlatBuffers usage in all of the supported languages (including Lobster). This
page is designed to cover the nuances of FlatBuffers usage, specific to
Lobster.
You should also have read the [Building](@ref flatbuffers_guide_building)
You should also have read the [Building](../building.md)
documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema).
[Using the schema compiler](../flatc.md) and
[Writing a schema](../schema.md).
## FlatBuffers Lobster library code location
@@ -34,7 +34,7 @@ platform.
## Using the FlatBuffers Lobster library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
*Note: See [Tutorial](../tutorial.md) for a more in-depth
example of how to use FlatBuffers in Lobster.*
There is support for both reading and writing FlatBuffers in Lobster.

10
docs/source/languages/lua.md
View File

@@ -4,15 +4,15 @@ Use in Lua {#flatbuffers_guide_use_lua}
## Before you get started
Before diving into the FlatBuffers usage in Lua, it should be noted that the
[Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to general
[Tutorial](../tutorial.md) page has a complete guide to general
FlatBuffers usage in all of the supported languages (including Lua). This
page is designed to cover the nuances of FlatBuffers usage, specific to
Lua.
You should also have read the [Building](@ref flatbuffers_guide_building)
You should also have read the [Building](../building.md)
documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema).
[Using the schema compiler](../flatc.md) and
[Writing a schema](../schema.md).
## FlatBuffers Lua library code location
@@ -34,7 +34,7 @@ blob/master/tests/LuaTest.sh) shell script.
## Using the FlatBuffers Lua library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
*Note: See [Tutorial](../tutorial.md) for a more in-depth
example of how to use FlatBuffers in Lua.*
There is support for both reading and writing FlatBuffers in Lua.

10
docs/source/languages/php.md
View File

@@ -4,15 +4,15 @@ Use in PHP {#flatbuffers_guide_use_php}
## Before you get started
Before diving into the FlatBuffers usage in PHP, it should be noted that
the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to
the [Tutorial](../tutorial.md) page has a complete guide to
general FlatBuffers usage in all of the supported languages
(including PHP). This page is specifically designed to cover the nuances of
FlatBuffers usage in PHP.
You should also have read the [Building](@ref flatbuffers_guide_building)
You should also have read the [Building](../building.md)
documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema).
[Using the schema compiler](../flatc.md) and
[Writing a schema](../schema.md).
## FlatBuffers PHP library code location
@@ -33,7 +33,7 @@ You can run the test with `php phpTest.php` from the command line.
## Using theFlatBuffers PHP library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
*Note: See [Tutorial](../tutorial.md) for a more in-depth
example of how to use FlatBuffers in PHP.*
FlatBuffers supports both reading and writing FlatBuffers in PHP.

10
docs/source/languages/python.md
View File

@@ -4,15 +4,15 @@ Use in Python {#flatbuffers_guide_use_python}
## Before you get started
Before diving into the FlatBuffers usage in Python, it should be noted that the
[Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to general
[Tutorial](../tutorial.md) page has a complete guide to general
FlatBuffers usage in all of the supported languages (including Python). This
page is designed to cover the nuances of FlatBuffers usage, specific to
Python.
You should also have read the [Building](@ref flatbuffers_guide_building)
You should also have read the [Building](../building.md)
documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema).
[Using the schema compiler](../flatc.md) and
[Writing a schema](../schema.md).
## FlatBuffers Python library code location
@@ -35,7 +35,7 @@ installed.*
## Using the FlatBuffers Python library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
*Note: See [Tutorial](../tutorial.md) for a more in-depth
example of how to use FlatBuffers in Python.*
There is support for both reading and writing FlatBuffers in Python.

10
docs/source/languages/rust.md
View File

@@ -4,7 +4,7 @@ Use in Rust {#flatbuffers_guide_use_rust}
## Before you get started
Before diving into the FlatBuffers usage in Rust, it should be noted that
the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide
the [Tutorial](../tutorial.md) page has a complete guide
to general FlatBuffers usage in all of the supported languages (including Rust).
This page is designed to cover the nuances of FlatBuffers usage, specific to
Rust.
@@ -13,8 +13,8 @@ Rust.
This page assumes you have written a FlatBuffers schema and compiled it
with the Schema Compiler. If you have not, please see
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler)
and [Writing a schema](@ref flatbuffers_guide_writing_schema).
[Using the schema compiler](../flatc.md)
and [Writing a schema](../schema.md).
Assuming you wrote a schema, say `mygame.fbs` (though the extension doesn't
matter), you've generated a Rust file called `mygame_generated.rs` using the
@@ -36,7 +36,7 @@ The test code itself is located in
[integration_test.rs](https://github.com/google/flatbuffers/blob/master/tests/rust_usage_test/tests/integration_test.rs)
This test file requires `flatc` to be present. To review how to build the project,
please read the [Building](@ref flatbuffers_guide_building) documentation.
please read the [Building](../building.md) documentation.
To run the tests, execute `RustTest.sh` from the `flatbuffers/tests` directory.
For example, on [Linux](https://en.wikipedia.org/wiki/Linux), you would simply
@@ -47,7 +47,7 @@ be installed.*
## Using the FlatBuffers Rust library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
*Note: See [Tutorial](../tutorial.md) for a more in-depth
example of how to use FlatBuffers in Rust.*
FlatBuffers supports both reading and writing FlatBuffers in Rust.

10
docs/source/languages/swift.md
View File

@@ -4,15 +4,15 @@ Use in Swift {#flatbuffers_guide_use_swift}
## Before you get started
Before diving into the FlatBuffers usage in Swift, it should be noted that
the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide
the [Tutorial](../tutorial.md) page has a complete guide
to general FlatBuffers usage in all of the supported languages (including Swift).
This page is designed to cover the nuances of FlatBuffers usage, specific to
Swift.
You should also have read the [Building](@ref flatbuffers_guide_building)
You should also have read the [Building](../building.md)
documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema).
[Using the schema compiler](../flatc.md) and
[Writing a schema](../schema.md).
## FlatBuffers Swift library code location
@@ -32,7 +32,7 @@ be installed.*
## Using the FlatBuffers Swift library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
*Note: See [Tutorial](../tutorial.md) for a more in-depth
example of how to use FlatBuffers in Swift.*
FlatBuffers supports reading and writing binary FlatBuffers in Swift.

10
docs/source/languages/typescript.md
View File

@@ -4,15 +4,15 @@ Use in TypeScript {#flatbuffers_guide_use_typescript}
## Before you get started
Before diving into the FlatBuffers usage in TypeScript, it should be noted that
the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to
the [Tutorial](../tutorial.md) page has a complete guide to
general FlatBuffers usage in all of the supported languages
(including TypeScript). This page is specifically designed to cover the nuances
of FlatBuffers usage in TypeScript.
You should also have read the [Building](@ref flatbuffers_guide_building)
You should also have read the [Building](../building.md)
documentation to build `flatc` and should be familiar with
[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
[Writing a schema](@ref flatbuffers_guide_writing_schema).
[Using the schema compiler](../flatc.md) and
[Writing a schema](../schema.md).
## FlatBuffers TypeScript library code location
@@ -28,7 +28,7 @@ flatbuffers/blob/master/tests/TypeScriptTest.py) Python3 script.
## Using the FlatBuffers TypeScript library
*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
*Note: See [Tutorial](../tutorial.md) for a more in-depth
example of how to use FlatBuffers in TypeScript.*
FlatBuffers supports both reading and writing FlatBuffers in TypeScript.

8
docs/source/schema.md
View File

@@ -214,11 +214,9 @@ variable sized integers (e.g., `varints`).
| 32-bit | `int` (`int32`) | `uint` (`uint32`) | `float` (`float32`) |
| 64-bit | `long` (`int64`) | `ulong` (`uint64`) | `double` (`float64`) |
!!! note "Alias Types"
The type names in parentheses are alias names such that for example `uint8`
can be used in place of `ubyte`, and `int32` can be used in place of `int`
without affecting code generation.
The type names in parentheses are alias names such that for example `uint8` can
be used in place of `ubyte`, and `int32` can be used in place of `int` without
affecting code generation.
### Non-scalars

78
docs/source/tutorial.md
View File

@@ -11,13 +11,11 @@ in your application.
4. Serializing data into a flatbuffer.
5. Deserializing a flatbuffer.
!!! note
The tutorial is structured to be language agnostic, with language specifics
in code blocks providing more context. Additionally, this tries to cover the
major parts and type system of flatbuffers to give a general overview. It's
not expected to be an exhaustive list of all features, or provide the best
way to do things.
The tutorial is structured to be language agnostic, with language specifics in
code blocks providing more context. Additionally, this tries to cover the major
parts and type system of flatbuffers to give a general overview. It's not
expected to be an exhaustive list of all features, or provide the best way to do
things.
## FlatBuffers Schema (`.fbs`)
@@ -123,8 +121,6 @@ root_type Monster; //(14)!
14. The root of the flatbuffer is always a `table`. This indicates the type of
`table` the "entry" point of the flatbuffer will point to.
!!! bug "Get FlatBuffers schema syntax highlighting"
## Compiling Schema to Code (`flatc`)
After a schema file is written, you compile it to code in the languages you wish
@@ -173,11 +169,9 @@ serializing and deserializing the flatbuffer binary data.
flatc --csharp monster.fbs
```
!!! tip
You can deserialize flatbuffers in languages that differ from the language
that serialized it. For purpose of this tutorial, we assume one language
is used for both serializing and deserializing.
You can deserialize flatbuffers in languages that differ from the language that
serialized it. For purpose of this tutorial, we assume one language is used for
both serializing and deserializing.
## Application Integration
@@ -209,11 +203,8 @@ For some languages the runtime libraries are just code files you compile into
your application. While other languages provide packaged libraries via their
package managers.
!!! note
The generated files include APIs for both serializing and deserializing
flatbuffers. So these steps are identical for both the consumer and
producer.
The generated files include APIs for both serializing and deserializing
FlatBuffers. So these steps are identical for both the consumer and producer.
## Serialization
@@ -327,11 +318,9 @@ the weapon's name and a numerical value for the damage field.
Weapon.CreateWeapon(builder, weaponTwoName, weaponTwoDamage);
```
!!! Tip
The generated functions from `flatc`, like `CreateWeapon`, are just composed
of various Builder API methods. So its not required to use the generated
code, but it does make things much simpler and compact.
The generated functions from `flatc`, like `CreateWeapon`, are just composed of
various Builder API methods. So its not required to use the generated code, but
it does make things much simpler and compact.
Just like the `CreateString` methods, the table serialization functions return
an offset to the location of the serialized `Weapon` table.
@@ -504,12 +493,6 @@ the necessary values and Offsets to make a `Monster`.
Offset<Monster> orc = Monster.EndMonster(builder);
```
!!! warning
When serializing tables, you must fully serialize it before attempting to
serialize another reference type. If you try to serialize in a nested
manner, you will get an assert/exception/panic depending on your language.
### Finishing
At this point, we have serialized a `Monster` we've named "orc" to the
@@ -571,22 +554,17 @@ like so:
Now you can write the bytes to a file or send them over the network. The buffer
stays valid until the Builder is cleared or destroyed.
!!! warning "BINARY Mode"
Make sure your file mode (or transfer protocol) is set to BINARY, and not
TEXT. If you try to transfer a flatbuffer in TEXT mode, the buffer will be
corrupted and be hard to diagnose.
Make sure your file mode (or transfer protocol) is set to BINARY, and not TEXT.
If you try to transfer a flatbuffer in TEXT mode, the buffer will be corrupted
and be hard to diagnose.
## Deserialization
!!! note "Misnomer"
Deserialization is a bit of a misnomer, since FlatBuffers doesn't
deserialize the whole buffer when accessed. It just "decodes" the data that
is requested, leaving all the other data untouched. It is up to the
application to decide if the data is copied out or even read in the first
place. However, we continue to use the word `deserialize` to mean accessing
data from a binary flatbuffer.
Deserialization is a bit of a misnomer, since FlatBuffers doesn't deserialize
the whole buffer when accessed. It just "decodes" the data that is requested,
leaving all the other data untouched. It is up to the application to decide if
the data is copied out or even read in the first place. However, we continue to
use the word `deserialize` to mean accessing data from a binary flatbuffer.
Now that we have successfully create an orc FlatBuffer, the data can be saved,
sent over a network, etc. At some point, the buffer will be accessed to obtain
@@ -619,10 +597,8 @@ functions to get the root object given the buffer.
Monster monster = Monster.GetRootAsMonster(new ByteBuffer(bytes));
```
!!! warning "BINARY mode"
Again, make sure you read the bytes in BINARY mode, otherwise the buffer may
be corrupted.
Again, make sure you read the bytes in BINARY mode, otherwise the buffer may be
corrupted.
In most languages, the returned object is just a "view" of the data with helpful
accessors. Data is typically not copied out of the backing buffer. This also
@@ -655,11 +631,9 @@ some of the accessors of the `Monster` root table would look like:
These accessors should hold the values `300`, `150`, and `"Orc"` respectively.
!!! note "Default Values"
The default value of `150` wasn't stored in the `mana` field, but we are
still able to retrieve it. That is because the generated accessors return a
hard-coded default value when it doesn't find the value in the buffer.
The default value of `150` wasn't stored in the `mana` field, but we are still
able to retrieve it. That is because the generated accessors return a hard-coded
default value when it doesn't find the value in the buffer.
#### Nested Object Access