Files
bgfx/build.html
Бранимир Караџић 2168bb74db Updated docs.
2023-07-01 08:40:54 -07:00

318 lines
22 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="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Building &mdash; bgfx 1.121.8531 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<script 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"> bgfx
</a>
<div class="version">
1.121.8531
</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="Navigation menu">
<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="Mobile navigation menu" >
<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="Page 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">
<section id="building">
<h1>Building<a class="headerlink" href="#building" title="Permalink to this heading"></a></h1>
<section id="dependencies">
<h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this heading"></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>
</section>
<section id="getting-source">
<h2>Getting Source<a class="headerlink" href="#getting-source" title="Permalink to this heading"></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>
</section>
<section id="quick-start">
<h2>Quick Start<a class="headerlink" href="#quick-start" title="Permalink to this heading"></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>
</section>
<section id="prerequisites">
<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this heading"></a></h2>
<section id="android">
<h3>Android<a class="headerlink" href="#android" title="Permalink to this heading"></a></h3>
<p>Download Android NDK (r23 or newer):</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>
</pre></div>
</div>
</section>
<section id="linux">
<h3>Linux<a class="headerlink" href="#linux" title="Permalink to this heading"></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>
</section>
<section id="windows">
<h3>Windows<a class="headerlink" href="#windows" title="Permalink to this heading"></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 class="admonition note">
<p class="admonition-title">Note</p>
<p><strong>MSYS</strong>, <strong>Cygwin</strong>, etc. shells are not supported!
You must use use <strong>cmd.exe</strong> with provided makefiles.</p>
</div>
</section>
</section>
<section id="build">
<h2>Build<a class="headerlink" href="#build" title="Permalink to this heading"></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, macOS, and Windows are included in
bx repository.</p>
<section id="general">
<h3>General<a class="headerlink" href="#general" title="Permalink to this heading"></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>
</section>
<section id="id1">
<h3>Windows<a class="headerlink" href="#id1" title="Permalink to this heading"></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>
</section>
<section id="xcode">
<h3>Xcode<a class="headerlink" href="#xcode" title="Permalink to this heading"></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>
</section>
<section id="id2">
<h3>Linux<a class="headerlink" href="#id2" title="Permalink to this heading"></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>
</section>
<section id="winrt-uwp">
<h3>WinRT / UWP<a class="headerlink" href="#winrt-uwp" title="Permalink to this heading"></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>
</section>
</section>
<section id="amalgamated-build">
<h2>Amalgamated Build<a class="headerlink" href="#amalgamated-build" title="Permalink to this heading"></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 macOS/iOS/iPadOS/tvOS 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>
</section>
<section id="tools">
<h2>Tools<a class="headerlink" href="#tools" title="Permalink to this heading"></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>
</section>
<section id="alternative-build-systems">
<h2>Alternative build systems<a class="headerlink" href="#alternative-build-systems" title="Permalink to this heading"></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>
</section>
<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 heading"></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>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="overview.html" class="btn btn-neutral float-left" title="Overview" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="examples.html" class="btn btn-neutral float-right" title="Examples" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2010-2023, Branimir Karadžić.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>