bgfx/build.html
Бранимир Караџић ed2e0d45e0 Updated docs.
2022-07-23 11:01:21 -07:00

425 lines
24 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Building &mdash; bgfx 1.115.8203 documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/language_data.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Examples" href="examples.html" />
<link rel="prev" title="Overview" href="overview.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home" alt="Documentation Home"> bgfx
</a>
<div class="version">
1.115.8203
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="overview.html">Overview</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Building</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#dependencies">Dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="#getting-source">Getting Source</a></li>
<li class="toctree-l2"><a class="reference internal" href="#quick-start">Quick Start</a></li>
<li class="toctree-l2"><a class="reference internal" href="#prerequisites">Prerequisites</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#android">Android</a></li>
<li class="toctree-l3"><a class="reference internal" href="#linux">Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="#windows">Windows</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#build">Build</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#general">General</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id1">Windows</a></li>
<li class="toctree-l3"><a class="reference internal" href="#xcode">Xcode</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id2">Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="#winrt-uwp">WinRT / UWP</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#amalgamated-build">Amalgamated Build</a></li>
<li class="toctree-l2"><a class="reference internal" href="#tools">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="#alternative-build-systems">Alternative build systems</a></li>
<li class="toctree-l2"><a class="reference internal" href="#minimal-example-without-bgfx-s-example-harness">Minimal example without bgfxs example harness</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="bgfx.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="tools.html">Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="internals.html">Internals</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">bgfx</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home"></a> &raquo;</li>
<li>Building</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="building">
<h1>Building<a class="headerlink" href="#building" title="Permalink to this headline"></a></h1>
<div class="section" id="dependencies">
<h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="https://github.com/bkaradzic/bx">https://github.com/bkaradzic/bx</a></p>
<p><a class="reference external" href="https://github.com/bkaradzic/bimg">https://github.com/bkaradzic/bimg</a></p>
</div>
<div class="section" id="getting-source">
<h2>Getting Source<a class="headerlink" href="#getting-source" title="Permalink to this headline"></a></h2>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">bkaradzic</span><span class="o">/</span><span class="n">bx</span><span class="o">.</span><span class="n">git</span>
<span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">bkaradzic</span><span class="o">/</span><span class="n">bimg</span><span class="o">.</span><span class="n">git</span>
<span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">bkaradzic</span><span class="o">/</span><span class="n">bgfx</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
</div>
<div class="section" id="quick-start">
<h2>Quick Start<a class="headerlink" href="#quick-start" title="Permalink to this headline"></a></h2>
<p>These are step for users who use Windows with Visual Studio.</p>
<p>Enter bgfx directory:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">bgfx</span>
</pre></div>
</div>
<p>Generate Visual Studio 2017 project files:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span>\<span class="n">bx</span>\<span class="n">tools</span>\<span class="nb">bin</span>\<span class="n">windows</span>\<span class="n">genie</span> <span class="o">--</span><span class="k">with</span><span class="o">-</span><span class="n">examples</span> <span class="n">vs2017</span>
</pre></div>
</div>
<p>Open bgfx solution in Visual Studio 2017:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">start</span> <span class="o">.</span><span class="n">build</span>\<span class="n">projects</span>\<span class="n">vs2017</span>\<span class="n">bgfx</span><span class="o">.</span><span class="n">sln</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>For more detailed prerequisites and build steps on other platforms see below.</p>
</div>
</div>
<div class="section" id="prerequisites">
<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline"></a></h2>
<div class="section" id="android">
<h3>Android<a class="headerlink" href="#android" title="Permalink to this headline"></a></h3>
<p>Download AndroidNDK:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference external" href="https://developer.android.com/tools/sdk/ndk/index.html">https://developer.android.com/tools/sdk/ndk/index.html</a></p></li>
</ul>
</div></blockquote>
<p>Set following environment variables:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setx</span> <span class="n">ANDROID_NDK_ROOT</span> <span class="o">&lt;</span><span class="n">path</span> <span class="n">to</span> <span class="n">AndroidNDK</span> <span class="n">directory</span><span class="o">&gt;</span>
<span class="n">setx</span> <span class="n">ANDROID_NDK_ARM</span> <span class="o">&lt;</span><span class="n">path</span> <span class="n">to</span> <span class="n">AndroidNDK</span> <span class="n">directory</span><span class="o">&gt;</span>\<span class="n">toolchains</span>\<span class="n">arm</span><span class="o">-</span><span class="n">linux</span><span class="o">-</span><span class="n">androideabi</span><span class="o">-</span><span class="mf">4.7</span>\<span class="n">prebuilt</span>\<span class="n">windows</span><span class="o">-</span><span class="n">x86_64</span>
<span class="n">setx</span> <span class="n">ANDROID_NDK_MIPS</span> <span class="o">&lt;</span><span class="n">path</span> <span class="n">to</span> <span class="n">AndroidNDK</span> <span class="n">directory</span><span class="o">&gt;</span>\<span class="n">toolchains</span>\<span class="n">mipsel</span><span class="o">-</span><span class="n">linux</span><span class="o">-</span><span class="n">android</span><span class="o">-</span><span class="mf">4.7</span>\<span class="n">prebuilt</span>\<span class="n">windows</span><span class="o">-</span><span class="n">x86_64</span>
<span class="n">setx</span> <span class="n">ANDROID_NDK_X86</span> <span class="o">&lt;</span><span class="n">path</span> <span class="n">to</span> <span class="n">AndroidNDK</span> <span class="n">directory</span><span class="o">&gt;</span>\<span class="n">toolchains</span>\<span class="n">x86</span><span class="o">-</span><span class="mf">4.7</span>\<span class="n">prebuilt</span>\<span class="n">windows</span><span class="o">-</span><span class="n">x86_64</span>
</pre></div>
</div>
<p>To deploy on Android you can use bgfx android activity:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference external" href="https://github.com/Nodrev/bgfx-android-activity#bgfx-android-activity---android-glue-for-bgfx">https://github.com/Nodrev/bgfx-android-activity#bgfx-android-activity—android-glue-for-bgfx</a></p></li>
</ul>
</div></blockquote>
</div>
<div class="section" id="linux">
<h3>Linux<a class="headerlink" href="#linux" title="Permalink to this headline"></a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">libgl1</span><span class="o">-</span><span class="n">mesa</span><span class="o">-</span><span class="n">dev</span> <span class="n">x11proto</span><span class="o">-</span><span class="n">core</span><span class="o">-</span><span class="n">dev</span> <span class="n">libx11</span><span class="o">-</span><span class="n">dev</span>
</pre></div>
</div>
</div>
<div class="section" id="windows">
<h3>Windows<a class="headerlink" href="#windows" title="Permalink to this headline"></a></h3>
<p>Windows users download GnuWin32 utilities:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference external" href="http://gnuwin32.sourceforge.net/packages/make.htm">http://gnuwin32.sourceforge.net/packages/make.htm</a></p></li>
<li><p><a class="reference external" href="http://gnuwin32.sourceforge.net/packages/coreutils.htm">http://gnuwin32.sourceforge.net/packages/coreutils.htm</a></p></li>
<li><p><a class="reference external" href="http://gnuwin32.sourceforge.net/packages/libiconv.htm">http://gnuwin32.sourceforge.net/packages/libiconv.htm</a></p></li>
<li><p><a class="reference external" href="http://gnuwin32.sourceforge.net/packages/libintl.htm">http://gnuwin32.sourceforge.net/packages/libintl.htm</a></p></li>
</ul>
</div></blockquote>
</div>
</div>
<div class="section" id="build">
<h2>Build<a class="headerlink" href="#build" title="Permalink to this headline"></a></h2>
<p>bgfx uses <a class="reference external" href="https://github.com/bkaradzic/genie#genie---project-generator-tool">GENie - Project generator tool</a>
to generate project files for various platform. Binaries for Linux, OSX, and Windows are included in
bx repository.</p>
<div class="section" id="general">
<h3>General<a class="headerlink" href="#general" title="Permalink to this headline"></a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">bgfx</span>
<span class="n">make</span>
</pre></div>
</div>
<p>After calling <code class="docutils literal notranslate"><span class="pre">make</span></code>, .build/projects/* directory will be generated.
All intermediate files generated by compiler will be inside .build
directory structure. Deleting .build directory at any time is safe.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="o">&lt;</span><span class="n">configuration</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Configuration is <code class="docutils literal notranslate"><span class="pre">&lt;platform&gt;-&lt;debug/release&gt;[32/64]</span></code>. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">linux</span><span class="o">-</span><span class="n">release64</span><span class="p">,</span> <span class="n">wasm</span><span class="o">-</span><span class="n">debug</span><span class="p">,</span> <span class="n">wasm</span><span class="o">-</span><span class="n">release</span><span class="p">,</span> <span class="n">osx</span><span class="o">-</span><span class="n">debug</span><span class="p">,</span> <span class="n">osx</span><span class="o">-</span><span class="n">release</span><span class="p">,</span> <span class="n">android</span><span class="o">-</span><span class="n">arm64</span><span class="o">-</span><span class="n">release</span><span class="p">,</span> <span class="n">etc</span><span class="o">.</span>
</pre></div>
</div>
</div>
<div class="section" id="id1">
<h3>Windows<a class="headerlink" href="#id1" title="Permalink to this headline"></a></h3>
<p>Visual Studio 2017 command line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">vs2017</span><span class="o">-</span><span class="n">release64</span>
</pre></div>
</div>
<p>Visual Studio 2017 IDE:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">start</span> <span class="o">.</span><span class="n">build</span><span class="o">/</span><span class="n">projects</span><span class="o">/</span><span class="n">vs2017</span><span class="o">/</span><span class="n">bgfx</span><span class="o">.</span><span class="n">sln</span>
</pre></div>
</div>
</div>
<div class="section" id="xcode">
<h3>Xcode<a class="headerlink" href="#xcode" title="Permalink to this headline"></a></h3>
<p>Xcode command line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">osx</span><span class="o">-</span><span class="n">release</span>
<span class="n">cd</span> <span class="n">examples</span><span class="o">/</span><span class="n">runtime</span>
<span class="o">../../.</span><span class="n">build</span><span class="o">/</span><span class="n">osx64_clang</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">examples</span><span class="o">.</span><span class="n">app</span><span class="o">/</span><span class="n">Contents</span><span class="o">/</span><span class="n">MacOS</span><span class="o">/</span><span class="n">examplesRelease</span>
</pre></div>
</div>
<p>Xcode IDE:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">../</span><span class="n">bx</span><span class="o">/</span><span class="n">tools</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">darwin</span><span class="o">/</span><span class="n">genie</span> <span class="o">--</span><span class="k">with</span><span class="o">-</span><span class="n">combined</span><span class="o">-</span><span class="n">examples</span> <span class="o">--</span><span class="n">xcode</span><span class="o">=</span><span class="n">osx</span> <span class="n">xcode9</span>
<span class="nb">open</span> <span class="o">.</span><span class="n">build</span><span class="o">/</span><span class="n">projects</span><span class="o">/</span><span class="n">xcode9</span><span class="o">-</span><span class="n">osx</span><span class="o">/</span><span class="n">bgfx</span><span class="o">.</span><span class="n">xcworkspace</span>
</pre></div>
</div>
<p>Due to <a class="reference external" href="https://github.com/bkaradzic/genie/blob/master/docs/scripting-reference.md#debugdirpath">inability</a>
to set working directory for an Xcode project from <a class="reference external" href="https://github.com/bkaradzic/genie#genie---project-generator-tool">GENie</a>
configuration file, it has to be set manually for each example project:</p>
<ol class="arabic simple">
<li><p>Open <em>“Edit scheme…”</em> dialog for a given project.</p></li>
<li><p>Select <em>“Run”</em> settings.</p></li>
<li><p>Check <em>“Use custom working directory”</em> and enter following path:
<code class="docutils literal notranslate"><span class="pre">${PROJECT_DIR}/../../../examples/runtime</span></code>.</p></li>
</ol>
</div>
<div class="section" id="id2">
<h3>Linux<a class="headerlink" href="#id2" title="Permalink to this headline"></a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">linux</span><span class="o">-</span><span class="n">release64</span>
</pre></div>
</div>
</div>
<div class="section" id="winrt-uwp">
<h3>WinRT / UWP<a class="headerlink" href="#winrt-uwp" title="Permalink to this headline"></a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span>\<span class="n">bx</span>\<span class="n">tools</span>\<span class="nb">bin</span>\<span class="n">windows</span>\<span class="n">genie</span> <span class="o">--</span><span class="n">vs</span><span class="o">=</span><span class="n">winstore100</span> <span class="n">vs2017</span>
</pre></div>
</div>
<p>Build the resulting solution and deploy to device.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Shaders will need to be compiled with the appropriate target profile for your platform.</p>
</div>
</div>
</div>
<div class="section" id="amalgamated-build">
<h2>Amalgamated Build<a class="headerlink" href="#amalgamated-build" title="Permalink to this headline"></a></h2>
<p>For ease of integration to other build system bgfx library can be built
with single .cpp file. Its only necessary to build
<a class="reference external" href="https://github.com/bkaradzic/bgfx/blob/master/src/amalgamated.cpp">src/amalgamated.cpp</a>
(for OSX/iOS use
<a class="reference external" href="https://github.com/bkaradzic/bgfx/blob/master/src/amalgamated.mm">src/amalgamated.mm</a>
instead) inside different build system.</p>
</div>
<div class="section" id="tools">
<h2>Tools<a class="headerlink" href="#tools" title="Permalink to this headline"></a></h2>
<p>To build bgfx project files for tools, use <code class="docutils literal notranslate"><span class="pre">--with-tools</span></code> option:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span>\<span class="n">bx</span>\<span class="n">tools</span>\<span class="nb">bin</span>\<span class="n">windows</span>\<span class="n">genie</span> <span class="o">--</span><span class="k">with</span><span class="o">-</span><span class="n">tools</span> <span class="n">vs2017</span>
</pre></div>
</div>
</div>
<div class="section" id="alternative-build-systems">
<h2>Alternative build systems<a class="headerlink" href="#alternative-build-systems" title="Permalink to this headline"></a></h2>
<p><strong>CMake</strong></p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference external" href="https://github.com/bkaradzic/bgfx.cmake">https://github.com/bkaradzic/bgfx.cmake</a></p></li>
<li><p><a class="reference external" href="https://github.com/JoshuaBrookover/bgfx.cmake#bgfxcmake">https://github.com/JoshuaBrookover/bgfx.cmake#bgfxcmake</a></p></li>
<li><p><a class="reference external" href="https://github.com/pr0g/sdl-bgfx-imgui-starter#sdl-bgfx-imgui-starter">https://github.com/pr0g/sdl-bgfx-imgui-starter#sdl-bgfx-imgui-starter</a></p></li>
<li><p><a class="reference external" href="https://github.com/yuki-koyama/hello-bgfx">https://github.com/yuki-koyama/hello-bgfx</a></p></li>
<li><p><a class="reference external" href="https://github.com/ataulien/bgfx-cmake">https://github.com/ataulien/bgfx-cmake</a></p></li>
</ul>
</div></blockquote>
<p><strong>fips</strong> is a highlevel build system wrapper written in Python for C/C++ projects.
<a class="reference external" href="https://github.com/floooh/fips#fips">https://github.com/floooh/fips#fips</a></p>
<p><strong>Conan</strong> package
<a class="reference external" href="https://github.com/firefalcom/bgfx-conan">https://github.com/firefalcom/bgfx-conan</a></p>
</div>
<div class="section" id="minimal-example-without-bgfx-s-example-harness">
<h2>Minimal example without bgfxs example harness<a class="headerlink" href="#minimal-example-without-bgfx-s-example-harness" title="Permalink to this headline"></a></h2>
<p>This project demonstrates minimal amount of code needed to integrate bgfx with GLFW, but without
any of existing bgfx example harness. It also demonstrates how to build bgfx with alternative build
system.</p>
<p><a class="reference external" href="https://github.com/jpcy/bgfx-minimal-example">https://github.com/jpcy/bgfx-minimal-example</a></p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="examples.html" class="btn btn-neutral float-right" title="Examples" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="overview.html" class="btn btn-neutral float-left" title="Overview" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2010-2022, Branimir Karadžić
</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>