1 Building {#flatbuffers_guide_building} 2 ======== 3 4 ## Building with CMake 5 6 The distribution comes with a `cmake` file that should allow 7 you 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 9 e.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 15 Then, build as normal for your platform. This should result in a `flatc` 16 executable, essential for the next steps. 17 Note that to use clang instead of gcc, you may need to set up your environment 18 variables, e.g. 19 `CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake -G "Unix Makefiles"`. 20 21 Optionally, run the `flattests` executable from the root `flatbuffers/` 22 directory to ensure everything is working correctly on your system. If this 23 fails, please contact us! 24 25 Building 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 30 run 'flattests' or `flatsampletext`, or it will fail to load its files.* 31 32 ## Building for Android 33 34 There is a `flatbuffers/android` directory that contains all you need to build 35 the 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 37 if tests succeeded or not. 38 39 You may also run an android sample from inside the `flatbuffers/samples`, by 40 running 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 46 For C++, there is usually no runtime to compile, as the code consists of a 47 single header, `include/flatbuffers/flatbuffers.h`. You should add the 48 `include` folder to your include paths. If you wish to be 49 able to load schemas and/or parse text into binary buffers at runtime, 50 you additionally need the other headers in `include/flatbuffers`. You must 51 also compile/link `src/idl_parser.cpp` (and `src/idl_gen_text.cpp` if you 52 also want to be able convert binary to text). 53 54 To see how to include FlatBuffers in any of our supported languages, please 55 view the [Tutorial](@ref flatbuffers_guide_tutorial) and select your appropriate 56 language using the radio buttons. 57 58 ### Using in CMake-based projects 59 If you want to use FlatBuffers in a project which already uses CMake, then a more 60 robust and flexible approach is to build FlatBuffers as part of that project directly. 61 This is done by making the FlatBuffers source code available to the main build 62 and adding it using CMake's `add_subdirectory()` command. This has the 63 significant advantage that the same compiler and linker settings are used 64 between FlatBuffers and the rest of your project, so issues associated with using 65 incompatible libraries (eg debug/release), etc. are avoided. This is 66 particularly useful on Windows. 67 68 Suppose you put FlatBuffers source code in directory `${FLATBUFFERS_SRC_DIR}`. 69 To 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. 72 add_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. 78 target_link_libraries(own_project_target PRIVATE flatbuffers) 79 ``` 80 When build your project the `flatbuffers` library will be compiled and linked 81 to a target as part of your project. 82 83 #### Override default depth limit of nested objects 84 To override [the depth limit of recursion](@ref flatbuffers_guide_use_cpp), 85 add this directive: 86 ```cmake 87 set(FLATBUFFERS_MAX_PARSING_DEPTH 16) 88 ``` 89 to `CMakeLists.txt` file before `add_subdirectory(${FLATBUFFERS_SRC_DIR})` line. 90 91 #### For Google Play apps 92 93 For applications on Google Play that integrate this library, usage is tracked. 94 This tracking is done automatically using the embedded version string 95 (flatbuffer_version_string), and helps us continue to optimize it. 96 Aside from consuming a few extra bytes in your application binary, it shouldn't 97 affect your application at all. We use this information to let us know if 98 FlatBuffers is useful and if we should continue to invest in it. Since this is 99 open source, you are free to remove the version string but we would appreciate 100 if you would leave it in. 101
