steam: added documentation to nixpkgs manual

doc/package-notes.xml

@@ -382,4 +382,141 @@ it. Place the resulting <filename>package.nix</filename> file into
 
 </section>
 
+<section xml:id="sec-steam">
+
+<title>Steam</title>
+
+<section xml:id="sec-steam-nix">
+
+<title>Steam in Nix</title>
+
+<para>
+  Steam is distributed as a <filename>.deb</filename> file, for now only 
+  as an i686 package (the amd64 package only has documentation). 
+  When unpacked, it has a script called <filename>steam</filename> that 
+  in ubuntu (their target distro) would go to <filename>/usr/bin
+  </filename>. When run for the first time, this script copies some 
+  files to the user's home, which include another script that is the 
+  ultimate responsible for launching the steam binary, which is also 
+  in $HOME.
+</para>
+<para>
+  Nix problems and constraints:
+<itemizedlist>
+  <listitem><para>We don't have <filename>/bin/bash</filename> and many 
+  scripts point there. Similarly for <filename>/usr/bin/python</filename>
+  .</para></listitem>
+  <listitem><para>We don't have the dynamic loader in <filename>/lib
+  </filename>.</para></listitem>
+  <listitem><para>The <filename>steam.sh</filename> script in $HOME can 
+  not be patched, as it is checked and rewritten by steam.</para></listitem>
+  <listitem><para>The steam binary cannot be patched, it's also checked.</para></listitem>
+</itemizedlist>
+</para>
+<para>
+  The current approach to deploy Steam in NixOS is composing a FHS-compatible
+  chroot environment, as documented
+  <link xlink:href="http://sandervanderburg.blogspot.nl/2013/09/composing-fhs-compatible-chroot.html">here</link>.
+  This allows us to have binaries in the expected paths without disrupting the system,
+  and to avoid patching them.
+</para>
+
+</section>
+
+<section xml:id="sec-steam-play">
+
+<title>How to play</title>
+
+<para>
+  For 64-bit systems it's important to have 
+  <programlisting>hardware.opengl.driSupport32Bit = true;</programlisting> 
+  in your <filename>/etc/nixos/configuration.nix</filename>. You'll also need 
+  <programlisting>hardware.pulseaudio.support32Bit = true;</programlisting> 
+  if you are using PulseAudio - this will enable 32bit ALSA apps integration.
+  To use the Steam controller, you need to add
+  <programlisting>services.udev.extraRules = ''
+    SUBSYSTEM=="usb", ATTRS{idVendor}=="28de", MODE="0666"
+    KERNEL=="uinput", MODE="0660", GROUP="users", OPTIONS+="static_node=uinput"
+  '';</programlisting>
+  to your configuration.
+</para>
+
+</section>
+
+<section xml:id="sec-steam-troub">
+
+<title>Troubleshooting</title>
+
+<para>
+<variablelist>
+
+  <varlistentry>
+    <term>Steam fails to start. What do I do?</term>
+    <listitem><para>Try to run 
+    <programlisting>strace steam</programlisting>
+    to see what is causing steam to fail.</para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>Game X fails to start</term>
+    <listitem><para>Games may fail to start because they lack 
+    dependencies (this should be added to the script, for now), 
+    or because they cannot be patched.The steps to launch a game 
+    directly are: 
+    <orderedlist>
+    <listitem><para>Patch the script/binary if you can.</para></listitem>
+    <listitem><para>Add a file named <filename>steam_appid.txt</filename> in 
+    the binary folder, with the appid as contents (it can be found in the 
+    stdout from steam).</para></listitem>
+    <listitem><para>Using the LD_LIBRARY_PATH from the nix/store steam script, 
+    with some additions, launch the game binary:
+    <programlisting>LD_LIBRARY_PATH=~/.steam/bin32:$LD_LIBRARY_PATH:/nix/store/pfsa... blabla ...curl-7.29.0/lib:. ./Osmos.bin3
+    </programlisting> (if you could not patchelf the game, call ld.so directly 
+    with the binary as param). With this technique, I can play many games
+    directly from steam. Others, like Team Fortress, cannot be patched
+    so I only managed to run them from the cmd line.
+    </para></listitem>
+    </orderedlist>
+    </para>
+    </listitem>
+  </varlistentry>
+  
+  <varlistentry>
+  <term>Using the FOSS Radeon drivers</term>
+  <listitem><itemizedlist><listitem><para>
+  The open source radeon drivers need a newer libc++ than is provided 
+  by the default runtime, which leads to a crash on launch. Use
+  <programlisting>environment.systemPackages = [(pkgs.steam.override { newStdcpp = true; })];</programlisting>
+  in your config if you get an error like
+  <programlisting>
+libGL error: unable to load driver: radeonsi_dri.so
+libGL error: driver pointer missing
+libGL error: failed to load driver: radeonsi
+libGL error: unable to load driver: swrast_dri.so
+libGL error: failed to load driver: swrast</programlisting></para></listitem>
+  <listitem><para>
+  Steam ships statically linked with a version of libcrypto that
+  conflics with the one dynamically loaded by radeonsi_dri.so.
+  If you get the error
+  <programlisting>steam.sh: line 713: 7842 Segmentation fault (core dumped)</programlisting>
+  have a look at <link xlink:href="https://github.com/NixOS/nixpkgs/pull/20269">this pull request</link>.
+  </para></listitem>
+  </itemizedlist></listitem></varlistentry>
+
+  <varlistentry>
+  <term>Known issues</term>
+  <listitem><orderedlist>
+  <listitem><para>
+  No java in steam chrootenv. Games affected: Towns:
+  <programlisting>/home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found</programlisting>
+  </para></listitem>
+  </orderedlist></listitem></varlistentry>
+
+</variablelist>
+</para>
+
+</section>
+
+</section>
+
 </chapter>