diff options
Diffstat (limited to 'md__build.html')
| -rw-r--r-- | md__build.html | 120 |
1 files changed, 80 insertions, 40 deletions
diff --git a/md__build.html b/md__build.html index 9b63d0f6..63f3fa4a 100644 --- a/md__build.html +++ b/md__build.html @@ -1,9 +1,9 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://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.8.13"/> +<meta name="generator" content="Doxygen 1.8.17"/> <meta name="viewport" content="width=device-width, initial-scale=1"/> <title>LLFIO: Build instructions</title> <link href="tabs.css" rel="stylesheet" type="text/css"/> @@ -13,9 +13,6 @@ <script type="text/javascript" src="resize.js"></script> <script type="text/javascript" src="navtreedata.js"></script> <script type="text/javascript" src="navtree.js"></script> -<script type="text/javascript"> - $(document).ready(initResizable); -</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> @@ -29,7 +26,7 @@ <tr style="height: 56px;"> <td id="projectalign" style="padding-left: 0.5em;"> <div id="projectname">LLFIO -  <span id="projectnumber">v2.00 late alpha</span> +  <span id="projectnumber">v2.00 late beta</span> </div> </td> </tr> @@ -37,18 +34,21 @@ </table> </div> <!-- end header part --> -<!-- Generated by Doxygen 1.8.13 --> +<!-- Generated by Doxygen 1.8.17 --> <script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ var searchBox = new SearchBox("searchBox", "search",false,'Search'); +/* @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&dn=gpl-2.0.txt GPL-v2 */ $(function() { initMenu('',true,false,'search.php','Search'); $(document).ready(function() { init_search(); }); }); -</script> +/* @license-end */</script> <div id="main-nav"></div> </div><!-- top --> <div id="side-nav" class="ui-resizable side-nav-resizable"> @@ -62,7 +62,9 @@ $(function() { </div> </div> <script type="text/javascript"> -$(document).ready(function(){initNavTree('md__build.html','');}); +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +$(document).ready(function(){initNavTree('md__build.html',''); initResizable(); }); +/* @license-end */ </script> <div id="doc-content"> <!-- window showing the filter options --> @@ -79,54 +81,92 @@ $(document).ready(function(){initNavTree('md__build.html','');}); </iframe> </div> -<div class="header"> +<div class="PageDoc"><div class="header"> <div class="headertitle"> <div class="title">Build instructions </div> </div> </div><!--header--> <div class="contents"> <div class="textblock"><p>These compilers and OSs are regularly tested:</p> <ul> -<li><a href="https://gcc.gnu.org/">GCC</a> 7.0 (Linux 4.x x64)</li> -<li><a href="https://clang.llvm.org/">Clang</a> 4.0 (Linux 4.x x64)</li> -<li>Clang 5.0 (macOS 10.12 x64)</li> -<li>Visual Studio 2017 (Windows 10 x64). Note that LLFIO does not currently compile with <code>/permissive-</code> due a bug in MSVC.</li> +<li><a href="https://gcc.gnu.org/">GCC</a> 7.5 (Linux 4.x x64)</li> +<li><a href="https://clang.llvm.org/">Clang</a> 7 (Linux 4.x x64)</li> +<li>Xcode 11.6 (macOS 10.15 x64)</li> +<li>Visual Studio 2017 (Windows 10 x64).</li> </ul> -<p>Other compilers, architectures and OSs may work, but are not tested regularly. You will need a working <a href="https://en.cppreference.com/w/cpp/experimental/fs">Filesystem TS</a> implementation in your STL, and C++ 14.</p> -<h2>Get a copy of the source</h2> -<p>Download <a href="https://dedi5.nedprod.com/static/files/llfio-v2.0-source-latest.tar.xz">this archive</a> or clone from the GitHub repository:</p> -<div class="fragment"><div class="line">git config --system core.longpaths true</div><div class="line">git clone --recursive https://github.com/ned14/llfio.git</div><div class="line">cd llfio</div></div><!-- fragment --><p>The first command is relevant so deeply nested paths on Windows will work when cloning the repository and submodules. It may require elevated privileges, but you can also use <code>git config --global core.longpaths true</code> instead.</p> -<h3>If you already cloned before reading this</h3> -<p>If you had already cloned <em>this</em> repository, but didn't use the <code>--recursive</code> switch, you can simply run the following command from inside the work tree:</p> -<div class="fragment"><div class="line">git submodule update --init --recursive</div></div><!-- fragment --><h2>Header only usage</h2> -<p>LLFIO defaults to header only library configuration, so you don't actually need any of the prebuilt binaries below, or to build anything. Simply:</p> -<div class="fragment"><div class="line"><span class="preprocessor">#include "llfio/include/llfio.hpp"</span></div></div><!-- fragment --><p>Note that on Microsoft Windows, the default header only configuration is unsafe to use outside of toy projects. You will get warnings of the form:</p> -<div class="fragment"><div class="line">warning : LLFIO_HEADERS_ONLY=1, LLFIO_EXPERIMENTAL_STATUS_CODE=0 and NTKERNEL_ERROR_CATEGORY_INLINE=1 on Windows, this can produce unreliable binaries where semantic comparisons of error codes randomly fail!</div></div><!-- fragment --><p>... and ...</p> -<div class="fragment"><div class="line">Defining custom error code category ntkernel_category() via header only form is unreliable! Semantic comparisons will break! Define NTKERNEL_ERROR_CATEGORY_INLINE to 0 and only ever link in ntkernel_category() from a prebuilt shared library to avoid this problem.</div></div><!-- fragment --><p>The cause is that <code><system_error></code> has a design flaw not rectified until (<a href="https://wg21.link/P1196">probably</a>) C++ 20 where custom error code categories are unsafe when shared libraries are in use.</p> +<p>Other compilers, architectures and OSs may work, but are not tested regularly. You will need a working <a href="https://en.cppreference.com/w/cpp/experimental/fs">Filesystem TS</a> implementation in your STL, and at least C++ 14.</p> +<p>LLFIO has your choice of header-only, static library, and shared library build modes. Note that on Microsoft Windows, the default header only configuration is unsafe to use outside of toy projects. You will get warnings of the form:</p> +<div class="fragment"><div class="line">warning : LLFIO_HEADERS_ONLY=1, LLFIO_EXPERIMENTAL_STATUS_CODE=0 and NTKERNEL_ERROR_CATEGORY_INLINE=1 on Windows, this can produce unreliable binaries where semantic comparisons of error codes randomly fail!</div> +</div><!-- fragment --><p>... and ...</p> +<div class="fragment"><div class="line">Defining custom error code category ntkernel_category() via header only form is unreliable! Semantic comparisons will break! Define NTKERNEL_ERROR_CATEGORY_INLINE to 0 and only ever link in ntkernel_category() from a prebuilt shared library to avoid this problem.</div> +</div><!-- fragment --><p>The cause is that <code><system_error></code> has a design flaw not rectified until (<a href="https://wg21.link/P1196">probably</a>) C++ 20 where custom error code categories are unsafe when shared libraries are in use.</p> <p>You have one of three choices here: (i) Use <a href="https://wg21.link/P1028">experimental SG14 <code>status_code</code></a> which doesn't have this problem (define <code>LLFIO_EXPERIMENTAL_STATUS_CODE=1</code>) (ii) Use the NT kernel error category as a shared library (<a href="https://github.com/ned14/ntkernel-error-category">see its documentation</a>) (iii) Don't use header only LLFIO on Windows (see below).</p> -<h2>Prebuilt binaries</h2> +<h1><a class="anchor" id="autotoc_md21"></a> +Install from the vcpkg package manager</h1> +<p>This is particularly easy, and works on Mac OS, Linux and Microsoft Windows:</p> +<div class="fragment"><div class="line">vcpkg install llfio</div> +</div><!-- fragment --><p>LLFIO appears at <code><llfio/llfio.hpp></code>.</p> +<h1><a class="anchor" id="autotoc_md22"></a> +Prebuilt binaries</h1> <p>It is faster to build programs using LLFIO if you don't use a header only build. In this situation, define <code>LLFIO_HEADERS_ONLY=0</code>, and choose one of <code>LLFIO_DYN_LINK</code> or <code>LLFIO_STATIC_LINK</code> depending on whether you are using the prebuilt shared or static libraries respectively.</p> -<ul> -<li><a href="https://dedi5.nedprod.com/static/files/llfio-v2.0-binaries-linux64-latest.tgz">https://dedi5.nedprod.com/static/files/llfio-v2.0-binaries-linux64-latest.tgz</a></li> -<li><a href="https://dedi5.nedprod.com/static/files/llfio-v2.0-binaries-win64-latest.zip">https://dedi5.nedprod.com/static/files/llfio-v2.0-binaries-win64-latest.zip</a></li> -</ul> -<h2>Build static libraries from source</h2> -<p>You will need <a href="https://cmake.org/">CMake</a> installed, v3.1 or better. It is important to do an out-of-tree build, because the build will otherwise fail.</p> +<p>You can find prebuilt binaries for Mac OS, Ubuntu and Microsoft Windows at <a href="https://github.com/ned14/llfio/releases">https://github.com/ned14/llfio/releases</a>. Choose a release, and under the Assets you will find the prebuilt binaries packages which include headers.</p> +<h1><a class="anchor" id="autotoc_md23"></a> +Get a copy of the source</h1> +<p>Clone from the GitHub repository:</p> +<div class="fragment"><div class="line">git config --system core.longpaths true</div> +<div class="line">git clone --recursive https://github.com/ned14/llfio.git</div> +<div class="line">cd llfio</div> +</div><!-- fragment --><p>The first command is relevant so deeply nested paths on Windows will work when cloning the repository and submodules. It may require elevated privileges, but you can also use <code>git config --global core.longpaths true</code> instead.</p> +<h2><a class="anchor" id="autotoc_md24"></a> +If you already cloned before reading this</h2> +<p>If you had already cloned <em>this</em> repository, but didn't use the <code>--recursive</code> switch, you can simply run the following command from inside the work tree:</p> +<div class="fragment"><div class="line">git submodule update --init --recursive</div> +</div><!-- fragment --><h1><a class="anchor" id="autotoc_md25"></a> +Build static libraries from source</h1> +<p>You will need <a href="https://cmake.org/">CMake</a> installed, v3.5 or better. It is important to do an out-of-tree build, because the build will otherwise fail.</p> +<p>If you want C++ Coroutines support, you will need a C++ Coroutines supporting compiler. It should get automatically discovered and detected, however note that on Linux you currently need a very recent clang combined with a very recent libc++ as no recent GCC implements C++ Coroutines yet. For Debian/Ubuntu, <code>apt install libc++-dev-9 libc++abi-dev-9</code> might do it.</p> <p>To build and test on POSIX (<code>make</code>, <code>ninja</code> etc):</p> -<div class="fragment"><div class="line">mkdir build</div><div class="line">cd build</div><div class="line">cmake ..</div><div class="line">cmake --build .</div><div class="line">ctest -R llfio_sl</div></div><!-- fragment --><p>To build and test on Windows or Mac OS (Visual Studio, XCode etc):</p> -<div class="fragment"><div class="line">mkdir build</div><div class="line">cd build</div><div class="line">cmake .. -G<your generator here></div><div class="line">cmake --build . --config Release</div><div class="line">ctest -C Release -R llfio_sl</div></div><!-- fragment --><h2>Build shared libraries from source</h2> -<p>You will need <a href="https://cmake.org/">CMake</a> installed, v3.1 or better. It is important to do an out-of-tree build, because the build will otherwise fail.</p> +<div class="fragment"><div class="line">mkdir build</div> +<div class="line">cd build</div> +<div class="line">cmake ..</div> +<div class="line">cmake --build .</div> +<div class="line">ctest -R llfio_sl</div> +</div><!-- fragment --><p>To build and test on Windows or Mac OS (Visual Studio, XCode etc):</p> +<div class="fragment"><div class="line">mkdir build</div> +<div class="line">cd build</div> +<div class="line">cmake .. -G<your generator here></div> +<div class="line">cmake --build . --config Release</div> +<div class="line">ctest -C Release -R llfio_sl</div> +</div><!-- fragment --><h1><a class="anchor" id="autotoc_md26"></a> +Build shared libraries from source</h1> +<p>You will need <a href="https://cmake.org/">CMake</a> installed, v3.5 or better. It is important to do an out-of-tree build, because the build will otherwise fail.</p> <p>To build and test on POSIX (<code>make</code>, <code>ninja</code> etc):</p> -<div class="fragment"><div class="line">mkdir build</div><div class="line">cd build</div><div class="line">cmake ..</div><div class="line">cmake --build . -- _dl</div><div class="line">ctest -R llfio_dl</div></div><!-- fragment --><p>To build and test on Windows or Mac OS (Visual Studio, XCode etc):</p> -<div class="fragment"><div class="line">mkdir build</div><div class="line">cd build</div><div class="line">cmake .. -G<your generator here></div><div class="line">cmake --build . --config Release --target _dl</div><div class="line">ctest -C Release -R llfio_dl</div></div><!-- fragment --><h2>Installing libraries from source</h2> -<p>Installing the libraries from CMake does not currently work right due to unfinished single header generation. It's a TODO/FIXME item. </p> -</div></div><!-- contents --> +<div class="fragment"><div class="line">mkdir build</div> +<div class="line">cd build</div> +<div class="line">cmake ..</div> +<div class="line">cmake --build . -- _dl</div> +<div class="line">ctest -R llfio_dl</div> +</div><!-- fragment --><p>To build and test on Windows or Mac OS (Visual Studio, XCode etc):</p> +<div class="fragment"><div class="line">mkdir build</div> +<div class="line">cd build</div> +<div class="line">cmake .. -G<your generator here></div> +<div class="line">cmake --build . --config Release --target _dl</div> +<div class="line">ctest -C Release -R llfio_dl</div> +</div><!-- fragment --><h1><a class="anchor" id="autotoc_md27"></a> +Installing libraries from source</h1> +<div class="fragment"><div class="line">mkdir build</div> +<div class="line">cd build</div> +<div class="line">cmake ..</div> +<div class="line">cmake --build . -- _dl _sl _hl</div> +<div class="line">cmake --build . --target install</div> +</div><!-- fragment --> </div></div><!-- contents --> +</div><!-- PageDoc --> </div><!-- doc-content --> <!-- start footer part --> <div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> <ul> <li class="footer">Generated by <a href="http://www.doxygen.org/index.html"> - <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.13 </li> + <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.17 </li> </ul> </div> </body> |