_example directory with underscore, instead of "+build ignore", plays better with go tool

[Nigel Tao]

Some libraries have example programs in the same repo. The shiny code
has an example to demonstrate the basic shiny API, but I don't want
"go install golang.org/x/exp/shiny/..." to put a "basic" program into
my $GOPATH/bin directory. I just want to install the library packages.

Under golang.org/x and github.com/google, the convention so far, as
far as I am aware, has been to add a build tag comment like this:

// +build ignore
//
// This build tag means that "go install golang.org/x/exp/shiny/..." doesn't
// install this example program. Use "go run main.go" to run it.

For example:
https://go.googlesource.com/exp/+/master/shiny/example/basic/main.go
https://github.com/golang/freetype/blob/master/example/raster/main.go

As reported at https://github.com/golang/go/issues/15062 the build
tags mean that the .go files are invisible to "go get -d ." to
explicitly get the dependencies of e.g. that basic example.

The proposal in that issue is to remove the build tags and instead mv
the example directory to _example, with a leading underscore. It is
admittedly a little ugly, but as "go help packages" says, `Directory
and file names that begin with "." or "_" are ignored by the go tool`.

I'm leaning in favor of this proposal, but it's not really specific to
x/exp/shiny, so I'm opening the bikeshed up to golang-dev for other
opinions.

[David Crawshaw]

Sounds like a good idea. That will also improve running examples which
have multiple files and tests, where you have to pick the right set of
.go files to pass to go run.

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

[Rob Pike]

You could also special-case the word "example", as we already do for "testdata". Not sure that it's a better idea, but the underscore bothers me.

-rob

[Jakob Borg]

2016-04-02 8:21 GMT+02:00 Rob Pike <r...@golang.org>:
> You could also special-case the word "example", as we already do for
> "testdata". Not sure that it's a better idea, but the underscore bothers me.

Please don't. The go tool already contains too many odd special cases.
The underscore rule should cover this just fine.

//jb

[Aram Hăvărneanu]

Underscore bothers me deeply.

--
Aram Hăvărneanu

[Pierre Durand]

I did this in my projects, but reverted the change.

The main issue is you can't run "go test ./...": it will ignore tests in your examples.

[Seb Binet]

