Tooling experience feedback

[Jaana Burcu Dogan]

Hello gophers,

I am going to spend some time on improving the not-documented or hard-to-use parts of the Go tools. I will mainly focus on go build and go test. The work will consist of reorganizing manuals, proposing new subcommands or flags to support commonly used multi-step things and so on.

To give you some concrete examples:

I have been in cases where users cannot find the build flags because they are hidden. E.g.

    $ go test -help

    test [build/test flags] [packages] [build/test flags & test binary flags]
    ...

requires you to know about where the build flags are. Some tools are invisible for the newcomers.

The other example is about test coverage. It is so tedious that I need an alias.

func gocover() {

    go test -v -coverprofile=coverage.out && go tool cover -html=coverage.out

} 

I want to learn more about your experience, aliases, etc to propose improvements and work on the most commonly suggested items. I also am planning to go through this mailing list, stack overflow and other channels to see the common complaints.

Feel free to reply to this thread or write to me privately.

Thanks,

JBD

[Zellyn]

I run go tests with something like this:

while true; do go test ./foo/bar; fswatch -1 -r . > /dev/null; sleep 0.3; done

It would be nice if go test could do that itself. (The 0.3 second sleep is to let the file-write that triggered the test complete.)

Zellyn

[Russ Egan]

1. A "no vendor" switch (for build, test, fmt, vet, etc) would be nice.

2. Multi-package coverage would be nice.  We end up copying this stanza throughout our makefiles:

PACKAGES = $$(go list ./... | grep -v /vendor/)

 

test:

echo 'mode: atomic' > build/coverage.out

for pkg in $(PACKAGES) ; do \

go test -v -covermode=count -coverprofile=build/coverage.tmp $$pkg 2>&1 | tee -a build/test.out; \

if [ -e build/coverage.tmp ] ; then tail -n +2 build/coverage.tmp >> build/coverage.out; rm build/coverage.tmp; fi \

done

go tool cover -html=build/coverage.out -o build/coverage.html

[Egon]

On Tuesday, 18 October 2016 14:02:08 UTC-5, Zellyn wrote:

I run go tests with something like this:

while true; do go test ./foo/bar; fswatch -1 -r . > /dev/null; sleep 0.3; done

It would be nice if go test could do that itself. (The 0.3 second sleep is to let the file-write that triggered the test complete.)

I've built a tool for myself based on Watch by Russ Cox (he showed it in this video http://research.swtch.com/acme)

Located at: https://github.com/loov/watchrun

$ go get github.com/loov/watchrun

$ watchrun go test ./foo/bar

Keeping it as a separate tool is much more flexible and useful... e.g.

$ watchrun go build myapp ;; myapp

Which would build the application and then start it. Or... chain it with code generation...

$ watchrun go generate . ;; go build . ;; myapp

etc... of course depending on your needs you may want some other features or an alternative implementation.

[Florin Pățan]

Hi Jaana,

Thank you for this initiative.

I think currently one of the points that I think that is missing is easy to access documentation online.

My use-case is usually around the web and making things easier to access from there. Maybe I've got used to the command line for common tasks but the things that are really hard to find are the special instructions to the go compiler and linker (gcflags and ldflags), like here for example: https://godoc.org/cmd/go And having all of this in a single page, while convenient can be overwhelming the first few times.

 Also the documentation, while from a godoc point of view logically lists the flags and tools / subtools, is rather well hidden for the things that you'd search as a newbie and while the Tour tries to teach you some aspects of the language, it doesn't show anything related to how to use the tools of the language (nor does it show how to install it correctly for example, many people still having problems with understanding how to correctly set their workspace with env vars and so on).

I think more usage examples should be shown in general, with concrete use-cases:

- this is how you test things

- this is how you test things without vendors (which is a major pita right now btw)

- this is how you also get the coverage

- this is how you compile and set a random string value at compile time

- etc.

I'll try and come up with more examples later on.

I also see the pattern in other apps where main command has some flags then the subcommand has other flags so I guess that's ok, probably introducing aliases would make it even more complex to use.

Kind regards,

Florin

[Jan Mercl]

On Tue, Oct 18, 2016 at 8:54 PM 'Jaana Burcu Dogan' via golang-nuts <golan...@googlegroups.com> wrote:

The go tool already does a lot of things, perhaps too much of them. The observation that newcomers have trouble to use it to their advantage is both correct and the evidence of its complexity. Adding new sub-commands has the potential to only make that worse, I'm afraid.

--

-j

[Jaana Burcu Dogan]

