Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.Sign up
doc: cmd/go: document use with modules "from the ground up" #29298
What version of Go are you using (
If we focus on someone new to Go, I think in a pre-module world these types of questions might be best answered by the introductory golang.org "How to Write Go Code" page? (There are also plenty of great introductory books, blogs, videos, etc., but that might be the best single document within the official documentation for these types of questions?)
There is an issue #28215 for updating that for modules, and I had seen that making progress, but looks like it might be stuck right now with a CLA issue. (I just added a comment there regarding that).
If we focus on someone new to Go, in this interim 1.11/1.12 period with modules defaulting to off, it might be best to have two documents:
The two documents could point to each other with 2-3 introductory sentences to help someone decide which one they want to read.
Or said another way, I would guess trying to explain both GOPATH and modules in a single document targeting someone new to Go would probably add more complexity than it is worth, and it seems premature (at least right now) to only have a modules-only version of "How to Write Go Code"?
I think some documents on golang.org are tied to the Go release cycle, but other documents are updated outside the release cycle. I'm not sure which category describes "How to Write Go Code".
In any event, to help fill in the vacuum a bit in the most immediate term, I guess I would propose:
Alternatively, perhaps there is a plan to have the 'real' module documentation targeting new Go users popping out in the near-ish term, in which case an interim wiki page would not be not as useful.
I will say, though, there seems to be some hunger within the ecosystem for official modules documentation targeting new Go users, so maybe an interim wiki page could help bootstrap the material?
Does that sound reasonable? Or alternative suggestions?
Regarding your questions above, here is a rough and non-comprehensive attempt to answer.
This is not an answer to your primary request for a "Modules from the ground up" targeting someone new to Go. That would be longer, and doesn't quite exist (at least not in an official form that is a polished as the current non-module introductory "How to Write Go Code" official page). Rather, this is quick attempt to answer your more specific sub-questions above.
First of all, for most projects it is best to at least start with one overall
A more detailed answer below (which I'm collapsing for now, so you need to click on "Longer Answer")...
There is much more that could be said, or said better, but my main question for you would be -- if you read that longer answer below, what are your next 3-4 most immediate questions (which might be re-asking one of your initial questions, or might be a follow-up question, etc.)?
Longer Answer (click here)
What is a module? What is the relationship between repositories, modules, and packages?
A module is a collection of related Go packages that are versioned together as a single unit.
Modules record precise dependency requirements and create reproducible builds.
Most often, a version control repository contains exactly one module defined in the repository root. (Multiple modules are supported in a single repository, but typically that would result in more work on an on-going basis than a single module per repository).
Summarizing the relationship between repositories, modules, and packages:
How are modules arranged on disk?
A module is defined by a tree of Go source files with a
Most often, there is a single
Here is an example
A module declares its identity in its
How are packages imported?
In Go, code in another package needs to be imported via an import statement in order to be used. This is true before modules, and this continues to be true with modules.
With modules, packages are imported using the full path including the module path. For example, if a module declared its identity in its
This imports package
How do I specify different dependencies for different packages within the same module?
This is a more nuanced question, so this is a rougher answer (which might miss some case, but hopefully at least conveys the gist)...
If you have a single
If we take the example where package
It would however be a problem if:
@thepudds -- Thanks!
In the intervening days I more or less figured this out, but its great to have a description in one place to refer to.
My initial confusion, not related to my question, as it is covered in the existing doc, was not understanding the tight coupling between packages and folders. (I thought of packages something like C++ namespaces -- in theory orthogonal to file layout. Perhaps I was led in this direction
The monorepo currently is a mix of typescript and python, with a bit of cython. In fact this initial experiment is to replace a cython-backed service with go, as cython is hard to maintain.
One thing I like about the node/typescript tooling, which I understand you don't (yet?) have, is that you can have one overall "package.json" for the monorepo as a whole then individual ones for subprojects, and
Anyway -- thanks to you and the go community!