From 23de67915c0a8957764ffe1726e843bbf6c7c014 Mon Sep 17 00:00:00 2001
From: John Murray <5672686+JRMurr@users.noreply.github.com>
Date: Mon, 11 Dec 2023 22:01:38 -0500
Subject: [PATCH 01/10] add basic flake template to use roc in another project

---
 flake.nix                      | 15 ++++++++++-----
 nix/templates/default.nix      |  6 ++++++
 nix/templates/simple/flake.nix | 34 ++++++++++++++++++++++++++++++++++
 3 files changed, 50 insertions(+), 5 deletions(-)
 create mode 100644 nix/templates/default.nix
 create mode 100644 nix/templates/simple/flake.nix

diff --git a/flake.nix b/flake.nix
index 8652e8f9630..dd6c912fd19 100644
--- a/flake.nix
+++ b/flake.nix
@@ -27,11 +27,16 @@
   };
 
   outputs = { self, nixpkgs, rust-overlay, flake-utils, nixgl, ... }@inputs:
-    let supportedSystems = [ "x86_64-linux" "x86_64-darwin" "aarch64-darwin" "aarch64-linux" ];
-    in flake-utils.lib.eachSystem supportedSystems (system:
+    let
+      supportedSystems = [ "x86_64-linux" "x86_64-darwin" "aarch64-darwin" "aarch64-linux" ];
+
+      templates = import ./nix/templates { };
+    in
+    { inherit templates; } //
+    flake-utils.lib.eachSystem supportedSystems (system:
       let
         overlays = [ (import rust-overlay) ]
-          ++ (if system == "x86_64-linux" then [ nixgl.overlay ] else [ ]);
+        ++ (if system == "x86_64-linux" then [ nixgl.overlay ] else [ ]);
         pkgs = import nixpkgs { inherit system overlays; };
 
         rocBuild = import ./nix { inherit pkgs; };
@@ -105,7 +110,7 @@
 
         devShell = pkgs.mkShell {
           buildInputs = sharedInputs ++ sharedDevInputs ++ darwinInputs ++ darwinDevInputs ++ linuxDevInputs
-            ++ (if system == "x86_64-linux" then
+          ++ (if system == "x86_64-linux" then
             [ pkgs.nixgl.nixVulkanIntel ]
           else
             [ ]);
@@ -121,7 +126,7 @@
           LD_LIBRARY_PATH = with pkgs;
             lib.makeLibraryPath
               ([ pkg-config stdenv.cc.cc.lib libffi ncurses zlib ]
-                ++ linuxDevInputs);
+              ++ linuxDevInputs);
           NIXPKGS_ALLOW_UNFREE =
             1; # to run the GUI examples with NVIDIA's closed source drivers
 
diff --git a/nix/templates/default.nix b/nix/templates/default.nix
new file mode 100644
index 00000000000..fe1e0f21aee
--- /dev/null
+++ b/nix/templates/default.nix
@@ -0,0 +1,6 @@
+{ ... }: {
+  simple = {
+    description = "Basic flake with roc cli + lsp";
+    path = ./simple.nix;
+  };
+}
diff --git a/nix/templates/simple/flake.nix b/nix/templates/simple/flake.nix
new file mode 100644
index 00000000000..38a5f05b1bd
--- /dev/null
+++ b/nix/templates/simple/flake.nix
@@ -0,0 +1,34 @@
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+    roc.url = "github:roc-lang/roc";
+  };
+
+  outputs = { self, nixpkgs, flake-utils, roc, roc2nix, ... }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        pkgs = import nixpkgs { inherit system; };
+
+        rocPkgs = roc.packages.${system};
+
+        rocFull = rocPkgs.full;
+
+      in
+      {
+        formatter = pkgs.nixpkgs-fmt;
+
+        devShells = {
+          default = pkgs.mkShell {
+            buildInputs = with pkgs;
+              [
+                rocFull # cli included in here
+              ];
+
+            shellHook = ''
+              export ROC_LSP_PATH=${rocFull}/bin/roc_ls
+            '';
+          };
+        };
+      });
+}

From 1b45a4b0d4c519599efd0f768ec26f999587f73b Mon Sep 17 00:00:00 2001
From: John Murray <5672686+JRMurr@users.noreply.github.com>
Date: Mon, 11 Dec 2023 22:03:25 -0500
Subject: [PATCH 02/10] fix path

---
 nix/templates/default.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nix/templates/default.nix b/nix/templates/default.nix
