Update gh-pages for 1250f04

reference/supported-ghc-versions/index.html

@@ -240,7 +240,7 @@
 
                 <h1 id="supported-ghc-versions">Supported GHC Versions<a class="headerlink" href="#supported-ghc-versions" title="Permanent link">&para;</a></h1>
 <p>The following versions of GHC built on the CI servers and should be included
-in the cache (for the default haskell.nix <code>nixpkgs</code>).</p>
+in the binary cache (for the default haskell.nix <code>nixpkgs</code>).</p>
 <ul>
 <li>8.6.5 <code>compiler-nix-name = "ghc865";</code></li>
 <li>8.8.3 <code>compiler-nix-name = "ghc883";</code></li>
@@ -263,10 +263,7 @@ <h1 id="supported-ghc-versions">Supported GHC Versions<a class="headerlink" href
 </ul>
 <p>See <a href="https://github.com/input-output-hk/haskell.nix/blob/master/overlays/bootstrap.nix">overlays/bootstrap.nix</a>
 for a list of all the valid <code>compiler-nix-names</code>.</p>
-<p>See also:</p>
-<ul>
-<li><a href="../../dev/adding-new-ghc/">Instructions on adding new GHC versions</a>.</li>
-</ul>
+<p>See also: <a href="../../dev/adding-new-ghc/">Instructions on adding new GHC versions</a>.</p>
 
             </div>
           </div>

troubleshooting/index.html

@@ -138,9 +138,9 @@
 
         <ul>
 
-            <li><a class="toctree-l3" href="#general-troubleshooting-when-using-cabalprojectstackprojectproject">General troubleshooting when using cabalProject/stackProject/project</a></li>
+            <li><a class="toctree-l3" href="#issues-with-building-and-garbage-collection">Issues with building and garbage-collection</a></li>
 
-            <li><a class="toctree-l3" href="#specific-issues">Specific issues</a></li>
+            <li><a class="toctree-l3" href="#general-troubleshooting-when-using-cabalprojectstackprojectproject">General troubleshooting when using cabalProject/stackProject/project</a></li>
 
         </ul>
 
@@ -243,6 +243,23 @@
             <div class="section">
 
                 <h1 id="troubleshooting">Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permanent link">&para;</a></h1>
+<h2 id="issues-with-building-and-garbage-collection">Issues with building and garbage-collection<a class="headerlink" href="#issues-with-building-and-garbage-collection" title="Permanent link">&para;</a></h2>
+<h3 id="why-am-i-building-ghc">Why am I building GHC?<a class="headerlink" href="#why-am-i-building-ghc" title="Permanent link">&para;</a></h3>
+<p>It's easier to list the reverse: when will you <em>not</em> build GHC?</p>
+<ul>
+<li>You have configured the <a href="../tutorials/getting-started/">binary cache</a> correctly.</li>
+<li>You are using one of the GHC versions which <a href="../reference/supported-ghc-versions/">we support</a>.</li>
+<li>You are using one of the nixpkgs versions used by our CI (you can access the sources for these <a href="../tutorials/getting-started/">through haskell.nix</a>.</li>
+</ul>
+<p>If you think you are doing all of these and you still find you're building GHC, drop us a line.</p>
+<h3 id="why-am-i-building-lots-of-haskell-packages">Why am I building lots of Haskell packages?<a class="headerlink" href="#why-am-i-building-lots-of-haskell-packages" title="Permanent link">&para;</a></h3>
+<p>We don't generally cache much of Hackage (there's a lot of it!), except for the parts which are used by our tests.
+So this is expected, unfortunately.</p>
+<h3 id="how-do-i-prevent-the-evaluation-time-dependencies-of-my-project-from-being-garbage-collected">How do I prevent the evaluation-time dependencies of my project from being garbage-collected?<a class="headerlink" href="#how-do-i-prevent-the-evaluation-time-dependencies-of-my-project-from-being-garbage-collected" title="Permanent link">&para;</a></h3>
+<p>The <code>haskell-nix.roots "ghc884"</code> should include all the evaluation-time dependencies
+and the main build time dependencies of a project using ghc 8.8.4.
+So you can add that to the relevant GC root.
+In practice, if you're using a CI system like Hydra/Hercules, this means adding it to a job in <code>release.nix</code>/<code>ci.nix</code>.</p>
 <h2 id="general-troubleshooting-when-using-cabalprojectstackprojectproject">General troubleshooting when using <code>cabalProject</code>/<code>stackProject</code>/<code>project</code><a class="headerlink" href="#general-troubleshooting-when-using-cabalprojectstackprojectproject" title="Permanent link">&para;</a></h2>
 <h3 id="does-the-cabalstack-build-work">Does the cabal/stack build work?<a class="headerlink" href="#does-the-cabalstack-build-work" title="Permanent link">&para;</a></h3>
 <p>In <code>haskell.nix</code>, we strive to take the build configuration from the cabal/stack configuration files.
@@ -272,23 +289,6 @@ <h4 id="nix-only-configuration-options">Nix-only configuration options<a class="
 <p>Where possible, try to do the configuration in your cabal/stack configuration, e.g. setting <code>profiling: true</code> in <code>cabal.project</code>.
 This will ensure that the two builds agree.</p>
 <p>If you want or need to set some of them in Nix, try bringing the two into sync temporarily for troubleshooting.</p>
