From f5f7eb10bca8293849b45bba9c2697dfbb6deaf5 Mon Sep 17 00:00:00 2001
From: Evan Hanson <evhan@foldling.org>
Date: Thu, 24 Nov 2022 10:26:23 +1300
Subject: [PATCH] Add examples of linking to external libraries with Nix
 helpers

---
 nix.md | 47 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/nix.md b/nix.md
index 9d9e30c..4aa6406 100644
--- a/nix.md
+++ b/nix.md
@@ -10,7 +10,7 @@ The helpers can be imported directly from the Git repository archive:
 This library only includes two attributes, so it's also relatively harmless to
 pull into scope, for example:
 
-    with import (fetchTarball https://git.sr.ht/~evhan/beaker/archive/6836a7bf.tar.gz) {};
+    with import (fetchTarball https://git.sr.ht/~evhan/beaker/archive/e9a0d500.tar.gz) {};
 
     eggProgram {
       name = "example";
@@ -132,6 +132,51 @@ whenever the current source directory changes.
         buildInputs = [ compiledEggs ];
       }
 
+==== Linking With External Libraries
+
+When linking to external libraries, it's usually enough to use
+`buildInputs`. This can either be done when compiling the egg itself, or
+when building a program that uses the egg sources.
+
+For example, to build a program using the openssl egg, you can either
+build the program and its dependencies (including the OpenSSL library)
+from source all at once, or you can compile the openssl egg first, then
+link to the result. In either case, the `openssl` package should be
+provided in `buildInputs` when building the egg:
+
+    let
+      opensslEggDependencies = [ pkgs.openssl pkgs.pkg-config ];
+      opensslEggSources = eggCache {
+        hash = "sha256-RCjCBvKOFmz92RIP1lP0svxjAC00gAmOLdeAB9PxE+8=";
+        eggs = [
+          { name = "openssl"; version = "2.2.4"; }
+          { name = "srfi-18"; version = "0.1.6"; }
+          { name = "address-info"; version = "1.0.5"; }
+          { name = "srfi-1"; version = "0.5.1"; }
+          { name = "srfi-14"; version = "0.2.1"; }
+          { name = "srfi-13"; version = "0.3.3"; }
+        ];
+      };
+      compiledOpensslEgg = eggRepository {
+        src = opensslEggSources;
+        buildInputs = opensslEggDependencies;
+      };
+    in {
+      # build a program using the openssl egg sources
+      fromSourceEgg = eggProgram {
+        name = "example-from-source";
+        src = ./.;
+        eggCache = opensslEggSources;
+        buildInputs = opensslEggDependencies;
+      };
+      # build a program linking to the compiled openssl egg
+      fromCompiledEgg = eggProgram {
+        name = "example-from-compiled";
+        src = ./.;
+        buildInputs = [ compiledOpensslEgg ];
+      };
+    }
+
 === Development Shell
 
 When using `eggProgram`, the `nix develop` command will start a development
-- 
2.38.5