Skip to content

Commit

Permalink
quick_start.md: Add quick start guide (#8469)
Browse files Browse the repository at this point in the history
  • Loading branch information
dbaileychess authored Dec 27, 2024
1 parent c9125e6 commit 0f90dc8
Show file tree
Hide file tree
Showing 2 changed files with 91 additions and 0 deletions.
1 change: 1 addition & 0 deletions docs/mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ markdown_extensions:

nav:
- Overview: "index.md"
- Quick Start: "quick_start.md"
- Tutorial: "tutorial.md"
- Compiler (flatc):
- Building: "building.md"
Expand Down
90 changes: 90 additions & 0 deletions docs/source/quick_start.md
Original file line number Diff line number Diff line change
@@ -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++`.

0 comments on commit 0f90dc8

Please sign in to comment.