From f3d11714540280b83c6af3028a8ea8661571acca Mon Sep 17 00:00:00 2001
From: Brian Goff <cpuguy83@gmail.com>
Date: Thu, 11 Apr 2024 21:33:51 +0000
Subject: [PATCH] Update docs reflect gomod generator feature

Signed-off-by: Brian Goff <cpuguy83@gmail.com>
---
 docs/examples/go-md2man-1.yml |  1 +
 docs/examples/go-md2man-2.yml | 22 +++------------
 docs/intro.md                 | 51 ++++++++++++++++++++++++++++++++++-
 3 files changed, 54 insertions(+), 20 deletions(-)

diff --git a/docs/examples/go-md2man-1.yml b/docs/examples/go-md2man-1.yml
index 4142df3a3..2a70920c6 100644
--- a/docs/examples/go-md2man-1.yml
+++ b/docs/examples/go-md2man-1.yml
@@ -1,6 +1,7 @@
 # syntax=ghcr.io/azure/dalec/frontend:latest
 name: go-md2man
 version: 2.0.3
+revision: "1"
 packager: Dalec Example
 vendor: Dalec Example
 license: MIT
diff --git a/docs/examples/go-md2man-2.yml b/docs/examples/go-md2man-2.yml
index 771dd23fd..ef3ac442d 100644
--- a/docs/examples/go-md2man-2.yml
+++ b/docs/examples/go-md2man-2.yml
@@ -1,6 +1,7 @@
 # syntax=ghcr.io/azure/dalec/frontend:latest
 name: go-md2man
 version: 2.0.3
+revision: "1"
 packager: Dalec Example
 vendor: Dalec Example
 license: MIT
@@ -9,27 +10,11 @@ website: https://github.com/cpuguy83/go-md2man
 
 sources:
   src:
+    generators:
+      - gomod
     git:
       url: https://github.com/cpuguy83/go-md2man.git
       commit: "v2.0.3"
-  gomods: # This is required when the build environment does not allow network access. This downloads all the go modules.
-    path: /build/gomodcache # This is the path we will be extracing after running the command below.
-    image:
-      ref: mcr.microsoft.com/oss/go/microsoft/golang:1.21
-      cmd:
-        dir: /build/src
-        mounts:
-          # Mount a source (inline, under `spec`), so our command has access to it.
-          - dest: /build/src
-            spec:
-              git:
-                url: https://github.com/cpuguy83/go-md2man.git
-                commit: "v2.0.3"
-        steps:
-          - command: go mod download
-            env:
-              # This variable controls where the go modules are downloaded to.
-              GOMODCACHE: /build/gomodcache
 
 dependencies:
   build:
@@ -40,7 +25,6 @@ build:
     CGO_ENABLED: "0"
   steps:
     - command: |
-        export GOMODCACHE="$(pwd)/gomods"
         cd src
         go build -o go-md2man .
 
diff --git a/docs/intro.md b/docs/intro.md
index 3631473ae..c12b2566c 100644
--- a/docs/intro.md
+++ b/docs/intro.md
@@ -27,6 +27,7 @@ In this examnple wee'll build a virtual package that just installs other package
 # syntax=ghcr.io/azure/dalec/frontend:latest
 name: my-package
 version: 1.0.0
+revision: "1"
 packager: Contoso
 vendor: Contoso
 license: MIT
@@ -61,6 +62,7 @@ as the base image which includes a shell and other tools.
 # syntax=ghcr.io/azure/dalec/frontend:latest
 name: my-package
 version: 1.0.0
+revision: "1"
 packager: Contoso
 vendor: Contoso
 license: MIT
@@ -130,6 +132,7 @@ It will use the `go-md2man` repo and build the `go-md2man` from the v2.0.3 tag i
 # syntax=ghcr.io/azure/dalec/frontend:latest
 name: go-md2man
 version: 2.0.3
+revision: "1"
 packager: Dalec Example
 vendor: Dalec Example
 license: MIT
@@ -151,7 +154,6 @@ build:
     CGO_ENABLED: "0"
   steps:
     - command: |
-        export GOMODCACHE="$(pwd)/gomods"
         cd src
         go build -o go-md2man .
 
@@ -194,6 +196,7 @@ go modules from the resulting filesystem.
 # syntax=ghcr.io/azure/dalec/frontend:latest
 name: go-md2man
 version: 2.0.3
+revision: "1"
 packager: Dalec Example
 vendor: Dalec Example
 license: MIT
@@ -246,6 +249,52 @@ image:
   cmd: --help
 ```
 
+The nice thing about this is you can see exactly what's being done to generate the go modules.
+The downside is its extremely verbose and even requires you to do things outside of the toolchainf or the targeted distribution.
+The below example does something similar but in a more concise way:
+
+```yaml
+name: go-md2man
+version: 2.0.3
+revision: "1"
+packager: Dalec Example
+vendor: Dalec Example
+license: MIT
+description: A tool to convert markdown into man pages (roff).
+website: https://github.com/cpuguy83/go-md2man
+
+sources:
+  src:
+    generators:
+      - gomod
+    git:
+      url: https://github.com/cpuguy83/go-md2man.git
+      commit: "v2.0.3"
+dependencies:
+  build:
+    golang:
+
+build:
+  env:
+    CGO_ENABLED: "0"
+  steps:
+    - command: |
+        cd src
+        go build -o go-md2man .
+
+artifacts:
+  binaries:
+    src/go-md2man:
+
+image:
+  entrypoint: go-md2man
+  cmd: --help
+```
+
+The above "gomod" generator takes care of fetching the module dependencies for any and all sources that have the generator set.
+The module dependencies are managed by Dalec and injected into the build sources.
+The neccessary go environment variables are set in the build environment so that the go build toolchain knows where to find the modules.
+
 Finally, we can add a test case to the spec file which helps ensure the package is assembled as expected.
 The following test will make sure `/usr/bin/go-md2man` is installed and has the expected permissions.
 These tests are automatically executed when building the container image.