flatcc

Ubuntu, macOS and Windows: Windows: Weekly:

The JSON parser may change the interface for parsing union vectors in a future release which requires code generation to match library versions.

FlatCC FlatBuffers in C for C

flatcc has no external dependencies except for build and compiler tools, and the C runtime library. With concurrent Ninja builds, a small client project can build flatcc with libraries, generate schema code, link the project and execute a test case in a few seconds, produce binaries between 15K and 60K, read small buffers in 30ns, build FlatBuffers in about 600ns, and with a larger executable also handle optional json parsing or printing in less than 2 us for a 10 field mixed type message.

• Online Forums
• Introduction
  • Integrating FlatCC
• Project Details
• Reporting Bugs
• Status
  • Main features supported as of 0.6.1
  • Supported platforms (CI tested)
  • Platforms reported to work by users
  • Portability
• Time / Space / Usability Tradeoff
• Generated Files
  • Use of Macros in Generated Code
  • Extracting Documentation
• Using flatcc
• Trouble Shooting
• Quickstart
  • Reading a Buffer
  • Compiling for Read-Only
  • Building a Buffer
  • Verifying a Buffer
  • Potential Name Conflicts
  • Debugging a Buffer
• File and Type Identifiers
  • File Identifiers
  • Type Identifiers
• JSON Parsing and Printing
  • Base64 Encoding
  • Parsing Fixed Length Arrays
  • Runtime Flags
  • Generic Parsing and Printing.
  • Performance Notes
• Global Scope and Included Schema
• Required Fields and Duplicate Fields
• Fast Buffers
• Types
• Unions
  • Union Scope Resolution
• Fixed Length Arrays
• Optional Fields
• Endianness
• Pitfalls in Error Handling
• Searching and Sorting
• Null Values
• Portability Layer
• Building
  • Unix Build (OS-X, Linux, related)
  • Windows Build (MSVC)
  • Docker
  • Cross-compilation
  • Custom Allocation
  • Custom Asserts
  • Shared Libraries
  • Strict Aliasing
• Distribution
  • Unix Files
  • Windows Files
• Running Tests on Unix
• Running Tests on Windows
• Configuration
• Using the Compiler and Builder library
• FlatBuffers Binary Format
• Security Considerations
• Style Guide
• Benchmarks

Online Forums

• Discord - FlatBuffers
• Github - FlatCC Discussions

Introduction

This project builds flatcc, a compiler that generates FlatBuffers code for C given a FlatBuffer schema file. This introduction also creates a separate test project with the traditional monster example, here in a C version.

For now assume a Unix like system although that is not a general requirement - see also Building. You will need git, cmake, bash, a C compiler, and either the ninja build system, or make.

git clone https://github.com/dvidelabs/flatcc.git
cd flatcc
# scripts/initbuild.sh ninja
scripts/initbuild.sh make
scripts/setup.sh -a ../mymonster
ls bin
ls lib
cd ../mymonster
ls src
scripts/build.sh
ls generated

scripts/initbuild.sh is optional and chooses the build backend, which defaults to ninja.

The setup script builds flatcc using CMake, then creates a test project directory with the monster example, and a build script which is just a small shell script. The headers and libraries are symbolically linked into the test project. You do not need CMake to build your own projects once flatcc is compiled.

To create another test project named foobar, call scripts/setup.sh -s -x ../foobar. This will avoid rebuilding the flatcc project from scratch.

Integrating FlatCC

To answer the question:

"How do I integrate FlatCC into my project with minimal dependencies"

You do not need CMake and you do not need a prebuilt runtime library.

You do need the flatcc tool to initially generate your own schema files and then you need to update your project to:

