FlatBuffers Version 25.1.24

Co-authored-by: Derek Bailey <derekbailey@google.com>

.bazelci/presubmit.yml

@@ -1,25 +1,16 @@
 ---
 buildifier: latest
-bazel: 6.4.0
+matrix:
-platforms:
+  bazel:
-  ubuntu1804:
+    - 7.x
+    - 8.x
+tasks:
+  verify_ubuntu2004:
+    platform: ubuntu2004
+    bazel: ${{ bazel }}
     environment:
       CC: clang
-      SWIFT_VERSION: "5.5.3"
+      SWIFT_VERSION: "5.8"
-      SWIFT_HOME: "$HOME/swift-$SWIFT_VERSION"
-      PATH: "$PATH:$SWIFT_HOME/usr/bin"
-    shell_commands:
-      - "echo --- Downloading and extracting Swift $SWIFT_VERSION to $SWIFT_HOME"
-      - "mkdir $SWIFT_HOME"
-      - "curl https://download.swift.org/swift-${SWIFT_VERSION}-release/ubuntu1804/swift-${SWIFT_VERSION}-RELEASE/swift-${SWIFT_VERSION}-RELEASE-ubuntu18.04.tar.gz | tar xvz --strip-components=1 -C $SWIFT_HOME"
-    build_targets:
-    - "//..."
-    test_targets:
-    - "//..."
-  ubuntu2004:
-    environment:
-      CC: clang
-      SWIFT_VERSION: "5.5.3"
       SWIFT_HOME: "$HOME/swift-$SWIFT_VERSION"
       PATH: "$PATH:$SWIFT_HOME/usr/bin"
     shell_commands:
@@ -30,8 +21,40 @@ platforms:
     - "//..."
     test_targets:
     - "//..."
-  macos:
+  verify_ubuntu2204:
+    platform: ubuntu2204
+    bazel: ${{ bazel }}
+    environment:
+      CC: clang
+      SWIFT_VERSION: "5.8"
+      SWIFT_HOME: "$HOME/swift-$SWIFT_VERSION"
+      PATH: "$PATH:$SWIFT_HOME/usr/bin"
+    shell_commands:
+      - "echo --- Downloading and extracting Swift $SWIFT_VERSION to $SWIFT_HOME"
+      - "mkdir $SWIFT_HOME"
+      - "curl https://download.swift.org/swift-${SWIFT_VERSION}-release/ubuntu2204/swift-${SWIFT_VERSION}-RELEASE/swift-${SWIFT_VERSION}-RELEASE-ubuntu22.04.tar.gz | tar xvz --strip-components=1 -C $SWIFT_HOME"
     build_targets:
     - "//..."
     test_targets:
     - "//..."
+  test_module_cpp:
+    platform: ubuntu2204
+    bazel: ${{ bazel }}
+    working_directory: tests/bazel_repository_test_dir
+    build_targets:
+    - "//..."
+  test_module_ts:
+    platform: ubuntu2204
+    bazel: ${{ bazel }}
+    working_directory: tests/ts/bazel_repository_test_dir
+    test_targets:
+    - "//..."
+  verify_macos:
+    platform: macos
+    bazel: ${{ bazel }}
+    xcode_version: "15.2"
+    build_targets:
+    - "//:flatbuffers"
+    - "//:flatc"
+    test_targets:
+    - "//tests:flatbuffers_test"

.bazelignore

@@ -1 +1,5 @@
-node_modules
+ts/node_modules
+
+# Test workspaces
+tests/bazel_repository_test_dir
+tests/ts/bazel_repository_test_dir

.bazelrc

@@ -1,4 +1,18 @@
 # We cannot use "common" here because the "version" command doesn't support
 # --deleted_packages. We need to specify it for both build and query instead.
-build --deleted_packages=tests/ts/bazel_repository_test_dir
+build --deleted_packages=tests/bazel_repository_test_dir,tests/ts/bazel_repository_test_dir
-query --deleted_packages=tests/ts/bazel_repository_test_dir
+query --deleted_packages=tests/bazel_repository_test_dir,tests/ts/bazel_repository_test_dir
+# Point tools such as coursier (used in rules_jvm_external) to Bazel's internal JDK
+# suggested in https://github.com/bazelbuild/rules_jvm_external/issues/445
+common --repo_env=JAVA_HOME=../bazel_tools/jdk
+common --action_env=JAVA_HOME=../bazel_tools/jdk
+# Workaround "Error: need --enable_runfiles on Windows for to support rules_js"
+common:windows --enable_runfiles
+# Swift is not required on Windows
+common:windows --deleted_packages=swift
+# Ignore warnings in external dependencies
+build --per_file_copt=external/.*@-Wno-everything --host_per_file_copt=external/.*@-Wno-everything
+# Honor the setting of `skipLibCheck` in the tsconfig.json file.
+common --@aspect_rules_ts//ts:skipLibCheck=honor_tsconfig
+# Use "tsc" as the transpiler when ts_project has no `transpiler` set.
+common --@aspect_rules_ts//ts:default_to_tsc_transpiler

.github/ISSUE_TEMPLATE/404-doc.md

@@ -0,0 +1,11 @@
+---
+name: 404 Doc
+about: To fix broken documentation links
+title: "[Doc 404]"
+labels: documentation
+assignees: dbaileychess
+
+---
+
+Target URL:
+[Optional] Source Site:

.github/workflows/build.yml

@@ -12,6 +12,9 @@ on:
   pull_request:
     branches:
       - master
+  schedule:
+    # Run daily at 4:45 A.M. to catch dependencies that break us.
+    - cron: '45 4 * * *'
 
 jobs:
   build-linux:
@@ -21,10 +24,10 @@ jobs:
       digests-gcc: ${{ steps.hash-gcc.outputs.hashes }}
       digests-clang: ${{ steps.hash-clang.outputs.hashes }}
     name: Build Linux
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
-        cxx: [g++-13, clang++-15]
+        cxx: [g++-13, clang++-18]
       fail-fast: false
     steps:
     - uses: actions/checkout@v3
@@ -39,7 +42,7 @@ jobs:
         chmod +x flatc
         ./flatc --version
     - name: upload build artifacts
-      uses: actions/upload-artifact@v1
+      uses: actions/upload-artifact@v4
       with:
         name: Linux flatc binary ${{ matrix.cxx }}
         path: flatc
@@ -53,7 +56,7 @@ jobs:
       with:
         files: Linux.flatc.binary.${{ matrix.cxx }}.zip
     - name: Generate SLSA subjects - clang
-      if: matrix.cxx == 'clang++-15' && startsWith(github.ref, 'refs/tags/')
+      if: matrix.cxx == 'clang++-18' && startsWith(github.ref, 'refs/tags/')
       id: hash-clang
       run: echo "hashes=$(sha256sum Linux.flatc.binary.${{ matrix.cxx }}.zip | base64 -w0)" >> $GITHUB_OUTPUT
     - name: Generate SLSA subjects - gcc
@@ -63,11 +66,11 @@ jobs:
 
   build-linux-no-file-tests:
     name: Build Linux with -DFLATBUFFERS_NO_FILE_TESTS
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     steps:
     - uses: actions/checkout@v3
     - name: cmake
-      run: CXX=clang++-15 cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DFLATBUFFERS_STRICT_MODE=ON -DFLATBUFFERS_CXX_FLAGS="-DFLATBUFFERS_NO_FILE_TESTS" .
+      run: CXX=clang++-18 cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DFLATBUFFERS_STRICT_MODE=ON -DFLATBUFFERS_CXX_FLAGS="-DFLATBUFFERS_NO_FILE_TESTS" .
     - name: build
       run: make -j
     - name: test
@@ -75,7 +78,7 @@ jobs:
 
   build-linux-out-of-source:
     name: Build Linux with out-of-source build location
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     steps:
     - uses: actions/checkout@v3
     - name: make build directory
@@ -83,7 +86,7 @@ jobs:
     - name: cmake
       working-directory: build
       run: >
-        CXX=clang++-15 cmake .. -G "Unix Makefiles" -DFLATBUFFERS_STRICT_MODE=ON
+        CXX=clang++-18 cmake .. -G "Unix Makefiles" -DFLATBUFFERS_STRICT_MODE=ON
         -DFLATBUFFERS_BUILD_CPP17=ON -DFLATBUFFERS_CPP_STD=17
     - name: build
       working-directory: build
@@ -97,15 +100,15 @@ jobs:
 
   build-linux-cpp-std:
     name: Build Linux C++
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     strategy:
       fail-fast: false
       matrix:
         std: [11, 14, 17, 20, 23]
-        cxx: [g++-13, clang++-15]
+        cxx: [g++-13, clang++-18]
         exclude:
           # Clang++15 10.3.0 stdlibc++ doesn't fully support std 23
-          - cxx: clang++-15
+          - cxx: clang++-18
             std: 23
 
     steps:
@@ -167,7 +170,7 @@ jobs:
     - name: test
       run: Release\flattests.exe
     - name: upload build artifacts
-      uses: actions/upload-artifact@v1
+      uses: actions/upload-artifact@v4
       with:
         name: Windows flatc binary
         path: Release\flatc.exe
@@ -200,7 +203,7 @@ jobs:
     steps:
     - uses: actions/checkout@v3
     - name: Setup .NET Core SDK
-      uses: actions/setup-dotnet@v3
+      uses: actions/setup-dotnet@v4.2.0
       with:
         dotnet-version: '8.0.x'
     - name: Build
@@ -208,11 +211,16 @@ jobs:
         cd tests\FlatBuffers.Test
         dotnet new sln --force --name FlatBuffers.Test
         dotnet sln FlatBuffers.Test.sln add FlatBuffers.Test.csproj
-        dotnet build -c Release ${{matrix.configuration}} -o out FlatBuffers.Test.sln
+        dotnet build -c Release ${{matrix.configuration}} FlatBuffers.Test.sln
-    - name: Run
+    - name: Run net6.0
       run: |
-        cd tests\FlatBuffers.Test
+        cd tests\FlatBuffers.Test\bin\Release\net6.0
-        out\FlatBuffers.Test.exe
+        dir
+        .\FlatBuffers.Test.exe
+    - name: Run net8.0
+      run: |
+        cd tests\FlatBuffers.Test\bin\Release\net8.0
+        .\FlatBuffers.Test.exe
 
   build-mac-intel:
     permissions:
@@ -220,11 +228,11 @@ jobs:
     outputs:
       digests: ${{ steps.hash.outputs.hashes }}
     name: Build Mac (for Intel)
-    runs-on: macos-latest
+    runs-on: macos-latest-large
     steps:
     - uses: actions/checkout@v3
     - name: cmake
-      run: cmake -G "Xcode" -DCMAKE_BUILD_TYPE=Release -DFLATBUFFERS_STRICT_MODE=ON .
+      run: cmake -G "Xcode" -DCMAKE_OSX_ARCHITECTURES="x86_64" -DCMAKE_BUILD_TYPE=Release -DFLATBUFFERS_STRICT_MODE=ON .
     - name: build
       run: xcodebuild -toolchain clang -configuration Release -target flattests
     - name: check that the binary is x86_64
@@ -239,9 +247,9 @@ jobs:
         chmod +x Release/flatc
         Release/flatc --version
     - name: upload build artifacts
-      uses: actions/upload-artifact@v1
+      uses: actions/upload-artifact@v4
       with:
-        name: Mac flatc binary
+        name: Mac flatc binary Intel
         path: Release/flatc
     # Below if only for release.
     - name: Zip file
@@ -282,9 +290,9 @@ jobs:
         chmod +x Release/flatc
         Release/flatc --version
     - name: upload build artifacts
-      uses: actions/upload-artifact@v1
+      uses: actions/upload-artifact@v4
       with:
-        name: Mac flatc binary
+        name: Mac flatc binary Universal
         path: Release/flatc
     # Below if only for release.
     - name: Zip file
@@ -302,7 +310,7 @@ jobs:
 
   build-android:
    name: Build Android (on Linux)
-   runs-on: ubuntu-22.04-64core
+   runs-on: ubuntu-24.04
    steps:
    - uses: actions/checkout@v3
    - name: set up Java
@@ -321,10 +329,10 @@ jobs:
 
   build-generator:
     name: Check Generated Code
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
-        cxx: [g++-13, clang++-15]
+        cxx: [g++-13, clang++-18]
     steps:
     - uses: actions/checkout@v3
     - name: cmake
@@ -352,7 +360,7 @@ jobs:
 
   build-benchmarks:
     name: Build Benchmarks (on Linux)
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
         cxx: [g++-13]
@@ -363,14 +371,14 @@ jobs:
     - name: Run benchmarks
       run: ./flatbenchmark --benchmark_repetitions=5 --benchmark_display_aggregates_only=true --benchmark_out_format=console --benchmark_out=benchmarks/results_${{matrix.cxx}}
     - name: Upload benchmarks results
-      uses: actions/upload-artifact@v1
+      uses: actions/upload-artifact@v4
       with:
         name: Linux flatbenchmark results ${{matrix.cxx}}
         path: benchmarks/results_${{matrix.cxx}}
 
   build-java:
     name: Build Java
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     steps:
     - uses: actions/checkout@v3
     - name: test
@@ -379,10 +387,17 @@ jobs:
 
   build-kotlin-macos:
     name: Build Kotlin MacOS
-    runs-on: macos-latest
+    runs-on: macos-13
     steps:
     - name: Checkout
       uses: actions/checkout@v3
+      # Force Xcode 14.3 since Xcode 15 doesnt support older versions of
+      # kotlin. For Xcode 15, kotlin should be bumpped to 1.9.10
+      # https://stackoverflow.com/a/77150623
+      # For now, run with macos-13 which has this 14.3 installed: 
+      # https://github.com/actions/runner-images/blob/main/images/macos/macos-13-Readme.md#xcode
+    - name: Set up Xcode version
+      run: sudo xcode-select -s /Applications/Xcode_14.3.app/Contents/Developer
     - uses: gradle/wrapper-validation-action@v1.0.5
     - uses: actions/setup-java@v3
       with:
@@ -399,7 +414,7 @@ jobs:
 
   build-kotlin-linux:
     name: Build Kotlin Linux
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     steps:
     - name: Checkout
       uses: actions/checkout@v3
@@ -422,7 +437,7 @@ jobs:
 
   build-rust-linux:
     name: Build Rust Linux
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     steps:
     - uses: actions/checkout@v3
     - name: test
@@ -440,7 +455,7 @@ jobs:
 
   build-python:
     name: Build Python
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     steps:
     - uses: actions/checkout@v3
     - name: flatc
@@ -452,7 +467,7 @@ jobs:
 
   build-go:
     name: Build Go
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     steps:
     - uses: actions/checkout@v3
     - name: flatc
@@ -464,7 +479,7 @@ jobs:
 
   build-php:
    name: Build PHP
-   runs-on: ubuntu-22.04-64core
+   runs-on: ubuntu-24.04
    steps:
    - uses: actions/checkout@v3
    - name: flatc
@@ -478,9 +493,18 @@ jobs:
 
   build-swift:
     name: Build Swift
-    runs-on: ubuntu-22.04-64core
+    strategy:
+      matrix:
+        swift: ["5.8", "5.9", "5.10"]
+    # Only 22.04 has swift at the moment https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Readme.md?plain=1#L30
+    runs-on: ubuntu-22.04
     steps:
     - uses: actions/checkout@v3
+    - uses: swift-actions/setup-swift@v2
+      with:
+        swift-version: ${{ matrix.swift }}
+    - name: Get swift version
+      run: swift --version
     - name: test
       working-directory: tests/swift/tests
       run: |
@@ -489,20 +513,22 @@ jobs:
 
   build-swift-wasm:
     name: Build Swift Wasm
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     container:
-      image: ghcr.io/swiftwasm/carton:0.15.3
+      image: ghcr.io/swiftwasm/carton:0.20.1
     steps:
-      - uses: actions/checkout@v3
+       - uses: actions/checkout@v3
-      - name: Setup Wasmer
+       - uses: bytecodealliance/actions/wasmtime/setup@v1
-        uses: wasmerio/setup-wasmer@v2
+       - uses: swiftwasm/setup-swiftwasm@v1
-      - name: Test
+         with:
-        working-directory: tests/swift/Wasm.tests
+           swift-version: "wasm-6.0.2-RELEASE"
-        run: carton test
+       - name: Test
+         working-directory: tests/swift/Wasm.tests
+         run: swift run carton test
 
   build-ts:
     name: Build TS
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     steps:
     - uses: actions/checkout@v3
     - name: flatc
@@ -520,7 +546,7 @@ jobs:
 
   build-dart:
     name: Build Dart
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v3
       - uses: dart-lang/setup-dart@v1
@@ -535,7 +561,7 @@ jobs:
 
   build-nim:
     name: Build Nim
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     steps:
     - uses: actions/checkout@v3
     - name: flatc
@@ -549,12 +575,27 @@ jobs:
       working-directory: tests/nim
       run: python3 testnim.py
 
+  bazel:
+    name: Bazel
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v3
+      - name: bazel build
+        run: >
+          bazel build 
+          //:flatc
+          //:flatbuffers
+      - name: bazel test
+        run: >
+          bazel test 
+          //tests:flatbuffers_test
+
   release-digests:
     if: startsWith(github.ref, 'refs/tags/')
     needs: [build-linux, build-windows, build-mac-intel, build-mac-universal]
     outputs:
       digests: ${{ steps.hash.outputs.digests }}
-    runs-on: ubuntu-22.04-64core
+    runs-on: ubuntu-24.04
     steps:
       - name: Merge results
         id: hash

.github/workflows/codeql.yml

@@ -1,71 +0,0 @@
-# For most projects, this workflow file will not need changing; you simply need
-# to commit it to your repository.
-#
-# You may wish to alter this file to override the set of languages analyzed,
-# or to provide custom queries or build logic.
-#
-# ******** NOTE ********
-# We have attempted to detect the languages in your repository. Please check
-# the `language` matrix defined below to confirm you have the correct set of
-# supported CodeQL languages.
-#
-name: "CodeQL"
-permissions: read-all
-
-on:
-  push:
-    branches: [ master ]
-  pull_request:
-    # The branches below must be a subset of the branches above
-    branches: [ master ]
-  schedule:
-    - cron: '16 20 * * 0'
-
-jobs:
-  analyze:
-    name: Analyze
-    runs-on: ubuntu-latest
-    permissions:
-      actions: read
-      contents: read
-      security-events: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        language: [ 'cpp' ]
-        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
-        # Learn more about CodeQL language support at https://git.io/codeql-language-support
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v3
-
-    # Initializes the CodeQL tools for scanning.
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
-      with:
-        languages: ${{ matrix.language }}
-        # If you wish to specify custom queries, you can do so here or in a config file.
-        # By default, queries listed here will override any specified in a config file.
-        # Prefix the list here with "+" to use these queries and those in the config file.
-        # queries: ./path/to/local/query, your-org/your-repo/queries@main
-
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-    # If this step fails, then you should remove it and run the build manually (see below)
-    # - name: Autobuild
-    #  uses: github/codeql-action/autobuild@v2
-
-    # ℹ️ Command-line programs to run using the OS shell.
-    # 📚 https://git.io/JvXDl
-
-    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
-    #    and modify them (or add more) to build your code if your project
-    #    uses a compiled language
-
-    - run: |
-       cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DFLATBUFFERS_STRICT_MODE=ON .
-       make -j       
-
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2

.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+name: docs
+on:
+  # For manual pushes.
+  workflow_dispatch: 
+
+  # Pushes to main that touch the documentation directory.
+  push:
+    branches:
+      - master
+    paths:
+      - 'docs/**'
+
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: pip install mkdocs-redirects
+      - run: mkdocs gh-deploy --force -f docs/mkdocs.yml