-<h2 id="specific-issues">Specific issues<a class="headerlink" href="#specific-issues" title="Permanent link">&para;</a></h2>
-<h3 id="why-am-i-building-ghc">Why am I building GHC?<a class="headerlink" href="#why-am-i-building-ghc" title="Permanent link">&para;</a></h3>
-<p>It's easier to list the reverse: when will you <em>not</em> build GHC?</p>
-<ul>
-<li>You have configured the <a href="../tutorials/getting-started/">binary caches</a> correctly.</li>
-<li>You are using one of the GHC versions built by our CI (have a look in <a href="../ci.nix">ci.nix</a> to see what gets built).</li>
-<li>You are using one of the nixpkgs versions used by our CI (you can access the sources for these <a href="../tutorials/getting-started/">through haskell.nix</a>.</li>
-</ul>
-<p>If you think you are doing all of these and you still find you're building GHC, drop us a line.</p>
-<h3 id="why-am-i-building-lots-of-haskell-packages">Why am I building lots of Haskell packages?<a class="headerlink" href="#why-am-i-building-lots-of-haskell-packages" title="Permanent link">&para;</a></h3>
-<p>We don't generally cache much of Hackage (there's a lot of it!), except for the parts which are used by our tests.
-So this is expected, unfortunately.</p>
-<h3 id="how-do-i-prevent-the-evaluation-time-dependencies-of-my-project-from-being-garbage-collected">How do I prevent the evaluation-time dependencies of my project from being garbage-collected?<a class="headerlink" href="#how-do-i-prevent-the-evaluation-time-dependencies-of-my-project-from-being-garbage-collected" title="Permanent link">&para;</a></h3>
-<p>The <code>haskell-nix.roots "ghc884"</code> should include all the evaluation-time dependencies
-and the main build time dependencies of a project using ghc 8.8.4.
-So you can add that to the relevant GC root.
-In practice, if you're using a CI system like Hydra/Hercules, this means adding it to a job in <code>release.nix</code>/<code>ci.nix</code>.</p>
 
             </div>
           </div>

tutorials/getting-started/index.html

@@ -76,7 +76,7 @@
 
         <ul>
 
-            <li><a class="toctree-l4" href="#setting-up-the-cachix-binary-cache">Setting up the Cachix binary cache</a></li>
+            <li><a class="toctree-l4" href="#setting-up-the-binary-cache">Setting up the binary cache</a></li>
 
             <li><a class="toctree-l4" href="#scaffolding">Scaffolding</a></li>
 
@@ -255,24 +255,15 @@ <h1 id="getting-started">Getting started<a class="headerlink" href="#getting-sta
 project and its dependencies into Nix code.</p>
 <p>Assuming you have <a href="https://nixos.org/download.html">Nix</a> installed, you can
 start setting up your project.</p>
-<h2 id="setting-up-the-cachix-binary-cache">Setting up the Cachix binary cache<a class="headerlink" href="#setting-up-the-cachix-binary-cache" title="Permanent link">&para;</a></h2>
-<p>You can <strong>avoid compiling GHC and nix-tools</strong> by configuring
-<a href="https://cachix.org">Cachix</a> so you can benefit from the binary cache built by
-CI:</p>
-<pre><code class="bash">$ nix-env -iA cachix -f https://cachix.org/api/v1/install
-installing 'cachix-0.3.8'
-building '/nix/store/bh176xhpk4wrjm56iahm86wf85jaz23v-user-environment.drv'...
-created 42 symlinks in user environment
-
-$ cachix use iohk
-Configured https://iohk.cachix.org binary cache in ~/.config/nix/nix.conf
-</code></pre>
-
-<p>Note: <code>haskell.nix</code> currently uses multiple CI providers to build derivations and store outputs. To improve your chances of getting a cache hit, you might want to add the following additional substituter to <code>~/.config/nix/nix.conf</code>:</p>
+<h2 id="setting-up-the-binary-cache">Setting up the binary cache<a class="headerlink" href="#setting-up-the-binary-cache" title="Permanent link">&para;</a></h2>
+<p>IMPORTANT: you <em>must</em> do this or you <em>will</em> build several copies of GHC!</p>
+<p>You can configure Nix to use our binary cache, which is pushed to by CI, so should contain the artifacts that you need.</p>
+<p>You need to add the following sections to <code>/etc/nix/nix.conf</code> or, if you are a trusted user, <code>~/.config/nix/nix.conf</code> (if you don't know what a "trusted user" is, you probably want to do the former).</p>
 <pre><code>trusted-public-keys = [...] hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= [...]
 substituters = [...] https://hydra.iohk.io [...]
 </code></pre>
 
+<p>This can be tricky to get setup properly. If you're still having trouble getting cache hits, consult the corresponding <a href="../reference/troubleshooting#why-am-i-building-ghc">troubleshooting section</a>.</p>
 <h2 id="scaffolding">Scaffolding<a class="headerlink" href="#scaffolding" title="Permanent link">&para;</a></h2>
 <p>The following work with <code>stack.yaml</code> and <code>cabal.project</code> based
 projects.</p>