From 234e9e091dcbec0d86f5e9d7c09136e838bcdc91 Mon Sep 17 00:00:00 2001
From: Rodney Lorrimar <rodney.lorrimar@iohk.io>
Date: Sat, 13 Jul 2019 17:54:53 +1000
Subject: [PATCH] docs: Add some information about mapping non-Haskell
 dependencies (#200)

Relates to #198
---
 docs/dev/pkg-map.md         | 46 +++++++++++++++++++++++++++++++++++++
 lib/pkgconf-nixpkgs-map.nix |  1 +
 lib/system-nixpkgs-map.nix  |  1 +
 mkdocs.yml                  |  3 ++-
 4 files changed, 50 insertions(+), 1 deletion(-)
 create mode 100644 docs/dev/pkg-map.md

diff --git a/docs/dev/pkg-map.md b/docs/dev/pkg-map.md
new file mode 100644
index 0000000000..36f16670b9
--- /dev/null
+++ b/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.
diff --git a/lib/pkgconf-nixpkgs-map.nix b/lib/pkgconf-nixpkgs-map.nix
index 7eb497686e..17f24ff01c 100644
--- a/lib/pkgconf-nixpkgs-map.nix
+++ b/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 //
   {
diff --git a/lib/system-nixpkgs-map.nix b/lib/system-nixpkgs-map.nix
index f57363a0f2..89a447f069 100644
--- a/lib/system-nixpkgs-map.nix
+++ b/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
diff --git a/mkdocs.yml b/mkdocs.yml
index 115fc7fe67..4d87df20a4 100644
--- a/mkdocs.yml
+++ b/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