1Building {#flatbuffers_guide_building}
2========
3
4## Building with CMake
5
6The distribution comes with a `cmake` file that should allow
7you to build project/make files for any platform. For details on `cmake`, see
8<https://www.cmake.org>. In brief, depending on your platform, use one of
9e.g.:
10
11 cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release
12 cmake -G "Visual Studio 10" -DCMAKE_BUILD_TYPE=Release
13 cmake -G "Xcode" -DCMAKE_BUILD_TYPE=Release
14
15Then, build as normal for your platform. This should result in a `flatc`
16executable, essential for the next steps.
17Note that to use clang instead of gcc, you may need to set up your environment
18variables, e.g.
19`CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake -G "Unix Makefiles"`.
20
21Optionally, run the `flattests` executable from the root `flatbuffers/`
22directory to ensure everything is working correctly on your system. If this
23fails, please contact us!
24
25Building should also produce two sample executables, `flatsamplebinary` and
26`flatsampletext`, see the corresponding `.cpp` files in the
27`flatbuffers/samples` directory.
28
29*Note that you MUST be in the root of the FlatBuffers distribution when you
30run 'flattests' or `flatsampletext`, or it will fail to load its files.*
31
32### Make all warnings into errors
33
34By default all Flatbuffers `cmake` targets are **not** built with the `-Werror`
35(or `/WX` for MSVC) flag that treats any warning as an error. This allows more
36flexibility for users of Flatbuffers to use newer compilers and toolsets that
37may add new warnings that would cause a build failure.
38
39To enable a stricter build that does treat warnings as errors, set the
40`FLATBUFFERS_STRICT_MODE` `cmake` compliation flag to `ON`.
41
42```
43cmake . -DFLATBUFFERS_STRICT_MODE=ON
44```
45
46Our CI builds run with strict mode on, ensuring the code that is committed to
47the project is as portable and warning free as possible. Thus developers
48contributing to the project should enable strict mode locally before making a
49PR.
50
51## Building with VCPKG
52
53You can download and install flatbuffers using the [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager:
54
55 git clone https://github.com/Microsoft/vcpkg.git
56 cd vcpkg
57 ./bootstrap-vcpkg.sh
58 ./vcpkg integrate install
59 ./vcpkg install flatbuffers
60
61The flatbuffers port in vcpkg is kept up to date by Microsoft team members and community contributors.
62If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
63
64## Downloading binaries
65You can download the binaries from the
66[GitHub release page](https://github.com/google/flatbuffers/releases).
67
68We generate [SLSA3 signatures](slsa.dev) using the OpenSSF's [slsa-framework/slsa-github-generator](https://github.com/slsa-framework/slsa-github-generator). To verify the binaries:
691. Install the verification tool from [slsa-framework/slsa-verifier#installation](https://github.com/slsa-framework/slsa-verifier#installation)
701. Download the file named `attestation.intoto.jsonl` from the GitHub release
711. Run:
72```shell
73$ slsa-verifier -artifact-path <downloaded.zip> -provenance attestation.intoto.jsonl -source github.com/google/flatbuffers -tag <version>
74 PASSED: Verified SLSA provenance
75
76## Building for Android
77
78There is a `flatbuffers/android` directory that contains all you need to build
79the test executable on android (use the included `build_apk.sh` script, or use
80`ndk_build` / `adb` etc. as usual). Upon running, it will output to the log
81if tests succeeded or not.
82
83You may also run an android sample from inside the `flatbuffers/samples`, by
84running the `android_sample.sh` script. Optionally, you may go to the
85`flatbuffers/samples/android` folder and build the sample with the
86`build_apk.sh` script or `ndk_build` / `adb` etc.
87
88## Using FlatBuffers in your own projects
89
90For C++, there is usually no runtime to compile, as the code consists of a
91single header, `include/flatbuffers/flatbuffers.h`. You should add the
92`include` folder to your include paths. If you wish to be
93able to load schemas and/or parse text into binary buffers at runtime,
94you additionally need the other headers in `include/flatbuffers`. You must
95also compile/link `src/idl_parser.cpp` (and `src/idl_gen_text.cpp` if you
96also want to be able convert binary to text).
97
98To see how to include FlatBuffers in any of our supported languages, please
99view the [Tutorial](@ref flatbuffers_guide_tutorial) and select your appropriate
100language using the radio buttons.
101
102### Using in CMake-based projects
103If you want to use FlatBuffers in a project which already uses CMake, then a more
104robust and flexible approach is to build FlatBuffers as part of that project directly.
105This is done by making the FlatBuffers source code available to the main build
106and adding it using CMake's `add_subdirectory()` command. This has the
107significant advantage that the same compiler and linker settings are used
108between FlatBuffers and the rest of your project, so issues associated with using
109incompatible libraries (eg debug/release), etc. are avoided. This is
110particularly useful on Windows.
111
112Suppose you put FlatBuffers source code in directory `${FLATBUFFERS_SRC_DIR}`.
113To build it as part of your project, add following code to your `CMakeLists.txt` file:
114```cmake
115# Add FlatBuffers directly to our build. This defines the `flatbuffers` target.
116add_subdirectory(${FLATBUFFERS_SRC_DIR}
117 ${CMAKE_CURRENT_BINARY_DIR}/flatbuffers-build
118 EXCLUDE_FROM_ALL)
119
120# Now simply link against flatbuffers as needed to your already declared target.
121# The flatbuffers target carry header search path automatically if CMake > 2.8.11.
122target_link_libraries(own_project_target PRIVATE flatbuffers)
123```
124When build your project the `flatbuffers` library will be compiled and linked
125to a target as part of your project.
126
127#### Override default depth limit of nested objects
128To override [the depth limit of recursion](@ref flatbuffers_guide_use_cpp),
129add this directive:
130```cmake
131set(FLATBUFFERS_MAX_PARSING_DEPTH 16)
132```
133to `CMakeLists.txt` file before `add_subdirectory(${FLATBUFFERS_SRC_DIR})` line.
View as plain text