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