2 files changed, 36 insertions, 6 deletions
diff --git a/doc/languages-frameworks/android.section.md b/doc/languages-frameworks/android.section.md
index 237f3441874f0..f268c55256602 100644
--- a/doc/languages-frameworks/android.section.md
+++ b/doc/languages-frameworks/android.section.md
@@ -185,10 +185,9 @@ with import <nixpkgs> {};
 
 androidenv.emulateApp {
   name = "emulate-MyAndroidApp";
-  platformVersion = "24";
-  abiVersion = "armeabi-v7a"; # mips, x86 or x86_64
-  systemImageType = "default";
-  useGoogleAPIs = false;
+  platformVersion = "28";
+  abiVersion = "x86_64"; # armeabi-v7a, mips, x86
+  systemImageType = "google_apis_playstore";
 }
 ```
 
@@ -201,7 +200,7 @@ with import <nixpkgs> {};
 androidenv.emulateApp {
   name = "emulate-MyAndroidApp";
   platformVersion = "24";
-  abiVersion = "armeabi-v7a"; # mips, x86 or x86_64
+  abiVersion = "armeabi-v7a"; # mips, x86, x86_64
   systemImageType = "default";
   useGoogleAPIs = false;
   app = ./MyApp.apk;
diff --git a/doc/languages-frameworks/perl.xml b/doc/languages-frameworks/perl.xml
index d0f124f29d422..065212a0e1807 100644
--- a/doc/languages-frameworks/perl.xml
+++ b/doc/languages-frameworks/perl.xml
@@ -75,7 +75,8 @@ foo = import ../path/to/foo.nix {
      It adds the contents of the <envar>PERL5LIB</envar> environment variable
      to <literal>#! .../bin/perl</literal> line of Perl scripts as
      <literal>-I<replaceable>dir</replaceable></literal> flags. This ensures
-     that a script can find its dependencies.
+     that a script can find its dependencies. (This can cause this shebang line
+     to become too long for Darwin to handle; see the note below.)
     </para>
    </listitem>
    <listitem>
@@ -137,6 +138,36 @@ ClassC3Componentised = buildPerlPackage rec {
 </programlisting>
  </para>
 
+ <para>
+  On Darwin, if a script has too many
+  <literal>-I<replaceable>dir</replaceable></literal> flags in its first line
+  (its “shebang line”), it will not run. This can be worked around by calling
+  the <literal>shortenPerlShebang</literal> function from the
+  <literal>postInstall</literal> phase:
+<programlisting>
+{ stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
+
+ImageExifTool = buildPerlPackage {
+  pname = "Image-ExifTool";
+  version = "11.50";
+
+  src = fetchurl {
+    url = "https://www.sno.phy.queensu.ca/~phil/exiftool/Image-ExifTool-11.50.tar.gz";
+    sha256 = "0d8v48y94z8maxkmw1rv7v9m0jg2dc8xbp581njb6yhr7abwqdv3";
+  };
+
+  buildInputs = stdenv.lib.optional stdenv.isDarwin shortenPerlShebang;
+  postInstall = stdenv.lib.optional stdenv.isDarwin ''
+    shortenPerlShebang $out/bin/exiftool
+  '';
+};
+</programlisting>
+ This will remove the <literal>-I</literal> flags from the shebang line,
+ rewrite them in the <literal>use lib</literal> form, and put them on the next
+ line instead. This function can be given any number of Perl scripts as
+ arguments; it will modify them in-place.
+ </para>
+
  <section xml:id="ssec-generation-from-CPAN">
   <title>Generation from CPAN</title>