docs: Add some information about mapping non-Haskell dependencies (#200)

Relates to #198

docs/dev/pkg-map.md

@@ -0,0 +1,46 @@
+# Mapping non-Haskell dependencies to Nixpkgs
+
+Cabal files may contain dependencies to external non-Haskell
+dependencies via:
+* [`build-tool-depends`](https://cabal.readthedocs.io/en/latest/developing-packages.html#pkg-field-build-tool-depends) 
+* [`pkgconfig-depends`](https://cabal.readthedocs.io/en/latest/developing-packages.html#pkg-field-pkgconfig-depends).
+* [`frameworks`](https://cabal.readthedocs.io/en/latest/developing-packages.html#pkg-field-frameworks)
+* [`extra-libraries`](https://cabal.readthedocs.io/en/latest/developing-packages.html#pkg-field-extra-libraries)
+
+If there is a `pkgs` attribute in Nixpkgs that matches the name given
+in the Cabal file, then it will be added as a dependency (see the
+output of `cabal-to-nix`). Otherwise, there needs to be a mapping from
+Cabal file names (decided by the package author) to Nix package
+identifiers.
+
+### Nixpkgs overlay
+
+The user may solve it by themself by overriding Nixpkgs and adding a
+package alias. For example:
+
+```nix
+nixpkgs.overlays = [
+  (self: super: {
+    icuuc = self.icu;
+    icui18n = self.icu;
+    icudata = self.icu;
+  })
+];
+```
+
+### Haskell component/package configuration
+
+This is not implemented yet, tracked by issue
+[#198](https://github.com/input-output-hk/haskell.nix/issues/198).
+
+### Mapping in Haskell.nix
+
+Alternatively, if the name is commonly used, an alias can be added to
+the Haskell.nix sources, so that it's solved for all users.
+
+* [`lib/pkgconf-nixpkgs-map.nix`](https://github.com/input-output-hk/haskell.nix/blob/master/lib/pkgconf-nixpkgs-map.nix) - for `pkgconfig-depends`
+* [`lib/system-nixpkgs-map.nix`](https://github.com/input-output-hk/haskell.nix/blob/master/lib/system-nixpkgs-map.nix) - for `build-tool-depends`, `frameworks`, `extra-libraries`, etc.
+
+!!! tip "Open a PR"
+    Please go ahead and open a [pull request](https://github.com/input-output-hk/haskell.nix/pulls)
+    to improve the package mappings.

lib/pkgconf-nixpkgs-map.nix

@@ -1,4 +1,5 @@
 # pkgconfig entries to nixpkgs map
+# See ../docs/dev/pkg-map.md
 pkgs:
   pkgs.lib.mapAttrs (name: value: [ value ]) pkgs //
   {

lib/system-nixpkgs-map.nix

@@ -1,5 +1,6 @@
 # Maps of system pkg refenreces from
 # cabal file to nixpkgs pkgs.
+# See ../docs/dev/pkg-map.md
 pkgs:
 # fetchgit should always come from the buildPackages
 # if it comes from the targetPackages we won't even

mkdocs.yml

@@ -39,8 +39,9 @@ pages:
     - 'IOHKs nix library': iohk-nix.md
   - 'Dev Notes':
     - 'Architecture': dev/dev-architecture.md
-    - 'Removing withPackage wrapper': dev/removing-with-package-wrapper.md
     - 'Maintainer Scripts': dev/maintainer-scripts.md
+    - 'Mapping non-Haskell dependencies to Nixpkgs': dev/pkg-map.md
     - 'Nixpkgs Pin': dev/nixpkgs-pin.md
+    - 'Removing withPackage wrapper': dev/removing-with-package-wrapper.md
     - 'Test Suite': dev/tests.md
   - 'ChangeLog': changelog.md