On Tue, Oct 18, 2016 at 12:34 PM, Jan Mercl <0xj...@gmail.com> wrote:

On Tue, Oct 18, 2016 at 8:54 PM 'Jaana Burcu Dogan' via golang-nuts <golan...@googlegroups.com> wrote:

The go tool already does a lot of things, perhaps too much of them.

Please contribute with specific items. Hiding complexity is also a goal we want to achieve.

 

The observation that newcomers have trouble to use it to their advantage is both correct and the evidence of its complexity. Adding new sub-commands has the potential to only make that worse, I'm afraid.

 

This is not a thread where we discuss what specifically will be added or not. Major improvement ideas will be followed by proposals and will go through the typical proposal process where you can give concrete feedback about each item. This topic is about what could have improved by looking at user's workflow and their actual daily interactions with the tools.

 

--

-j

[ondrej...@gmail.com]

go tool trace was nicely explained here

https://groups.google.com/forum/#!topic/Golang-Nuts/Ktvua7AGdkI

and had no proper documentation at the time. Would be good if it had a high level overview like that

[kbur...@gmail.com]

One tool I add to most of my projects is a Make target that opens documentation for the current project in a web browser.

I wrote a short binary to do this here: https://github.com/kevinburke/godocdoc

It would also be nice to be able to jump easily from a bug number, e.g. 17391, to the relevant description, e.g. github.com/golang/go/issues/17391.

[Nate Finch]

Please give us an easy way to ensure all tests in a list of packages compile..... right now I have to go test ./... -test.run=xxx  ... and that does all the linking and crap that I don't care about into N binaries, which takes forever.  I just want to know if I caught all the places that need to get updated in the tests when I do a change.  For juju this takes *minutes* when a single compile of the actual code only takes ~15 seconds.

+1 for consolidated documentation on testing, building, etc.  Having to look at specific package to know how to test is really unintuitive... and it assumes you know that there's a testing package that has that information.  I expect there to be a "here's how to test with go" in some obvious top level place in golang.org.

Put the package selector "..." directly in the help for tools that use it.  It took me a long time to figure out how to build more than a single directory, and it's something that gets used all the time.  It's buried in a separate help menu halfway down a wall of text... and I've seen a ton of newbies ask how to do it.

Put examples in the help output.  I can't tell you how often examples help far more than a wall of text.  Something as simple as this would save a lot of newbie questions:

Examples:

// build this directory and all subdirectories

go build ./...   

Are there still tools you have to download separately from the go tool, like coverage?  I've had everything installed so long, I forget if this is still a thing.  But if it is, please just include it in the normal install.

Choose a default GOPATH.  Just pick one.  Doesn't matter if it's good or bad, as long as people can just go get as soon as they have the tool on disk.

[Nathan Youngman]

There is a 2013 proposal from Russ Cox that includes a -watch flag in the go tool.

https://docs.google.com/document/d/1xl_aRcCbksFRmCKtoyRQG9L7j6DIdMZtrkFAoi5EXaA/edit

"a possible extension would be to add -watch flag to “go test,” “go install,” and “go run,” which would repeat the command each time a prerequisite file was modified. For example, running “go test -watch” in a terminal window would automatically show compile errors or test output each time a source file was saved."

That might be nice to see, but it isn't a trivial project.

Nathan.

[Nathan Youngman]

Even if there wasn't a -novendor flag, it would be nice if there was a consistent way to ignore the /vendor/ directory. This approach was provided by Andrew Gerrand's talk "Stupid Gopher Talks":

go test $(go list ./... | grep -v vendor) 

However, the same doesn't work for all tools. The gofmt and golint tools report no such file or directory:

gofmt -s -l -w $(go list ./... | grep -v vendor) 

golint $(go list ./... | grep -v vendor)

This means our Makefile has a few different ways of getting the *.go files to check, and it took some time to figure out (multiply by every team / new project using Go).

Personally, I find it a bit confusing to get all these tools in the first place. I've heard that some of the x/tools have moved into core (gofmt) in 1.6, but some haven't. There are a number of really useful third-party tools like gometalinter and gocode too. Right now it looks like each text editor / IDE needs to provide installation scripts to get all these tools.

Btw, the open issue for multiple package test coverage is here: https://github.com/golang/go/issues/6909

Thanks,

Nathan.

[Aram Hăvărneanu]

On Wed, Oct 19, 2016 at 7:27 PM, Nate Finch <nate....@gmail.com> wrote:
> Please give us an easy way to ensure all tests in a list of packages compile

Do something like this:

go test -toolexec wrapper -exec success pkgs...

