Merge master into staging-next

3 files changed, 115 insertions, 39 deletions

diff --git a/doc/languages-frameworks/idris.section.md b/doc/languages-frameworks/idris.section.md
index 005ed360285..50979d76d98 100644
--- a/doc/languages-frameworks/idris.section.md
+++ b/doc/languages-frameworks/idris.section.md
@@ -1,39 +1,115 @@
-Idris packages
-==============
+# Idris packages
 
-This directory contains build rules for idris packages. In addition,
-it contains several functions to build and compose those packages.
-Everything is exposed to the user via the `idrisPackages` attribute.
+## Installing Idris
 
-callPackage
-------------
+The easiest way to get a working idris version is to install the `idris` attribute:
 
-This is like the normal nixpkgs callPackage function, specialized to
-idris packages.
+```
+$ # On NixOS
+$ nix-env -i nixos.idris
+$ # On non-NixOS
+$ nix-env -i nixpkgs.idris
+```
 
-builtins
----------
+This however only provides the `prelude` and `base` libraries. To install additional libraries:
 
-This is a list of all of the libraries that come packaged with Idris
-itself.
+```
+$ nix-env -iE 'pkgs: pkgs.idrisPackages.with-packages (with pkgs.idrisPackages; [ contrib pruviloj ])'
+```
 
-build-idris-package
---------------------
+To see all available Idris packages:
+```
+$ # On NixOS
+$ nix-env -qaPA nixos.idrisPackages
+$ # On non-NixOS
+$ nix-env -qaPA nixpkgs.idrisPackages
+```
 
-A function to build an idris package. Its sole argument is a set like
-you might pass to `stdenv.mkDerivation`, except `build-idris-package`
-sets several attributes for you. See `build-idris-package.nix` for
-details.
+Similarly, entering a `nix-shell`:
+```
+$ nix-shell -p 'idrisPackages.with-packages (with idrisPackages; [ contrib pruviloj ])'
+```
 
-build-builtin-package
-----------------------
+## Starting Idris with library support
 
-A version of `build-idris-package` specialized to builtin libraries.
-Mostly for internal use.
+To have access to these libraries in idris, call it with an argument `-p <library name>` for each library:
 
-with-packages
--------------
+```
+$ nix-shell -p 'idrisPackages.with-packages (with idrisPackages; [ contrib pruviloj ])'
+[nix-shell:~]$ idris -p contrib -p pruviloj
+```
 
-Bundle idris together with a list of packages. Because idris currently
-only supports a single directory in its library path, you must include
-all desired libraries here, including `prelude` and `base`.
\ No newline at end of file
+A listing of all available packages the Idris binary has access to is available via `--listlibs`:
+
+```
+$ idris --listlibs
+00prelude-idx.ibc
+pruviloj
+base
+contrib
+prelude
+00pruviloj-idx.ibc
+00base-idx.ibc
+00contrib-idx.ibc
+```
+
+## Building an Idris project with Nix
+
+As an example of how a Nix expression for an Idris package can be created, here is the one for `idrisPackages.yaml`:
+
+```nix
+{ build-idris-package
+, fetchFromGitHub
+, contrib
+, lightyear
+, lib
+}:
+build-idris-package  {
+  name = "yaml";
+  version = "2018-01-25";
+
+  # This is the .ipkg file that should be built, defaults to the package name
+  # In this case it should build `Yaml.ipkg` instead of `yaml.ipkg`
+  # This is only necessary because the yaml packages ipkg file is
+  # different from its package name here.
+  ipkgName = "Yaml";
+  # Idris dependencies to provide for the build
+  idrisDeps = [ contrib lightyear ];
+
+  src = fetchFromGitHub {
+    owner = "Heather";
+    repo = "Idris.Yaml";
+    rev = "5afa51ffc839844862b8316faba3bafa15656db4";
+    sha256 = "1g4pi0swmg214kndj85hj50ccmckni7piprsxfdzdfhg87s0avw7";
+  };
+
+  meta = {
+    description = "Idris YAML lib";
+    homepage = https://github.com/Heather/Idris.Yaml;
+    license = lib.licenses.mit;
+    maintainers = [ lib.maintainers.brainrape ];
+  };
+}
+```
+
+Assuming this file is saved as `yaml.nix`, it's buildable using
+
+```
+$ nix-build -E '(import <nixpkgs> {}).idrisPackages.callPackage ./yaml.nix {}'
+```
+
+Or it's possible to use
+
+```nix
+with import <nixpkgs> {};
+
+{
+  yaml = idrisPackages.callPackage ./yaml.nix {};
+}
+```
+
+in another file (say `default.nix`) to be able to build it with
+
+```
+$ nix-build -A yaml
+```
diff --git a/doc/languages-frameworks/node.section.md b/doc/languages-frameworks/node.section.md
index f6701c1ab9c..c6dce04c7b8 100644
--- a/doc/languages-frameworks/node.section.md
+++ b/doc/languages-frameworks/node.section.md
@@ -14,7 +14,7 @@ project.
 
 The package set also provides support for multiple Node.js versions. The policy
 is that a new package should be added to the collection for the latest stable LTS
