Makefile: adjust documentation for variable extensions

Author: majewsky

Makefile

@@ -50,7 +50,7 @@ install-reuse: FORCE
 
 prepare-static-check: FORCE install-golangci-lint install-modernize install-shellcheck install-go-licence-detector install-addlicense install-reuse
 
-# To add additional flags or values, specify the variable in the environment, e.g. `GO_BUILDFLAGS='-tags experimental' make`.
+# To add additional flags or values (before the default ones), specify the variable in the environment, e.g. `GO_BUILDFLAGS='-tags experimental' make`.
 # To override the default flags or values, specify the variable on the command line, e.g. `make GO_BUILDFLAGS='-tags experimental'`.
 GO_BUILDFLAGS += -mod vendor
 GO_LDFLAGS +=

README.md

@@ -455,11 +455,11 @@ This mechanism cannot be used to define new variables to use in your own rules;
 By default, all accepted variables are empty.
 The only exception is that `GO_BUILDFLAGS` defaults to `-mod vendor` when vendoring is enabled (see below).
 
-When invoking the respective targets utilizing the variables, it's possible to either append to the provided values by modifying the calling environment:
+When invoking the respective targets utilizing the variables, it's possible to either prepend to the provided values by modifying the calling environment:
 
 ```console
 $ GO_BUILDFLAGS="-work -v" make build/go-makefile-maker
-env  go build -mod vendor -work -v -ldflags ...
+env  go build -work -v -mod vendor -ldflags ...
 ```
 
 or to override their values by passing the variables as `make` arguments:

internal/makefile/makefile.go

@@ -214,7 +214,7 @@ endif
 	if isGolang {
 		// WARNING: DO NOT CHANGE THIS WITHOUT FIRST UNDERSTANDING THE CONSEQUENCES.
 		// All changes have to be okay'd by Stefan Majewsky to avoid breaking setups.
-		build.addDefinition("# To add additional flags or values, specify the variable in the environment, e.g. `GO_BUILDFLAGS='-tags experimental' make`.")
+		build.addDefinition("# To add additional flags or values (before the default ones), specify the variable in the environment, e.g. `GO_BUILDFLAGS='-tags experimental' make`.")
 		build.addDefinition("# To override the default flags or values, specify the variable on the command line, e.g. `make GO_BUILDFLAGS='-tags experimental'`.")
 		build.addDefinition("GO_BUILDFLAGS +=%s", cfg.Variable("GO_BUILDFLAGS", defaultBuildFlags))
 		build.addDefinition("GO_LDFLAGS +=%s", cfg.Variable("GO_LDFLAGS", strings.TrimSpace(defaultLdFlags)))