Set default log to src-cli.debug.log if build tag debug is used (#533)

* Set default log to src-cli.debug.log if build tag debug is used

I don't care about the specifics - filename, build tag, etc. - but I
*need* this. And the reason why I need it is that it's hard to log
something when our TUI is active. Not because of how the TUI is
implemented, but because the whole concept of an updating TUI doesn't
gel with printf-debugging.

And this is perfect for me: I can `tail -f` the log file and then use
`log.Printf` whereever I want.

* Add info to DEVELOPMENT.md

Author: mrnugget

DEVELOPMENT.md

@@ -78,3 +78,17 @@ To remove it and then force the upstream image on Docker Hub to be used again:
 ```sh
 docker rmi sourcegraph/src-batch-change-volume-workspace
 ```
+
+## Use `debug` build tag to debug batch changes functionality
+
+Since `src batch apply` and `src batch preview` start up a TUI that gets updated repeatedly it's nearly impossible to do printf-debugging by printing debug information - the TUI would hide those or overwrite them.
+
+To help with that you can compile your src binary (or run the tests) with the `debug` build flag:
+
+```
+go build -tags debug -o ~/src ./cmd/src
+```
+
+This will cause the `./internal/batches/debug.go` file to be included in the build. In that file the `log` default package logger is setup to log to `~/.sourcegraph/src-cli.debug.log`.
+
+That allows you to `tail -f ~/.sourcegraph/src-cli.debug.log` and use `log.Println()` in your code to debug.

cmd/src/batch_common.go

@@ -201,7 +201,6 @@ type executeBatchSpecOpts struct {
 // Sourcegraph, including execution as needed and applying the resulting batch
 // spec if specified.
 func executeBatchSpec(ctx context.Context, opts executeBatchSpecOpts) error {
-	batches.DebugOut = opts.out
 	svc := service.New(&service.Opts{
 		AllowUnsupported: opts.flags.allowUnsupported,
 		AllowIgnored:     opts.flags.allowIgnored,

internal/batches/debug.go

@@ -1,9 +1,27 @@
+// +build debug
+
 package batches
 
 import (
-	"github.com/sourcegraph/sourcegraph/lib/output"
+	"log"
+	"os"
+	"path/filepath"
 )
 
-// DebugOut can be used to print debug messages in development to the TUI.
-// For that it needs to be set to an actual *output.Output.
-var DebugOut output.Writer = output.NoopWriter{}
+// In builds with the debug flag (i.e. `go build -tags debug -o src ./cmd/src`)
+// init() sets up the default logger to log to a file in ~/.sourcegraph.
+func init() {
+	homedir, err := os.UserHomeDir()
+	if err != nil {
+		log.Fatalf("getting user home directory: %s", err)
+	}
+
+	fullPath := filepath.Join(homedir, ".sourcegraph", "src-cli.debug.log")
+
+	f, err := os.OpenFile(fullPath, os.O_RDWR|os.O_CREATE|os.O_APPEND, 0666)
+	if err != nil {
+		log.Fatalf("setting debug log file failed: %s", err)
+	}
+
+	log.SetOutput(f)
+}