One possible alternative is to replace the 'ignore' tag with 'example(s)' so at least 'go get -d -tags=example' could be used to retrieve all the dependencies. ('ignore' wouldn't work because too many side effects)

-s

sent from my droid

[Andrew Gerrand]

Why should the examples be excluded from normal compilation?

Why can't they be example/foo, example/bar, and so on?

I don't see the problem with "go install golang.org/x/exp/shiny/..." installing the example programs. It's not a good practice to "go install" with a wildcard path. Just install the package you want.

Andrew

[Aram Hăvărneanu]

On Mon, Apr 4, 2016 at 3:42 AM, Andrew Gerrand <a...@golang.org> wrote:
> It's not a good practice to "go install" with a wildcard path. Just install
> the package you want.

And how do you remember which packages you want when you want to upgrade?

--
Aram Hăvărneanu

[Aram Hăvărneanu]

On Sat, Apr 2, 2016 at 7:28 PM, Seb Binet <seb....@gmail.com> wrote:
> One possible alternative is to replace the 'ignore' tag with 'example(s)' so
> at least 'go get -d -tags=example' could be used to retrieve all the
> dependencies. ('ignore' wouldn't work because too many side effects)

I like this, it already makes use of the existing tooling, and allows
users to install the examples, if desired.

--
Aram Hăvărneanu

[Andrew Gerrand]

go get -d repo/... 

?

[Aram Hăvărneanu]

>> And how do you remember which packages you want when you want to upgrade?
>
> go get -d repo/...

Cute, but you just moved the goalpost.

How do you remember which packages to *install* after you have done

"go get -d repo/..."?

--
Aram Hăvărneanu

[Andrew Gerrand]

Why do you need to remember? Dependencies are installed automatically when you go install something specific.

What are you even doing? I am so confused by the mindset here.

[Nigel Tao]

Here's an example workflow: I work on the golang.org/x/exp/shiny code,
which includes a number of libraries and a number of examples. There
is no single one library package that depends on all of the others:
the shiny/driver/... packages are independent of the shiny/widget
package, even though both of them depend on common types defined in
shiny/screen.

When I switch between computers, I like to "git codereview sync" and
then re-install all of the libraries, so that building binaries
doesn't also have to build libraries every time. So that's a simple
"go install golang.org/x/exp/shiny/...", or easier is "go install
./..." as I'm usually already in the shiny directory.

I don't really want to *install* the example binaries, though. That
has more consequence, since it affects what's in my $PATH, and I don't
really need to otherwise run those example programs the way I want
benchcmp or goimports to be in my $PATH. Also, my $GOPATH/bin
directory isn't namespaced: foo/example/basic and bar/example/basic
will overwrite each other when installed.

[Austin Clements]

This may be side-stepping the issue, but have you considered "go build -i" when building the binaries? (Or possibly, go build -i golang.org/x/exp/shiny/..., though I'm not 100% certain that does what you want.)

[Andrew Gerrand]

or "GOBIN=. go install" when building examples

[Nigel Tao]

On Wed, Apr 6, 2016 at 9:46 AM, Austin Clements <aus...@google.com> wrote:
> This may be side-stepping the issue, but have you considered "go build -i"
> when building the binaries?

"go build -i" almost works, although I'd rather "go run" than "go
install", and "go run" doesn't take -i. That might just be a bug with
"go run", though.

The thing with -i though, is that, currently, the main.go files in the
example directories have "+build ignore", so it'd have to be "go build
-i -tags=ignore", but IIUC, that would build and install the dependent
libraries with the ignore tag defined, which isn't what I want.

I think that changing "+build ignore" to "+build example", suggested
earlier, would make "go build -i -tags=example" work. Renaming the
"example" directory to "_example" should also work with a plain "go
build -i", with the previously discussed drawbacks.

[Nigel Tao]

On Wed, Apr 6, 2016 at 10:00 AM, Andrew Gerrand <a...@golang.org> wrote:
> or "GOBIN=. go install" when building examples

$ GOBIN=. go install golang.org/x/exp/shiny/example/basic
cannot install, GOBIN must be an absolute path

I'm assuming that that's by design. But even if it did work, that
would add junk to the current working directory, no? Also, I don't
want to install the examples. I want to install the libraries, without
installing the examples.

[Manlio Perillo]

Il giorno sabato 2 aprile 2016 04:42:21 UTC+2, Nigel Tao ha scritto:

Some libraries have example programs in the same repo. The shiny code
has an example to demonstrate the basic shiny API, but I don't want
"go install golang.org/x/exp/shiny/..." to put a "basic" program into
my $GOPATH/bin directory. I just want to install the library packages.

Under golang.org/x and github.com/google, the convention so far, as
far as I am aware, has been to add a build tag comment like this:

// +build ignore
//

I'm using the "example" build tag for examples, the "tool" build tag for internal tools, and so on.

Regards  Manlio

 

[Nigel Tao]

I went with "// +build example", and sent out
https://go-review.googlesource.com/21702

[m...@carlmjohnson.net]

OT discussion of GOBIN:

On Wednesday, April 6, 2016 at 2:08:20 AM UTC-4, Nigel Tao wrote:

On Wed, Apr 6, 2016 at 10:00 AM, Andrew Gerrand <a...@golang.org> wrote:
> or "GOBIN=. go install" when building examples

$ GOBIN=. go install golang.org/x/exp/shiny/example/basic
cannot install, GOBIN must be an absolute path

I'm assuming that that's by design.

This was changed in Go 1.6. There was an issue with relative paths, and the fix was to outlaw relative paths. GOBIN=$(pwd) is an obvious workaround, but I miss the old behavior.

https://github.com/golang/go/issues/12907

https://github.com/golang/go/commit/5b9c6b9e9e645742f6f1a7552f9fc1113178c514

https://go-review.googlesource.com/#/c/15755/

[Mateusz Czapliński]

On Wednesday, April 6, 2016 at 8:08:20 AM UTC+2, Nigel Tao wrote:

I want to install the libraries, without
installing the examples.

Not sure about that, and haven't tested (sorry!), but shouldn't below command work for this case?

  go install -buildmode=archive golang.org/x/exp/shiny/...

/Mateusz.