`quick_start.md`: Add quick start guide (#8469)

This commit is contained in:
Derek Bailey 2024-12-27 08:52:22 -08:00 committed by GitHub
parent c9125e6385
commit 0f90dc8290
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 91 additions and 0 deletions

View File

@ -56,6 +56,7 @@ markdown_extensions:
nav:
- Overview: "index.md"
- Quick Start: "quick_start.md"
- Tutorial: "tutorial.md"
- Compiler (flatc):
- Building: "building.md"

View File

@ -0,0 +1,90 @@
# Quick Start
This will quickly go over the parts of using FlatBuffers to serialize some data.
See the [Tutorial](tutorial.md) for a more in depth guide.
1. **Build the compiler for FlatBuffers ([`flatc`](flatc.md))**
```sh
cmake -G "Unix Makefiles"
make -j
```
2. **Define your FlatBuffer [schema](schema.md) (`.fbs`)**
```c title="monster.fbs" linenums="1"
table Monster {
name:string;
health:int;
}
root_type Monster;
```
See [monster.fbs](https://github.com/google/flatbuffers/blob/master/samples/monster.fbs)
for an complete example.
3. **Generate code for your language(s)**
Use the `flatc` compiler to take your schema and generate language-specific
code:
```sh
./flatc --cpp --rust mosnter.fbs
```
Which generates `monster_generated.h` and `monster_generated.rs` files.
4. **Serialize data**
Use the generated code files, as well as the `FlatBufferBuilder` to construct
your serialized buffer.
```c++ title="my_monster_factory.cc" linenums="1"
#include "flatbuffers.h"
#include "monster_generated.h"
int main() {
// Used to build the flatbuffer
FlatBufferBuilder builder;
// Auto-generated function emitted from `flatc` and the input
// `monster.fbs` schema.
auto monster = CreateMonsterDirect(builder, "Abominable Snowman", 100);
// Finalize the buffer.
builder.Finish(monster);
}
```
See complete [C++ Example](https://github.com/google/flatbuffers/blob/master/samples/sample_binary.cpp#L24-L56).
5. **Transmit/Store the serialized FlatBuffer**
Use your serialized buffer however you want. Send it to someone, save if for
later, etc...
```c++ title="my_monster_factory.cc" linenums="13"
// Get a pointer to the flatbuffer.
const uint8_t* flatbuffer = builder.GetBufferPointer();
```
6. **Read the data**
Use the generated accessors to read the data from the serialized buffer.
It doesn't need to be the same language, or even schema version (see
[Evolving](evolution.md)), FlatBuffers ensures the data is readable across
languages and schema versions.
```c++ title="my_monster_factory.cc" linenums="15"
// Get a view of the root monster from the flatbuffer.
const Monster snowman = GetMonster(flatbuffer);
// Access the monster's fields directly.
ASSERT_EQ(snowman.name(), "Abominable Snowman");
ASSERT_EQ(snowman.health(), 100);
```
See [`Rust` examples](https://github.com/google/flatbuffers/blob/master/samples/sample_binary.rs#L92-L106)
for reading the data written by `C++`.