Travis CI updates documentation

1 files changed, 22 insertions, 17 deletions

diff --git a/md__build.html b/md__build.html
index 921cfb0a..27fad23d 100644
--- a/md__build.html
+++ b/md__build.html
@@ -84,36 +84,41 @@ $(document).ready(function(){initNavTree('md__build.html','');});
 <div class="title">Build instructions </div>  </div>
 </div><!--header-->
 <div class="contents">
-<div class="textblock"><p>These compilers and OS are regularly tested:</p><ul>
-<li>GCC 7.0 (Linux 4,x x64)</li>
-<li>clang 4.0 (Linux 4.x x64)</li>
-<li>clang 5.0 (OS X 10.12 x64)</li>
+<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)</li>
 </ul>
-<p>Other compilers, architectures and OSs may work, but are not tested regularly. You will need a working Filesystem TS implementation in your STL, and C++ 14.</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 C++ 14.</p>
 <h2>Get a copy of the source</h2>
-<ul>
-<li><a href="https://dedi5.nedprod.com/static/files/llfio-v2.0-source-latest.tar.xz">https://dedi5.nedprod.com/static/files/llfio-v2.0-source-latest.tar.xz</a></li>
-</ul>
-<p>Or from github:</p>
-<div class="fragment"><div class="line">git config --system core.longpaths true</div><div class="line">git clone https://github.com/ned14/llfio.git</div><div class="line">cd llfio</div><div class="line">git submodule update --init --recursive</div></div><!-- fragment --><h2>Header only usage</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 &quot;llfio/include/llfio.hpp&quot;</span></div></div><!-- fragment --><h2>Prebuilt binaries</h2>
-<p>It is faster to build programs using LLFIO if you don't user 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>
+<div class="fragment"><div class="line"><span class="preprocessor">#include &quot;llfio/include/llfio.hpp&quot;</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>&lt;system_error&gt;</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>
+<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 cmake installed, v3.1 or better.</p>
-<p>To build and test on POSIX (make, ninja etc):</p>
+<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>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&lt;your generator here&gt;</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 cmake installed, v3.1 or better.</p>
-<p>To build and test on POSIX (make, ninja etc):</p>
+<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>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&lt;your generator here&gt;</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>
+<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><!-- doc-content -->
 <!-- start footer part -->