• Include the generated header files.
• Add include/flatcc (correct version) to the include path, e.g., using -I include if at flatcc root.
• Link with zero or more files from src/runtime/*.c (correct version).
• Possibly disable certain warnings (notably disable GCC pedantic).
• Potentially work around platform limitations, e.g., using -DPORTABLE_HAS_INCLUDE_STDALIGN=0 if stdalign.h should be, but isn't, available on your platform. See include/flatcc/portable/*.h for details.

You should be able to compile a test project with just a single line like:

cc -I include src/runtime/build.c myprogram.c

If you only read flatbuffer files, and do not build, verify, parse JSON, or print JSON, you will not need any runtime .c files.

If you have a system installed flatcc package, it might have the wrong version of header or library files. You need to somehow override that if you have generated files from a more recent version of flatcc.

That said, you can also use the main CMake project to build libraries, or just look at it to see which warnings and flags are important to your compiler.

See also Building.

Project Details

NOTE: see CHANGELOG. There are occasionally minor breaking changes as API inconsistencies are discovered. Unless clearly stated, breaking changes will not affect the compiled runtime library, only the header files. In case of trouble, make sure the flatcc tool is same version as the include/flatcc path.

The project includes:

• an executable flatcc FlatBuffers schema compiler for C and a corresponding library libflatcc.a. The compiler generates C header files or a binary flatbuffers schema.
• a typeless runtime library libflatccrt.a for building and verifying flatbuffers from C. Generated builder headers depend on this library. It may also be useful for other language interfaces. The library maintains a stack state to make it easy to build buffers from a parser or similar.
• a small flatcc/portable header only library for non-C11 compliant compilers, and small helpers for all compilers including endian handling and numeric printing and parsing.

See also:

• Reporting Bugs

• Google FlatBuffers

• Build Instructions

• Quickstart

• [Builder Interface Reference]

• [Benchmarks]

The flatcc compiler is implemented as a standalone tool instead of extending Googles flatc compiler in order to have a pure portable C library implementation of the schema compiler that is designed to fail graciously on abusive input in long running processes. It is also believed a C version may help provide schema parsing to other language interfaces that find interfacing with C easier than C++. The FlatBuffers team at Googles FPL lab has been very helpful in providing feedback and answering many questions to help ensure the best possible compatibility. Notice the name flatcc (FlatBuffers C Compiler) vs Googles flatc.

The JSON format is compatible with Googles flatc tool. The flatc tool converts JSON from the command line using a schema and a buffer as input. flatcc generates schema specific code to read and write JSON at runtime. While the flatcc approach is likely much faster and also easier to deploy, the flatc approach is likely more convenient when manually working with JSON such as editing game scenes. Both tools have their place.

NOTE: Big-endian platforms are only supported as of release 0.4.0.

Reporting Bugs

If possible, please provide a short reproducible schema and source file with a main program the returns 1 on error and 0 on success and a small build script. Preferably generate a hexdump and call the buffer verifier to ensure the input is valid and link with the debug library flatccrt_d.

See also Debugging a Buffer, and [readfile.h] useful for reading an existing buffer for verification.

Example:

samples/bugreport

eclectic.fbs :

namespace Eclectic;

enum Fruit : byte { Banana = -1, Orange = 42 }
table FooBar {
    meal      : Fruit = Banana;
    density   : long (deprecated);
    say       : string;
    height    : short;
}
file_identifier "NOOB";
root_type FooBar;

myissue.c :

…

build.sh :

#!/bin/sh
cd $(dirname $0)

FLATBUFFERS_DIR=../..
NAME=myissue
SCHEMA=eclectic.fbs
OUT=build

FLATCC_EXE=$FLATBUFFERS_DIR/bin/flatcc
FLATCC_INCLUDE=$FLATBUFFERS_DIR/include
FLATCC_LIB=$FLATBUFFERS_DIR/lib

mkdir -p $OUT
$FLATCC_EXE --outfile $OUT/${NAME}_generated.h -a $SCHEMA || exit 1
cc -I$FLATCC_INCLUDE -g -o $OUT/$NAME $NAME.c -L$FLATCC_LIB -lflatccrt_d || exit 1
echo "running $OUT/$NAME"
if $OUT/$NAME; then
    echo "success"
else
    echo "failed"
    exit 1
fi

Status

Release 0.6.4 fixes a few unlikely vulnerabilities (adversial schema in flatcc parser), a memory leak on builder reuse, and a failure to allow a retry after an allocation error in low memory. Some were reported as CVEs through apparent AI assisted issue reporting, despite low practical impact, hence this release.

Release 0.6.3 is a point release immediately following 0.6.2 because the master branch would report flatcc --version as 0.6.2 instead of 0.6.2-pre prior to the 0.6.2 release and version comment in generated headers would do the same. By bumping to 0.6.3 ensures that 0.6.3 is indeeded a release version and not a development snapshot. 0.6.3 is unctionally equivalent to the 0.6.2 release.

Release 0.6.2 is primarily a bug fix release, please refer to CHANGELOG for details, this note only mentions a subset of these. A long standing bug has been fixed where where objects created before a call to _create_as_root would not be properly aligned, and buffer end is now also padded to largest object seen within the buffer. Note that for clang debug builds, -fsanitize=undefined has been added and this may require dependent source code to also use that flag to avoid missing linker symbols. The feature can be disabled in CMakeLists.txt. CMake has been bumped to version 3.16 which is the latest version where Appveyor will build MVSC 2025. A buffer overrun in flatcc parser on