blob: a6bc5be1406b3b1651c685999bced9616bdef9c0 [file] [log] [blame]
<!-- HTML header for doxygen 1.8.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<title>FlatBuffers: Building</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,700" rel="stylesheet">
<link href="style.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea" style="height: 110px;">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="commonprojectlogo">
<img alt="Logo" src="fpl_logo_small.png"/>
</td>
<td style="padding-left: 0.5em;">
<div id="projectname">FlatBuffers
</div>
<div style="font-size:12px;">
An open source project by <a href="https://developers.google.com/games/#Tools">FPL</a>.
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('flatbuffers_guide_building.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Building </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="md_Building"></a></p>
<h1><a class="anchor" id="autotoc_md7"></a>
Building with CMake</h1>
<p>The distribution comes with a <code>cmake</code> file that should allow you to build project/make files for any platform. For details on <code>cmake</code>, see <a href="https://www.cmake.org">https://www.cmake.org</a>. In brief, depending on your platform, use one of e.g.: </p><pre class="fragment">cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release
cmake -G "Visual Studio 10" -DCMAKE_BUILD_TYPE=Release
cmake -G "Xcode" -DCMAKE_BUILD_TYPE=Release
</pre><p> Then, build as normal for your platform. This should result in a <code>flatc</code> executable, essential for the next steps. Note that to use clang instead of gcc, you may need to set up your environment variables, e.g. <code>CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake -G "Unix Makefiles"</code>.</p>
<p>Optionally, run the <code>flattests</code> executable from the root <code>flatbuffers/</code> directory to ensure everything is working correctly on your system. If this fails, please contact us!</p>
<p>Building should also produce two sample executables, <code>flatsamplebinary</code> and <code>flatsampletext</code>, see the corresponding <code>.cpp</code> files in the <code>flatbuffers/samples</code> directory.</p>
<p><em>Note that you MUST be in the root of the FlatBuffers distribution when you run 'flattests' or <code>flatsampletext</code>, or it will fail to load its files.</em></p>
<h2><a class="anchor" id="autotoc_md8"></a>
Make all warnings into errors</h2>
<p>By default all Flatbuffers <code>cmake</code> targets are build with <code>-Werror</code> flag. With this flag (or <code>/WX</code> for MSVC) C++ compiler will treat all warnings as errors. Additionally <code>-Wall -pedantic -Wextra</code> (or <code>/W4</code> form MSVC) flags are set. These flags minimize the number of possible defects in code and keep code highly portable. Using these flags is considered good practice but sometimes it can break dependent projects if a compiler is upgraded or a toolset is changed. Usually, newer compiler versions add new compile-time diagnostics that were unavailable before. These new diagnostic warnings could stop the build process if <code>-Werror</code> flag is set.</p>
<p>It is possible to cancel <code>warnings as errors</code> flag at <code>cmake</code> configuration stage using <code>FLATBUFFERS_CXX_FLAGS</code> option. Compilation flags declared in <code>FLATBUFFERS_CXX_FLAGS</code> will be appended to the project-level <code>CMAKE_CXX_FLAGS</code> variable. Examples:</p>
<ul>
<li>GCC and Clang: <code>cmake . -D FLATBUFFERS_CXX_FLAGS="-Wno-error"</code></li>
<li>MSVC: <code>cmake . -D FLATBUFFERS_CXX_FLAGS="/WX-"</code></li>
<li>MSVC: <code>cmake . -D FLATBUFFERS_CXX_FLAGS="/Wv &lt;compiler.version&gt;"</code></li>
</ul>
<h1><a class="anchor" id="autotoc_md9"></a>
Building with VCPKG</h1>
<p>You can download and install flatbuffers using the <a href="https://github.com/Microsoft/vcpkg/">vcpkg</a> dependency manager: </p><pre class="fragment">git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install flatbuffers
</pre><p> The flatbuffers port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please <a href="https://github.com/Microsoft/vcpkg">create an issue or pull request</a> on the vcpkg repository.</p>
<h1><a class="anchor" id="autotoc_md10"></a>
Building for Android</h1>
<p>There is a <code>flatbuffers/android</code> directory that contains all you need to build the test executable on android (use the included <code>build_apk.sh</code> script, or use <code>ndk_build</code> / <code>adb</code> etc. as usual). Upon running, it will output to the log if tests succeeded or not.</p>
<p>You may also run an android sample from inside the <code>flatbuffers/samples</code>, by running the <code>android_sample.sh</code> script. Optionally, you may go to the <code>flatbuffers/samples/android</code> folder and build the sample with the <code>build_apk.sh</code> script or <code>ndk_build</code> / <code>adb</code> etc.</p>
<h1><a class="anchor" id="autotoc_md11"></a>
Using FlatBuffers in your own projects</h1>
<p>For C++, there is usually no runtime to compile, as the code consists of a single header, <code>include/flatbuffers/flatbuffers.h</code>. You should add the <code>include</code> folder to your include paths. If you wish to be able to load schemas and/or parse text into binary buffers at runtime, you additionally need the other headers in <code>include/flatbuffers</code>. You must also compile/link <code>src/idl_parser.cpp</code> (and <code>src/idl_gen_text.cpp</code> if you also want to be able convert binary to text).</p>
<p>To see how to include FlatBuffers in any of our supported languages, please view the <a class="el" href="flatbuffers_guide_tutorial.html">Tutorial</a> and select your appropriate language using the radio buttons.</p>
<h2><a class="anchor" id="autotoc_md12"></a>
Using in CMake-based projects</h2>
<p>If you want to use FlatBuffers in a project which already uses CMake, then a more robust and flexible approach is to build FlatBuffers as part of that project directly. This is done by making the FlatBuffers source code available to the main build and adding it using CMake's <code>add_subdirectory()</code> command. This has the significant advantage that the same compiler and linker settings are used between FlatBuffers and the rest of your project, so issues associated with using incompatible libraries (eg debug/release), etc. are avoided. This is particularly useful on Windows.</p>
<p>Suppose you put FlatBuffers source code in directory <code>${FLATBUFFERS_SRC_DIR}</code>. To build it as part of your project, add following code to your <code>CMakeLists.txt</code> file: </p><div class="fragment"><div class="line"># Add FlatBuffers directly to our build. This defines the `flatbuffers` target.</div>
<div class="line">add_subdirectory(${FLATBUFFERS_SRC_DIR}</div>
<div class="line"> ${CMAKE_CURRENT_BINARY_DIR}/flatbuffers-build</div>
<div class="line"> EXCLUDE_FROM_ALL)</div>
<div class="line"> </div>
<div class="line"># Now simply link against flatbuffers as needed to your already declared target.</div>
<div class="line"># The flatbuffers target carry header search path automatically if CMake &gt; 2.8.11.</div>
<div class="line">target_link_libraries(own_project_target PRIVATE flatbuffers)</div>
</div><!-- fragment --><p> When build your project the <code>flatbuffers</code> library will be compiled and linked to a target as part of your project.</p>
<h3><a class="anchor" id="autotoc_md13"></a>
Override default depth limit of nested objects</h3>
<p>To override <a class="el" href="flatbuffers_guide_use_cpp.html">the depth limit of recursion</a>, add this directive: </p><div class="fragment"><div class="line">set(FLATBUFFERS_MAX_PARSING_DEPTH 16)</div>
</div><!-- fragment --><p> to <code>CMakeLists.txt</code> file before <code>add_subdirectory(${FLATBUFFERS_SRC_DIR})</code> line.</p>
<h3><a class="anchor" id="autotoc_md14"></a>
For Google Play apps</h3>
<p>For applications on Google Play that integrate this library, usage is tracked. This tracking is done automatically using the embedded version string (flatbuffer_version_string), and helps us continue to optimize it. Aside from consuming a few extra bytes in your application binary, it shouldn't affect your application at all. We use this information to let us know if FlatBuffers is useful and if we should continue to invest in it. Since this is open source, you are free to remove the version string but we would appreciate if you would leave it in. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-49880327-7', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>