From c66440c1048387599e002a1c2d17ba5cbaebf3f8 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Tue, 17 Apr 2018 16:08:21 -0400
Subject: doc: Document `config.allowUnsupportedSystem` and its env var

---
 doc/configuration.xml | 40 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/configuration.xml b/doc/configuration.xml
index 55c5ea809d354..5370265c53ad8 100644
--- a/doc/configuration.xml
+++ b/doc/configuration.xml
@@ -14,6 +14,8 @@ true:</para>
   its <literal>meta.broken</literal> set to
   <literal>true</literal>.</para></listitem>
 
+  <listitem><para>The package isn't intended to run on the given system, as none of its <literal>meta.platforms</literal> match the given system.</para></listitem>
+
   <listitem><para>The package's <literal>meta.license</literal> is set
   to a license which is considered to be unfree.</para></listitem>
 
@@ -88,6 +90,42 @@ distributing the software.</para>
   </itemizedlist>
 </section>
 
+<section xml:id="sec-allow-unsupported-system">
+  <title>Installing packages on unsupported systems</title>
+
+
+  <para>
+    There are also two ways to try compiling a package which has been marked as unsuported for the given system.
+  </para>
+
+  <itemizedlist>
+    <listitem><para>
+      For allowing the build of a broken package once, you can use an environment variable for a single invocation of the nix tools:
+
+      <programlisting>$ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1</programlisting>
+    </para></listitem>
+
+    <listitem>
+      <para>
+        For permanently allowing broken packages to be built, you may add <literal>allowUnsupportedSystem = true;</literal> to your user's configuration file, like this:
+
+<programlisting>
+{
+  allowUnsupportedSystem = true;
+}
+</programlisting>
+      </para>
+    </listitem>
+  </itemizedlist>
+
+  <para>
+    The difference between an a package being unsupported on some system and being broken is admittedly a bit fuzzy.
+    If a program <emphasis>ought</emphasis> to work on a certain platform, but doesn't, the platform should be included in <literal>meta.platforms</literal>, but marked as broken with e.g. <literal>meta.broken = !hostPlatform.isWindows</literal>.
+    Of course, this begs the question of what "ought" means exactly.
+    That is left to the package maintainer.
+  </para>
+</section>
+
 <section xml:id="sec-allow-unfree">
   <title>Installing unfree packages</title>
 
@@ -397,7 +435,7 @@ fi
     </para>
 
   </section>
-    
+
   <section xml:id="sec-gnu-info-setup">
     <title>GNU info setup</title>
 
-- 
cgit 1.4.1