-release (which is currently 8.x), unless there is an explicit reason to support
+release (which is currently 10.x), unless there is an explicit reason to support
 a different release.
 
 If your package uses native addons, you need to examine what kind of native
@@ -26,7 +26,7 @@ build system it uses. Here are some examples:
 
 After you have identified the correct system, you need to override your package
 expression while adding in build system as a build input. For example, `dat`
-requires `node-gyp-build`, so we override its expression in `default-v8.nix`:
+requires `node-gyp-build`, so we override its expression in `default-v10.nix`:
 
 ```nix
 dat = nodePackages.dat.override (oldAttrs: {
@@ -36,9 +36,9 @@ dat = nodePackages.dat.override (oldAttrs: {
 
 To add a package from NPM to nixpkgs:
 
- 1. Modify `pkgs/development/node-packages/node-packages-v8.json` to add, update
-    or remove package entries. (Or `pkgs/development/node-packages/node-packages-v10.json`
-    for packages depending on Node.js 10.x)
+ 1. Modify `pkgs/development/node-packages/node-packages-v10.json` to add, update
+    or remove package entries. (Or `pkgs/development/node-packages/node-packages-v8.json`
+    for packages depending on Node.js 8.x)
  2. Run the script: `(cd pkgs/development/node-packages && ./generate.sh)`.
  3. Build your new package to test your changes:
     `cd /path/to/nixpkgs && nix-build -A nodePackages.<new-or-updated-package>`.
diff --git a/doc/stdenv.xml b/doc/stdenv.xml
index ef45ec301a6..d27adc0de5a 100644
--- a/doc/stdenv.xml
+++ b/doc/stdenv.xml
@@ -2077,7 +2077,7 @@ someVar=$(stripHash $name)
    Nix itself considers a build-time dependency merely something that should
    previously be built and accessible at build time—packages themselves are
    on their own to perform any additional setup. In most cases, that is fine,
-   and the downstream derivation can deal with it's own dependencies. But for a
+   and the downstream derivation can deal with its own dependencies. But for a
    few common tasks, that would result in almost every package doing the same
    sort of setup work---depending not on the package itself, but entirely on
    which dependencies were used.
@@ -2131,10 +2131,10 @@ someVar=$(stripHash $name)
    <literal>n + 1</literal> dependencies, as only those ones match the
    compiler's target platform. The <envar>hostOffset</envar> variable is
    defined with the current dependency's host offset
-   <envar>targetOffset</envar> with its target offset, before it's setup hook
-   is sourced. Additionally, since most environment hooks don't care about the
-   target platform, That means the setup hook can append to the right bash
-   array by doing something like
+   <envar>targetOffset</envar> with its target offset, before its setup hook is
+   sourced. Additionally, since most environment hooks don't care about the
+   target platform, That means the setup hook can append to the right bash array
+   by doing something like
 <programlisting language="bash">
 addEnvHooks "$hostOffset" myBashFunction
   </programlisting>
@@ -2142,7 +2142,7 @@ addEnvHooks "$hostOffset" myBashFunction
 
   <para>
    The <emphasis>existence</emphasis> of setups hooks has long been documented
-   and packages inside Nixpkgs are free to use these mechanism. Other packages,
+   and packages inside Nixpkgs are free to use this mechanism. Other packages,
    however, should not rely on these mechanisms not changing between Nixpkgs
    versions. Because of the existing issues with this system, there's little
    benefit from mandating it be stable for any period of time.