Makefile: 💅

Makefile

@@ -1,36 +1,81 @@
+# GIT_LFS_SHA is the '--short'-form SHA1 of the current revision of Git LFS.
 GIT_LFS_SHA ?= $(shell git rev-parse --short HEAD)
+# VERSION is the longer-form describe output of the current revision of Git LFS,
+# used for identifying intermediate releases.
+#
+# If Git LFS is being built for a published release, VERSION and GIT_LFS_SHA
+# should be identical.
 VERSION ?= $(shell git describe HEAD)
 
+# GO is the name of the 'go' binary used to compile Git LFS.
 GO ?= go
 
+# GO_TEST_EXTRA_ARGS are extra arguments given to invocations of 'go test'.
+#
+# Examples include:
+#
+# 	make test GO_TEST_EXTRA_ARGS=-v
+# 	make test GO_TEST_EXTRA_ARGS='-run TestMyExample'
 GO_TEST_EXTRA_ARGS =
 
+# BUILTIN_LD_FLAGS are the internal flags used to pass to the linker. By default
+# the config.GitCommit variable is always set via this variable, and
+# DWARF-stripping is enabled unless DWARF=YesPlease.
 BUILTIN_LD_FLAGS =
 BUILTIN_LD_FLAGS += -X github.com/git-lfs/git-lfs/config.GitCommit=$(GIT_LFS_SHA)
 ifneq ("$(DWARF)","YesPlease")
 BUILTIN_LD_FLAGS += -s
 BUILTIN_LD_FLAGS += -w
 endif
+# EXTRA_LD_FLAGS are given by the caller, and are passed to the Go linker after
+# BUILTIN_LD_FLAGS are processed.
 EXTRA_LD_FLAGS =
+# LD_FLAGS is the union of the above two BUILTIN_LD_FLAGS and EXTRA_LD_FLAGS.
 LD_FLAGS = $(BUILTIN_LD_FLAGS) $(EXTRA_LD_FLAGS)
 
+# BUILTIN_GC_FLAGS are the internal flags used to pass compiler.
 BUILTIN_GC_FLAGS =
+# EXTRA_GC_FLAGS are the caller-provided flags to pass to the compiler.
 EXTRA_GC_FLAGS =
+# GC_FLAGS are the union of the above two BUILTIN_GC_FLAGS and EXTRA_GC_FLAGS.
 GC_FLAGS = $(BUILTIN_GC_FLAGS) $(EXTRA_GC_FLAGS)
 
+# GLIDE is the name of the 'glide' binary used to manage vendored dependencies.
 GLIDE ?= glide
 
+# RONN is the name of the 'ronn' program used to generate man pages.
 RONN ?= ronn
+# RONN_EXTRA_ARGS are extra arguments given to the $(RONN) program when invoked.
 RONN_EXTRA_ARGS ?=
 
+# GREP is the name of the program used for regular expression matching, or
+# 'grep' if unset.
 GREP ?= grep
+# RM is the name of the program used removing files, or 'rm -f' if unset.
 RM ?= rm -f
+# XARGS is the name of the program used to turn stdin into program arguments, or
+# 'xargs' if unset.
 XARGS ?= xargs
 
+# GOIMPORTS is the name of the program formatter used before compiling.
 GOIMPORTS ?= goimports
+# GOIMPORTS_EXTRA_OPTS are the default options given to the $(GOIMPORTS)
+# program.
 GOIMPORTS_EXTRA_OPTS ?= -w -l
 
-SOURCES = $(shell find . -type f -name '*.go')
+# SOURCES is a listing of all .go files in this and child directories, excluding
+# that in vendor.
+SOURCES = $(shell find . -type f -name '*.go' | grep -v vendor)
+# PKGS is a listing of packages that are considered to be a part of Git LFS, and
+# are used in package-specific commands, such as the 'make test' targets. For
+# example:
+#
+# 	make test                               # run 'go test' in all packages
+# 	make PKGS='config git/githistory' test  # run 'go test' in config and
+# 	                                        # git/githistory
+#
+# By default, it is a listing of all packages in Git LFS. When new packages (or
+# sub-packages) are created, they should be added here.
 ifndef PKGS
 PKGS =
 PKGS += commands