Where wrapper is a binary that dispatches to the compiler, but a nop
when called with the linker, and success is a binary that just exits
successfully.

--
Aram Hăvărneanu

[Aram Hăvărneanu]

Yes, just tried it, it works:

: emerald:aram; go test -toolexec toolexec_nolink -exec /usr/bin/true crypto...
? crypto [no test files]
ok crypto/aes 0.004s
ok crypto/cipher 0.012s
ok crypto/des 0.012s
ok crypto/dsa 0.011s
ok crypto/ecdsa 0.008s
ok crypto/elliptic 0.010s
ok crypto/hmac 0.008s
ok crypto/md5 0.011s
ok crypto/rand 0.007s
ok crypto/rc4 0.005s
ok crypto/rsa 0.003s
ok crypto/sha1 0.004s
ok crypto/sha256 0.005s
ok crypto/sha512 0.004s
ok crypto/subtle 0.006s
ok crypto/tls 0.002s
ok crypto/x509 0.002s
? crypto/x509/pkix [no test files]
: emerald:aram; printf 'package tls_test\n\nbad' >`go env
GOROOT`/src/crypto/tls/bad_test.go
: emerald:aram; go build crypto...
: emerald:aram; go test -toolexec toolexec_nolink -exec /usr/bin/true crypto...
# crypto/tls
go/src/crypto/tls/bad_test.go:3:1: expected declaration, found 'IDENT' bad
FAIL crypto/tls [setup failed]
? crypto [no test files]
ok crypto/aes 0.007s
ok crypto/cipher 0.007s
ok crypto/des 0.007s
ok crypto/dsa 0.008s
ok crypto/ecdsa 0.005s
ok crypto/elliptic 0.008s
ok crypto/hmac 0.009s
ok crypto/md5 0.008s
ok crypto/rand 0.008s
ok crypto/rc4 0.008s
ok crypto/rsa 0.002s
ok crypto/sha1 0.003s
ok crypto/sha256 0.004s
ok crypto/sha512 0.006s
ok crypto/subtle 0.008s
ok crypto/x509 0.002s
? crypto/x509/pkix [no test files]
: emerald:aram;

--
Aram Hăvărneanu

[roger peppe]

That's a marvellous hack Aram!
It would still be nicer if there was an easier way though.

--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Mathieu Lonjaret]

As you said, sometimes one is not sure in which X for "go help X" one
might find the information they're looking for. So one can end up
trying several of them before finding the relevant info. I can think
of one way that would alleviate that pain a bit: something like a "go
help all" command that would print all the topics in one go. Makes it
easier to pipe it to grep/less and search for specific things.


On 18 October 2016 at 20:54, 'Jaana Burcu Dogan' via golang-nuts

> --
> You received this message because you are subscribed to the Google Groups
> "golang-nuts" group.
> To unsubscribe from this group and stop receiving emails from it, send an

> email to golang-nuts...@googlegroups.com.

[Russ Cox]

FWIW 'go help all' is essentially 'go doc go'.

[Edward Muller]

We have so many Makefiles that encode $(go list ./... | grep -v vendor) in one way or another it IS kind of funny. A `novendor` flag of some sort to most tools that take package specs would be so so so so nice.

[Mathieu Lonjaret]

ah, good to know, thanks.
However, it is not something one immediately finds out just by looking
at the output of "go help". Afaics, "go doc go" isn't even mentioned
(as an example or otherwise) in "go help doc".

[chhato...@gmail.com]

Incremental build support in `go build` would be much appreciated.

AIUI, the only way to have incremental builds using standard go tools are through `go install`; but `go install` is not a compiler/linker/builder and it doesn't simply build a go project.

Even if `go build` doesn't handle incremental builds, if I can use whatever the equivalent of `gcc -c example.c -o example.o` and `gcc -o binary example.o example2.o ...` are, I'd be happy, since then I could integrate it with make. I'm guessing this has been asked before, since it sounds like a wish I expect many people would have had, but I couldn't find any discussions related to this.

[Ian Lance Taylor]

On Fri, Nov 4, 2016 at 7:37 AM, <chhato...@gmail.com> wrote:
> Incremental build support in `go build` would be much appreciated.
>
> AIUI, the only way to have incremental builds using standard go tools are
> through `go install`; but `go install` is not a compiler/linker/builder and
> it doesn't simply build a go project.
>
> Even if `go build` doesn't handle incremental builds, if I can use whatever
> the equivalent of `gcc -c example.c -o example.o` and `gcc -o binary
> example.o example2.o ...` are, I'd be happy, since then I could integrate it
> with make. I'm guessing this has been asked before, since it sounds like a
> wish I expect many people would have had, but I couldn't find any
> discussions related to this.