.github/workflows/extrabuild.yml

@@ -1,35 +0,0 @@
-name: Build and unit tests that are more time consuming
-permissions: read-all
-
-on:
-  # For manual tests.
-  workflow_dispatch:
-  pull_request:
-    types:
-      - closed
-  schedule:
-  - cron: "30 20 * * *"
-
-jobs:
-  build-linux-s390x:
-    name: Build Linux on s390x arch and run unit tests
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: uraimo/run-on-arch-action@v2
-        name: Run commands
-        id: runcmd
-        with:
-          arch: s390x
-          distro: ubuntu_latest
-          install: |
-            apt-get update -q -y
-            apt-get -y install cmake
-            apt-get -y install make
-            apt-get -y install g++
-          run: |
-            lscpu | grep Endian
-            cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release
-            make -j
-            ./flattests
-

.github/workflows/main.yml

@@ -1,7 +1,7 @@
 name: OSS-Fuzz
 permissions: read-all
 
-on: 
+on:
   pull_request:
     branches:
       - master
@@ -27,7 +27,7 @@ jobs:
        language: c++
        fuzz-seconds: 60
    - name: Upload Crash
-     uses: actions/upload-artifact@v1
+     uses: actions/upload-artifact@v4
      if: failure() && steps.build.outcome == 'success'
      with:
        name: artifacts

.github/workflows/release.yml

@@ -5,7 +5,7 @@ on:
   # For manual tests.
   workflow_dispatch:
   release:
-    types: [created]
+    types: [published]
 
 jobs:
   publish-npm:
@@ -97,9 +97,56 @@ jobs:
       - name: Publish Maven
         run: mvn --batch-mode clean deploy
         env:
-          OSSRH_USERNAME: ${{ secrets.OSSRH_USERNAME }}
+          OSSRH_USERNAME: ${{ secrets.OSSRH_USER_V2 }}
-          OSSRH_PASSWORD: ${{ secrets.OSSRH_TOKEN }}
+          OSSRH_PASSWORD: ${{ secrets.OSSRH_TOKEN_V2 }}
+          MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}
+          
+  publish-maven-kotlin:
+    name: Publish Maven - Kotlin
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./kotlin
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Maven Central Repository
+        uses: actions/setup-java@v3
+        with:
+          java-version: '11'
+          distribution: 'adopt'
+          cache: 'maven'
+          server-id: ossrh
+          server-username: OSSRH_USERNAME
+          server-password: OSSRH_PASSWORD
+          gpg-private-key: ${{ secrets.MAVEN_GPG_PRIVATE_KEY }}
+          gpg-passphrase: MAVEN_GPG_PASSPHRASE # this needs to be an env var
+
+      - name: Publish Kotlin Library on Maven
+        run: ./gradlew publishAllPublicationsToSonatypeRepository
+        env:
+          OSSRH_USERNAME: ${{ secrets.OSSRH_USER_V2 }}
+          OSSRH_PASSWORD: ${{ secrets.OSSRH_TOKEN_V2 }}
           MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}
 
 
+  publish-crates:
+    name: Publish crates.io
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+          
+      - name: Publish Flatbuffers
+        uses: katyo/publish-crates@v2
+        with:
+          path: ./rust/flatbuffers
+          registry-token: ${{ secrets.CARGO_TOKEN }}
 
+      - name: Publish Flexbuffers
+        uses: katyo/publish-crates@v2
+        with:
+          path: ./rust/flexbuffers
+          registry-token: ${{ secrets.CARGO_TOKEN }}

.github/workflows/scorecards.yml

@@ -1,55 +0,0 @@
-name: Scorecards supply-chain security
-on:
-  # Only the default branch is supported.
-  branch_protection_rule:
-  schedule:
-    - cron: '21 2 * * 5'
-  push:
-    branches: [ master ]
-
-# Declare default permissions as read only.
-permissions: read-all
-
-jobs:
-  analysis:
-    name: Scorecards analysis
-    runs-on: ubuntu-latest
-    permissions:
-      # Needed to upload the results to code-scanning dashboard.
-      security-events: write
-      actions: read
-      contents: read
-
-    steps:
-      - name: "Checkout code"
-        uses: actions/checkout@a12a3943b4bdde767164f792f33f40b04645d846 # v3.0.0
-        with:
-          persist-credentials: false
-
-      - name: "Run analysis"
-        uses: ossf/scorecard-action@ce330fde6b1a5c9c75b417e7efc510b822a35564 # v1.1.2
-        with:
-          results_file: results.sarif
-          results_format: sarif
-          # Read-only PAT token. To create it,
-          # follow the steps in https://github.com/ossf/scorecard-action#pat-token-creation.
-          repo_token: ${{ secrets.SCORECARD_READ_TOKEN }}
-          # Publish the results to enable scorecard badges. For more details, see
-          # https://github.com/ossf/scorecard-action#publishing-results.
-          # For private repositories, `publish_results` will automatically be set to `false`,
-          # regardless of the value entered here.
-          publish_results: true
-
-      # Upload the results as artifacts (optional).
-      - name: "Upload artifact"
-        uses: actions/upload-artifact@6673cd052c4cd6fcf4b4e6e60ea986c889389535 # v3.0.0
-        with:
-          name: SARIF file
-          path: results.sarif
-          retention-days: 5
-
-      # Upload the results to GitHub's code scanning dashboard.
-      - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@5f532563584d71fdef14ee64d17bafb34f751ce5 # v1.0.26
-        with:
-          sarif_file: results.sarif

.gitignore

@@ -153,3 +153,7 @@ cmake-build-debug/
 _deps/
 **/.gradle/**
 kotlin/**/generated
+MODULE.bazel.lock
+
+# Ignore the generated docs
+docs/site

BUILD.bazel

@@ -1,5 +1,3 @@
-load("@aspect_rules_js//npm:defs.bzl", "npm_link_package")
-load("@npm//:defs.bzl", "npm_link_all_packages")
 load("@rules_cc//cc:defs.bzl", "cc_binary", "cc_library")
 
 licenses(["notice"])
@@ -8,13 +6,6 @@ package(
     default_visibility = ["//visibility:public"],
 )
 