@@ -53,55 +98,96 @@ PKGS += tools/kv
 PKGS += tq
 endif
 
+# X is the platform-specific extension for Git LFS binaries. It is automatically
+# set to .exe on Windows, and the empty string on all other platforms. It may be
+# overridden.
 ifeq ($(OS),Windows_NT)
 X ?= .exe
 else
 X ?=
 endif
-.DEFAULT_GOAL := bin/git-lfs$(X)
 
+# BUILD is a macro used to build a single binary of Git LFS using the above
+# LD_FLAGS and GC_FLAGS.
+#
+# It takes three arguments:
+#
+# 	$(1) - a valid GOOS value, or empty-string
+# 	$(2) - a valid GOARCH value, or empty-string
+# 	$(3) - an optional program extension. If $(3) is given as '-foo', then the
+# 	       program will be written to bin/git-lfs-foo.
 BUILD = GOOS=$(1) GOARCH=$(2) \
 	$(GO) build \
 	-ldflags="$(LD_FLAGS)" \
 	-gcflags="$(GC_FLAGS)" \
 	-o ./bin/git-lfs$(3) ./git-lfs.go
 
+# BUILD_TARGETS is the set of all platforms and architectures that Git LFS is
+# built for.
 BUILD_TARGETS = bin/git-lfs-darwin-amd64 bin/git-lfs-darwin-386 \
 	bin/git-lfs-linux-amd64 bin/git-lfs-linux-386 \
 	bin/git-lfs-freebsd-amd64 bin/git-lfs-freebsd-386 \
 	bin/git-lfs-windows-amd64.exe bin/git-lfs-windows-386.exe
 
+# Targets 'all' and 'build' build binaries of Git LFS for the above release
+# matrix.
 .PHONY : all build
 all build : $(BUILD_TARGETS)
 
-bin/git-lfs-darwin-amd64 : fmt
+# The following bin/git-lfs-% targets make a single binary compilation of Git
+# LFS for a specific operating system and architecture pair.
+#
+# They function by translating target names into arguments for the above BUILD
+# builtin, and appending the appropriate suffix to the build target.
+#
+# On Windows, they also depend on the .PHONY version-info target, which installs
+# and embeds the versioninfo into the binary.
+bin/git-lfs-darwin-amd64 : $(SOURCES)
 	$(call BUILD,darwin,amd64,-darwin-amd64)
-bin/git-lfs-darwin-386 : fmt
+bin/git-lfs-darwin-386 : $(SOURCES)
 	$(call BUILD,darwin,386,-darwin-386)
-bin/git-lfs-linux-amd64 : fmt
+bin/git-lfs-linux-amd64 : $(SOURCES)
 	$(call BUILD,linux,amd64,-linux-amd64)
-bin/git-lfs-linux-386 : fmt
+bin/git-lfs-linux-386 : $(SOURCES)
 	$(call BUILD,linux,386,-linux-386)
-bin/git-lfs-freebsd-amd64 : fmt
+bin/git-lfs-freebsd-amd64 : $(SOURCES)
 	$(call BUILD,freebsd,amd64,-freebsd-amd64)
-bin/git-lfs-freebsd-386 : fmt
+bin/git-lfs-freebsd-386 : $(SOURCES)
 	$(call BUILD,freebsd,386,-freebsd-386)
-bin/git-lfs-windows-amd64.exe : version-info fmt
+bin/git-lfs-windows-amd64.exe : version-info $(SOURCES)
 	$(call BUILD,windows,amd64,-windows-amd64.exe)
-bin/git-lfs-windows-386.exe : version-info fmt
+bin/git-lfs-windows-386.exe : version-info $(SOURCES)
 	$(call BUILD,windows,386,-windows-386.exe)
 
