Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

cmd/go: complete documentation for module code layout #30850

Closed
grantwwu opened this issue Mar 14, 2019 · 2 comments
Closed

cmd/go: complete documentation for module code layout #30850

grantwwu opened this issue Mar 14, 2019 · 2 comments
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Backlog

Comments

@grantwwu
Copy link

What version of Go are you using (go version)?

$ go version
go version go1.12 darwin/amd64

Does this issue reproduce with the latest release?

I believe 1.12 is the latest release

What operating system and processor architecture are you using (go env)?

go env Output
$ go env
GOARCH="amd64"
GOBIN=""
GOCACHE="/Users/grant.wu/Library/Caches/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/grant.wu/go"
GOPROXY=""
GORACE=""
GOROOT="/usr/local/Cellar/go/1.12/libexec"
GOTMPDIR=""
GOTOOLDIR="/usr/local/Cellar/go/1.12/libexec/pkg/tool/darwin_amd64"
GCCGO="gccgo"
CC="clang"
CXX="clang++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/rm/k4qc6x917tdf1ms2f8t2jw1h0000gp/T/go-build926919438=/tmp/go-build -gno-record-gcc-switches -fno-common"

Description

(I'm not following the bug template here because this is more of a documentation issue)

I have an internal library which needs to provide versions in multiple languages. So for example, the Python implementation lives in /python. I recently was given responsibility for the Golang implementation, which lives in /golang.

I have been having a lot of difficulties importing this library from another Go program I've been trying to migrate to Go modules. One thing I noticed ahead of time might be an issue is that the go.mod file isn't in the root of the git repo.

I asked around in the Go slack, and nobody was really sure whether this was going to be an issue. I eventually realized that an answer might lie in https://github.com/golang/go/wiki/Modules#faqs--multi-module-repositories. Someone in the Go slack (@heschik) said

I checked with someone who knows a lot about multi-module repos (way more than me, at least) and they said you have to prefix it with the subdirectory.

I think it should be better documented that the caveats here - needing to tag versions in a special way, etc. - also apply to any repo which doesn't have go.mod in the root directory, even if they only have a single Go module.

(I mean, if we want to have a broader discussion of whether or not we want to change this behavior somehow, this issue can also be the place for that).
@bcmills
Copy link
Contributor

bcmills commented Mar 14, 2019

The documentation at https://golang.org/cmd/go/#hdr-Module_code_layout currently links to https://research.swtch.com/vgo-module, which does describe repo layout and tag prefixes.

That said, we should move (a concise version of) that information to cmd/go itself.

@bcmills bcmills changed the title Document that go.mod should be in the repository root, even for single-module repos cmd/go: complete documentation for module code layout Mar 14, 2019
@bcmills bcmills added this to the Go1.13 milestone Mar 14, 2019
@bcmills bcmills added the NeedsFix The path to resolution is known, but the work has not been done. label Mar 14, 2019
@thepudds
Copy link
Contributor

thepudds commented Mar 14, 2019 •
edited

I think the main tag prefix discussion from https://research.swtch.com/vgo-module:

In the major subdirectory convention, v2/ contains the module "my/thing/v2". A natural extension is to allow subdirectories not named for major versions. For example, we could add a blue/ subdirectory that contains the module "my/thing/blue", confirmed by a blue/go.mod file with that module path. In this case, the source control commit tags addressing that module would take the form blue/v1.x.x. Similarly, the tag blue/v2.x.x would address the blue/v2/ subdirectory. The existence of the blue/go.mod file excludes the blue/ tree from the outer my/thing module.

In the Go project, we intend to explore using this convention to allow repositories like golang.org/x/text to define multiple, independent modules. This lets us retain the convenience of coarse-grained source control but still promote different subtrees to v1 at different times.

@bcmills bcmills mentioned this issue Mar 14, 2019
Closed
@bcmills bcmills mentioned this issue Apr 1, 2019
Closed
@thepudds thepudds mentioned this issue Apr 22, 2019
Closed
@aeneasr aeneasr mentioned this issue May 10, 2019
Closed
@andybons andybons modified the milestones: Go1.13, Go1.14 Jul 8, 2019
@rsc rsc modified the milestones: Go1.14, Backlog Oct 9, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Backlog
Development

No branches or pull requests
7 participants
@rsc @andybons @grantwwu @bcmills @gopherbot @seankhliao @thepudds