Merge pull request #60 from adisbladis/getting-started-docs

Add getting started docs

.github/workflows/ci.yml

@@ -14,8 +14,8 @@ jobs:
     env:
       NIX_PATH: "nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-unstable.tar.gz"
     steps:
-    - uses: cachix/install-nix-action@v12
-    - uses: actions/checkout@v1
+    - uses: cachix/install-nix-action@v17
+    - uses: actions/checkout@v3
     - name: Check format
       run: nix-shell --run 'nixpkgs-fmt --check .'
 
@@ -24,8 +24,8 @@ jobs:
     env:
       NIX_PATH: "nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-unstable.tar.gz"
     steps:
-    - uses: cachix/install-nix-action@v12
-    - uses: actions/checkout@v1
+    - uses: cachix/install-nix-action@v17
+    - uses: actions/checkout@v3
     - name: Check format
       run: nix-shell --run 'golangci-lint run'
 
@@ -34,8 +34,8 @@ jobs:
     env:
       NIX_PATH: "nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-unstable.tar.gz"
     steps:
-    - uses: cachix/install-nix-action@v12
-    - uses: actions/checkout@v1
+    - uses: cachix/install-nix-action@v17
+    - uses: actions/checkout@v3
     - name: "Build gomod2nix"
       run: nix-shell --run "go build"
     - name: Run gomod2nix

README.md

@@ -25,6 +25,8 @@ in pkgs.buildGoApplication {
 }
 ```
 
+For more in-depth usage check the [Getting Started](./docs/getting-started.md) docs.
+
 ## FAQ
 
 ### Why not continue work on vgo2nix?
@@ -36,6 +38,10 @@ We need a better build abstraction that takes Go modules into account, while rem
 
 Yes. Once the API is considered stable.
 
+## Motivation
+
+The [announcement blog post](https://www.tweag.io/blog/2021-03-04-gomod2nix/) contains comparisons with other Go build systems for Nix and additional notes on the design choices made.
+
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE)

docs/getting-started.md

@@ -0,0 +1,79 @@
+# Getting started with Gomod2nix
+
+## Installation
+
+### Using Niv
+
+First initialize Niv:
+``` bash
+$ niv init --latest
+$ niv add tweag/gomod2nix
+```
+
+Create a `shell.nix` used for development:
+``` nix
+{ pkgs ? (
+    let
+      sources = import ./nix/sources.nix;
+    in
+    import sources.nixpkgs {
+      overlays = [
+        (import "${sources.gomod2nix}/overlay.nix")
+      ];
+    }
+  )
+}:
+
+let
+  goEnv = pkgs.mkGoEnv { pwd = ./.; };
+in
+pkgs.mkShell {
+  packages = [
+    goEnv
+    pkgs.gomod2nix
+    pkgs.niv
+  ];
+}
+```
+
+And a `default.nix` for building your package
+``` nix
+{ pkgs ? (
+    let
+      sources = import ./nix/sources.nix;
+    in
+    import sources.nixpkgs {
+      overlays = [
+        (import "${sources.gomod2nix}/overlay.nix")
+      ];
+    }
+  )
+}:
+
+pkgs.buildGoApplication {
+  pname = "myapp";
+  version = "0.1";
+  pwd = ./.;
+  src = ./.;
+  modules = ./gomod2nix.toml;
+}
+```
+
+### Using Flakes
+
+The quickest way to get started if using Nix Flakes is to use the Flake template:
+``` bash
+$ nix flake init -t github:tweag/gomod2nix#app
+```
+
+## Basic usage
+
+After you have entered your development shell you can generate a `gomod2nix.toml` using:
+``` bash
+$ gomod2nix generate
+```
+
+To speed up development and avoid downloading dependencies again in the Nix store you can import them directly from the Go cache using:
+``` bash
+$ gomod2nix import
+```

shell.nix

@@ -1,14 +1,8 @@
 { pkgs ? (
     let
-      inherit (builtins) fromJSON readFile;
-      flakeLock = fromJSON (readFile ./flake.lock);
-      locked = flakeLock.nodes.nixpkgs.locked;
-      nixpkgs = assert locked.type == "github"; builtins.fetchTarball {
-        url = "https://github.com/${locked.owner}/${locked.repo}/archive/${locked.rev}.tar.gz";
-        sha256 = locked.narHash;
-      };
+      inherit (builtins) fetchTree fromJSON readFile;
     in
-    import nixpkgs {
+    import (fetchTree (fromJSON (readFile ./flake.lock)).nodes.nixpkgs.locked) {
       overlays = [
         (import ./overlay.nix)
       ];

templates/app/default.nix

@@ -1,10 +1,20 @@
-{ buildGoApplication, go, lib }:
+{ pkgs ? (
+    let
+      inherit (builtins) fetchTree fromJSON readFile;
+      inherit ((fromJSON (readFile ./flake.lock)).nodes) nixpkgs gomod2nix;
+    in
+    import (fetchTree nixpkgs.locked) {
+      overlays = [
+        (import "${fetchTree gomod2nix.locked}/overlay.nix")
+      ];
+    }
+  )
+}:
 
-buildGoApplication {
-  inherit go;
+pkgs.buildGoApplication {
   pname = "myapp";
   version = "0.1";
+  pwd = ./.;
   src = ./.;
   modules = ./gomod2nix.toml;
-  subPackages = [ "." ];
 }

templates/app/shell.nix

@@ -1,8 +1,22 @@
-{ pkgs ? import <nixpkgs> { } }:
+{ pkgs ? (
+    let
+      inherit (builtins) fetchTree fromJSON readFile;
+      inherit ((fromJSON (readFile ./flake.lock)).nodes) nixpkgs gomod2nix;
+    in
+    import (fetchTree nixpkgs.locked) {
+      overlays = [
+        (import "${fetchTree gomod2nix.locked}/overlay.nix")
+      ];
+    }
+  )
+}:
 
+let
+  goEnv = pkgs.mkGoEnv { pwd = ./.; };
+in
 pkgs.mkShell {
   packages = [
-    pkgs.go
+    goEnv
     pkgs.gomod2nix
   ];
 }