index fe1e0f21aee..75052ff9e67 100644
--- a/nix/templates/default.nix
+++ b/nix/templates/default.nix
@@ -1,6 +1,6 @@
 { ... }: {
   simple = {
     description = "Basic flake with roc cli + lsp";
-    path = ./simple.nix;
+    path = ./simple;
   };
 }

From 5a9dfe8f8c41cb282c262ef7fb581da18057c12f Mon Sep 17 00:00:00 2001
From: John Murray <5672686+JRMurr@users.noreply.github.com>
Date: Mon, 11 Dec 2023 22:04:02 -0500
Subject: [PATCH 03/10] update inputs

---
 nix/templates/simple/flake.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nix/templates/simple/flake.nix b/nix/templates/simple/flake.nix
index 38a5f05b1bd..0790595f396 100644
--- a/nix/templates/simple/flake.nix
+++ b/nix/templates/simple/flake.nix
@@ -5,7 +5,7 @@
     roc.url = "github:roc-lang/roc";
   };
 
-  outputs = { self, nixpkgs, flake-utils, roc, roc2nix, ... }:
+  outputs = { self, nixpkgs, flake-utils, roc, ... }:
     flake-utils.lib.eachDefaultSystem (system:
       let
         pkgs = import nixpkgs { inherit system; };

From ce7fb7ec5072738e626117795639a0284fd93430 Mon Sep 17 00:00:00 2001
From: John Murray <5672686+JRMurr@users.noreply.github.com>
Date: Mon, 11 Dec 2023 22:56:02 -0500
Subject: [PATCH 04/10] add basic docs for nix install

---
 getting_started/README.md      |  1 +
 getting_started/nix.md         | 49 ++++++++++++++++++++++++++++++++++
 nix/templates/simple/flake.nix |  1 +
 www/content/install.md         |  3 ++-
 4 files changed, 53 insertions(+), 1 deletion(-)
 create mode 100644 getting_started/nix.md

diff --git a/getting_started/README.md b/getting_started/README.md
index 78cd4b57c33..c3f37301f13 100644
--- a/getting_started/README.md
+++ b/getting_started/README.md
@@ -11,6 +11,7 @@ If you have a specific question, the [FAQ](../FAQ.md) might have an answer, alth
 ## Installation
 
 - [🐧 Linux x86_64](linux_x86_64.md)
+- [❄️ Nix Linux/MacOS](nix.md)
 - [🍏 MacOS Apple Silicon](macos_apple_silicon.md)
 - [🍏 MacOS x86_64](macos_x86_64.md)
 - [🟦 Windows](windows.md)
diff --git a/getting_started/nix.md b/getting_started/nix.md
new file mode 100644
index 00000000000..ecf1a0e7188
--- /dev/null
+++ b/getting_started/nix.md
@@ -0,0 +1,49 @@
+# Roc installation guide for Nix
+
+
+## NixOS quick start
+
+<details>
+<summary>
+
+## Install via Flakes
+
+</summary>
+
+### Bootstrap a project with a template
+
+```shell
+# use the template in the current directory
+nix flake init --template github:roc-lang/roc#simple --refresh
+```
+
+### Add roc to existing flake
+```nix
+{
+    inputs = {
+        roc.url = "github:roc-lang/roc";
+    };
+
+    outputs = {roc,flake-utils, ...}:
+        flake-utils.lib.eachDefaultSystem (system:
+            let
+            pkgs = import nixpkgs { inherit system; };
+
+            rocPkgs = roc.packages.${system};
+            in
+            {
+                devShells = {
+                    default = pkgs.mkShell {
+                        buildInputs = with pkgs;
+                        [
+                            rocPkgs.cli
+                        ];
+                    };
+                };
+            }
+        );
+}
+```
+
+
+</details>
diff --git a/nix/templates/simple/flake.nix b/nix/templates/simple/flake.nix
index 0790595f396..6eca1b290fd 100644
--- a/nix/templates/simple/flake.nix
+++ b/nix/templates/simple/flake.nix
@@ -25,6 +25,7 @@
                 rocFull # cli included in here
               ];
 
+            # ROC_LSP_PATH will be read by https://github.com/ivan-demchenko/roc-vscode-unofficial
             shellHook = ''
               export ROC_LSP_PATH=${rocFull}/bin/roc_ls
             '';
