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## Building for Android
33
34There is a `flatbuffers/android` directory that contains all you need to build
35the test executable on android (use the included `build_apk.sh` script, or use
36`ndk_build` / `adb` etc. as usual). Upon running, it will output to the log
37if tests succeeded or not.
38
39You may also run an android sample from inside the `flatbuffers/samples`, by
40running the `android_sample.sh` script. Optionally, you may go to the
41`flatbuffers/samples/android` folder and build the sample with the
42`build_apk.sh` script or `ndk_build` / `adb` etc.
43
44## Using FlatBuffers in your own projects
45
46For C++, there is usually no runtime to compile, as the code consists of a
47single header, `include/flatbuffers/flatbuffers.h`. You should add the
48`include` folder to your include paths. If you wish to be
49able to load schemas and/or parse text into binary buffers at runtime,
50you additionally need the other headers in `include/flatbuffers`. You must
51also compile/link `src/idl_parser.cpp` (and `src/idl_gen_text.cpp` if you
52also want to be able convert binary to text).
53
54To see how to include FlatBuffers in any of our supported languages, please
55view the [Tutorial](@ref flatbuffers_guide_tutorial) and select your appropriate
56language using the radio buttons.
57
58### Using in CMake-based projects
59If you want to use FlatBuffers in a project which already uses CMake, then a more
60robust and flexible approach is to build FlatBuffers as part of that project directly.
61This is done by making the FlatBuffers source code available to the main build
62and adding it using CMake's `add_subdirectory()` command. This has the
63significant advantage that the same compiler and linker settings are used
64between FlatBuffers and the rest of your project, so issues associated with using
65incompatible libraries (eg debug/release), etc. are avoided. This is
66particularly useful on Windows.
67
68Suppose you put FlatBuffers source code in directory `${FLATBUFFERS_SRC_DIR}`.
69To build it as part of your project, add following code to your `CMakeLists.txt` file:
70```cmake
71# Add FlatBuffers directly to our build. This defines the `flatbuffers` target.
72add_subdirectory(${FLATBUFFERS_SRC_DIR}
73                 ${CMAKE_CURRENT_BINARY_DIR}/flatbuffers-build
74                 EXCLUDE_FROM_ALL)
75
76# Now simply link against flatbuffers as needed to your already declared target.
77# The flatbuffers target carry header search path automatically if CMake > 2.8.11.
78target_link_libraries(own_project_target PRIVATE flatbuffers)
79```
80When build your project the `flatbuffers` library will be compiled and linked
81to a target as part of your project.
82
83#### Override default depth limit of nested objects
84To override [the depth limit of recursion](@ref flatbuffers_guide_use_cpp),
85add this directive:
86```cmake
87set(FLATBUFFERS_MAX_PARSING_DEPTH 16)
88```
89to `CMakeLists.txt` file before `add_subdirectory(${FLATBUFFERS_SRC_DIR})` line.
90
91#### For Google Play apps
92
93For applications on Google Play that integrate this library, usage is tracked.
94This tracking is done automatically using the embedded version string
95(flatbuffer_version_string), and helps us continue to optimize it.
96Aside from consuming a few extra bytes in your application binary, it shouldn't
97affect your application at all. We use this information to let us know if
98FlatBuffers is useful and if we should continue to invest in it. Since this is
99open source, you are free to remove the version string but we would appreciate
100if you would leave it in.
101