-bin/git-lfs : $(SOURCES)
+# .DEFAULT_GOAL sets the operating system-appropriate Git LFS binary as the
+# default output of 'make'.
+.DEFAULT_GOAL := bin/git-lfs$(X)
+
+# bin/git-lfs targets the default output of Git LFS on non-Windows operating
+# systems, and respects the build knobs as above.
+bin/git-lfs : $(SOURCES) fmt
 	$(call BUILD,$(GOOS),$(GOARCH),)
 
+# bin/git-lfs targets the default output of Git LFS on Windows systems, and
+# respects the build knobs as above.
 bin/git-lfs.exe : $(SOURCES) version-info
 	$(call BUILD,$(GOOS),$(GOARCH),.exe)
 
+# version-info installs the 'goversioninfo' command and uses it in order to
+# generate a binary that has information included necessary to create the
+# Windows installer.
 .PHONY : version-info
 version-info:
 	go get github.com/josephspurrier/goversioninfo/cmd/goversioninfo
 	PATH=$$PATH:$$GOPATH/bin/windows_386 $(GO) generate
 
+# RELEASE_TARGETS is the set of all release artifacts that we generate over a
+# particular release. They each have a corresponding entry in BUILD_TARGETS as
+# above.
+#
+# Unlike BUILD_TARGETS above, each of the below create a compressed directory
+# containing the matching binary, as well as the contents of RELEASE_INCLUDES
+# below.
 RELEASE_TARGETS = bin/releases/git-lfs-darwin-amd64-$(VERSION).tar.gz \
 	bin/releases/git-lfs-darwin-386-$(VERSION).tar.gz \
 	bin/releases/git-lfs-linux-amd64-$(VERSION).tar.gz \
@@ -111,50 +197,98 @@ RELEASE_TARGETS = bin/releases/git-lfs-darwin-amd64-$(VERSION).tar.gz \
 	bin/releases/git-lfs-windows-amd64-$(VERSION).zip \
 	bin/releases/git-lfs-windows-386-$(VERSION).zip
 
-RELEASE_INCLUDES = README.md CHANGELOG.md script/install.sh
+# RELEASE_INCLUDES are the names of additional files that are added to each
+# release artifact.
+RELEASE_INCLUDES = README.md CHANGELOG.md
 
+# release is a phony target that builds all of the release artifacts, and then
+# shows the SHA 256 signature of each.
 .PHONY : release
 release : $(RELEASE_TARGETS)
 	shasum -a 256 $(RELEASE_TARGETS)
 
-bin/releases/git-lfs-%-$(VERSION).tar.gz : $(RELEASE_INCLUDES) bin/git-lfs-%
+# bin/releases/git-lfs-%-$(VERSION).tar.gz generates a gzip-compressed TAR of
+# the non-Windows release artifacts.
+#
+# It includes all of RELEASE_INCLUDES, as well as script/install.sh.
+bin/releases/git-lfs-%-$(VERSION).tar.gz : \
+$(RELEASE_INCLUDES) bin/git-lfs-% script/install.sh
 	@mkdir -p bin/releases
 	tar -s '!bin/git-lfs-.*!git-lfs!' -s '!script/!!' -czf $@ $^
 
+# bin/releases/git-lfs-%-$(VERSION).zip generates a ZIP compression of all of
+# the Windows release artifacts.
+#
+# It includes all of the RELEASE_INCLUDES, and converts LF-style line endings to
+# CRLF in the non-binary components of the artifact.
 bin/releases/git-lfs-%-$(VERSION).zip : $(RELEASE_INCLUDES) bin/git-lfs-%.exe
 	@mkdir -p bin/releases
 	zip -j -l $@ $^
 
+# TEST_TARGETS is a list of all phony test targets. Each one of them corresponds
+# to a specific kind or subset of tests to run.
 TEST_TARGETS := test-bench test-verbose test-race
 .PHONY : $(TEST_TARGETS) test
 $(TEST_TARGETS) : test
 
+# test-bench runs all Go benchmark tests, and nothing more.
 test-bench : GO_TEST_EXTRA_ARGS=-run=__nothing__ -bench=.