diff --git a/www/content/install.md b/www/content/install.md
index ddaa322cdff..67af6cb5d92 100644
--- a/www/content/install.md
+++ b/www/content/install.md
@@ -5,7 +5,7 @@ Roc is a very young language with many incomplete features and known bugs. It do
 There are currently a few known OS-specific issues:
 * **macOS:** There are no known compatibility issues, but the compiler doesn't run as fast as it does on Linux or Windows, because we don't (yet) do our own linking like we do on those targets. (Linking works similarly on Linux and Windows, but the way macOS does it is both different and significantly more complicated.)
 * **Windows:** There are some known Windows-specific compiler bugs, and probably some other unknown ones because more people have tried out Roc on Mac and Linux than on Windows.
-* **Linux:** The nightlies are built with glibc, so they aren't usable on distros that don't use (dynamically linked) glibc, like Alpine or NixOS. In the future we plan to build Linux releases with [musl libc](https://wiki.musl-libc.org/) to address this, but this requires [building LLVM from source with musl](https://wiki.musl-libc.org/building-llvm.html).
+* **Linux:** The nightlies are built with glibc, so they aren't usable on distros that don't use (dynamically linked) glibc, like Alpine. In the future we plan to build Linux releases with [musl libc](https://wiki.musl-libc.org/) to address this, but this requires [building LLVM from source with musl](https://wiki.musl-libc.org/building-llvm.html).
 * **Other operating systems:** Roc has not been built on any other operating systems. [Building from source](https://github.com/roc-lang/roc/blob/main/BUILDING_FROM_SOURCE.md) on another OS might work, but you might very well be the first person ever to try it!
 
 ### [Getting Started](#getting-started) {#getting-started}
@@ -14,6 +14,7 @@ Here are some Getting Started guides for different operating systems:
 <!-- TODO detect current OS with browser and only show link for that, provide other button for others  -->
 
 - [Linux x86-64](https://github.com/roc-lang/roc/blob/main/getting_started/linux_x86_64.md)
+- [Nix Linux/MacOS](https://github.com/roc-lang/roc/blob/main/getting_started/nix.md)
 - [MacOS Apple Silicon](https://github.com/roc-lang/roc/blob/main/getting_started/macos_apple_silicon.md)
 - [MacOS x86-64](https://github.com/roc-lang/roc/blob/main/getting_started/macos_x86_64.md)
 - [Windows](https://github.com/roc-lang/roc/blob/main/getting_started/windows.md)

From e853d3b5ac3a9841e3b6e529f1fab8320d2aefc0 Mon Sep 17 00:00:00 2001
From: John Murray <5672686+JRMurr@users.noreply.github.com>
Date: Mon, 11 Dec 2023 23:20:28 -0500
Subject: [PATCH 05/10] support nix run and add basic doc

---
 flake.nix              | 7 +++++++
 getting_started/nix.md | 8 ++++++--
 nix/builder.nix        | 9 +++++++++
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/flake.nix b/flake.nix
index dd6c912fd19..fb89ed4c559 100644
--- a/flake.nix
+++ b/flake.nix
@@ -148,5 +148,12 @@
           cli = rocBuild.roc-cli;
           lang-server = rocBuild.roc-lang-server;
         };
+
+        apps = {
+          default = {
+            type = "app";
+            program = "${rocBuild.roc-cli}/bin/roc";
+          };
+        };
       });
 }
diff --git a/getting_started/nix.md b/getting_started/nix.md
index ecf1a0e7188..91809839ff2 100644
--- a/getting_started/nix.md
+++ b/getting_started/nix.md
@@ -1,7 +1,11 @@
 # Roc installation guide for Nix
 
-
-## NixOS quick start
+If you want to quickly get started you can do
+```shell
+nix run roc-lang/roc -- <roc args>
+# example nix run roc-lang/roc -- repl
+```
+to try out roc!
 
 <details>
 <summary>
diff --git a/nix/builder.nix b/nix/builder.nix
index 4038a1bfbe8..265df5a310a 100644
--- a/nix/builder.nix
+++ b/nix/builder.nix
@@ -3,6 +3,8 @@ let
   inherit (compile-deps) zigPkg llvmPkgs llvmVersion llvmMajorMinorStr glibcPath libGccSPath;
 
   subPackagePath = if subPackage != null then "crates/${subPackage}" else null;
+
+  mainBin = if subPackage == "lang_srv" then "roc_ls" else "roc";
 in
 rustPlatform.buildRustPackage {
   pname = "roc" + lib.optionalString (subPackage != null) "_${subPackage}";
@@ -84,4 +86,11 @@ rustPlatform.buildRustPackage {
         ${wrapRoc}
       fi
     '';
+
+  # https://ryantm.github.io/nixpkgs/stdenv/meta/
+  meta = {
+    homepage = "https://www.roc-lang.org/";
+    license = lib.licenses.upl;
+    mainProgram = mainBin;
+  };
 }

From 7075bd6049e9ed522fab9f771863359f628b1392 Mon Sep 17 00:00:00 2001
From: John Murray <5672686+JRMurr@users.noreply.github.com>
Date: Mon, 11 Dec 2023 23:23:23 -0500
Subject: [PATCH 06/10] update wording

---
 getting_started/nix.md | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/getting_started/nix.md b/getting_started/nix.md
index 91809839ff2..c69f8db10ee 100644
--- a/getting_started/nix.md
+++ b/getting_started/nix.md
@@ -1,11 +1,10 @@
 # Roc installation guide for Nix
 
-If you want to quickly get started you can do
+To quickly try out roc, use `nix run`
 ```shell
 nix run roc-lang/roc -- <roc args>
 # example nix run roc-lang/roc -- repl
 ```
-to try out roc!
 
 <details>
 <summary>
@@ -25,14 +24,15 @@ nix flake init --template github:roc-lang/roc#simple --refresh
 ```nix
 {
     inputs = {
+        nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+        flake-utils.url = "github:numtide/flake-utils";
         roc.url = "github:roc-lang/roc";
     };
 
-    outputs = {roc,flake-utils, ...}:
+    outputs = {nixpkgs, roc, flake-utils, ...}:
         flake-utils.lib.eachDefaultSystem (system:
             let
             pkgs = import nixpkgs { inherit system; };
-
             rocPkgs = roc.packages.${system};
             in
             {
@@ -49,5 +49,4 @@ nix flake init --template github:roc-lang/roc#simple --refresh
 }
 ```
 
-
 </details>

From 7397245836064106d0f816dcddd9d57f561c0af2 Mon Sep 17 00:00:00 2001
From: John Murray <5672686+JRMurr@users.noreply.github.com>
Date: Mon, 11 Dec 2023 23:52:34 -0500
Subject: [PATCH 07/10] update default nix

---
 default.nix               | 2 +-
 nix/templates/default.nix | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/default.nix b/default.nix
index f05dbb5e430..3aa2e0bace8 100644
--- a/default.nix
+++ b/default.nix
@@ -1,4 +1,4 @@
-(import
+{ ... }: (import
   (
     let lock = builtins.fromJSON (builtins.readFile ./flake.lock);
     in fetchTarball {
diff --git a/nix/templates/default.nix b/nix/templates/default.nix
index 75052ff9e67..fe1e7ea98b9 100644
--- a/nix/templates/default.nix
+++ b/nix/templates/default.nix
@@ -1,4 +1,5 @@
-{ ... }: {
+{ ... }: rec {
+  default = simple;
   simple = {
     description = "Basic flake with roc cli + lsp";
     path = ./simple;

From 0066e660514a8a1b77d98125e6b2a1163d50b645 Mon Sep 17 00:00:00 2001
From: John Murray <5672686+JRMurr@users.noreply.github.com>
Date: Thu, 14 Dec 2023 18:39:33 -0500
Subject: [PATCH 08/10] remove summary tag

---
 getting_started/nix.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/getting_started/nix.md b/getting_started/nix.md
index c69f8db10ee..253d5e27e8f 100644
--- a/getting_started/nix.md
+++ b/getting_started/nix.md
@@ -6,12 +6,8 @@ nix run roc-lang/roc -- <roc args>
 # example nix run roc-lang/roc -- repl
 ```
 
-<details>
-<summary>
-
 ## Install via Flakes
 
-</summary>
 
 ### Bootstrap a project with a template
 

From 5a3761f1a16a2fd951ecd987f9c91fb30a3b4c0a Mon Sep 17 00:00:00 2001
From: John Murray <5672686+JRMurr@users.noreply.github.com>
Date: Thu, 14 Dec 2023 18:46:00 -0500
Subject: [PATCH 09/10] small cleanup

---
 default.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/default.nix b/default.nix
index 3aa2e0bace8..f05dbb5e430 100644
--- a/default.nix
+++ b/default.nix
@@ -1,4 +1,4 @@
-{ ... }: (import
+(import
   (
     let lock = builtins.fromJSON (builtins.readFile ./flake.lock);
     in fetchTarball {

From 7aa01fa0e10b8f9f7ed6d0c39e4d630b33f4184d Mon Sep 17 00:00:00 2001
From: Anton-4 <17049058+Anton-4@users.noreply.github.com>
Date: Fri, 15 Dec 2023 15:38:45 +0100
Subject: [PATCH 10/10] minor improvements

---
 getting_started/nix.md         | 18 +++++++++---------
 nix/templates/simple/flake.nix |  7 +++++--
 www/content/install.md         |  2 +-
 3 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/getting_started/nix.md b/getting_started/nix.md
index 253d5e27e8f..51bfce72460 100644
--- a/getting_started/nix.md
+++ b/getting_started/nix.md
@@ -1,15 +1,17 @@
-# Roc installation guide for Nix
+## Try out
 
-To quickly try out roc, use `nix run`
+To quickly try out roc without installing, use `nix run`:
 ```shell
 nix run roc-lang/roc -- <roc args>
-# example nix run roc-lang/roc -- repl
+# examples:
+# - nix run roc-lang/roc -- repl
+# - nix run roc-lang/roc -- dev main.roc
 ```
 
-## Install via Flakes
+## Use with Flakes
 
 
-### Bootstrap a project with a template
+### Start your project with our template
 
 ```shell
 # use the template in the current directory
@@ -28,8 +30,8 @@ nix flake init --template github:roc-lang/roc#simple --refresh
     outputs = {nixpkgs, roc, flake-utils, ...}:
         flake-utils.lib.eachDefaultSystem (system:
             let
-            pkgs = import nixpkgs { inherit system; };
-            rocPkgs = roc.packages.${system};
+                pkgs = import nixpkgs { inherit system; };
+                rocPkgs = roc.packages.${system};
             in
             {
                 devShells = {
@@ -44,5 +46,3 @@ nix flake init --template github:roc-lang/roc#simple --refresh
         );
 }
 ```
-
-</details>
diff --git a/nix/templates/simple/flake.nix b/nix/templates/simple/flake.nix
index 6eca1b290fd..244687c428e 100644
--- a/nix/templates/simple/flake.nix
+++ b/nix/templates/simple/flake.nix
@@ -1,4 +1,6 @@
 {
+  description = "Roc flake template";
+
   inputs = {
     nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
     flake-utils.url = "github:numtide/flake-utils";
@@ -10,6 +12,7 @@
       let
         pkgs = import nixpkgs { inherit system; };
 
+        # see "packages =" in https://github.com/roc-lang/roc/blob/main/flake.nix
         rocPkgs = roc.packages.${system};
 
         rocFull = rocPkgs.full;
@@ -22,10 +25,10 @@
           default = pkgs.mkShell {
             buildInputs = with pkgs;
               [
-                rocFull # cli included in here
+                rocFull # includes CLI
               ];
 
-            # ROC_LSP_PATH will be read by https://github.com/ivan-demchenko/roc-vscode-unofficial
+            # For vscode plugin https://github.com/ivan-demchenko/roc-vscode-unofficial
             shellHook = ''
               export ROC_LSP_PATH=${rocFull}/bin/roc_ls
             '';
diff --git a/www/content/install.md b/www/content/install.md
index 67af6cb5d92..fb267ef15d0 100644
--- a/www/content/install.md
+++ b/www/content/install.md
@@ -5,7 +5,7 @@ Roc is a very young language with many incomplete features and known bugs. It do
 There are currently a few known OS-specific issues:
 * **macOS:** There are no known compatibility issues, but the compiler doesn't run as fast as it does on Linux or Windows, because we don't (yet) do our own linking like we do on those targets. (Linking works similarly on Linux and Windows, but the way macOS does it is both different and significantly more complicated.)
 * **Windows:** There are some known Windows-specific compiler bugs, and probably some other unknown ones because more people have tried out Roc on Mac and Linux than on Windows.
-* **Linux:** The nightlies are built with glibc, so they aren't usable on distros that don't use (dynamically linked) glibc, like Alpine. In the future we plan to build Linux releases with [musl libc](https://wiki.musl-libc.org/) to address this, but this requires [building LLVM from source with musl](https://wiki.musl-libc.org/building-llvm.html).
+* **Linux:** The nightlies are built with glibc, so they aren't usable on distros that don't use glibc, like Alpine. In the future we plan to build Linux releases with [musl libc](https://wiki.musl-libc.org/) to address this, but this requires [building LLVM from source with musl](https://wiki.musl-libc.org/building-llvm.html).
 * **Other operating systems:** Roc has not been built on any other operating systems. [Building from source](https://github.com/roc-lang/roc/blob/main/BUILDING_FROM_SOURCE.md) on another OS might work, but you might very well be the first person ever to try it!
 
 ### [Getting Started](#getting-started) {#getting-started}