From 569e6cb461738f0aefccbada0f04afefe1a43a1a Mon Sep 17 00:00:00 2001 From: Derek Bailey Date: Thu, 9 Jan 2025 23:48:13 -0800 Subject: [PATCH] Fixed broken links --- docs-old/source/Building.md | 1 + docs/source/annotation.md | 13 ++-- docs/source/building.md | 93 +++++++++++++++++++++++++++-- docs/source/evolution.md | 5 +- docs/source/flexbuffers.md | 2 +- docs/source/internals.md | 2 +- docs/source/languages/c.md | 2 +- docs/source/languages/c_sharp.md | 12 ++-- docs/source/languages/cpp.md | 20 +++---- docs/source/languages/dart.md | 10 ++-- docs/source/languages/go.md | 10 ++-- docs/source/languages/java.md | 10 ++-- docs/source/languages/javascript.md | 12 ++-- docs/source/languages/lobster.md | 10 ++-- docs/source/languages/lua.md | 10 ++-- docs/source/languages/php.md | 10 ++-- docs/source/languages/python.md | 10 ++-- docs/source/languages/rust.md | 10 ++-- docs/source/languages/swift.md | 10 ++-- docs/source/languages/typescript.md | 10 ++-- docs/source/schema.md | 8 +-- docs/source/tutorial.md | 78 ++++++++---------------- 22 files changed, 200 insertions(+), 148 deletions(-) diff --git a/docs-old/source/Building.md b/docs-old/source/Building.md index a12abac0e..1315467c5 100644 --- a/docs-old/source/Building.md +++ b/docs-old/source/Building.md @@ -72,6 +72,7 @@ We generate [SLSA3 signatures](slsa.dev) using the OpenSSF's [slsa-framework/sls ```shell $ slsa-verifier -artifact-path -provenance attestation.intoto.jsonl -source github.com/google/flatbuffers -tag PASSED: Verified SLSA provenance +``` ## Building for Android diff --git a/docs/source/annotation.md b/docs/source/annotation.md index 326c1a33d..1e66eb67c 100644 --- a/docs/source/annotation.md +++ b/docs/source/annotation.md @@ -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 diff --git a/docs/source/building.md b/docs/source/building.md index de224c6d0..21f80e3b2 100644 --- a/docs/source/building.md +++ b/docs/source/building.md @@ -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 -provenance attestation.intoto.jsonl -source github.com/google/flatbuffers -tag + PASSED: Verified SLSA provenance +``` \ No newline at end of file diff --git a/docs/source/evolution.md b/docs/source/evolution.md index 32f34a1aa..19ec6e96f 100644 --- a/docs/source/evolution.md +++ b/docs/source/evolution.md @@ -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 diff --git a/docs/source/flexbuffers.md b/docs/source/flexbuffers.md index 974dd693f..bf8bbcc47 100644 --- a/docs/source/flexbuffers.md +++ b/docs/source/flexbuffers.md @@ -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 diff --git a/docs/source/internals.md b/docs/source/internals.md index e53ce9a78..5b126ba75 100644 --- a/docs/source/internals.md +++ b/docs/source/internals.md @@ -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 diff --git a/docs/source/languages/c.md b/docs/source/languages/c.md index bd1ec159d..a0c269087 100644 --- a/docs/source/languages/c.md +++ b/docs/source/languages/c.md @@ -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) diff --git a/docs/source/languages/c_sharp.md b/docs/source/languages/c_sharp.md index 398a7259d..07f879a47 100644 --- a/docs/source/languages/c_sharp.md +++ b/docs/source/languages/c_sharp.md @@ -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 diff --git a/docs/source/languages/cpp.md b/docs/source/languages/cpp.md index e694a5961..d12e28ffa 100644 --- a/docs/source/languages/cpp.md +++ b/docs/source/languages/cpp.md @@ -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`. diff --git a/docs/source/languages/dart.md b/docs/source/languages/dart.md index 515a64411..ca370c71f 100644 --- a/docs/source/languages/dart.md +++ b/docs/source/languages/dart.md @@ -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. diff --git a/docs/source/languages/go.md b/docs/source/languages/go.md index e2aa115e8..75ee79dfe 100644 --- a/docs/source/languages/go.md +++ b/docs/source/languages/go.md @@ -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. diff --git a/docs/source/languages/java.md b/docs/source/languages/java.md index 30ba06133..bfbd3e41c 100644 --- a/docs/source/languages/java.md +++ b/docs/source/languages/java.md @@ -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. diff --git a/docs/source/languages/javascript.md b/docs/source/languages/javascript.md index 64764e216..d75442d23 100644 --- a/docs/source/languages/javascript.md +++ b/docs/source/languages/javascript.md @@ -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: diff --git a/docs/source/languages/lobster.md b/docs/source/languages/lobster.md index 723966be7..109341f71 100644 --- a/docs/source/languages/lobster.md +++ b/docs/source/languages/lobster.md @@ -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. diff --git a/docs/source/languages/lua.md b/docs/source/languages/lua.md index 43c370f5d..6843d468f 100644 --- a/docs/source/languages/lua.md +++ b/docs/source/languages/lua.md @@ -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. diff --git a/docs/source/languages/php.md b/docs/source/languages/php.md index cdff44954..8cb966481 100644 --- a/docs/source/languages/php.md +++ b/docs/source/languages/php.md @@ -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. diff --git a/docs/source/languages/python.md b/docs/source/languages/python.md index f338cda43..a16ed6c6e 100644 --- a/docs/source/languages/python.md +++ b/docs/source/languages/python.md @@ -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. diff --git a/docs/source/languages/rust.md b/docs/source/languages/rust.md index 2a162588a..0d5af1871 100644 --- a/docs/source/languages/rust.md +++ b/docs/source/languages/rust.md @@ -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. diff --git a/docs/source/languages/swift.md b/docs/source/languages/swift.md index c6116f6ae..b967c54d1 100644 --- a/docs/source/languages/swift.md +++ b/docs/source/languages/swift.md @@ -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. diff --git a/docs/source/languages/typescript.md b/docs/source/languages/typescript.md index 0dd1da2eb..f0e333c58 100644 --- a/docs/source/languages/typescript.md +++ b/docs/source/languages/typescript.md @@ -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. diff --git a/docs/source/schema.md b/docs/source/schema.md index a72d9ed0d..2baa5b78a 100644 --- a/docs/source/schema.md +++ b/docs/source/schema.md @@ -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 diff --git a/docs/source/tutorial.md b/docs/source/tutorial.md index cbdddd7cb..ad4785674 100644 --- a/docs/source/tutorial.md +++ b/docs/source/tutorial.md @@ -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 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