+# test-verbose runs all Go tests in verbose mode.
 test-verbose : GO_TEST_EXTRA_ARGS=-v
+# test-race runs all Go tests in race-detection mode.
 test-race : GO_TEST_EXTRA_ARGS=-race
 
+# test runs the Go tests with GO_TEST_EXTRA_ARGS in all specified packages,
+# given by the PKGS variable.
+#
+# For example, a caller can invoke the race-detection tests in just the config
+# package by running:
+#
+# 		make PKGS=config test-race
+#
+# Or in a series of packages, like:
+#
+# 		make PKGS="config lfsapi tools/kv" test-race
+#
+# And so on.
 test : fmt
 	$(GO) test $(GO_TEST_EXTRA_ARGS) $(addprefix ./,$(PKGS))
 
+# integration is a shorthand for running 'make' in the 't' directory.
+.PHONY : integration
+integration : bin/git-lfs$(X)
+	make -C t test
+
+# glide.lock is the permanent record of the glide.yaml file, and it is built by
+# running 'glide update'.
 glide.lock : glide.yaml
 	$(GLIDE) update
 
+# vendor updates the glide.lock-file, and installs vendored dependencies into
+# the vendor/ sub-tree, removing sub-packages (listed below) that are unused by
+# Git LFS.
+.PHONY : vendor
 vendor : glide.lock
 	$(GLIDE) install
 	$(RM) -r vendor/github.com/ThomsonReutersEikon/go-ntlm/utils
 	$(RM) -r vendor/github.com/davecgh/go-spew
 	$(RM) -r vendor/github.com/pmezard/go-difflib
 
+# fmt runs goimports over all files in Git LFS (as defined by $(SOURCES) above),
+# and replaces their contents with a formatted one in-place.
 .PHONY : fmt
 fmt : $(SOURCES) | lint
 	$(GOIMPORTS) $(GOIMPORTS_EXTRA_OPTS) $?
 
+# lint ensures that there are all dependencies outside of the standard library
+# are vendored in via vendor (see: above).
 .PHONY : lint
 lint : $(SOURCES)
 	$(GO) list -f '{{ join .Deps "\n" }}' . \
 	| $(XARGS) $(GO) list -f '{{ if not .Standard }}{{ .ImportPath }}{{ end }}' \
 	| $(GREP) -v "github.com/git-lfs/git-lfs" || exit 0
 
+# MAN_ROFF_TARGETS is a list of all ROFF-style targets in the man pages.
 MAN_ROFF_TARGETS = man/git-lfs-checkout.1 \
   man/git-lfs-clean.1 \
   man/git-lfs-clone.1 \
@@ -186,6 +320,7 @@ MAN_ROFF_TARGETS = man/git-lfs-checkout.1 \
   man/git-lfs-update.1 \
   man/git-lfs.1
 
+# MAN_HTML_TARGETS is a list of all HTML-style targets in the man pages.
 MAN_HTML_TARGETS = man/git-lfs-checkout.1.html \
   man/git-lfs-clean.1.html \
   man/git-lfs-clone.1.html \
@@ -217,13 +352,16 @@ MAN_HTML_TARGETS = man/git-lfs-checkout.1.html \
   man/git-lfs-update.1.html \
   man/git-lfs.1.html
 
+# man generates all ROFF- and HTML-style manpage targets.
 .PHONY : man
 man : $(MAN_ROFF_TARGETS) $(MAN_HTML_TARGETS)
 
+# man/% generates ROFF-style man pages from the corresponding .ronn file.
 man/% : docs/man/%.ronn
 	@mkdir -p man
 	$(RONN) $(RONN_EXTRA_ARGS) -r --pipe < $^ > $@
 
+# man/%.html generates HTML-style man pages from the corresponding .ronn file.
 man/%.html : docs/man/%.ronn
 	@mkdir -p man
 	$(RONN) $(RONN_EXTRA_ARGS) -5 --pipe < $^ > $@