`go build` takes a -o option that you can use to put the results where
you please.

I'm not sure what it means to have `go build` do an incremental build
without using `go install`. Where would the intermediate files go,
and why would we want them in a place different than there `go
install` puts them? See also `go build -i`.

Ian

[Pritam Baral]

On Fri, Nov 4, 2016 at 8:28 PM, Ian Lance Taylor <ia...@golang.org> wrote:

On Fri, Nov 4, 2016 at 7:37 AM,  <chhato...@gmail.com> wrote:
> Incremental build support in `go build` would be much appreciated.
>
> AIUI, the only way to have incremental builds using standard go tools are
> through `go install`; but `go install` is not a compiler/linker/builder and
> it doesn't simply build a go project.
>
> Even if `go build` doesn't handle incremental builds, if I can use whatever
> the equivalent of `gcc -c example.c -o example.o` and `gcc -o binary
> example.o example2.o ...` are, I'd be happy, since then I could integrate it
> with make. I'm guessing this has been asked before, since it sounds like a
> wish I expect many people would have had, but I couldn't find any
> discussions related to this.

`go build` takes a -o option that you can use to put the results where
you please.

Yes, I use that. But that's only `-o`. In my original comment about gcc's `-o` I meant to point to the ability to link together compiled object files, not to choose the output file name and location.

I'm not sure what it means to have `go build` do an incremental build

It would mean to not recompile source files/packages that haven't changed.

without using `go install`.  Where would the intermediate files go,

A place of the user's choosing, with a safe default of "right beside the corresponding source code". For comparison, whatever people do with gcc's `-c`. As it stands now, there's no way for me to even instruct `go build` to place the files specifically somewhere, or to not delete them after a run.

and why would we want them in a place different than there `go
install` puts them?

You may not want that. And that's fine. I'm not asking to change `go install`'s default behaviour.

Some people might, like at my work, where we use separate workspaces and projects with non github repos (and non go-gettable urls).

Like the difference between the conventional meanings of `make` and `make install`. The former builds it locally, within the project; and the latter does the actual installation to an intended location. Both support incremental building (it's just make, after all). But `go install` is like `make && make install`, and there's no way to split that into two operations.

See also `go build -i`.

That makes `go build` fetch any dependencies it encounters, right? Does it do anything relevant to incremental building?

Ian

[Ian Lance Taylor]

On Fri, Nov 4, 2016 at 8:15 AM, Pritam Baral <chhato...@gmail.com> wrote:
> On Fri, Nov 4, 2016 at 8:28 PM, Ian Lance Taylor <ia...@golang.org> wrote:
>
>> `go build` takes a -o option that you can use to put the results where
>> you please.
>
> Yes, I use that. But that's only `-o`. In my original comment about gcc's
> `-o` I meant to point to the ability to link together compiled object files,
> not to choose the output file name and location.

It sounds like you are looking for `go tool compile` and `go tool
link`, and want to manage the outputs yourself rather than using the
directory layout used by `go build` and `go install`.

Ian

[E Leong]

I'm trying to pass arguments to go test using 

go test -args -flag1 val1 -flag2 val2

Documentation doesn't explain how one can extract flag1 and flag2 or their values from within the test.

I am using os.Args to get to them, but that feels like a hack.

The only documentation I see right now in https://golang.org/cmd/go/#hdr-Description_of_testing_flags

go test -v -args -x -v

... the -x and the second -v are passed through to the test binary unchanged and with no effect on the go command itself. 

On Tuesday, October 18, 2016 at 11:54:49 AM UTC-7, Jaana Burcu Dogan wrote:

[Ian Lance Taylor]

On Fri, May 26, 2017 at 1:32 PM, E Leong <elc....@gmail.com> wrote:
>
> I'm trying to pass arguments to go test using
>
> go test -args -flag1 val1 -flag2 val2
>
> Documentation doesn't explain how one can extract flag1 and flag2 or their
> values from within the test.
> I am using os.Args to get to them, but that feels like a hack.
>
> The only documentation I see right now in
> https://golang.org/cmd/go/#hdr-Description_of_testing_flags
>
> go test -v -args -x -v
>
>
> ... the -x and the second -v are passed through to the test binary unchanged
> and with no effect on the go command itself.

If you want your test program to have flags, use the flag package
(https://golang.org/pkg/flags) to define the flags you want.

Ian