v0.2.0

.github/workflows/ci.yaml

@@ -0,0 +1,43 @@
+name: main
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.20'
+      - name: Run CI checks
+        run: 'make ci'
+  tag:
+    if: github.ref == 'refs/heads/main'
+    needs: ci
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Tag for release
+        run: 'make tag-release'
+  release:
+    if: github.ref == 'refs/heads/main'
+    needs: tag
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.20'
+      - name: Package binaries
+        run: 'make package'
+      - name: Create GitHub Release
+        run: gh release create "v$(grep -v '#' ./VERSION)" --generate-notes --verify-tag --latest ./dist/zipped/*
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -4,4 +4,3 @@
 *cache*
 build/
 deps/
-dist/

Containerfile

@@ -0,0 +1,14 @@
+# This Containerfile isn't mean for creating artifacts etc., it's just a way to
+# perform portable, local CI checks in case there are workstation-specific
+# issues a developer faces.
+FROM docker.io/library/golang:1.20
+
+RUN apt-get update && apt-get install -y \
+      ca-certificates \
+      make \
+      sudo
+
+COPY . /go/app
+WORKDIR /go/app
+
+RUN make ci

Makefile

@@ -2,58 +2,60 @@ SHELL = /usr/bin/env bash -euo pipefail
 
 BINNAME := vdm
 
-all: test clean
-
 .PHONY: %
 
-test: clean
-	go vet ./...
-	go test -cover -coverprofile=./cover.out ./...
-	staticcheck ./...
-	make -s clean
+all: ci package package-debian
+
+ci: clean
+	@bash ./scripts/ci.sh
+
+# test is just an alias for ci
+test: ci
+
+ci-container:
+	@docker build -f ./Containerfile -t vdm-test:latest .
 
 test-coverage: test
 	go tool cover -html=./cover.out -o cover.html
 	xdg-open ./cover.html
 
+# builds for the current platform only
 build: clean
-	@mkdir -p build/$$(go env GOOS)-$$(go env GOARCH)
-	@go build -o build/$$(go env GOOS)-$$(go env GOARCH)/$(BINNAME)
+	@go build -buildmode=pie -o build/$$(go env GOOS)-$$(go env GOARCH)/$(BINNAME) -ldflags "-s -w"
 
 xbuild: clean
-	@for target in \
-		darwin-amd64 \
-		linux-amd64 \
-		linux-arm \
-		linux-arm64 \
-		windows-amd64 \
-	; \
-	do \
-		GOOS=$$(echo "$${target}" | cut -d'-' -f1) ; \
-		GOARCH=$$(echo "$${target}" | cut -d'-' -f2) ; \
-		outdir=build/"$${GOOS}-$${GOARCH}" ; \
-		mkdir -p "$${outdir}" ; \
-		printf "Building for %s-%s into build/ ...\n" "$${GOOS}" "$${GOARCH}" ; \
-		GOOS="$${GOOS}" GOARCH="$${GOARCH}" go build -o "$${outdir}"/$(BINNAME) ; \
-	done
+	@bash ./scripts/xbuild.sh
 
 package: xbuild
-	@mkdir -p dist
-	@cd build || exit 1; \
-	for built in * ; do \
-		printf 'Packaging for %s into dist/ ...\n' "$${built}" ; \
-		cd $${built} && tar -czf ../../dist/$(BINNAME)_$${built}.tar.gz * && cd - >/dev/null ; \
-	done
+	@bash ./scripts/package.sh
+
+package-debian: build
+	@bash ./scripts/package-debian.sh
 
 clean:
 	@rm -rf \
 		/tmp/$(BINNAME)-tests \
 		*cache* \
 		.*cache* \
 		./build/ \
-		./dist/ \
-		./deps/ \
-		./testdata/deps/
+		./dist/zipped/*.tar.gz \
+		./dist/zipped/*.zip \
+		./dist/debian/vdm.deb \
+		*.out
+	@sudo rm -rf ./dist/debian/vdm/usr
+# TODO: until I sort out the tests to write test data consistently, these deps/
+# directories etc. can kind of show up anywhere
+	@find . -type d -name '*deps*' -exec rm -rf {} +
+	@find . -type f -name '*VDMMETA*' -delete
+
+bump-versions: clean
+	@bash ./scripts/bump-versions.sh "$${old_version:-}"
+
+tag-release: clean
+	@bash ./scripts/tag-release.sh
+
+pre-commit-hook:
+	cp ./scripts/ci.sh ./.git/hooks/pre-commit
 
 # Some targets that help set up local workstations with rhad tooling. Assumes
 # ~/.local/bin is on $PATH

README.md

@@ -1,44 +1,116 @@
-# vdm: Versioned Dependency Manager
+# vdm: A General-Purpose Versioned-Dependency Manager
 
-`vdm` is an alternative to git submodules for managing external dependencies for
-the same reasons, in a more sane way.
+`vdm` is an alternative to e.g. Git Submodules for managing arbitrary external
+dependencies for the same reasons, in a more sane way. Unlike some other tools
+that try to solve this problem, `vdm` is language-agnostic, and can be used for
+any purpose that you would need remote development resources.
 
-To get started, you'll need a `vdm` spec file, which is just a JSON array of all
-your external dependencies along with their revisions & where you want them to
-live in your repo:
+`vdm` can be used for many different purposes, but most commonly as a way to
+track external dependencies that your own code might need, but that you don't
+have a language-native way to specify. Some examples might be:
 
-    [
-      {
-        "remote":     "https://github.com/opensourcecorp/go-common",
-        "version":    "v0.2.0", // tag; can also be a branch, short or long commit hash, or the word 'latest'
-        "local_path": "./deps/go-common"
-      }
-    ]
+- You have a shared CI repo from which you need to access common shell scripts,
+  hosted build tasks, etc.
 
-You can have as many dependency specifications in that array as you want. By
-default, this spec file is called `vdm.json` and lives at the calling location
-(which is probably your repo's root), but you can call it whatever you want and
-point to it using the `-spec-file` flag to `vdm`.
+- You're building & testing a backend application and need to test serving
+  frontend code from it, and your team has that frontend code in another
+  repository.
+
+- Your team uses protocol buffers and you need to be able to import other loose
+  `.proto` files to generate your own code.
+
+`vdm` lets you clearly specify all those remote dependencies & more, and
+retrieve them whenever you need them.
+
+## Getting Started
+
+### Installation
+
+`vdm` can be installed from [its GitHub Releases
+page](https://github.com/opensourcecorp/vdm/releases). There is a zipped binary
+for major platforms & architectures, and those are indicated in the Asset file
+name. For example, if you have an M2 macOS laptop, you would download the
+`vdm_darwin-arm64.tar.gz` file, and extract it to somewhere on your `$PATH`.
+
+If you have a recent version of the Go toolchain available, you can also install
+or run `vdm` using `go`:
+
+```sh
+go install github.com/opensourcecorp/vdm@<vX.Y.Z|latest>
+# or
+go run github.com/opensourcecorp/vdm@<vX.Y.Z|latest> ...
+```
+
+### Usage
+
+To get started, you'll need a `vdm` spec file, which is just a YAML (or JSON)
+file specifying all your external dependencies along with (usually) their
+revisions & where you want them to live on your filesystem:
+
+```yaml
+remotes:
+
+  - type:       "git" # the default, and so can be omitted if desired
+    remote:     "https://github.com/opensourcecorp/go-common" # can specify as 'git@...' to use SSH instead
+    local_path: "./deps/go-common"
+    version:    "v0.2.0" # tag example; can also be a branch, commit hash, or the word 'latest'
+
+  - type:       "file" # the 'file' type assumes the version is in the remote field itself somehow, so 'version' can be omitted
+    remote:     "https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/http.proto"
+    local_path: "./deps/proto/http/http.proto"
+```
+
+You can have as many dependency specifications in that array as you want, and
+they can be stored wherever you want. By default, this spec file is called
+`vdm.yaml` and lives at the calling location (which is probably your repo's
+root), but you can call it whatever you want and point to it using the
+`--spec-file` flag to `vdm`.
 
 Once you have a spec file, just run:
 
-    vdm sync
+```sh
+vdm sync
+```
+
+and `vdm` will process the spec file, retrieve your dependencies as specified,
+and put them where you told them to go. By default, `vdm sync` also removes the
+local `.git` directories for each `git` remote, so as to not upset your local
+Git tree. If you want to change the version/revision of a remote, just update
+your spec file and run `vdm sync` again.
+
+After running `vdm sync` with the above example spec file, your directory tree
+would look something like this:
 
-and `vdm` will process the spec file, grab your dependencies, put them where
-they belong, and check out the right versions. By default, `vdm sync` also
-removes the local `.git` directories for each remote, so as to not upset your
-local Git tree. If you want to change the version/revision of a remote, just
-update your spec file and run `vdm sync` again.
+```txt
+./vdm.yaml
+./deps/
+    go-common/
+        <stuff in that repo>
+    http.proto
+```
 
-If for any reason you want all the deps in the spec file to retain their `.git`
-directories (such as if you're using `vdm` to initialize a new computer with
-actual repos you'd be working in), you can pass the `-keep-git-dir` flag to `vdm
-sync`.
+## Dependencies
+
+`vdm` is distributed as a statically-linked binary per platform that has no
+language-specific dependencies. However, note that at the time of this writing,
+`vdm` *does* depends on `git` being installed if you specify any `git` remote
+types. `vdm` will fail with an informative error if it can't find `git` on your
+`$PATH`.
+
+## A note about auth
+
+`vdm` has zero goals to be an authN/authZ manager. If a remote in your spec file
+depends on a certain auth setup (an SSH key, something for HTTP basic auth like
+a `.netrc` file, an `.npmrc` config file, etc.), that setup is out of `vdm`'s
+scope. If required, you will need to ensure proper auth is configured before
+running `vdm` commands.
 
 ## Future work
 
 - Make the sync mechanism more robust, such that if your spec file changes to
   remove remotes, they'll get cleaned up automatically.
 
-- Support more than just Git -- but I really don't care that much about this
-  right now.
+- Add `--keep-git-dir` flag so that `git` remote types don't wipe the `.git`
+  directory at clone-time.
+
+- Support more than just `git` and `file` types, and make `file` better

VERSION

@@ -0,0 +1,3 @@
+# Version number used as an anchor for listed versions in various files in the
+# tree, orchestrated by scripts/bump-versions.sh
+0.2.0

cmd/doc.go

@@ -0,0 +1,4 @@
+/*
+Package cmd calls the implementation logic for vdm.
+*/
+package cmd

cmd/flagsupport.go

@@ -0,0 +1,19 @@
+package cmd
+
+import (
+	"os"
+
+	"github.com/opensourcecorp/vdm/internal/message"
+	"github.com/spf13/viper"
+)
+
+// MaybeSetDebug sets the DEBUG environment variable if it was set as a flag by
+// the caller.
+func MaybeSetDebug() {
+	if viper.GetBool(debugFlagKey) {
+		err := os.Setenv("DEBUG", "true")
+		if err != nil {
+			message.Fatalf("internal error: unable to set environment variable DEBUG")
+		}
+	}
+}