-npm_link_all_packages(name = "node_modules")
-
-npm_link_package(
-    name = "node_modules/flatbuffers",
-    src = "//ts:flatbuffers",
-)
-
 exports_files([
     "LICENSE",
     "tsconfig.json",
@@ -37,11 +28,16 @@ config_setting(
 filegroup(
     name = "distribution",
     srcs = [
+        ".bazelignore",
+        ".npmrc",
         "BUILD.bazel",
-        "WORKSPACE",
+        "MODULE.bazel",
         "build_defs.bzl",
+        "package.json",
+        "pnpm-lock.yaml",
         "typescript.bzl",
         "//grpc/src/compiler:distribution",
+        "//include/codegen:distribution",
         "//reflection:distribution",
         "//src:distribution",
         "//ts:distribution",
@@ -125,15 +121,7 @@ filegroup(
 # Library used by flatbuffer_cc_library rules.
 cc_library(
     name = "runtime_cc",
-    hdrs = [
+    hdrs = ["//:public_headers"],
-        "include/flatbuffers/base.h",
-        "include/flatbuffers/flatbuffers.h",
-        "include/flatbuffers/flexbuffers.h",
-        "include/flatbuffers/stl_emulation.h",
-        "include/flatbuffers/util.h",
-        "include/flatbuffers/vector.h",
-        "include/flatbuffers/verifier.h",
-    ],
     linkstatic = 1,
     strip_include_prefix = "/include",
 )

CHANGELOG.md

@@ -4,6 +4,22 @@ All major or breaking changes will be documented in this file, as well as any
 new features that should be highlighted. Minor fixes or improvements are not
 necessarily listed.
 
+## [25.1.24] (January 24 2024)(https://github.com/google/flatbuffers/releases/tag/v25.1.24))
+
+* Mostly related to bazel build support.
+* Min bazel supported is now 7 or higher, as WORKSPACE files are removed (#8509)
+* Minor C++ codegen fix removing extra semicolon (#8488)
+
+## [25.1.21] (January 21 2025)(https://github.com/google/flatbuffers/releases/tag/v25.1.21)
+
+* Rust Full Reflection (#8102)
+* Mostly documentation updates hosted at https://flatbuffers.dev
+
+## [24.3.25] (March 25 2024)(https://github.com/google/flatbuffers/releases/tag/v24.3.25)
+
+* Fixed license metadata parsing (#8253)
+* [C++] Allow string_view in `LookUpByKey` in addition to null-terminated c-style strings (#8203)
+
 ## [24.3.7] (March 7 2024)(https://github.com/google/flatbuffers/releases/tag/v24.3.7)
 
 * Just to fix some of the CI build issues from the 24.3.6 release.

CMake/Version.cmake

@@ -1,6 +1,6 @@
-set(VERSION_MAJOR 24)
+set(VERSION_MAJOR 25)
-set(VERSION_MINOR 3)
+set(VERSION_MINOR 1)
-set(VERSION_PATCH 7)
+set(VERSION_PATCH 24)
 set(VERSION_COMMIT 0)
 
 if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/.git")

CMakeLists.txt

@@ -183,6 +183,10 @@ set(FlatBuffers_Compiler_SRCS
   src/bfbs_gen_lua.h
   src/bfbs_gen_nim.h
   src/bfbs_namer.h
+  include/codegen/idl_namer.h
+  include/codegen/namer.h
+  include/codegen/python.h
+  include/codegen/python.cc
   include/flatbuffers/code_generators.h
   src/binary_annotator.h
   src/binary_annotator.cpp

FlatBuffers.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name             = 'FlatBuffers'
-  s.version          = '24.3.7'
+  s.version          = '25.1.24'
   s.summary          = 'FlatBuffers: Memory Efficient Serialization Library'
 
   s.description      = "FlatBuffers is a cross platform serialization library architected for
@@ -10,12 +10,15 @@ Pod::Spec.new do |s|
 
   s.homepage         = 'https://github.com/google/flatbuffers'
   s.license          = { :type => 'Apache2.0', :file => 'LICENSE' }
-  s.author           = { 'mustii' => 'mustii@mmk.one' }
+  s.author           = { 'mustii' => 'me@mustiikhalil.se' }
-  s.source           = { :git => 'https://github.com/google/flatbuffers.git', :tag => s.version.to_s, :submodules => true }
+  s.source           = { :git => 'https://github.com/google/flatbuffers.git', :tag => "v" + s.version.to_s, :submodules => true }
 
   s.ios.deployment_target = '11.0'
   s.osx.deployment_target = '10.14'
 
   s.swift_version = '5.0'
   s.source_files = 'swift/Sources/Flatbuffers/*.swift'
+  s.pod_target_xcconfig = {
+    'BUILD_LIBRARY_FOR_DISTRIBUTION' => 'YES'
+  }
 end

MODULE.bazel

@@ -0,0 +1,73 @@
+module(
+    name = "flatbuffers",
+    version = "25.1.24",
+    compatibility_level = 1,
+    repo_name = "com_github_google_flatbuffers",
+)
+
+bazel_dep(
+    name = "aspect_bazel_lib",
+    version = "2.11.0",
+)
+bazel_dep(
+    name = "aspect_rules_esbuild",
+    version = "0.21.0",
+)
+bazel_dep(
+    name = "aspect_rules_js",
+    version = "2.1.3",
+)
+bazel_dep(
+    name = "aspect_rules_ts",
+    version = "3.4.0",
+)
+bazel_dep(
+    name = "grpc",
+    version = "1.69.0",
+    repo_name = "com_github_grpc_grpc",
+)
+bazel_dep(
+    name = "platforms",
+    version = "0.0.10",
+)
+bazel_dep(
+    name = "rules_cc",
+    version = "0.0.16",
+)
+bazel_dep(
+    name = "rules_go",
+    version = "0.50.1",
+    repo_name = "io_bazel_rules_go",
+)
+bazel_dep(
+    name = "rules_nodejs",
+    version = "6.3.3",
+)
+bazel_dep(
+    name = "rules_swift",
+    version = "1.18.0",
+    repo_name = "build_bazel_rules_swift",
+)
+bazel_dep(
+    name = "bazel_skylib",
+    version = "1.7.1",
+)
+
+npm = use_extension("@aspect_rules_js//npm:extensions.bzl", "npm")
+npm.npm_translate_lock(
+    name = "flatbuffers_npm",
+    npmrc = "//:.npmrc",
+    pnpm_lock = "//ts:pnpm-lock.yaml",
+    # Override the Bazel package where pnpm-lock.yaml is located and link
+    # to the specified package instead.
+    root_package = "ts",
+    verify_node_modules_ignored = "//:.bazelignore",
+)
+use_repo(npm, "flatbuffers_npm")
+
+node = use_extension("@rules_nodejs//nodejs:extensions.bzl", "node")
+use_repo(node, "nodejs_linux_amd64")
+
+rules_ts_ext = use_extension("@aspect_rules_ts//ts:extensions.bzl", "ext")
+rules_ts_ext.deps()
+use_repo(rules_ts_ext, "npm_typescript")

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.6
+// swift-tools-version:5.8
 /*
  * Copyright 2020 Google Inc. All rights reserved.
  *

Package@swift-5.5.swift

@@ -1,37 +0,0 @@
-// swift-tools-version:5.5
-/*
- * Copyright 2020 Google Inc. All rights reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import PackageDescription
-
-let package = Package(
-  name: "FlatBuffers",
-  platforms: [
-    .iOS(.v11),
-    .macOS(.v10_14),
-  ],
-  products: [
-    .library(
-      name: "FlatBuffers",
-      targets: ["FlatBuffers"]),
-  ],
-  targets: [
-    .target(
-      name: "FlatBuffers",
-      dependencies: [],
-      path: "swift/Sources"),
-  ])
-

README.md

@@ -4,8 +4,6 @@
 ![Build status](https://github.com/google/flatbuffers/actions/workflows/build.yml/badge.svg?branch=master)
 [![BuildKite status](https://badge.buildkite.com/7979d93bc6279aa539971f271253c65d5e8fe2fe43c90bbb25.svg)](https://buildkite.com/bazel/flatbuffers)
 [![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/flatbuffers.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:flatbuffers)
-[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/google/flatbuffers/badge)](https://api.securityscorecards.dev/projects/github.com/google/flatbuffers)
-[![Join the chat at https://gitter.im/google/flatbuffers](https://badges.gitter.im/google/flatbuffers.svg)](https://gitter.im/google/flatbuffers?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 [![Discord Chat](https://img.shields.io/discord/656202785926152206.svg)](https:///discord.gg/6qgKs3R)
 [![Twitter Follow](https://img.shields.io/twitter/follow/wvo.svg?style=social)](https://twitter.com/wvo)
 [![Twitter Follow](https://img.shields.io/twitter/follow/dbaileychess.svg?style=social)](https://twitter.com/dbaileychess)
@@ -18,7 +16,7 @@ maximum memory efficiency. It allows you to directly access serialized data with
 
 1. Build the compiler for flatbuffers (`flatc`)
 
-    Use `cmake` to create the build files for your platform and then perform the compliation (Linux example).
+    Use `cmake` to create the build files for your platform and then perform the compilation (Linux example).
 
     ```
     cmake -G "Unix Makefiles"

WORKSPACE

@@ -1,169 +0,0 @@
-workspace(name = "com_github_google_flatbuffers")
-
-load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive", "http_file")
-
-http_archive(
-    name = "platforms",
-    sha256 = "3a561c99e7bdbe9173aa653fd579fe849f1d8d67395780ab4770b1f381431d51",
-    urls = [
-        "https://mirror.bazel.build/github.com/bazelbuild/platforms/releases/download/0.0.7/platforms-0.0.7.tar.gz",
-        "https://github.com/bazelbuild/platforms/releases/download/0.0.7/platforms-0.0.7.tar.gz",
-    ],
-)
-
-http_archive(
-    name = "build_bazel_rules_apple",
-    sha256 = "34c41bfb59cdaea29ac2df5a2fa79e5add609c71bb303b2ebb10985f93fa20e7",
-    url = "https://github.com/bazelbuild/rules_apple/releases/download/3.1.1/rules_apple.3.1.1.tar.gz",
-)
-
-load(
-    "@build_bazel_rules_apple//apple:repositories.bzl",
-    "apple_rules_dependencies",
-)
-
-apple_rules_dependencies()
-
-http_archive(
-    name = "build_bazel_rules_swift",
-    sha256 = "a2fd565e527f83fb3f9eb07eb9737240e668c9242d3bc318712efa54a7deda97",
-    url = "https://github.com/bazelbuild/rules_swift/releases/download/0.27.0/rules_swift.0.27.0.tar.gz",
-)
-
-load(
-    "@build_bazel_rules_swift//swift:repositories.bzl",
-    "swift_rules_dependencies",
-)
-
-swift_rules_dependencies()
-
-load(
-    "@build_bazel_rules_swift//swift:extras.bzl",
-    "swift_rules_extra_dependencies",
-)
-
-swift_rules_extra_dependencies()
-
-http_archive(
-    name = "io_bazel_rules_go",
-    sha256 = "278b7ff5a826f3dc10f04feaf0b70d48b68748ccd512d7f98bf442077f043fe3",
-    urls = [
-        "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.41.0/rules_go-v0.41.0.zip",
-        "https://github.com/bazelbuild/rules_go/releases/download/v0.41.0/rules_go-v0.41.0.zip",
-    ],
-)
-
-load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies")
-
-go_rules_dependencies()
-
-##### Protobuf
-_PROTOBUF_VERSION = "3.15.2"
-
-http_archive(
-    name = "com_google_protobuf",
-    strip_prefix = "protobuf-" + _PROTOBUF_VERSION,
-    urls = [
-        "https://github.com/protocolbuffers/protobuf/archive/v" + _PROTOBUF_VERSION + ".tar.gz",
-    ],
-)
-
-##### GRPC
-_GRPC_VERSION = "1.49.0"  # https://github.com/grpc/grpc/releases/tag/v1.48.0
-
-http_archive(
-    name = "com_github_grpc_grpc",
-    patch_args = ["-p1"],
-    patches = ["//grpc:build_grpc_with_cxx14.patch"],
-    sha256 = "15715e1847cc9e42014f02c727dbcb48e39dbdb90f79ad3d66fe4361709ff935",
-    strip_prefix = "grpc-" + _GRPC_VERSION,
-    urls = ["https://github.com/grpc/grpc/archive/refs/tags/v" + _GRPC_VERSION + ".tar.gz"],
-)
-
-load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps")
-
-grpc_deps()
-
-load("@com_github_grpc_grpc//bazel:grpc_extra_deps.bzl", "grpc_extra_deps")
-
-grpc_extra_deps()
-
-# rules_go from https://github.com/bazelbuild/rules_go/releases/tag/v0.34.0
-
-http_archive(
-    name = "aspect_rules_js",
-    sha256 = "76a04ef2120ee00231d85d1ff012ede23963733339ad8db81f590791a031f643",
-    strip_prefix = "rules_js-1.34.1",
-    url = "https://github.com/aspect-build/rules_js/releases/download/v1.34.1/rules_js-v1.34.1.tar.gz",
-)
-
-load("@aspect_rules_js//js:repositories.bzl", "rules_js_dependencies")
-
-rules_js_dependencies()
-
-load("@aspect_rules_js//npm:npm_import.bzl", "npm_translate_lock", "pnpm_repository")
-
-pnpm_repository(name = "pnpm")
-
-http_archive(
-    name = "aspect_rules_ts",
-    sha256 = "4c3f34fff9f96ffc9c26635d8235a32a23a6797324486c7d23c1dfa477e8b451",
-    strip_prefix = "rules_ts-1.4.5",
-    url = "https://github.com/aspect-build/rules_ts/releases/download/v1.4.5/rules_ts-v1.4.5.tar.gz",
-)
-
-load("@aspect_rules_ts//ts:repositories.bzl", "rules_ts_dependencies")
-
-rules_ts_dependencies(
-    # Since rules_ts doesn't always have the newest integrity hashes, we
-    # compute it manually here.
-    #   $ curl --silent https://registry.npmjs.org/typescript/5.3.3 | jq ._integrity
-    ts_integrity = "sha512-pXWcraxM0uxAS+tN0AG/BF2TyqmHO014Z070UsJ+pFvYuRSq8KH8DmWpnbXe0pEPDHXZV3FcAbJkijJ5oNEnWw==",
-    ts_version_from = "//:package.json",
-)
-
-load("@rules_nodejs//nodejs:repositories.bzl", "DEFAULT_NODE_VERSION", "nodejs_register_toolchains")
-
-nodejs_register_toolchains(
-    name = "nodejs",
-    node_version = DEFAULT_NODE_VERSION,
-)
-
-npm_translate_lock(
-    name = "npm",
-    npmrc = "//:.npmrc",
-    pnpm_lock = "//:pnpm-lock.yaml",
-    # Set this to True when the lock file needs to be updated, commit the
-    # changes, then set to False again.
-    update_pnpm_lock = False,
-    verify_node_modules_ignored = "//:.bazelignore",
-)
-
-load("@npm//:repositories.bzl", "npm_repositories")
-
-npm_repositories()
-
-http_archive(
-    name = "aspect_rules_esbuild",
-    sha256 = "098e38e5ee868c14a6484ba263b79e57d48afacfc361ba30137c757a9c4716d6",
-    strip_prefix = "rules_esbuild-0.15.0",
-    url = "https://github.com/aspect-build/rules_esbuild/releases/download/v0.15.0/rules_esbuild-v0.15.0.tar.gz",
-)
-
-# Register a toolchain containing esbuild npm package and native bindings
-load("@aspect_rules_esbuild//esbuild:repositories.bzl", "LATEST_ESBUILD_VERSION", "esbuild_register_toolchains")
-
-esbuild_register_toolchains(
-    name = "esbuild",
-    esbuild_version = LATEST_ESBUILD_VERSION,
-)
-
-http_file(
-    name = "bazel_linux_x86_64",
-    downloaded_file_path = "bazel",
-    executable = True,
-    sha256 = "e78fc3394deae5408d6f49a15c7b1e615901969ecf6e50d55ef899996b0b8458",
-    urls = [
-        "https://github.com/bazelbuild/bazel/releases/download/6.3.2/bazel-6.3.2-linux-x86_64",
-    ],
-)

android/app/src/main/cpp/generated/animal_generated.h

@@ -8,9 +8,9 @@
 
 // Ensure the included flatbuffers.h is the same version as when this file was
 // generated, otherwise it may not be compatible.
-static_assert(FLATBUFFERS_VERSION_MAJOR == 23 &&
+static_assert(FLATBUFFERS_VERSION_MAJOR == 24 &&
-              FLATBUFFERS_VERSION_MINOR == 1 &&
+              FLATBUFFERS_VERSION_MINOR == 12 &&
-              FLATBUFFERS_VERSION_REVISION == 21,
+              FLATBUFFERS_VERSION_REVISION == 23,
              "Non-compatible flatbuffers version included");
 
 namespace com {

android/app/src/main/java/generated/com/fbs/app/Animal.kt

@@ -57,7 +57,7 @@ class Animal : Table() {
             return if(o != 0) bb.getShort(o + bb_pos).toUShort() else 0u
         }
     companion object {
-        fun validateVersion() = Constants.FLATBUFFERS_24_3_7()
+        fun validateVersion() = Constants.FLATBUFFERS_25_1_24()
         fun getRootAsAnimal(_bb: ByteBuffer): Animal = getRootAsAnimal(_bb, Animal())
         fun getRootAsAnimal(_bb: ByteBuffer, obj: Animal): Animal {
             _bb.order(ByteOrder.LITTLE_ENDIAN)

benchmarks/cpp/flatbuffers/bench_generated.h

@@ -8,9 +8,9 @@
 
 // Ensure the included flatbuffers.h is the same version as when this file was
 // generated, otherwise it may not be compatible.
-static_assert(FLATBUFFERS_VERSION_MAJOR == 2 &&
+static_assert(FLATBUFFERS_VERSION_MAJOR == 24 &&
-              FLATBUFFERS_VERSION_MINOR == 0 &&
+              FLATBUFFERS_VERSION_MINOR == 12 &&
-              FLATBUFFERS_VERSION_REVISION == 6,
+              FLATBUFFERS_VERSION_REVISION == 23,
              "Non-compatible flatbuffers version included");
 
 namespace benchmarks_flatbuffers {

benchmarks/swift/Benchmarks/FlatbuffersBenchmarks/FlatbuffersBenchmarks.swift

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 Google Inc. All rights reserved.
+ * Copyright 2024 Google Inc. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -178,4 +178,24 @@ let benchmarks = {
     let root = Offset(offset: fb.endTable(at: start))
     fb.finish(offset: root)
   }
+
+  Benchmark("Vector of Offsets") { benchmark in
+    let rawSize = ((16 * 5) * benchmark.scaledIterations.count) / 1024
+    var fb = FlatBufferBuilder(initialSize: Int32(rawSize * 1600))
+    benchmark.startMeasurement()
+    for _ in benchmark.scaledIterations {
+      let offsets = [
+        fb.create(string: "T"),
+        fb.create(string: "2"),
+        fb.create(string: "3"),
+      ]
+      let off = fb.createVector(ofOffsets: [
+        fb.createVector(ofOffsets: offsets),
+        fb.createVector(ofOffsets: offsets),
+      ])
+      let s = fb.startTable(with: 2)
+      fb.add(offset: off, at: 2)
+      blackHole(fb.endTable(at: s))
+    }
+  }
 }

benchmarks/swift/Package.swift

@@ -26,7 +26,7 @@ let package = Package(
     .package(path: "../.."),
     .package(
       url: "https://github.com/ordo-one/package-benchmark",
-      from: "1.12.0"),
+      from: "1.27.0"),
   ],
   targets: [
     .executableTarget(

build_defs.bzl

@@ -7,13 +7,13 @@ Rules for building C++ flatbuffers with Bazel.
 
 load("@rules_cc//cc:defs.bzl", "cc_library")
 
-TRUE_FLATC_PATH = "@com_github_google_flatbuffers//:flatc"
+TRUE_FLATC_PATH = Label("//:flatc")
 
 DEFAULT_INCLUDE_PATHS = [
     "./",
     "$(GENDIR)",
     "$(BINDIR)",
-    "$(execpath @com_github_google_flatbuffers//:flatc).runfiles/com_github_google_flatbuffers",
+    "$(execpath %s).runfiles/%s" % (TRUE_FLATC_PATH, TRUE_FLATC_PATH.repo_name),
 ]
 
 def default_include_paths(flatc_path):
@@ -21,7 +21,7 @@ def default_include_paths(flatc_path):
         "./",
         "$(GENDIR)",
         "$(BINDIR)",
-        "$(execpath %s).runfiles/com_github_google_flatbuffers" % (flatc_path),
+        "$(execpath %s).runfiles/%s" % (flatc_path, flatc_path.repo_name),
     ]
 
 DEFAULT_FLATC_ARGS = [
@@ -47,7 +47,7 @@ def flatbuffer_library_public(
         compatible_with = None,
         restricted_to = None,
         target_compatible_with = None,
-        flatc_path = "@com_github_google_flatbuffers//:flatc",
+        flatc_path = None,
         output_to_bindir = False,
         tools = None,
         extra_env = None,
@@ -87,6 +87,11 @@ def flatbuffer_library_public(
     optionally a Fileset([reflection_name]) with all generated reflection
     binaries.
     """
+    if flatc_path == None:
+        flatc_path = TRUE_FLATC_PATH
+    else:
+        flatc_path = native.package_relative_label(flatc_path)
+
     reflection_include_paths = include_paths
     if include_paths == None:
         include_paths = default_include_paths(flatc_path)
@@ -131,6 +136,8 @@ def flatbuffer_library_public(
         reflection_genrule_cmd = " ".join([
             "SRCS=($(SRCS));",
             "for f in $${SRCS[@]:0:%s}; do" % len(srcs),
+            # Move the .fbs file into the current package if it is not there already
+            'if [[ $$(dirname $$f) != "{0}" ]]; then s="$$f"; f="{0}/$$(basename "$$f")"; mkdir -p "{0}"; mv "$$s" "$$f"; fi;'.format(native.package_relative_label(":invalid").package),
             "$(location %s)" % (TRUE_FLATC_PATH),
             "-b --schema",
             " ".join(flatc_args),
@@ -141,9 +148,10 @@ def flatbuffer_library_public(
             "done",
         ])
         reflection_outs = [
-            (out_prefix + "%s.bfbs") % (s.replace(".fbs", "").split("/")[-1])
+            (out_prefix + "%s.bfbs") % (native.package_relative_label(s).name.removesuffix(".fbs"))
             for s in srcs
         ]
+
         native.genrule(
             name = "%s_srcs" % reflection_name,
             srcs = srcs + includes,
@@ -262,8 +270,8 @@ def flatbuffer_cc_library(
             "-parse_headers",
         ],
         deps = [
-            "@com_github_google_flatbuffers//:runtime_cc",
+            Label("//:runtime_cc"),
-            "@com_github_google_flatbuffers//:flatbuffers",
+            Label("//:flatbuffers"),
         ] + deps,
         includes = cc_include_paths,
         compatible_with = compatible_with,

dart/lib/flat_buffers.dart

@@ -386,7 +386,7 @@ class Builder {
   /// Updates the [offset] pointer.  This method is intended for use when writing structs to the buffer.
   void putFloat64(double value) {
     _prepare(_sizeofFloat64, 1);
-    _setFloat32AtTail(_tail, value);
+    _setFloat64AtTail(_tail, value);
   }
 
   /// Writes a Float32 to the tail of the buffer after preparing space for it.

dart/pubspec.yaml

@@ -1,11 +1,11 @@
 name: flat_buffers
-version: 24.3.7
+version: 25.1.24
 description: FlatBuffers reading and writing library for Dart. Based on original work by Konstantin Scheglov and Paul Berry of the Dart SDK team.
 homepage: https://github.com/google/flatbuffers
 documentation: https://google.github.io/flatbuffers/index.html
 
 environment:
-  sdk: '>=2.12.0 <4.0.0'
+  sdk: '>=2.17.0 <4.0.0'
 
 dev_dependencies:
   test: ^1.17.7

dart/test/bool_structs_generated.dart

@@ -1,5 +1,5 @@
 // automatically generated by the FlatBuffers compiler, do not modify
-// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable
+// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable, constant_identifier_names
 
 import 'dart:typed_data' show Uint8List;
 import 'package:flat_buffers/flat_buffers.dart' as fb;

dart/test/enums_generated.dart

@@ -1,43 +1,33 @@
 // automatically generated by the FlatBuffers compiler, do not modify
-// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable
+// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable, constant_identifier_names
 
 import 'dart:typed_data' show Uint8List;
 import 'package:flat_buffers/flat_buffers.dart' as fb;
 
 
-class OptionsEnum {
+enum OptionsEnum {
+  A(1),
+  B(2),
+  C(3);
+
   final int value;
-  const OptionsEnum._(this.value);
+  const OptionsEnum(this.value);
 
   factory OptionsEnum.fromValue(int value) {
-    final result = values[value];
+    switch (value) {
-    if (result == null) {
+      case 1: return OptionsEnum.A;
-        throw StateError('Invalid value $value for bit flag enum OptionsEnum');
+      case 2: return OptionsEnum.B;
+      case 3: return OptionsEnum.C;
+      default: throw StateError('Invalid value $value for bit flag enum');
     }
-    return result;
   }
 
-  static OptionsEnum? _createOrNull(int? value) => 
+  static OptionsEnum? _createOrNull(int? value) =>
       value == null ? null : OptionsEnum.fromValue(value);
 
   static const int minValue = 1;
   static const int maxValue = 3;
-  static bool containsValue(int value) => values.containsKey(value);
-
-  static const OptionsEnum A = OptionsEnum._(1);
-  static const OptionsEnum B = OptionsEnum._(2);
-  static const OptionsEnum C = OptionsEnum._(3);
-  static const Map<int, OptionsEnum> values = {
-    1: A,
-    2: B,
-    3: C};
-
   static const fb.Reader<OptionsEnum> reader = _OptionsEnumReader();
-
-  @override
-  String toString() {
-    return 'OptionsEnum{value: $value}';
-  }
 }
 
 class _OptionsEnumReader extends fb.Reader<OptionsEnum> {

dart/test/flat_buffers_test.dart

@@ -9,7 +9,7 @@ import 'package:test_reflective_loader/test_reflective_loader.dart';
 
 import './monster_test_my_game.example_generated.dart' as example;
 import './monster_test_my_game.example2_generated.dart' as example2;
-import './list_of_enums_generated.dart' as example3;
+import 'enums_generated.dart' as example3;
 import './bool_structs_generated.dart' as example4;
 
 main() {
@@ -63,11 +63,11 @@ class CheckOtherLangaugesData {
     expect(
         mon.toString(),
         'Monster{'
-        'pos: Vec3{x: 1.0, y: 2.0, z: 3.0, test1: 3.0, test2: Color{value: 2}, test3: Test{a: 5, b: 6}}, '
+        'pos: Vec3{x: 1.0, y: 2.0, z: 3.0, test1: 3.0, test2: Color.Green, test3: Test{a: 5, b: 6}}, '
         'mana: 150, hp: 80, name: MyMonster, inventory: [0, 1, 2, 3, 4], '
-        'color: Color{value: 8}, testType: AnyTypeId{value: 1}, '
+        'color: Color.Blue, testType: AnyTypeId.Monster, '
         'test: Monster{pos: null, mana: 150, hp: 100, name: Fred, '
-        'inventory: null, color: Color{value: 8}, testType: null, '
+        'inventory: null, color: Color.Blue, testType: null, '
         'test: null, test4: null, testarrayofstring: null, '
         'testarrayoftables: null, enemy: null, testnestedflatbuffer: null, '
         'testempty: null, testbool: false, testhashs32Fnv1: 0, '
@@ -82,18 +82,18 @@ class CheckOtherLangaugesData {
         'coOwningReference: 0, vectorOfCoOwningReferences: null, '
         'nonOwningReference: 0, vectorOfNonOwningReferences: null, '
         'anyUniqueType: null, anyUnique: null, anyAmbiguousType: null, '
-        'anyAmbiguous: null, vectorOfEnums: null, signedEnum: Race{value: -1}, '
+        'anyAmbiguous: null, vectorOfEnums: null, signedEnum: Race.None, '
         'testrequirednestedflatbuffer: null, scalarKeySortedTables: null, '
         'nativeInline: null, '
-        'longEnumNonEnumDefault: LongEnum{value: 0}, '
+        'longEnumNonEnumDefault: LongEnum._default, '
-        'longEnumNormalDefault: LongEnum{value: 2}, nanDefault: NaN, '
+        'longEnumNormalDefault: LongEnum.LongOne, nanDefault: NaN, '
         'infDefault: Infinity, positiveInfDefault: Infinity, infinityDefault: '
         'Infinity, positiveInfinityDefault: Infinity, negativeInfDefault: '
         '-Infinity, negativeInfinityDefault: -Infinity, doubleInfDefault: Infinity}, '
         'test4: [Test{a: 10, b: 20}, Test{a: 30, b: 40}], '
         'testarrayofstring: [test1, test2], testarrayoftables: null, '
         'enemy: Monster{pos: null, mana: 150, hp: 100, name: Fred, '
-        'inventory: null, color: Color{value: 8}, testType: null, '
+        'inventory: null, color: Color.Blue, testType: null, '
         'test: null, test4: null, testarrayofstring: null, '
         'testarrayoftables: null, enemy: null, testnestedflatbuffer: null, '
         'testempty: null, testbool: false, testhashs32Fnv1: 0, '
@@ -108,11 +108,11 @@ class CheckOtherLangaugesData {
         'coOwningReference: 0, vectorOfCoOwningReferences: null, '
         'nonOwningReference: 0, vectorOfNonOwningReferences: null, '
         'anyUniqueType: null, anyUnique: null, anyAmbiguousType: null, '
-        'anyAmbiguous: null, vectorOfEnums: null, signedEnum: Race{value: -1}, '
+        'anyAmbiguous: null, vectorOfEnums: null, signedEnum: Race.None, '
         'testrequirednestedflatbuffer: null, scalarKeySortedTables: null, '
         'nativeInline: null, '
-        'longEnumNonEnumDefault: LongEnum{value: 0}, '
+        'longEnumNonEnumDefault: LongEnum._default, '
-        'longEnumNormalDefault: LongEnum{value: 2}, nanDefault: NaN, '
+        'longEnumNormalDefault: LongEnum.LongOne, nanDefault: NaN, '
         'infDefault: Infinity, positiveInfDefault: Infinity, infinityDefault: '
         'Infinity, positiveInfinityDefault: Infinity, negativeInfDefault: '
         '-Infinity, negativeInfinityDefault: -Infinity, doubleInfDefault: Infinity}, '
@@ -137,12 +137,12 @@ class CheckOtherLangaugesData {
         'vectorOfNonOwningReferences: null, '
         'anyUniqueType: null, anyUnique: null, '
         'anyAmbiguousType: null, '
-        'anyAmbiguous: null, vectorOfEnums: null, signedEnum: Race{value: -1}, '
+        'anyAmbiguous: null, vectorOfEnums: null, signedEnum: Race.None, '
         'testrequirednestedflatbuffer: null, scalarKeySortedTables: [Stat{id: '
         'miss, val: 0, count: 0}, Stat{id: hit, val: 10, count: 1}], '
         'nativeInline: Test{a: 1, b: 2}, '
-        'longEnumNonEnumDefault: LongEnum{value: 0}, '
+        'longEnumNonEnumDefault: LongEnum._default, '
-        'longEnumNormalDefault: LongEnum{value: 2}, nanDefault: NaN, '
+        'longEnumNormalDefault: LongEnum.LongOne, nanDefault: NaN, '
         'infDefault: Infinity, positiveInfDefault: Infinity, infinityDefault: '
         'Infinity, positiveInfinityDefault: Infinity, negativeInfDefault: '
         '-Infinity, negativeInfinityDefault: -Infinity, doubleInfDefault: Infinity}');
@@ -215,6 +215,10 @@ class BuilderTest {
       ..addTestarrayofstringOffset(testArrayOfString);
     final mon = monBuilder.finish();
     fbBuilder.finish(mon);
+
+    final mon3 = example.Monster(fbBuilder.buffer);
+    expect(mon3.name, 'MyMonster');
+    expect(mon3.pos!.test1, 3.0);
   }
 
   void test_error_addInt32_withoutStartTable([Builder? builder]) {

dart/test/include_test1_generated.dart

@@ -1,5 +1,5 @@
 // automatically generated by the FlatBuffers compiler, do not modify
-// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable
+// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable, constant_identifier_names
 
 import 'dart:typed_data' show Uint8List;
 import 'package:flat_buffers/flat_buffers.dart' as fb;

dart/test/include_test2_my_game.other_name_space_generated.dart

@@ -1,5 +1,5 @@
 // automatically generated by the FlatBuffers compiler, do not modify
-// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable
+// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable, constant_identifier_names
 
 library my_game.other_name_space;
 
@@ -9,35 +9,25 @@ import 'package:flat_buffers/flat_buffers.dart' as fb;
 
 import './include_test1_generated.dart';
 
-class FromInclude {
+enum FromInclude {
+  IncludeVal(0);
+
   final int value;
-  const FromInclude._(this.value);
+  const FromInclude(this.value);
 
   factory FromInclude.fromValue(int value) {
-    final result = values[value];
+    switch (value) {
-    if (result == null) {
+      case 0: return FromInclude.IncludeVal;
-        throw StateError('Invalid value $value for bit flag enum FromInclude');
+      default: throw StateError('Invalid value $value for bit flag enum');
     }
-    return result;
   }
 
-  static FromInclude? _createOrNull(int? value) => 
+  static FromInclude? _createOrNull(int? value) =>
       value == null ? null : FromInclude.fromValue(value);
 
   static const int minValue = 0;
   static const int maxValue = 0;
-  static bool containsValue(int value) => values.containsKey(value);
-
-  static const FromInclude IncludeVal = FromInclude._(0);
-  static const Map<int, FromInclude> values = {
-    0: IncludeVal};
-
   static const fb.Reader<FromInclude> reader = _FromIncludeReader();
-
-  @override
-  String toString() {
-    return 'FromInclude{value: $value}';
-  }
 }
 
 class _FromIncludeReader extends fb.Reader<FromInclude> {

dart/test/keyword_test_keyword_test_generated.dart

@@ -1,5 +1,5 @@
 // automatically generated by the FlatBuffers compiler, do not modify
-// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable
+// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable, constant_identifier_names
 
 library keyword_test;
 
@@ -7,39 +7,29 @@ import 'dart:typed_data' show Uint8List;
 import 'package:flat_buffers/flat_buffers.dart' as fb;
 
 
-class Abc {
+enum Abc {
+  $void(0),
+  where(1),
+  stackalloc(2);
+
   final int value;
-  const Abc._(this.value);
+  const Abc(this.value);
 
   factory Abc.fromValue(int value) {
-    final result = values[value];
+    switch (value) {
-    if (result == null) {
+      case 0: return Abc.$void;
-        throw StateError('Invalid value $value for bit flag enum Abc');
+      case 1: return Abc.where;
+      case 2: return Abc.stackalloc;
+      default: throw StateError('Invalid value $value for bit flag enum');
     }
-    return result;
   }
 
-  static Abc? _createOrNull(int? value) => 
+  static Abc? _createOrNull(int? value) =>
       value == null ? null : Abc.fromValue(value);
 
   static const int minValue = 0;
   static const int maxValue = 2;
-  static bool containsValue(int value) => values.containsKey(value);
-
-  static const Abc $void = Abc._(0);
-  static const Abc where = Abc._(1);
-  static const Abc stackalloc = Abc._(2);
-  static const Map<int, Abc> values = {
-    0: $void,
-    1: where,
-    2: stackalloc};
-
   static const fb.Reader<Abc> reader = _AbcReader();
-
-  @override
-  String toString() {
-    return 'Abc{value: $value}';
-  }
 }
 
 class _AbcReader extends fb.Reader<Abc> {
@@ -53,35 +43,25 @@ class _AbcReader extends fb.Reader<Abc> {
       Abc.fromValue(const fb.Int32Reader().read(bc, offset));
 }
 
-class Public {
+enum Public {
+  NONE(0);
+
   final int value;
-  const Public._(this.value);
+  const Public(this.value);
 
   factory Public.fromValue(int value) {
-    final result = values[value];
+    switch (value) {
-    if (result == null) {
+      case 0: return Public.NONE;
-        throw StateError('Invalid value $value for bit flag enum Public');
+      default: throw StateError('Invalid value $value for bit flag enum');
     }
-    return result;
   }
 
-  static Public? _createOrNull(int? value) => 
+  static Public? _createOrNull(int? value) =>
       value == null ? null : Public.fromValue(value);
 
   static const int minValue = 0;
   static const int maxValue = 0;
-  static bool containsValue(int value) => values.containsKey(value);
-
-  static const Public NONE = Public._(0);
-  static const Map<int, Public> values = {
-    0: NONE};
-
   static const fb.Reader<Public> reader = _PublicReader();
-
-  @override
-  String toString() {
-    return 'Public{value: $value}';
-  }
 }
 
 class _PublicReader extends fb.Reader<Public> {
@@ -95,39 +75,29 @@ class _PublicReader extends fb.Reader<Public> {
       Public.fromValue(const fb.Int32Reader().read(bc, offset));
 }
 
-class KeywordsInUnionTypeId {
+enum KeywordsInUnionTypeId {
+  NONE(0),
+  $static(1),
+  internal(2);
+
   final int value;
-  const KeywordsInUnionTypeId._(this.value);
+  const KeywordsInUnionTypeId(this.value);
 
   factory KeywordsInUnionTypeId.fromValue(int value) {
-    final result = values[value];
+    switch (value) {
-    if (result == null) {
+      case 0: return KeywordsInUnionTypeId.NONE;
-        throw StateError('Invalid value $value for bit flag enum KeywordsInUnionTypeId');
+      case 1: return KeywordsInUnionTypeId.$static;
+      case 2: return KeywordsInUnionTypeId.internal;
+      default: throw StateError('Invalid value $value for bit flag enum');
     }
-    return result;
   }
 
-  static KeywordsInUnionTypeId? _createOrNull(int? value) => 
+  static KeywordsInUnionTypeId? _createOrNull(int? value) =>
       value == null ? null : KeywordsInUnionTypeId.fromValue(value);
 
   static const int minValue = 0;
   static const int maxValue = 2;
-  static bool containsValue(int value) => values.containsKey(value);
-
-  static const KeywordsInUnionTypeId NONE = KeywordsInUnionTypeId._(0);
-  static const KeywordsInUnionTypeId $static = KeywordsInUnionTypeId._(1);
-  static const KeywordsInUnionTypeId internal = KeywordsInUnionTypeId._(2);
-  static const Map<int, KeywordsInUnionTypeId> values = {
-    0: NONE,
-    1: $static,
-    2: internal};
-
   static const fb.Reader<KeywordsInUnionTypeId> reader = _KeywordsInUnionTypeIdReader();
-
-  @override
-  String toString() {
-    return 'KeywordsInUnionTypeId{value: $value}';
-  }
 }
 
 class _KeywordsInUnionTypeIdReader extends fb.Reader<KeywordsInUnionTypeId> {

dart/test/monster_test_my_game.example2_generated.dart

@@ -1,5 +1,5 @@
 // automatically generated by the FlatBuffers compiler, do not modify
-// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable
+// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable, constant_identifier_names
 
 library my_game.example2;
 

dart/test/monster_test_my_game.example_generated.dart

@@ -1,5 +1,5 @@
 // automatically generated by the FlatBuffers compiler, do not modify
-// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable
+// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable, constant_identifier_names
 
 library my_game.example;
 
@@ -12,46 +12,29 @@ import './monster_test_my_game.example2_generated.dart' as my_game_example2;
 import './include_test1_generated.dart';
 
 ///  Composite components of Monster color.
-class Color {
+enum Color {
+  Red(1),
+  Green(2),
+  Blue(8),
+  _default(0);
+
   final int value;
-  const Color._(this.value);
+  const Color(this.value);
 
   factory Color.fromValue(int value) {
-    final result = values[value];
+    switch (value) {
-    if (result == null) {
+      case 1: return Color.Red;
-      if (value == 0) {
+      case 2: return Color.Green;
-        return Color._(0);
+      case 8: return Color.Blue;
-      } else {
+      case 0: return Color._default;
-        throw StateError('Invalid value $value for bit flag enum Color');
+      default: throw StateError('Invalid value $value for bit flag enum');
-      }
     }
-    return result;
   }
 
-  static Color? _createOrNull(int? value) => 
+  static Color? _createOrNull(int? value) =>
       value == null ? null : Color.fromValue(value);
 
-  static bool containsValue(int value) => values.containsKey(value);
-
-  static const Color Red = Color._(1);
-
-  ///  \brief color Green
-  ///  Green is bit_flag with value (1u << 1)
-  static const Color Green = Color._(2);
-
-  ///  \brief color Blue (1u << 3)
-  static const Color Blue = Color._(8);
-  static const Map<int, Color> values = {
-    1: Red,
-    2: Green,
-    8: Blue};
-
   static const fb.Reader<Color> reader = _ColorReader();
-
-  @override
-  String toString() {
-    return 'Color{value: $value}';
-  }
 }
 
 class _ColorReader extends fb.Reader<Color> {
@@ -65,41 +48,31 @@ class _ColorReader extends fb.Reader<Color> {
       Color.fromValue(const fb.Uint8Reader().read(bc, offset));
 }
 
-class Race {
+enum Race {
+  None(-1),
+  Human(0),
+  Dwarf(1),
+  Elf(2);
+
   final int value;
-  const Race._(this.value);
+  const Race(this.value);
 
   factory Race.fromValue(int value) {
-    final result = values[value];
+    switch (value) {
-    if (result == null) {
+      case -1: return Race.None;
-        throw StateError('Invalid value $value for bit flag enum Race');
+      case 0: return Race.Human;
+      case 1: return Race.Dwarf;
+      case 2: return Race.Elf;
+      default: throw StateError('Invalid value $value for bit flag enum');
     }
-    return result;
   }
 
-  static Race? _createOrNull(int? value) => 
+  static Race? _createOrNull(int? value) =>
       value == null ? null : Race.fromValue(value);
 
   static const int minValue = -1;
   static const int maxValue = 2;
-  static bool containsValue(int value) => values.containsKey(value);
-
-  static const Race None = Race._(-1);
-  static const Race Human = Race._(0);
-  static const Race Dwarf = Race._(1);
-  static const Race Elf = Race._(2);
-  static const Map<int, Race> values = {
-    -1: None,
-    0: Human,
-    1: Dwarf,
-    2: Elf};
-
   static const fb.Reader<Race> reader = _RaceReader();
-
-  @override
-  String toString() {
-    return 'Race{value: $value}';
-  }
 }
 
 class _RaceReader extends fb.Reader<Race> {
@@ -113,41 +86,29 @@ class _RaceReader extends fb.Reader<Race> {
       Race.fromValue(const fb.Int8Reader().read(bc, offset));
 }
 
-class LongEnum {
+enum LongEnum {
+  LongOne(2),
+  LongTwo(4),
+  LongBig(1099511627776),
+  _default(0);
+
   final int value;
-  const LongEnum._(this.value);
+  const LongEnum(this.value);
 
   factory LongEnum.fromValue(int value) {
-    final result = values[value];
+    switch (value) {
-    if (result == null) {
+      case 2: return LongEnum.LongOne;
-      if (value == 0) {
+      case 4: return LongEnum.LongTwo;
-        return LongEnum._(0);
+      case 1099511627776: return LongEnum.LongBig;
-      } else {
+      case 0: return LongEnum._default;
-        throw StateError('Invalid value $value for bit flag enum LongEnum');
+      default: throw StateError('Invalid value $value for bit flag enum');
-      }
     }
-    return result;
   }
 
-  static LongEnum? _createOrNull(int? value) => 
+  static LongEnum? _createOrNull(int? value) =>
       value == null ? null : LongEnum.fromValue(value);
 
-  static bool containsValue(int value) => values.containsKey(value);
-
-  static const LongEnum LongOne = LongEnum._(2);
-  static const LongEnum LongTwo = LongEnum._(4);
-  static const LongEnum LongBig = LongEnum._(1099511627776);
-  static const Map<int, LongEnum> values = {
-    2: LongOne,
-    4: LongTwo,
-    1099511627776: LongBig};
-
   static const fb.Reader<LongEnum> reader = _LongEnumReader();
-
-  @override
-  String toString() {
-    return 'LongEnum{value: $value}';
-  }
 }
 
 class _LongEnumReader extends fb.Reader<LongEnum> {
@@ -161,41 +122,31 @@ class _LongEnumReader extends fb.Reader<LongEnum> {
       LongEnum.fromValue(const fb.Uint64Reader().read(bc, offset));
 }
 
-class AnyTypeId {
+enum AnyTypeId {
+  NONE(0),
+  Monster(1),
+  TestSimpleTableWithEnum(2),
+  MyGame_Example2_Monster(3);
+
   final int value;
-  const AnyTypeId._(this.value);
+  const AnyTypeId(this.value);
 
   factory AnyTypeId.fromValue(int value) {
-    final result = values[value];
+    switch (value) {
-    if (result == null) {
+      case 0: return AnyTypeId.NONE;
-        throw StateError('Invalid value $value for bit flag enum AnyTypeId');
+      case 1: return AnyTypeId.Monster;
+      case 2: return AnyTypeId.TestSimpleTableWithEnum;
+      case 3: return AnyTypeId.MyGame_Example2_Monster;
+      default: throw StateError('Invalid value $value for bit flag enum');
     }
-    return result;
   }
 
-  static AnyTypeId? _createOrNull(int? value) => 
+  static AnyTypeId? _createOrNull(int? value) =>
       value == null ? null : AnyTypeId.fromValue(value);
 
   static const int minValue = 0;
   static const int maxValue = 3;
-  static bool containsValue(int value) => values.containsKey(value);
-
-  static const AnyTypeId NONE = AnyTypeId._(0);
-  static const AnyTypeId Monster = AnyTypeId._(1);
-  static const AnyTypeId TestSimpleTableWithEnum = AnyTypeId._(2);
-  static const AnyTypeId MyGame_Example2_Monster = AnyTypeId._(3);
-  static const Map<int, AnyTypeId> values = {
-    0: NONE,
-    1: Monster,
-    2: TestSimpleTableWithEnum,
-    3: MyGame_Example2_Monster};
-
   static const fb.Reader<AnyTypeId> reader = _AnyTypeIdReader();
-
-  @override
-  String toString() {
-    return 'AnyTypeId{value: $value}';
-  }
 }
 
 class _AnyTypeIdReader extends fb.Reader<AnyTypeId> {
@@ -209,41 +160,31 @@ class _AnyTypeIdReader extends fb.Reader<AnyTypeId> {
       AnyTypeId.fromValue(const fb.Uint8Reader().read(bc, offset));
 }
 
-class AnyUniqueAliasesTypeId {
+enum AnyUniqueAliasesTypeId {
+  NONE(0),
+  M(1),
+  TS(2),
+  M2(3);
+
   final int value;
-  const AnyUniqueAliasesTypeId._(this.value);
+  const AnyUniqueAliasesTypeId(this.value);
 
   factory AnyUniqueAliasesTypeId.fromValue(int value) {
-    final result = values[value];
+    switch (value) {
-    if (result == null) {
+      case 0: return AnyUniqueAliasesTypeId.NONE;
-        throw StateError('Invalid value $value for bit flag enum AnyUniqueAliasesTypeId');
+      case 1: return AnyUniqueAliasesTypeId.M;
+      case 2: return AnyUniqueAliasesTypeId.TS;
+      case 3: return AnyUniqueAliasesTypeId.M2;
+      default: throw StateError('Invalid value $value for bit flag enum');
     }
-    return result;
   }
 
-  static AnyUniqueAliasesTypeId? _createOrNull(int? value) => 
+  static AnyUniqueAliasesTypeId? _createOrNull(int? value) =>
       value == null ? null : AnyUniqueAliasesTypeId.fromValue(value);
 
   static const int minValue = 0;
   static const int maxValue = 3;
-  static bool containsValue(int value) => values.containsKey(value);
-
-  static const AnyUniqueAliasesTypeId NONE = AnyUniqueAliasesTypeId._(0);
-  static const AnyUniqueAliasesTypeId M = AnyUniqueAliasesTypeId._(1);
-  static const AnyUniqueAliasesTypeId TS = AnyUniqueAliasesTypeId._(2);
-  static const AnyUniqueAliasesTypeId M2 = AnyUniqueAliasesTypeId._(3);
-  static const Map<int, AnyUniqueAliasesTypeId> values = {
-    0: NONE,
-    1: M,
-    2: TS,
-    3: M2};
-
   static const fb.Reader<AnyUniqueAliasesTypeId> reader = _AnyUniqueAliasesTypeIdReader();
-
-  @override
-  String toString() {
-    return 'AnyUniqueAliasesTypeId{value: $value}';
-  }
 }
 
 class _AnyUniqueAliasesTypeIdReader extends fb.Reader<AnyUniqueAliasesTypeId> {
@@ -257,41 +198,31 @@ class _AnyUniqueAliasesTypeIdReader extends fb.Reader<AnyUniqueAliasesTypeId> {
       AnyUniqueAliasesTypeId.fromValue(const fb.Uint8Reader().read(bc, offset));
 }
 
-class AnyAmbiguousAliasesTypeId {
+enum AnyAmbiguousAliasesTypeId {
+  NONE(0),
+  M1(1),
+  M2(2),
+  M3(3);
+
   final int value;
-  const AnyAmbiguousAliasesTypeId._(this.value);
+  const AnyAmbiguousAliasesTypeId(this.value);
 
   factory AnyAmbiguousAliasesTypeId.fromValue(int value) {
-    final result = values[value];
+    switch (value) {
-    if (result == null) {
+      case 0: return AnyAmbiguousAliasesTypeId.NONE;
-        throw StateError('Invalid value $value for bit flag enum AnyAmbiguousAliasesTypeId');
+      case 1: return AnyAmbiguousAliasesTypeId.M1;
+      case 2: return AnyAmbiguousAliasesTypeId.M2;
+      case 3: return AnyAmbiguousAliasesTypeId.M3;
+      default: throw StateError('Invalid value $value for bit flag enum');
     }
-    return result;
   }
 
-  static AnyAmbiguousAliasesTypeId? _createOrNull(int? value) => 
+  static AnyAmbiguousAliasesTypeId? _createOrNull(int? value) =>
       value == null ? null : AnyAmbiguousAliasesTypeId.fromValue(value);
 
   static const int minValue = 0;
   static const int maxValue = 3;
-  static bool containsValue(int value) => values.containsKey(value);
-
-  static const AnyAmbiguousAliasesTypeId NONE = AnyAmbiguousAliasesTypeId._(0);
-  static const AnyAmbiguousAliasesTypeId M1 = AnyAmbiguousAliasesTypeId._(1);
-  static const AnyAmbiguousAliasesTypeId M2 = AnyAmbiguousAliasesTypeId._(2);
-  static const AnyAmbiguousAliasesTypeId M3 = AnyAmbiguousAliasesTypeId._(3);
-  static const Map<int, AnyAmbiguousAliasesTypeId> values = {
-    0: NONE,
-    1: M1,
-    2: M2,
-    3: M3};
-
   static const fb.Reader<AnyAmbiguousAliasesTypeId> reader = _AnyAmbiguousAliasesTypeIdReader();
-
-  @override
-  String toString() {
-    return 'AnyAmbiguousAliasesTypeId{value: $value}';
-  }
 }
 
 class _AnyAmbiguousAliasesTypeIdReader extends fb.Reader<AnyAmbiguousAliasesTypeId> {
@@ -1461,7 +1392,7 @@ class MonsterT implements fb.Packable {
       this.testrequirednestedflatbuffer,
       this.scalarKeySortedTables,
       this.nativeInline,
-      this.longEnumNonEnumDefault = const LongEnum._(0),
+      this.longEnumNonEnumDefault = LongEnum._default,
       this.longEnumNormalDefault = LongEnum.LongOne,
       this.nanDefault = double.nan,
       this.infDefault = double.infinity,

dart/test/monster_test_my_game_generated.dart

@@ -1,5 +1,5 @@
 // automatically generated by the FlatBuffers compiler, do not modify
-// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable
+// ignore_for_file: unused_import, unused_field, unused_element, unused_local_variable, constant_identifier_names
 
 library my_game;
 

docs-old/README.md

@@ -0,0 +1,3 @@
+This is the source of the old docs that are being replaced. They are served
+from the `gh-pages-old` branch, while the new documentations (source in docs/)
+is served from the `gh-pages` branch.

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 <downloaded.zip> -provenance attestation.intoto.jsonl -source github.com/google/flatbuffers -tag <version>
   PASSED: Verified SLSA provenance
+```
 
 ## Building for Android
 

docs-old/source/Compiler.md

@@ -96,10 +96,10 @@ Additional options:
 
 -   `--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.`
@@ -238,5 +238,44 @@ Additional options:
 
 -   `--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.

docs/README.md

@@ -0,0 +1,24 @@
+# Documentation
+
+This is the source of the FlatBuffers documentation, that is served at
+https://flatbuffers.dev.
+
+
+## Local Building
+
+The documentation can be built and served locally during development, see [https//flatbuffers.dev/contributing/#local-development] for full details.
+
+__tl;dr__
+
+Install:
+
+```
+pip install mkdocs-material
+pip install mkdocs-redirects
+```
+
+Build and Serve:
+
+```
+mkdocs serve -f docs/mkdocs.yml
+```

docs/mkdocs.yml

@@ -0,0 +1,159 @@
+site_name: FlatBuffers Docs
+docs_dir: source
+site_url: https://flatbuffers.dev
+repo_name: google/FlatBuffers
+repo_url: https://github.com/google/flatbuffers
+edit_uri: edit/master/docs/source/
+copyright: Copyright © 2025 Google
+theme:
+  name: material
+  logo: assets/flatbuffers_logo.svg
+  icon:
+    repo: fontawesome/brands/github
+  custom_dir: overrides
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  features:
+    # Allows code block annotations
+    - content.code.annotate
+
+    # Allows content tabs to link together
+    - content.tabs.link
+  
+    # Expand nav folders by default
+    - navigation.expand
+
+    # Enable the footer
+    - navigation.footer
+    
+    # Auto hide the header after scrolling
+    - header.autohide
+
+    - content.action.edit
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/google/flatbuffers
+
+    - icon: fontawesome/brands/discord
+      link: https:///discord.gg/6qgKs3R
+
+    - icon: fontawesome/brands/x-twitter
+      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_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'
+        'md__schemas.html.md': 'schema.md' # issue #8485
+        '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:
+  - admonition
+  - attr_list
+  - md_in_html
+  - pymdownx.critic
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.snippets:
+      # Allows direct embedded of remote files
+      url_download: true
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+      slugify: !!python/object/apply:pymdownx.slugs.slugify
+        kwds:
+          case: lower
+  - pymdownx.highlight:
+      extend_pygments_lang:
+        # PHP wasn't highlighting correctly. This is a work around found
+        # https://github.com/squidfunk/mkdocs-material/issues/138#issuecomment-2294025627
+        - name: php
+          lang: php
+          options:
+            startinline: true
+  - tables
+
+
+
+nav:
+  - Overview: "index.md"
+  - Quick Start: "quick_start.md"
+  - Tutorial: "tutorial.md"
+  - Compiler (flatc): 
+    - Building: "building.md"
+    - Using: "flatc.md"
+  - Schema (.fbs): 
+    - Overview: "schema.md"
+    - Evolution: "evolution.md"
+    - Grammar: "grammar.md"
+  - Language Guides:
+    - 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"
+    - Kotlin: "languages/kotlin.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/overrides/404.html

@@ -0,0 +1,11 @@
+{% extends "main.html" %}
+
+<!-- Content -->
+{% block content %}
+  <h1>404 - Not found</h1>
+  <br>
+  FlatBuffers is currently migrating their documentation system and existing 
+  links may not work. 
+  
+  Please <a href="https://github.com/google/flatbuffers/issues/new?template=404-doc.md">file an issue</a> indicating the broken link.
+{% endblock %}

docs/overrides/main.html

@@ -0,0 +1,6 @@
+{% extends "base.html" %}
+
+<!-- Announcement bar -->
+{% block announce %}
+  Documentation migration in progress, view snapshot of the old documentation <a href="https://dbaileychess.github.io/flatbuffers">here.</a>
+{% endblock %}

docs/source/CNAME

@@ -0,0 +1 @@
+flatbuffers.dev

docs/source/annotation.md

@@ -0,0 +1,149 @@
+# Annotating FlatBuffers
+
+This provides a way to annotate flatbuffer binary data, byte-by-byte, with a
+schema. It is useful for development purposes and understanding the details of
+the internal format.
+
+## Annotating
+
+Given a `schema`, as either a plain-text (`.fbs`) or a binary schema (`.bfbs`),
+and `binary` file(s) that were created by the `schema`. You can annotate them
+using:
+
+```sh
+flatc --annotate SCHEMA -- BINARY_FILES...
+```
+
+This will produce a set of annotated files (`.afb` Annotated FlatBuffer)
+corresponding to the input binary files.
+
+### Example
+
+Taken from the [tests/annotated_binary](https://github.com/google/flatbuffers/tree/master/tests/annotated_binary).
+
+```sh
+cd tests/annotated_binary
+../../flatc --annotate annotated_binary.fbs -- annotated_binary.bin
+```
+
+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:
+
+```sh
+..\..\flatc -b annotated_binary.fbs annotated_binary.json
+```
+
+## .afb Text Format
+
+Currently there is a built-in text-based format for outputting the annotations.
+A full example is shown here:
+[`annotated_binary.afb`](https://github.com/google/flatbuffers/blob/master/tests/annotated_binary/annotated_binary.afb)
+
+The data is organized as a table with fixed [columns](#columns) grouped into
+Binary [sections](#binary-sections) and [regions](#binary-regions), starting
+from the beginning of the binary (offset `0`).
+
+### Columns
+
+The columns are as follows:
+
+1. The offset from the start of the binary, expressed in hexadecimal format
+   (e.g. `+0x003c`).
+
+    The prefix `+` is added to make searching for the offset (compared to some
+    random value) a bit easier.
+
+2. The raw binary data, expressed in hexadecimal format. 
+   
+    This is in the little endian format the buffer uses internally and what you
+    would see with a normal binary text viewer.
+
+3. The type of the data.
+
+    This may be the type specified in the schema or some internally defined
+    types:
+
+
+    | Internal Type | Purpose                                            |
+    |---------------|----------------------------------------------------|
+    | `VOffset16`   | Virtual table offset, relative to the table offset |
+    | `UOffset32`   | Unsigned offset, relative to the current offset    |
+    | `SOffset32`   | Signed offset, relative to the current offset      |
+
+
+4. The value of the data.
+
+    This is shown in big endian format that is generally written for humans to
+    consume (e.g. `0x0013`). As well as the "casted" value (e.g. `0x0013 `is
+    `19` in decimal) in parentheses.
+
+5. Notes about the particular data.
+
+    This describes what the data is about, either some internal usage, or tied
+    to the schema.
+
+### Binary Sections
+
+The file is broken up into Binary Sections, which are comprised of contiguous
+[binary regions](#binary-regions) that are logically grouped together. For
+example, a binary section may be a single instance of a flatbuffer `Table` or
+its `vtable`. The sections may be labelled with the name of the associated type,
+as defined in the input schema.
+
+An example of a `vtable` Binary Section that is associated with the user-defined
+`AnnotateBinary.Bar` table.
+
+```
+vtable (AnnotatedBinary.Bar):
+  +0x00A0 | 08 00      | uint16_t   | 0x0008 (8)   | size of this vtable
+  +0x00A2 | 13 00      | uint16_t   | 0x0013 (19)  | size of referring table
+  +0x00A4 | 08 00      | VOffset16  | 0x0008 (8)   | offset to field `a` (id: 0)
+  +0x00A6 | 04 00      | VOffset16  | 0x0004 (4)   | offset to field `b` (id: 1)
+```
+
+These are purely annotative, there is no embedded information about these
+regions in the flatbuffer itself.
+
+### Binary Regions
+
+Binary regions are contiguous bytes regions that are grouped together to form 
+some sort of value, e.g. a `scalar` or an array of scalars. A binary region may
+be split up over multiple text lines, if the size of the region is large.
+
+#### Annotation Example
+
+Looking at an example binary region:
+
+```
+vtable (AnnotatedBinary.Bar):
+  +0x00A0 | 08 00      | uint16_t   | 0x0008 (8)   | size of this vtable
+```
+
+The first column (`+0x00A0`) is the offset to this region from the beginning of
+the buffer. 
+
+The second column are the raw bytes (hexadecimal) that make up this region.
+These are expressed in the little-endian format that flatbuffers uses for the
+wire format.
+
+The third column is the type to interpret the bytes as. For the above example,
+the type is `uint16_t` which is a 16-bit unsigned integer type.
+
+The fourth column shows the raw bytes as a compacted, big-endian value. The raw
+bytes are duplicated in this fashion since it is more intuitive to read the data
+in the big-endian format (e.g., `0x0008`). This value is followed by the decimal
+representation of the value (e.g., `(8)`). For strings, the raw string value is
+shown instead. 
+
+The fifth column is a textual comment on what the value is. As much metadata as
+known is provided.
+
+### Offsets
+
+If the type in the 3rd column is of an absolute offset (`SOffet32` or
+`Offset32`), the fourth column also shows an `Loc: +0x025A` value which shows
+where in the binary this region is pointing to. These values are absolute from
+the beginning of the file, their calculation from the raw value in the 4th
+column depends on the context.

docs/source/assets/flatbuffers_logo.svg

@@ -0,0 +1,318 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="48"
+   height="48"
+   viewBox="0 0 12.699999 12.699999"
+   version="1.1"
+   id="svg5"
+   xml:space="preserve"
+   inkscape:version="1.2.1 (9c6d41e410, 2022-07-14)"
+   sodipodi:docname="flatbuffer_logo.svg"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg"><sodipodi:namedview
+     id="namedview7"
+     pagecolor="#ffffff"
+     bordercolor="#000000"
+     borderopacity="0.25"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     inkscape:document-units="mm"
+     showgrid="false"
+     inkscape:zoom="16"
+     inkscape:cx="30.03125"
+     inkscape:cy="31.0625"
+     inkscape:window-width="2560"
+     inkscape:window-height="1377"
+     inkscape:window-x="2552"
+     inkscape:window-y="-8"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="layer1" /><defs
+     id="defs2"><linearGradient
+       inkscape:collect="always"
+       id="linearGradient51996"><stop
+         style="stop-color:#ff0c0c;stop-opacity:1;"
+         offset="0"
+         id="stop51992" /><stop
+         style="stop-color:#ffc402;stop-opacity:1;"
+         offset="1"
+         id="stop51994" /></linearGradient><inkscape:path-effect
+       effect="mirror_symmetry"
+       start_point="78.68,115.48"
+       end_point="78.68,120.48705"
+       center_point="78.68,117.98353"
+       id="path-effect36913"
+       is_visible="true"
+       lpeversion="1.2"
+       lpesatellites=""
+       mode="free"
+       discard_orig_path="false"
+       fuse_paths="true"
+       oposite_fuse="true"
+       split_items="false"
+       split_open="false"
+       link_styles="false" /><inkscape:path-effect
+       effect="mirror_symmetry"
+       start_point="78.68,115.48"
+       end_point="78.68,120.48705"
+       center_point="78.68,117.98353"
+       id="path-effect36913-5"
+       is_visible="true"
+       lpeversion="1.2"
+       lpesatellites=""
+       mode="free"
+       discard_orig_path="false"
+       fuse_paths="true"
+       oposite_fuse="true"
+       split_items="false"
+       split_open="false"
+       link_styles="false" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient51998"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016"
+       gradientUnits="userSpaceOnUse" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1071"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1073"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1075"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.579903"
+       y2="124.25231" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1077"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1079"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1081"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1083"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1085"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1087"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1089"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1091"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1093"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1095"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1097"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1099"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /><linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient51996"
+       id="linearGradient1101"
+       gradientUnits="userSpaceOnUse"
+       x1="78.572853"
+       y1="121.57343"
+       x2="78.605698"
+       y2="123.67016" /></defs><g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"><path
+       style="fill:#ee2349;fill-opacity:1;stroke-width:0.264583"
+       d="m 78.679688,115.50977 c -0.120712,0.0641 -0.42793,0.23077 -0.582032,0.34961 -0.183353,0.14139 -0.341667,0.2967 -0.496094,0.48632 -0.09316,0.11439 -0.175141,0.29861 -0.208984,0.46485 -0.05593,0.27473 -0.01958,0.56221 0.01953,0.83984 0.0674,0.47849 0.369141,1.40234 0.369141,1.40234 0,0 -0.370215,0.25236 -0.529297,0.40821 -0.08369,0.082 -0.134669,0.16526 -0.179687,0.27344 -0.06269,0.15064 -0.0906,0.32319 -0.09375,0.48632 -0.0016,0.0822 0.01367,0.26563 0.01367,0.26563 -10e-7,0 0.365376,-0.37098 0.609374,-0.45117 0.135542,-0.0445 0.296791,-0.0606 0.427735,-0.004 0.05341,0.0231 0.05909,0.12539 0.117187,0.12891 0.134803,0.008 0.418285,0.003 0.533204,0 0.114918,0.003 0.3984,0.008 0.533203,0 0.05809,-0.004 0.06378,-0.10581 0.117187,-0.12891 0.130944,-0.0567 0.294146,-0.0406 0.429688,0.004 0.243998,0.0802 0.607422,0.45117 0.607422,0.45117 0,0 0.01722,-0.18343 0.01562,-0.26563 -0.0031,-0.16313 -0.03106,-0.33569 -0.09375,-0.48632 -0.04502,-0.10818 -0.09795,-0.19144 -0.18164,-0.27344 -0.159082,-0.15585 -0.529297,-0.40821 -0.529297,-0.40821 0,0 0.303694,-0.92385 0.371094,-1.40234 0.03911,-0.27763 0.07351,-0.56511 0.01758,-0.83984 -0.03384,-0.16624 -0.115825,-0.35046 -0.208985,-0.46485 -0.154426,-0.18962 -0.31274,-0.34493 -0.496093,-0.48632 -0.154102,-0.11884 -0.46132,-0.28549 -0.582031,-0.34961 z"
+       id="path36791-6"
+       sodipodi:nodetypes="csssscssscssscc"
+       class="UnoptimicedTransforms"
+       transform="matrix(-1.5867841,0,0,1.5867841,131.19823,-183.26425)"
+       inkscape:path-effect="#path-effect36913"
+       inkscape:original-d="m 78.629702,115.48256 c 0,0 0.438268,0.22675 0.632602,0.37661 0.183353,0.1414 0.340934,0.29733 0.49536,0.48695 0.09316,0.11439 0.17524,0.29778 0.209083,0.46402 0.05593,0.27473 0.02088,0.56327 -0.01823,0.8409 -0.0674,0.47849 -0.370162,1.40159 -0.370162,1.40159 0,0 0.369865,0.25228 0.528947,0.40813 0.08369,0.082 0.136292,0.16564 0.18131,0.27381 0.06269,0.15064 0.09017,0.32334 0.09332,0.48647 0.0016,0.0822 -0.01413,0.26601 -0.01413,0.26601 0,0 -0.36491,-0.37107 -0.608908,-0.45126 -0.135542,-0.0445 -0.29706,-0.0607 -0.428004,-0.004 -0.05341,0.0231 -0.06025,0.12485 -0.118343,0.12837 -0.171522,0.0104 -0.582695,-0.002 -0.582695,-0.002 z" /><circle
+       style="fill:#ffffff;fill-opacity:1;stroke-width:0.461723"
+       id="path37027"
+       cx="6.346231"
+       cy="2.3943322"
+       r="1.2447678" /><circle
+       style="font-variation-settings:normal;vector-effect:none;fill:#ffc402;fill-opacity:1;stroke-width:0.141574;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+       id="path37568-5-9-1-3-6-1"
+       cx="6.5362368"
+       cy="12.559268"
+       r="0.11592077" /><g
+       id="g51228"
+       style="fill:url(#linearGradient51998);fill-opacity:1"
+       transform="matrix(1.5867841,0,0,1.5867841,-120.3592,-185.13424)"><circle
+         style="fill:url(#linearGradient1071);fill-opacity:1;stroke-width:0.224809"
+         id="path37568"
+         cx="79.219589"
+         cy="121.77583"
+         r="0.18407404" /><circle
+         style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:url(#linearGradient1073);fill-opacity:1;stroke-width:0.377183;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000;stop-opacity:1"
+         id="path37568-5"
+         cx="79.928802"
+         cy="121.81054"
+         r="0.30883789" /><circle
+         style="font-variation-settings:normal;vector-effect:none;fill:url(#linearGradient1075);fill-opacity:1;stroke-width:0.518098;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+         id="path37568-5-9"
+         cx="79.265541"
+         cy="122.34314"
+         r="0.42421949" /><circle
+         style="font-variation-settings:normal;vector-effect:none;fill:url(#linearGradient1077);fill-opacity:1;stroke-width:0.194865;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+         id="path37568-5-9-8"
+         cx="78.911224"
+         cy="122.55578"
+         r="0.15955541" /><circle
+         style="font-variation-settings:normal;vector-effect:none;fill:url(#linearGradient1079);fill-opacity:1;stroke-width:0.317766;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+         id="path37568-5-9-1"
+         cx="79.634331"
+         cy="122.87711"
+         r="0.26018718" /><circle
+         style="font-variation-settings:normal;vector-effect:none;fill:url(#linearGradient1081);fill-opacity:1;stroke-width:0.378906;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+         id="path37568-5-9-1-3"
+         cx="80.265633"
+         cy="123.65545"
+         r="0.31024873" /><circle
+         style="font-variation-settings:normal;vector-effect:none;fill:url(#linearGradient1083);fill-opacity:1;stroke-width:0.177006;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+         id="path37568-5-9-1-3-6"
+         cx="79.914619"
+         cy="124.27737"
+         r="0.14493258" /><circle
+         style="font-variation-settings:normal;vector-effect:none;fill:url(#linearGradient1085);fill-opacity:1;stroke-width:0.0989143;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+         id="path37568-5-9-1-3-6-6"
+         cx="80.206474"
+         cy="124.00723"
+         r="0.080991074" /><circle
+         style="font-variation-settings:normal;vector-effect:none;fill:url(#linearGradient1087);fill-opacity:1;stroke-width:0.221224;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+         id="path37568-5-9-1-3-6-0"
+         cx="79.695312"
+         cy="123.76383"
+         r="0.18113838" /><ellipse
+         style="font-variation-settings:normal;vector-effect:none;fill:url(#linearGradient1089);fill-opacity:1;stroke-width:0.271828;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+         id="path37568-5-9-1-3-6-0-6"
+         cx="79.60508"
+         cy="123.37116"
+         rx="0.22375529"
+         ry="0.22139755" /><ellipse
+         style="font-variation-settings:normal;vector-effect:none;fill:url(#linearGradient1091);fill-opacity:1;stroke-width:0.271828;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+         id="path37568-5-9-1-3-6-0-6-7"
+         cx="79.846291"
+         cy="123.10796"
+         rx="0.22375529"
+         ry="0.22139755" /><ellipse
+         style="font-variation-settings:normal;vector-effect:none;fill:url(#linearGradient1093);fill-opacity:1;stroke-width:0.244555;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+         id="path37568-5-9-1-3-6-0-6-2"
+         cx="79.247681"
+         cy="123.40287"
+         rx="0.19959654"
+         ry="0.20088845" /><circle
+         style="font-variation-settings:normal;vector-effect:none;fill:url(#linearGradient1095);fill-opacity:1;stroke-width:0.243037;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+         id="path37568-5-9-1-2"
+         cx="80.333969"
+         cy="122.72621"
+         r="0.19899905" /><circle
+         style="font-variation-settings:normal;vector-effect:none;fill:url(#linearGradient1097);fill-opacity:1;stroke-width:0.282009;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+         id="path37568-5-9-1-2-0-9"
+         cx="80.747818"
+         cy="122.34882"
+         r="0.23090924" /><circle
+         style="font-variation-settings:normal;vector-effect:none;fill:url(#linearGradient1099);fill-opacity:1;stroke-width:0.313683;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-stroke:none;stop-color:#000000"
+         id="path37568-5-9-1-2-7"
+         cx="80.58844"
+         cy="122.97715"
+         r="0.25684434" /><circle
+         style="fill:url(#linearGradient1101);fill-opacity:1;stroke-width:0.426803"
+         id="path37568-5-6"
+         cx="80.422928"
+         cy="122.06255"
+         r="0.34946665" /></g></g></svg>

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/building.md

@@ -0,0 +1,177 @@
+# Building
+
+## Building with CMake
+
+The distribution main build system is configured by
+[`cmake`](https://www.cmake.org) which allows you to build the project for any
+platform.
+
+### Configuration
+
+Use `cmake` to configure a project based on your environment and platform.
+
+=== "Unix"
+
+    ```sh
+    cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release
+    ```
+
+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"
+
+    ```sh
+    cmake -G "Visual Studio 17 2022" -DCMAKE_BUILD_TYPE=Release
+    ```
+
+=== "MacOS"
+
+    ```sh
+    cmake -G "Xcode" -DCMAKE_BUILD_TYPE=Release
+    ```
+
+#### Strict Mode
+
+By default, `cmake` will configure targets to **not** build with strict warnings
+on (e.g. `-Werror` or `/WX`). This may cause into issues when submitting code
+changes since our CI requires the code to compile in strict mode.
+
+To enable the extra warnings, turn on strict mode with the
+`FLATBUFFERS_STRICT_MODE` cmake option.
+
+```cmake
+cmake -DFLATBUFFERS_STRICT_MODE=ON
+```
+
+
+### Building
+
+Once the project files are generated, build as normal for your platform.
+
+=== "Unix"
+
+    ```sh
+    make -j
+    ```
+
+=== "Windows"
+
+    ```sh
+    msbuild.exe FlatBuffers.sln
+    ```
+
+=== "MacOS"
+
+    ```sh
+    xcodebuild -toolchain clang -configuration Release
+    ```
+
+
+
+
+
+
+## Building with Bazel
+
+You can use [Bazelisk](https://github.com/bazelbuild/bazelisk) to manage your Bazel environment.
+For Swift support, you also need Clang and [Swift SDK](https://download.swift.org/).
+
+```sh
+curl -sL --fail https://github.com/bazelbuild/bazelisk/releases/download/v1.25.0/bazelisk-linux-amd64 -o bazelisk && chmod +x bazelisk
+sudo apt install -y clang
+SWIFT_VERSION="6.0.3"
+curl -L https://download.swift.org/swift-${SWIFT_VERSION}-release/debian12/swift-${SWIFT_VERSION}-RELEASE/swift-${SWIFT_VERSION}-RELEASE-debian12.tar.gz | tar xz
+CC=clang PATH=$PATH:$(pwd)/swift-${SWIFT_VERSION}-RELEASE-debian12/usr/bin bazel build //...
+CC=clang PATH=$PATH:$(pwd)/swift-${SWIFT_VERSION}-RELEASE-debian12/usr/bin bazel test //...
+```
+
+If you are unsure which versions to use, check our CI config at `.bazelci/presubmit.yml`.
+
+## 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
+```

docs/source/contributing.md

@@ -0,0 +1,80 @@
+# Contributing
+
+We encourage community contributions to FlatBuffers through pull requests at the
+main
+[http://github.com/google/flatbuffers](http://github.com/google/flatbuffers)
+repository.
+
+!!! note
+
+    The FlatBuffers project is not staffed by any full time Google employee, and
+    is managed by a small team of 20%ers. So response time and expertise vary.
+
+## Before you contribute
+
+Before we can use your contributions, you __must__ sign one of the following license agreements. The agreements are self-served at the following links.
+
+Our code review process will automatically check if you have signed the CLA, so
+don't fret. Though it may be prudent to check before spending a lot of time on 
+contribution.
+
+### Individual Contributions 
+
+For individuals, the [Google Individual
+Contributor License Agreement
+(CLA)](https://cla.developers.google.com/about/google-individual?csw=1) which is
+self served at the link. The CLA is required since you own the copyright to your
+changes, even after your contribution becomes part of our codebase, so we need
+your permission to use and distribute your code. 
+
+### Corporate Contributions
+
+Contributions made by corporations are covered by the [Google Software Grant and
+Corporate Contributor License
+Agreement](https://cla.developers.google.com/about/google-corporate).
+
+## Code Reviews
+
+All submissions require a code review via Github Pull Requests.
+
+1. Please adhere to the [Google Style Guide](https://google.github.io/styleguide/cppguide.html) for the language(s) you are submitting in.
+2. Keep PRs small and focused. Its good practice and makes it more likely your PR will be approved.
+3. Please add tests if possible.
+4. Include descriptive commit messages and context to the change/issues fixed.
+
+## Documentation
+
+FlatBuffers uses [MkDocs](https://www.mkdocs.org/) to generate the static
+documentation pages served at
+[https://flatbuffers.dev](https://flatbuffers.dev). Specifically, we use the
+[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) framework.
+
+The documentation source is contained in the main repo under the
+[docs/](https://github.com/google/flatbuffers/tree/master/docs) directory. This
+[automatically](https://github.com/google/flatbuffers/blob/46cc3d6432da17cca7694777dcce12e49dd48387/.github/workflows/docs.yml#L6-L11) get built and published when the commit is made.
+
+### Local Development
+
+We encourage contributors to keep the documentation up-to-date as well, and it
+is easy to with `MkDocs` local building and serving tools.
+
+First install `mkdocs-material` (see
+[Installation](https://squidfunk.github.io/mkdocs-material/getting-started/) for
+other ways)
+
+```
+pip install mkdocs-material
+pip install mkdocs-redirects
+```
+
+Then, in the `root` directory of flatbuffers, run 
+
+```
+mkdocs serve -f docs/mkdocs.yml
+```
+
+This will continually watch the repo for changes to the documentation and serve
+the rendered pages locally.
+
+Submit your documentation changes with your code changes and they will
+automatically get published when your code is submitted.

docs/source/evolution.md

@@ -0,0 +1,276 @@
+# Evolution
+
+FlatBuffers enables the [schema](schema.md) to evolve over time while still
+maintaining forwards and backwards compatibility with old flatbuffers.
+
+Some rules must be followed to ensure the evolution of a schema is valid.
+
+## Rules
+
+Adding new tables, vectors, structs to the schema is always allowed. Its only
+when you add a new field to a [`table`](schema.md#tables) that certain rules
+must be followed.
+
+### Addition
+
+**New fields MUST be added to the end of the table definition.**
+
+This allows older data to still be read correctly (giving you the default value
+of the added field if accessed).
+
+Older code will simply ignore the new field in the flatbuffer.
+
+You can ignore this rule if you use the `id` attribute on all the fields of a
+table.
+
+### Removal
+
+**You MUST not remove a field from the schema, even if you don't use it
+anymore.** You simply stop writing them to the buffer.
+
+Its encouraged to mark the field deprecated by adding the `deprecated`
+attribute. This will skip the generation of accessors and setters in the code,
+to enforce the field not to be used any more.
+
+### Name Changes
+
+Its generally OK to change the name of tables and fields, as these are not
+serialized to the buffer. It may break code that would have to be refactored
+with the updated name.
+
+## Examples
+
+The following examples uses a base schema and attempts to evolve it a few times.
+The versions are tracked by `V1`, `V2`, etc.. and `CodeV1` means code compiled
+against the `V1` schema.
+
+### Table Evolution
+
+Lets start with a simple table `T` with two fields.
+
+```c++ title="Schema V1"
+table T {
+  a:int;
+  b:int;
+}
+```
+
+=== "Well Evolved"
+
+    First lets extend the table with a new field.
+
+    ```c++ title="Schema V2"
+    table T {
+      a:int;
+      b:int;
+      c:int;
+    }
+    ```
+
+    This is OK. `CodeV1` reading `V2` data will simply ignore the presence of the
+    new field `c`. `CodeV2` reading `V1` data will get a default value (0) when
+    reading `c`.
+
+    ```c++ title="Schema V3"
+    table T {
+      a:int (deprecated);
+      b:int;
+      c:int;
+    }
+    ```
+
+    This is OK, removing field `a` via deprecation. `CodeV1`, `CodeV2` and `CodeV3`
+    reading `V3` data will now always get the default value of `a`, since it is not
+    present. `CodeV3` cannot write `a` anymore. `CodeV3` reading old data (`V1` or
+    `V2`) will not be able to access the field anymore, since no generated accessors
+    are omitted.
+
+=== "Improper Addition"
+
+    Add a new field, but this time at the beginning.
+
+    ```c++ title="Schema V2"
+    table T {
+      c:int;
+      a:int;
+      b:int;
+    }
+    ```
+
+    This is NOT OK, as it makes `V2` incompatible. `CodeV1` reading `V2` data
+    will access `a` but will read `c` data.
+
+    `CodeV2` reading `V1` data will access `c` but will read `a` data.
+
+=== "Improper Deletion"
+
+    Remove a field from the schema.
+
+    ```c++ title="Schema V2"
+    table T {
+      b:int;
+    }
+    ```
+
+    This is NOT OK. `CodeV1` reading `V2` data will access `a` but read `b` data.
+
+    `CodeV2` reading `V1` data will access `b` but will read `a` data.
+
+=== "Proper Reordering"
+
+    Lets add a new field to the beginning, but use `id` attributes.
+
+    ```c++ title="Schema V2"
+    table T {
+      c:int (id: 2);
+      a:int (id: 0);
+      b:int (id: 1);
+    }
+    ```
+
+    This is OK. This adds the a new field in the beginning, but because all the
+    `id` attributes were added, it is OK.
+
+=== "Changing Types"
+
+    Let change the types of the fields.
+
+    ```c++ title="Schema V2"
+    table T {
+      a:uint;
+      b:uint;
+    }
+    ```
+
+    This is MAYBE OK, and only in the case where the type change is the same
+    width. This is tricky if the `V1` data contained any negative numbers. So
+    this should be done with care.
+
+=== "Changing Defaults"
+
+    Lets change the default values of the existing fields.
+
+    ```c++ title="Schema V2"
+    table T {
+      a:int = 1;
+      b:int = 2;
+    }
+    ```
+
+    This is NOT OK. Any `V1` data that did not have a value written to the
+    buffer relied on generated code to provide the default value.
+
+    There MAY be cases where this is OK, if you control all the producers and
+    consumers, and you can update them in tandem.
+
+=== "Renaming Fields"
+
+    Lets change the name of the fields
+
+    ```c++ title="Schema V2"
+    table T {
+      aa:int;
+      bb:int;
+    }
+    ```
+
+    This is generally OK. You've renamed fields will break all code and JSON
+    files that use this schema, but you can refactor those without affecting the
+    binary data, since the binary only address fields by id and offset, not by
+    names.
+
+### Union Evolution
+
+Lets start with a simple union `U` with two members.
+
+```c++ title="Schema V1"
+union U {
+  A,
+  B
+}
+```
+
+=== "Well Evolved"
+
+    Lets add a another variant to the end.
+
+    ```c++ title="Schema V2"
+    union U {
+      A,
+      B,
+      another_a: A
+    }
+    ```
+
+    This is OK. `CodeV1` will not recognize the `another_a`.
+
+=== "Improper Evolved"
+
+    Lets add a another variant to the middle.
+
+    ```c++ title="Schema V2"
+    union U {
+      A,
+      another_a: A,
+      B
+    }
+    ```
+
+    This is NOT OK. `CodeV1` reading `V2` data will interpret `B` as `another_a`.
+    `CodeV2` reading `V1` data will interpret `another_a` as `B`.
+
+=== "Evolved With Discriminant"
+
+    Lets add a another variant to the middle, this time adding a union "discriminant".
+
+    ```c++ title="Schema V2"
+    union U {
+      A = 1,
+      another_a: A = 3,
+      B = 2
+    }
+    ```
+
+    This is OK. Its like you added it to the end, but using the discriminant
+    value to physically place it elsewhere in the union.
+
+## Version Control
+
+FlatBuffers relies on new field declarations being added at the end, and earlier
+declarations to not be removed, but be marked deprecated when needed. We think
+this is an improvement over the manual number assignment that happens in
+Protocol Buffers (and which is still an option using the `id` attribute
+mentioned above).
+
+One place where this is possibly problematic however is source control. If user
+`A` adds a field, generates new binary data with this new schema, then tries to
+commit both to source control after user `B` already committed a new field also,
+and just auto-merges the schema, the binary files are now invalid compared to
+the new schema.
+
+The solution of course is that you should not be generating binary data before
+your schema changes have been committed, ensuring consistency with the rest of
+the world. If this is not practical for you, use explicit field `id`s, which
+should always generate a merge conflict if two people try to allocate the same
+id.
+
+## Checking Conformity
+
+To check that schema are properly evolved, the [`flatc`](flatc.md) compiler has
+a [option](flatc.md#additional-options) to do just that:
+
+```sh
+--conform FILE
+``` 
+
+Where `FILE` is the base schema the rest of the input schemas must evolve from.
+It returns `0` if they are properly evolved, otherwise returns a non-zero value
+and provides errors on the reason why the schema are not properly evolved.
+
+As an example, the following checks if `schema_v2.fbs` is properly evolved from
+`schema_v1.fbs`.
+
+```sh
+flatc --conform schema_v1.fbs schema_v2.fbs
+```
+

docs/source/flatc.md

@@ -0,0 +1,303 @@
+# FlatBuffers Compiler (`flatc`)
+
+The main compiler for FlatBuffers is called `flatc` and is used to convert
+schema definitions into generated code files for a variety of languages. 
+
+After [building](building.md) `flatc`, it is used as follows:
+
+```sh
+flatc [ GENERATOR_OPTIONS ] [ -o PATH ] [- I PATH ] 
+  FILES... 
+  [ -- BINARY_FILES... ]
+```
+
+* The `GENERATOR_OPTIONS` specify the language(s) to compile code for as well as
+various features to enable/disable.
+
+* The `-o PATH` specifies the path where the generated files are placed. It
+defaults to the current path if not specified.
+
+* The `-I PATH` specifies the paths where included schema files are located. It
+  defaults to the current path if not specified.
+
+## Input Files
+
+`FILES...` specifies one or more schema or data files to process. They are
+processed in the order provided.
+
+### Schema Files
+
+For schema files, language specifiers indicate what languages to generate code
+for.
+
+  * `--cpp`: C++
+  * `--java`: Java
+  * `--kotlin`: Kotlin
+  * `--csharp`: C#
+  * `--go`: Golang
+  * `--python`: Python
+  * `--js`: JavaScript
+  * `--ts`: TypeScript
+  * `--php`: PHP
+  * `--dart`: Dart
+  * `--lua`: Lua
+  * `--lobster`: Lobster
+  * `--rust`: Rust
+  * `--swift`: Swift
+  * `--nim`: Nim
+
+Additionally, adding:
+
+  * `--grpc` Will generate RPC stub code for gRPC (not available in all
+    languages)
+
+### Data Files
+
+If `FILES...` contain data files, they can be exported to either a binary or
+JSON representation.
+
+* `--binary`, `-b`: Generate a binary file containing a serialized flatbuffer.
+* `--json`, `-j`: Generate JSON file from a serialized flatbuffer.
+
+Both options require the corresponding schema file to be included first in the
+list of `FILES...`.
+
+=== "To Binary"
+
+    To serialize the JSON data in `mydata.json` using the schema `myschema.fbs`:
+   
+    ```sh
+    flatc --binary myschema.fbs mydata.json
+    ```
+
+    This will generate a `mydata_wire.bin` file containing the serialized 
+    flatbuffer data.
+
+=== "To JSON"
+
+    To convert the serialized binary flatbuffer `mydata.bin` using the schema 
+    `myschema.fbs` to JSON:
+
+    ```sh
+    flatc --json myschema.fbs mydata.bin
+    ```
+
+    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.
+

docs/source/flexbuffers.md

@@ -0,0 +1,204 @@
+FlexBuffers    {#flexbuffers}
+==========
+
+FlatBuffers was designed around schemas, because when you want maximum
+performance and data consistency, strong typing is helpful.
+
+There are however times when you want to store data that doesn't fit a
+schema, because you can't know ahead of time what all needs to be stored.
+
+For this, FlatBuffers has a dedicated format, called FlexBuffers.
+This is a binary format that can be used in conjunction
+with FlatBuffers (by storing a part of a buffer in FlexBuffers
+format), or also as its own independent serialization format.
+
+While it loses the strong typing, you retain the most unique advantage
+FlatBuffers has over other serialization formats (schema-based or not):
+FlexBuffers can also be accessed without parsing / copying / object allocation.
+This is a huge win in efficiency / memory friendly-ness, and allows unique
+use cases such as mmap-ing large amounts of free-form data.
+
+FlexBuffers' design and implementation allows for a very compact encoding,
+combining automatic pooling of strings with automatic sizing of containers to
+their smallest possible representation (8/16/32/64 bits). Many values and
+offsets can be encoded in just 8 bits. While a schema-less representation is
+usually more bulky because of the need to be self-descriptive, FlexBuffers
+generates smaller binaries for many cases than regular FlatBuffers.
+
+FlexBuffers is still slower than regular FlatBuffers though, so we recommend to
+only use it if you need it.
+
+
+# Usage in C++
+
+Include the header `flexbuffers.h`, which in turn depends on `flatbuffers.h`
+and `util.h`.
+
+To create a buffer:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+flexbuffers::Builder fbb;
+fbb.Int(13);
+fbb.Finish();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You create any value, followed by `Finish`. Unlike FlatBuffers which requires
+the root value to be a table, here any value can be the root, including a lonely
+int value.
+
+You can now access the `std::vector<uint8_t>` that contains the encoded value
+as `fbb.GetBuffer()`. Write it, send it, or store it in a parent FlatBuffer. In
+this case, the buffer is just 3 bytes in size.
+
+To read this value back, you could just say:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+auto root = flexbuffers::GetRoot(my_buffer);
+int64_t i = root.AsInt64();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+FlexBuffers stores ints only as big as needed, so it doesn't differentiate
+between different sizes of ints. You can ask for the 64 bit version,
+regardless of what you put in. In fact, since you demand to read the root
+as an int, if you supply a buffer that actually contains a float, or a
+string with numbers in it, it will convert it for you on the fly as well,
+or return 0 if it can't. If instead you actually want to know what is inside
+the buffer before you access it, you can call `root.GetType()` or `root.IsInt()`
+etc.
+
+Here's a slightly more complex value you could write instead of `fbb.Int` above:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+fbb.Map([&]() {
+  fbb.Vector("vec", [&]() {
+    fbb.Int(-100);
+    fbb.String("Fred");
+    fbb.IndirectFloat(4.0f);
+  });
+  fbb.UInt("foo", 100);
+});
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This stores the equivalent of the JSON value
+`{ vec: [ -100, "Fred", 4.0 ], foo: 100 }`. The root is a dictionary that has
+just two key-value pairs, with keys `vec` and `foo`. Unlike FlatBuffers, it
+actually has to store these keys in the buffer (which it does only once if
+you store multiple such objects, by pooling key values), but also unlike
+FlatBuffers it has no restriction on the keys (fields) that you use.
+
+The map constructor uses a C++11 Lambda to group its children, but you can
+also use more conventional start/end calls if you prefer.
+
+The first value in the map is a vector. You'll notice that unlike FlatBuffers,
+you can use mixed types. There is also a `TypedVector` variant that only
+allows a single type, and uses a bit less memory.
+
+`IndirectFloat` is an interesting feature that allows you to store values
+by offset rather than inline. Though that doesn't make any visible change
+to the user, the consequence is that large values (especially doubles or
+64 bit ints) that occur more than once can be shared (see ReuseValue).
+Another use case is inside of vectors, where the largest element makes
+up the size of all elements (e.g. a single double forces all elements to
+64bit), so storing a lot of small integers together with a double is more efficient if the double is indirect.
+
+Accessing it:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+auto map = flexbuffers::GetRoot(my_buffer).AsMap();
+map.size();  // 2
+auto vec = map["vec"].AsVector();
+vec.size();  // 3
+vec[0].AsInt64();  // -100;
+vec[1].AsString().c_str();  // "Fred";
+vec[1].AsInt64();  // 0 (Number parsing failed).
+vec[2].AsDouble();  // 4.0
+vec[2].AsString().IsTheEmptyString();  // true (Wrong Type).
+vec[2].AsString().c_str();  // "" (This still works though).
+vec[2].ToString().c_str();  // "4" (Or have it converted).
+map["foo"].AsUInt8();  // 100
+map["unknown"].IsNull();  // true
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+# Usage in Java
+
+Java implementation follows the C++ one, closely.
+
+For creating the equivalent of the same JSON `{ vec: [ -100, "Fred", 4.0 ], foo: 100 }`,
+one could use the following code:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java}
+FlexBuffersBuilder builder = new FlexBuffersBuilder(ByteBuffer.allocate(512),
+		                                                FlexBuffersBuilder.BUILDER_FLAG_SHARE_KEYS_AND_STRINGS);
+int smap = builder.startMap();
+int svec = builder.startVector();
+builder.putInt(-100);
+builder.putString("Fred");
+builder.putFloat(4.0);
+builder.endVector("vec", svec, false, false);
+builder.putInt("foo", 100);
+builder.endMap(null, smap);
+ByteBuffer bb = builder.finish();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Similarly, to read the data, just:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java}
+FlexBuffers.Map map = FlexBuffers.getRoot(bb).asMap();
+map.size();  // 2
+FlexBuffers.Vector vec = map.get("vec").asVector();
+vec.size();  // 3
+vec.get(0).asLong();  // -100;
+vec.get(1).asString();  // "Fred";
+vec.get(1).asLong();  // 0 (Number parsing failed).
+vec.get(2).asFloat();  // 4.0
+vec.get(2).asString().isEmpty();  // true (Wrong Type).
+vec.get(2).asString();  // "" (This still works though).
+vec.get(2).toString();  // "4.0" (Or have it converted).
+map.get("foo").asUInt();  // 100
+map.get("unknown").isNull();  // true
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+# Binary encoding
+
+A description of how FlexBuffers are encoded is in the
+[internals](internals.md) document.
+
+
+# Nesting inside a FlatBuffer
+
+You can mark a field as containing a FlexBuffer, e.g.
+
+    a:[ubyte] (flexbuffer);
+
+A special accessor will be generated that allows you to access the root value
+directly, e.g. `a_flexbuffer_root().AsInt64()`.
+
+
+# Efficiency tips
+
+* Vectors generally are a lot more efficient than maps, so prefer them over maps
+  when possible for small objects. Instead of a map with keys `x`, `y` and `z`,
+  use a vector. Better yet, use a typed vector. Or even better, use a fixed
+  size typed vector.
+* Maps are backwards compatible with vectors, and can be iterated as such.
+  You can iterate either just the values (`map.Values()`), or in parallel with
+  the keys vector (`map.Keys()`). If you intend
+  to access most or all elements, this is faster than looking up each element
+  by key, since that involves a binary search of the key vector.
+* When possible, don't mix values that require a big bit width (such as double)
+  in a large vector of smaller values, since all elements will take on this
+  width. Use `IndirectDouble` when this is a possibility. Note that
+  integers automatically use the smallest width possible, i.e. if you ask
+  to serialize an int64_t whose value is actually small, you will use less
+  bits. Doubles are represented as floats whenever possible losslessly, but
+  this is only possible for few values.
+  Since nested vectors/maps are stored over offsets, they typically don't
+  affect the vector width.
+* To store large arrays of byte data, use a blob. If you'd use a typed
+  vector, the bit width of the size field may make it use more space than
+  expected, and may not be compatible with `memcpy`.
+  Similarly, large arrays of (u)int16_t may be better off stored as a
+  binary blob if their size could exceed 64k elements.
+  Construction and use are otherwise similar to strings.

docs/source/grammar.md

@@ -0,0 +1,73 @@
+## EBNF
+
+```ebnf
+schema = include* ( namespace_decl | type_decl | enum_decl | root_decl |
+           file_extension_decl | file_identifier_decl |
+           attribute_decl | rpc_decl | object )*
+
+include = `include` string_constant `;`
+
+namespace_decl = `namespace` ident ( `.` ident )* `;`
+
+attribute_decl = `attribute` ident | `"` ident `"` `;`
+
+type_decl = ( `table` | `struct` ) ident metadata `{` field_decl+ `}`
+
+enum_decl = ( `enum` ident `:` type | `union` ident )  metadata `{`
+commasep( enumval_decl ) `}`
+
+root_decl = `root_type` ident `;`
+
+field_decl = ident `:` type [ `=` scalar ] metadata `;`
+
+rpc_decl = `rpc_service` ident `{` rpc_method+ `}`
+
+rpc_method = ident `(` ident `)` `:` ident metadata `;`
+
+type = `bool` | `byte` | `ubyte` | `short` | `ushort` | `int` | `uint` |
+       `float` | `long` | `ulong` | `double` | `int8` | `uint8` | `int16` |
+       `uint16` | `int32` | `uint32`| `int64` | `uint64` | `float32` |
+       `float64` | `string` | `[` type `]` | ident
+
+enumval_decl = ident [ `=` integer_constant ] metadata
+
+metadata = [ `(` commasep( ident [ `:` single_value ] ) `)` ]
+
+scalar = boolean_constant | integer_constant | float_constant
+
+object = `{` commasep( ident `:` value ) `}`
+
+single_value = scalar | string_constant
+
+value = single_value | object | `[` commasep( value ) `]`
+
+commasep(x) = [ x ( `,` x )\* ]
+
+file_extension_decl = `file_extension` string_constant `;`
+
+file_identifier_decl = `file_identifier` string_constant `;`
+
+string_constant = `\".*?\"`
+
+ident = `[a-zA-Z_][a-zA-Z0-9_]*`
+
+`[:digit:]` = `[0-9]`
+
+`[:xdigit:]` = `[0-9a-fA-F]`
+
+dec_integer_constant = `[-+]?[:digit:]+`
+
+hex_integer_constant = `[-+]?0[xX][:xdigit:]+`
+
+integer_constant = dec_integer_constant | hex_integer_constant
+
+dec_float_constant = `[-+]?(([.][:digit:]+)|([:digit:]+[.][:digit:]*)|([:digit:]+))([eE][-+]?[:digit:]+)?`
+
+hex_float_constant = `[-+]?0[xX](([.][:xdigit:]+)|([:xdigit:]+[.][:xdigit:]*)|([:xdigit:]+))([pP][-+]?[:digit:]+)`
+
+special_float_constant = `[-+]?(nan|inf|infinity)`
+
+float_constant = dec_float_constant | hex_float_constant | special_float_constant
+
+boolean_constant = `true` | `false`
+```

docs/source/index.md

@@ -0,0 +1,59 @@
+# Overview
+
+FlatBuffers is an efficient cross platform serialization library for C++, C#, C,
+Go, Java, Kotlin, JavaScript, Lobster, Lua, TypeScript, PHP, Python, Rust and
+Swift. It was originally created at Google for game development and other
+performance-critical applications.
+
+It is available as Open Source on
+[GitHub](https://github.com/google/flatbuffers) under the Apache license v2.0.
+
+## Why Use FlatBuffers?
+
+<div class="grid cards" markdown>
+
+- :material-clock-fast:{ .lg .middle } **Access to serialized data without
+  parsing/unpacking**
+
+    ---
+    Access the data directly without unpacking or parsing.
+
+- :material-memory:{ .lg .middle } **Memory Efficiency and Speed**
+
+    ---
+    The only memory needed to access your data is that of the buffer. No heap is
+  required.
+
+- :material-compare-horizontal:{ .lg .middle } **Backwards and Forwards
+  Compatibility**
+
+    ---
+    The only memory needed to access your data is that of the buffer. No heap is
+  required.
+
+- :material-scale-off:{ .lg .middle } **Small Footprint**
+
+    ---
+    Minimal dependencies and small code footprint.
+
+</div>
+
+## Why not use...
+
+=== "Protocol Buffers"
+
+    Protocol Buffers is indeed relatively similar to FlatBuffers, with the primary
+    difference being that FlatBuffers does not need a parsing/unpacking step to a
+    secondary representation before you can access data, often coupled with
+    per-object memory allocation. The code is an order of magnitude bigger, too.
+
+=== "JSON"
+
+    JSON is very readable (which is why we use it as our optional text format) and
+    very convenient when used together with dynamically typed languages (such as
+    JavaScript). When serializing data from statically typed languages, however,
+    JSON not only has the obvious drawback of runtime inefficiency, but also forces
+    you to write more code to access data (counterintuitively) due to its
+    dynamic-typing serialization system. In this context, it is only a better choice
+    for systems that have very little to no information ahead of time about what
+    data needs to be stored.

docs/source/intermediate_representation.md

@@ -0,0 +1,35 @@
+# Flatbuffers Intermediate Representation {#intermediate_representation}
+
+We use [reflection.fbs](https://github.com/google/flatbuffers/blob/master/reflection/reflection.fbs)
+as our intermediate representation. `flatc` parses `.fbs` files, checks them for
+errors and stores the resulting data in this IR, outputting `.bfbs` files.
+Since this IR is a Flatbuffer, you can load and use it at runtime for runtime
+reflection purposes.
+
+There are some quirks: 
+- Tables and Structs are serialized as `Object`s.
+- Unions and Enums are serialized as `Enum`s.
+- It is the responsibility of the code generator to check the `advanced_features`
+  field of `Schema`. These mark the presence of new, backwards incompatible,
+  schema features. Code generators must error if generating a schema with
+  unrecognized advanced features.
+- Filenames are relative to a "project root" denoted by "//" in the path. This
+  may be specified in flatc with `--bfbs-filenames=$PROJECT_ROOT`, or it will be
+  inferred to be the directory containing the first provided schema file.
+
+
+## Invocation 
+You can invoke it like so
+```{.sh}
+flatc -b --schema ${your_fbs_files}
+```
+This generates `.bfbs` (binary flatbuffer schema) files.
+
+Some information is not included by default. See the `--bfbs-filenames` and
+`--bfbs-comments` flags. These may be necessary for code-generators, so they can
+add documentation and maybe name generated files (depending on the generator).
+
+
+TODO(cneo): Flags to output bfbs as flexbuffers or json.
+
+TODO(cneo): Tutorial for building a flatc plugin.

docs/source/internals.md

@@ -0,0 +1,466 @@
+FlatBuffer Internals    {#flatbuffers_internals}
+====================
+
+This section is entirely optional for the use of FlatBuffers. In normal
+usage, you should never need the information contained herein. If you're
+interested however, it should give you more of an appreciation of why
+FlatBuffers is both efficient and convenient.
+
+### Format components
+
+A FlatBuffer is a binary file and in-memory format consisting mostly of
+scalars of various sizes, all aligned to their own size. Each scalar is
+also always represented in little-endian format, as this corresponds to
+all commonly used CPUs today. FlatBuffers will also work on big-endian
+machines, but will be slightly slower because of additional
+byte-swap intrinsics.
+
+It is assumed that the following conditions are met, to ensure
+cross-platform interoperability:
+- The binary `IEEE-754` format is used for floating-point numbers.
+- The `two's complemented` representation is used for signed integers.
+- The endianness is the same for floating-point numbers as for integers.
+
+On purpose, the format leaves a lot of details about where exactly
+things live in memory undefined, e.g. fields in a table can have any
+order, and objects to some extent can be stored in many orders. This is
+because the format doesn't need this information to be efficient, and it
+leaves room for optimization and extension (for example, fields can be
+packed in a way that is most compact). Instead, the format is defined in
+terms of offsets and adjacency only. This may mean two different
+implementations may produce different binaries given the same input
+values, and this is perfectly valid.
+
+### Format identification
+
+The format also doesn't contain information for format identification
+and versioning, which is also by design. FlatBuffers is a statically typed
+system, meaning the user of a buffer needs to know what kind of buffer
+it is. FlatBuffers can of course be wrapped inside other containers
+where needed, or you can use its union feature to dynamically identify
+multiple possible sub-objects stored. Additionally, it can be used
+together with the schema parser if full reflective capabilities are
+desired.
+
+Versioning is something that is intrinsically part of the format (the
+optionality / extensibility of fields), so the format itself does not
+need a version number (it's a meta-format, in a sense). We're hoping
+that this format can accommodate all data needed. If format breaking
+changes are ever necessary, it would become a new kind of format rather
+than just a variation.
+
+### Offsets
+
+The most important and generic offset type (see `flatbuffers.h`) is
+`uoffset_t`, which is currently always a `uint32_t`, and is used to
+refer to all tables/unions/strings/vectors (these are never stored
+in-line). 32bit is
+intentional, since we want to keep the format binary compatible between
+32 and 64bit systems, and a 64bit offset would bloat the size for almost
+all uses. A version of this format with 64bit (or 16bit) offsets is easy to set
+when needed. Unsigned means they can only point in one direction, which
+typically is forward (towards a higher memory location). Any backwards
+offsets will be explicitly marked as such.
+
+The format starts with an `uoffset_t` to the root table in the buffer.
+
+We have two kinds of objects, structs and tables.
+
+### Structs
+
+These are the simplest, and as mentioned, intended for simple data that
+benefits from being extra efficient and doesn't need versioning /
+extensibility. They are always stored inline in their parent (a struct,
+table, or vector) for maximum compactness. Structs define a consistent
+memory layout where all components are aligned to their size, and
+structs aligned to their largest scalar member. This is done independent
+of the alignment rules of the underlying compiler to guarantee a cross
+platform compatible layout. This layout is then enforced in the generated
+code.
+
+### Tables
+
+Unlike structs, these are not stored in inline in their parent, but are
+referred to by offset.
+
+They start with an `soffset_t` to a vtable. This is a signed version of
+`uoffset_t`, since vtables may be stored anywhere relative to the object.
+This offset is subtracted (not added) from the object start to arrive at
+the vtable start. This offset is followed by all the
+fields as aligned scalars (or offsets). Unlike structs, not all fields
+need to be present. There is no set order and layout. A table may contain
+field offsets that point to the same value if the user explicitly
+serializes the same offset twice.
+
+To be able to access fields regardless of these uncertainties, we go
+through a vtable of offsets. Vtables are shared between any objects that
+happen to have the same vtable values.
+
+The elements of a vtable are all of type `voffset_t`, which is
+a `uint16_t`. The first element is the size of the vtable in bytes,
+including the size element. The second one is the size of the object, in bytes
+(including the vtable offset). This size could be used for streaming, to know
+how many bytes to read to be able to access all *inline* fields of the object.
+The remaining elements are the N offsets, where N is the amount of fields
+declared in the schema when the code that constructed this buffer was
+compiled (thus, the size of the table is N + 2).
+
+All accessor functions in the generated code for tables contain the
+offset into this table as a constant. This offset is checked against the
+first field (the number of elements), to protect against newer code
+reading older data. If this offset is out of range, or the vtable entry
+is 0, that means the field is not present in this object, and the
+default value is return. Otherwise, the entry is used as offset to the
+field to be read.
+
+### Unions
+
+Unions are encoded as the combination of two fields: an enum representing the
+union choice and the offset to the actual element. FlatBuffers reserves the
+enumeration constant `NONE` (encoded as 0) to mean that the union field is not
+set.
+
+### Strings and Vectors
+
+Strings are simply a vector of bytes, and are always
+null-terminated. Vectors are stored as contiguous aligned scalar
+elements prefixed by a 32bit element count (not including any
+null termination). Neither is stored inline in their parent, but are referred to
+by offset. A vector may consist of more than one offset pointing to the same
+value if the user explicitly serializes the same offset twice.
+
+### Construction
+
+The current implementation constructs these buffers backwards (starting
+at the highest memory address of the buffer), since
+that significantly reduces the amount of bookkeeping and simplifies the
+construction API.
+
+### Code example
+
+Here's an example of the code that gets generated for the `samples/monster.fbs`.
+What follows is the entire file, broken up by comments:
+
+    // automatically generated, do not modify
+
+    #include "flatbuffers/flatbuffers.h"
+
+    namespace MyGame {
+    namespace Sample {
+
+Nested namespace support.
+
+    enum {
+      Color_Red = 0,
+      Color_Green = 1,
+      Color_Blue = 2,
+    };
+
+    inline const char **EnumNamesColor() {
+      static const char *names[] = { "Red", "Green", "Blue", nullptr };
+      return names;
+    }
+
+    inline const char *EnumNameColor(int e) { return EnumNamesColor()[e]; }
+
+Enums and convenient reverse lookup.
+
+    enum {
+      Any_NONE = 0,
+      Any_Monster = 1,
+    };
+
+    inline const char **EnumNamesAny() {
+      static const char *names[] = { "NONE", "Monster", nullptr };
+      return names;
+    }
+
+    inline const char *EnumNameAny(int e) { return EnumNamesAny()[e]; }
+
+Unions share a lot with enums.
+
+    struct Vec3;
+    struct Monster;
+
+Predeclare all data types since circular references between types are allowed
+(circular references between object are not, though).
+
+    FLATBUFFERS_MANUALLY_ALIGNED_STRUCT(4) Vec3 {
+     private:
+      float x_;
+      float y_;
+      float z_;
+
+     public:
+      Vec3(float x, float y, float z)
+        : x_(flatbuffers::EndianScalar(x)), y_(flatbuffers::EndianScalar(y)), z_(flatbuffers::EndianScalar(z)) {}
+
+      float x() const { return flatbuffers::EndianScalar(x_); }
+      float y() const { return flatbuffers::EndianScalar(y_); }
+      float z() const { return flatbuffers::EndianScalar(z_); }
+    };
+    FLATBUFFERS_STRUCT_END(Vec3, 12);
+
+These ugly macros do a couple of things: they turn off any padding the compiler
+might normally do, since we add padding manually (though none in this example),
+and they enforce alignment chosen by FlatBuffers. This ensures the layout of
+this struct will look the same regardless of compiler and platform. Note that
+the fields are private: this is because these store little endian scalars
+regardless of platform (since this is part of the serialized data).
+`EndianScalar` then converts back and forth, which is a no-op on all current
+mobile and desktop platforms, and a single machine instruction on the few
+remaining big endian platforms.
+
+    struct Monster : private flatbuffers::Table {
+      const Vec3 *pos() const { return GetStruct<const Vec3 *>(4); }
+      int16_t mana() const { return GetField<int16_t>(6, 150); }
+      int16_t hp() const { return GetField<int16_t>(8, 100); }
+      const flatbuffers::String *name() const { return GetPointer<const flatbuffers::String *>(10); }
+      const flatbuffers::Vector<uint8_t> *inventory() const { return GetPointer<const flatbuffers::Vector<uint8_t> *>(14); }
+      int8_t color() const { return GetField<int8_t>(16, 2); }
+    };
+
+Tables are a bit more complicated. A table accessor struct is used to point at
+the serialized data for a table, which always starts with an offset to its
+vtable. It derives from `Table`, which contains the `GetField` helper functions.
+GetField takes a vtable offset, and a default value. It will look in the vtable
+at that offset. If the offset is out of bounds (data from an older version) or
+the vtable entry is 0, the field is not present and the default is returned.
+Otherwise, it uses the entry as an offset into the table to locate the field.
+
+    struct MonsterBuilder {
+      flatbuffers::FlatBufferBuilder &fbb_;
+      flatbuffers::uoffset_t start_;
+      void add_pos(const Vec3 *pos) { fbb_.AddStruct(4, pos); }
+      void add_mana(int16_t mana) { fbb_.AddElement<int16_t>(6, mana, 150); }
+      void add_hp(int16_t hp) { fbb_.AddElement<int16_t>(8, hp, 100); }
+      void add_name(flatbuffers::Offset<flatbuffers::String> name) { fbb_.AddOffset(10, name); }
+      void add_inventory(flatbuffers::Offset<flatbuffers::Vector<uint8_t>> inventory) { fbb_.AddOffset(14, inventory); }
+      void add_color(int8_t color) { fbb_.AddElement<int8_t>(16, color, 2); }
+      MonsterBuilder(flatbuffers::FlatBufferBuilder &_fbb) : fbb_(_fbb) { start_ = fbb_.StartTable(); }
+      flatbuffers::Offset<Monster> Finish() { return flatbuffers::Offset<Monster>(fbb_.EndTable(start_, 7)); }
+    };
+
+`MonsterBuilder` is the base helper struct to construct a table using a
+`FlatBufferBuilder`. You can add the fields in any order, and the `Finish`
+call will ensure the correct vtable gets generated.
+
+    inline flatbuffers::Offset<Monster> CreateMonster(flatbuffers::FlatBufferBuilder &_fbb,
+                                                      const Vec3 *pos, int16_t mana,
+                                                      int16_t hp,
+                                                      flatbuffers::Offset<flatbuffers::String> name,
+                                                      flatbuffers::Offset<flatbuffers::Vector<uint8_t>> inventory,
+                                                      int8_t color) {
+      MonsterBuilder builder_(_fbb);
+      builder_.add_inventory(inventory);
+      builder_.add_name(name);
+      builder_.add_pos(pos);
+      builder_.add_hp(hp);
+      builder_.add_mana(mana);
+      builder_.add_color(color);
+      return builder_.Finish();
+    }
+
+`CreateMonster` is a convenience function that calls all functions in
+`MonsterBuilder` above for you. Note that if you pass values which are
+defaults as arguments, it will not actually construct that field, so
+you can probably use this function instead of the builder class in
+almost all cases.
+
+    inline const Monster *GetMonster(const void *buf) { return flatbuffers::GetRoot<Monster>(buf); }
+
+This function is only generated for the root table type, to be able to
+start traversing a FlatBuffer from a raw buffer pointer.
+
+    }; // namespace MyGame
+    }; // namespace Sample
+
+### Encoding example.
+
+Below is a sample encoding for the following JSON corresponding to the above
+schema:
+
+    { pos: { x: 1, y: 2, z: 3 }, name: "fred", hp: 50 }
+
+Resulting in this binary buffer:
+
+    // Start of the buffer:
+    uint32_t 20  // Offset to the root table.
+
+    // Start of the vtable. Not shared in this example, but could be:
+    uint16_t 16 // Size of table, starting from here.
+    uint16_t 22 // Size of object inline data.
+    uint16_t 4, 0, 20, 16, 0, 0  // Offsets to fields from start of (root) table, 0 for not present.
+
+    // Start of the root table:
+    int32_t 16     // Offset to vtable used (default negative direction)
+    float 1, 2, 3  // the Vec3 struct, inline.
+    uint32_t 8     // Offset to the name string.
+    int16_t 50     // hp field.
+    int16_t 0      // Padding for alignment.
+
+    // Start of name string:
+    uint32_t 4  // Length of string.
+    int8_t 'f', 'r', 'e', 'd', 0, 0, 0, 0  // Text + 0 termination + padding.
+
+Note that this not the only possible encoding, since the writer has some
+flexibility in which of the children of root object to write first (though in
+this case there's only one string), and what order to write the fields in.
+Different orders may also cause different alignments to happen.
+
+### Additional reading.
+
+The author of the C language implementation has made a similar
+[document](https://github.com/dvidelabs/flatcc/blob/master/doc/binary-format.md#flatbuffers-binary-format)
+that may further help clarify the format.
+
+# FlexBuffers
+
+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
+over offsets, all scalars are aligned to their own size, and
+all data is always stored in little endian format.
+
+One difference is that FlexBuffers are built front to back, so children are
+stored before parents, and the root of the data starts at the last byte.
+
+Another difference is that scalar data is stored with a variable number of bits
+(8/16/32/64). The current width is always determined by the *parent*, i.e. if
+the scalar sits in a vector, the vector determines the bit width for all
+elements at once. Selecting the minimum bit width for a particular vector is
+something the encoder does automatically and thus is typically of no concern
+to the user, though being aware of this feature (and not sticking a double in
+the same vector as a bunch of byte sized elements) is helpful for efficiency.
+
+Unlike FlatBuffers there is only one kind of offset, and that is an unsigned
+integer indicating the number of bytes in a negative direction from the address
+of itself (where the offset is stored).
+
+### Vectors
+
+The representation of the vector is at the core of how FlexBuffers works (since
+maps are really just a combination of 2 vectors), so it is worth starting there.
+
+As mentioned, a vector is governed by a single bit width (supplied by its
+parent). This includes the size field. For example, a vector that stores the
+integer values `1, 2, 3` is encoded as follows:
+
+    uint8_t 3, 1, 2, 3, 4, 4, 4
+
+The first `3` is the size field, and is placed before the vector (an offset
+from the parent to this vector points to the first element, not the size
+field, so the size field is effectively at index -1).
+Since this is an untyped vector `SL_VECTOR`, it is followed by 3 type
+bytes (one per element of the vector), which are always following the vector,
+and are always a uint8_t even if the vector is made up of bigger scalars.
+
+A vector may include more than one offset pointing to the same value if the
+user explicitly serializes the same offset twice.
+
+### Types
+
+A type byte is made up of 2 components (see flexbuffers.h for exact values):
+
+* 2 lower bits representing the bit-width of the child (8, 16, 32, 64).
+  This is only used if the child is accessed over an offset, such as a child
+  vector. It is ignored for inline types.
+* 6 bits representing the actual type (see flexbuffers.h).
+
+Thus, in this example `4` means 8 bit child (value 0, unused, since the value is
+in-line), type `SL_INT` (value 1).
+
+### Typed Vectors
+
+These are like the Vectors above, but omit the type bytes. The type is instead
+determined by the vector type supplied by the parent. Typed vectors are only
+available for a subset of types for which these savings can be significant,
+namely inline signed/unsigned integers (`TYPE_VECTOR_INT` / `TYPE_VECTOR_UINT`),
+floats (`TYPE_VECTOR_FLOAT`), and keys (`TYPE_VECTOR_KEY`, see below).
+
+Additionally, for scalars, there are fixed length vectors of sizes 2 / 3 / 4
+that don't store the size (`TYPE_VECTOR_INT2` etc.), for an additional savings
+in space when storing common vector or color data.
+
+### Scalars
+
+FlexBuffers supports integers (`TYPE_INT` and `TYPE_UINT`) and floats
+(`TYPE_FLOAT`), available in the bit-widths mentioned above. They can be stored
+both inline and over an offset (`TYPE_INDIRECT_*`).
+
+The offset version is useful to encode costly 64bit (or even 32bit) quantities
+into vectors / maps of smaller sizes, and to share / repeat a value multiple
+times.
+
+### Booleans and Nulls
+
+Booleans (`TYPE_BOOL`) and nulls (`TYPE_NULL`) are encoded as inlined unsigned integers.
+
+### Blobs, Strings and Keys.
+
+A blob (`TYPE_BLOB`) is encoded similar to a vector, with one difference: the
+elements are always `uint8_t`. The parent bit width only determines the width of
+the size field, allowing blobs to be large without the elements being large.
+
+Strings (`TYPE_STRING`) are similar to blobs, except they have an additional 0
+termination byte for convenience, and they MUST be UTF-8 encoded (since an
+accessor in a language that does not support pointers to UTF-8 data may have to
+convert them to a native string type).
+
+A "Key" (`TYPE_KEY`) is similar to a string, but doesn't store the size
+field. They're so named because they are used with maps, which don't care
+for the size, and can thus be even more compact. Unlike strings, keys cannot
+contain bytes of value 0 as part of their data (size can only be determined by
+`strlen`), so while you can use them outside the context of maps if you so
+desire, you're usually better off with strings.
+
+### Maps
+
+A map (`TYPE_MAP`) is like an (untyped) vector, but with 2 prefixes before the
+size field:
+
+| index | field                                                        |
+| ----: | :----------------------------------------------------------- |
+| -3    | An offset to the keys vector (may be shared between tables). |
+| -2    | Byte width of the keys vector.                               |
+| -1    | Size (from here on it is compatible with `TYPE_VECTOR`)      |
+| 0     | Elements.                                                    |
+| Size  | Types.                                                       |
+
+Since a map is otherwise the same as a vector, it can be iterated like
+a vector (which is probably faster than lookup by key).
+
+The keys vector is a typed vector of keys. Both the keys and corresponding
+values *have* to be stored in sorted order (as determined by `strcmp`), such
+that lookups can be made using binary search.
+
+The reason the key vector is a separate structure from the value vector is
+such that it can be shared between multiple value vectors, and also to
+allow it to be treated as its own individual vector in code.
+
+An example map { foo: 13, bar: 14 } would be encoded as:
+
+    0 : uint8_t 'b', 'a', 'r', 0
+    4 : uint8_t 'f', 'o', 'o', 0
+    8 : uint8_t 2      // key vector of size 2
+    // key vector offset points here
+    9 : uint8_t 9, 6   // offsets to bar_key and foo_key
+    11: uint8_t 2, 1   // offset to key vector, and its byte width
+    13: uint8_t 2      // value vector of size
+    // value vector offset points here
+    14: uint8_t 14, 13 // values
+    16: uint8_t 4, 4   // types
+
+### The root
+
+As mentioned, the root starts at the end of the buffer.
+The last uint8_t is the width in bytes of the root (normally the parent
+determines the width, but the root has no parent). The uint8_t before this is
+the type of the root, and the bytes before that are the root value (of the
+number of bytes specified by the last byte).
+
+So for example, the integer value `13` as root would be:
+
+    uint8_t 13, 4, 1    // Value, type, root byte width.
+

docs/source/languages/c.md

@@ -0,0 +1,224 @@
+Use in C    {#flatbuffers_guide_use_c}
+==========
+
+The C language binding exists in a separate project named [FlatCC](https://github.com/dvidelabs/flatcc).
+
+The `flatcc` C schema compiler can generate code offline as well as
+online via a C library. It can also generate buffer verifiers and fast
+JSON parsers, printers.
+
+Great care has been taken to ensure compatibility with the main `flatc`
+project.
+
+## General Documention
+
+- [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)
+- [The Monster Sample in C](https://github.com/dvidelabs/flatcc/blob/master/samples/monster/monster.c)
+- [GitHub](https://github.com/dvidelabs/flatcc)
+
+
+## Supported Platforms
+
+- Ubuntu (clang / gcc, ninja / gnu make)
+- OS-X (clang / gcc, ninja / gnu make)
+- Windows MSVC 2010, 2013, 2015
+
+CI builds recent versions of gcc, clang and MSVC on OS-X, Ubuntu, and
+Windows, and occasionally older compiler versions. See main project [Status](https://github.com/dvidelabs/flatcc#status).
+
+Other platforms may well work, including Centos, but are not tested
+regularly.
+
+The monster sample project was specifically written for C99 in order to
+follow the C++ version and for that reason it will not work with MSVC
+2010.
+
+## Modular Object Creation
+
+In the tutorial we used the call `Monster_create_as_root` to create the
+root buffer object since this is easier in simple use cases. Sometimes
+we need more modularity so we can reuse a function to create nested
+tables and root tables the same way. For this we need the
+`flatcc_builder_buffer_create_call`. It is best to keep `flatcc_builder`
+calls isolated at the top driver level, so we get:
+
+<div class="language-c">
+~~~{.c}
+  ns(Monster_ref_t) create_orc(flatcc_builder_t *B)
+  {
+    // ... same as in the tutorial.
+    return s(Monster_create(B, ...));
+  }
+
+  void create_monster_buffer()
+  {
+      uint8_t *buf;
+      size_t size;
+      flatcc_builder_t builder, *B;
+
+      // Initialize the builder object.
+      B = &builder;
+      flatcc_builder_init(B);
+      // Only use `buffer_create` without `create/start/end_as_root`.
+      flatcc_builder_buffer_create(create_orc(B));
+      // Allocate and copy buffer to user memory.
+      buf = flatcc_builder_finalize_buffer(B, &size);
+      // ... write the buffer to disk or network, or something.
+
+      free(buf);
+      flatcc_builder_clear(B);
+  }
+~~~
+</div>
+
+The same principle applies with `start/end` vs `start/end_as_root` in
+the top-down approach.
+
+
+## Top Down Example
+
+The tutorial uses a bottom up approach. In C it is also possible to use
+a top-down approach by starting and ending objects nested within each
+other. In the tutorial there is no deep nesting, so the difference is
+limited, but it shows the idea:
+
+<div class="language-c">
+<br>
+~~~{.c}
+  uint8_t treasure[] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
+  size_t treasure_count = c_vec_len(treasure);
+  ns(Weapon_ref_t) axe;
+
+  // NOTE: if we use end_as_root, we MUST also start as root.
+  ns(Monster_start_as_root(B));
+  ns(Monster_pos_create(B, 1.0f, 2.0f, 3.0f));
+  ns(Monster_hp_add(B, 300));
+  ns(Monster_mana_add(B, 150));
+  // We use create_str instead of add because we have no existing string reference.
+  ns(Monster_name_create_str(B, "Orc"));
+  // Again we use create because we no existing vector object, only a C-array.
+  ns(Monster_inventory_create(B, treasure, treasure_count));
+  ns(Monster_color_add(B, ns(Color_Red)));
+  if (1) {
+      ns(Monster_weapons_start(B));
+      ns(Monster_weapons_push_create(B, flatbuffers_string_create_str(B, "Sword"), 3));
+      // We reuse the axe object later. Note that we dereference a pointer
+      // because push always returns a short-term pointer to the stored element.
+      // We could also have created the axe object first and simply pushed it.
+      axe = *ns(Monster_weapons_push_create(B, flatbuffers_string_create_str(B, "Axe"), 5));
+      ns(Monster_weapons_end(B));
+  } else {
+      // We can have more control with the table elements added to a vector:
+      //
+      ns(Monster_weapons_start(B));
+      ns(Monster_weapons_push_start(B));
+      ns(Weapon_name_create_str(B, "Sword"));
+      ns(Weapon_damage_add(B, 3));
+      ns(Monster_weapons_push_end(B));
+      ns(Monster_weapons_push_start(B));
+      ns(Monster_weapons_push_start(B));
+      ns(Weapon_name_create_str(B, "Axe"));
+      ns(Weapon_damage_add(B, 5));
+      axe = *ns(Monster_weapons_push_end(B));
+      ns(Monster_weapons_end(B));
+  }
+  // Unions can get their type by using a type-specific add/create/start method.
+  ns(Monster_equipped_Weapon_add(B, axe));
+
+  ns(Monster_end_as_root(B));
+~~~
+</div>
+
+
+## Basic Reflection
+
+The C-API does support reading binary schema (.bfbs)
+files via code generated from the `reflection.fbs` schema, and an
+[example usage](https://github.com/dvidelabs/flatcc/tree/master/samples/reflection)
+shows how to use this. The reflection schema files are pre-generated
+in the [runtime distribution](https://github.com/dvidelabs/flatcc/tree/master/include/flatcc/reflection).
+
+
+## Mutations and Reflection
+
+The C-API does not support mutating reflection like C++ does, nor does
+the reader interface support mutating scalars (and it is generally
+unsafe to do so even after verification).
+
+The generated reader interface supports sorting vectors in-place after
+casting them to a mutating type because it is not practical to do so
+while building a buffer. This is covered in the builder documentation.  
+The reflection example makes use of this feature to look up objects by
+name.
+
+It is possible to build new buffers using complex objects from existing
+buffers as source. This can be very efficient due to direct copy
+semantics without endian conversion or temporary stack allocation.
+
+Scalars, structs and strings can be used as source, as well vectors of
+these.
+
+It is currently not possible to use an existing table or vector of table
+as source, but it would be possible to add support for this at some
+point.
+
+
+## Namespaces
+
+The `FLATBUFFERS_WRAP_NAMESPACE` approach used in the tutorial is convenient
+when each function has a very long namespace prefix. But it isn't always
+the best approach. If the namespace is absent, or simple and
+informative, we might as well use the prefix directly. The
+[reflection example](https://github.com/dvidelabs/flatcc/blob/master/samples/reflection/bfbs2json.c)
+mentioned above uses this approach.
+
+
+## Checking for Present Members
+
+Not all languages support testing if a field is present, but in C we can
+elaborate the reader section of the tutorial with tests for this. Recall
+that `mana` was set to the default value `150` and therefore shouldn't
+be present.
+
+<div class="language-c">
+~~~{.c}
+  int hp_present = ns(Monster_hp_is_present(monster)); // 1
+  int mana_present = ns(Monster_mana_is_present(monster)); // 0
+~~~
+</div>
+
+## Alternative ways to add a Union
+
+In the tutorial we used a single call to add a union.  Here we show
+different ways to accomplish the same thing. The last form is rarely
+used, but is the low-level way to do it. It can be used to group small
+values together in the table by adding type and data at different
+points in time.
+
+<div class="language-c">
+~~~{.c}
+   ns(Equipment_union_ref_t) equipped = ns(Equipment_as_Weapon(axe));
+   ns(Monster_equipped_add(B, equipped));
+   // or alternatively
+   ns(Monster_equipped_Weapon_add(B, axe);
+   // or alternatively
+   ns(Monster_equipped_add_type(B, ns(Equipment_Weapon));
+   ns(Monster_equipped_add_member(B, axe));
+~~~
+</div>
+
+## Why not integrate with the `flatc` tool?
+
+[It was considered how the C code generator could be integrated into the
+`flatc` tool](https://github.com/dvidelabs/flatcc/issues/1), but it
+would either require that the standalone C implementation of the schema
+compiler was dropped, or it would lead to excessive code duplication, or
+a complicated intermediate representation would have to be invented.
+Neither of these alternatives are very attractive, and it isn't a big
+deal to use the `flatcc` tool instead of `flatc` given that the
+FlatBuffers C runtime library needs to be made available regardless.
+
+