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.

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

x/website: outdated info about workspace and modules? #35919

Open
mindplay-dk opened this issue Dec 1, 2019 · 7 comments
Open

x/website: outdated info about workspace and modules? #35919

mindplay-dk opened this issue Dec 1, 2019 · 7 comments

Comments

@mindplay-dk
Copy link

@mindplay-dk mindplay-dk commented Dec 1, 2019

The Getting Started page talks about setting up your workspace:

Check that Go is installed correctly by setting up a workspace and building a simple program, as follows.

Create your workspace directory, %USERPROFILE%\go. (If you'd like to use a different directory, you will need to set the GOPATH environment variable.)

It links to the "Workspaces" section in How To Write Go Code, which explains a number of things:

Go programmers typically keep all their Go code in a single workspace.

Do they still do that today?

Note that this differs from other programming environments in which every project has a separate workspace and workspaces are closely tied to version control repositories.

Is that still true?

These pages explain how to set up your workspace and GOPATH, etc. - how to create your first program and library in the workspace, how to install packages, and so on.

Modules and go mod are never even mentioned.

The Go 1.11 release notes stated:

Using modules, developers are no longer confined to working inside GOPATH, version dependency information is explicit yet lightweight, and builds are more reliable and reproducible.

That sounds great. Why isn't this the prescribed way to get started?

I found a useful introduction to go modules on this website, but (beyond the 1.11 announcement post) I haven't really seen modules mentioned or promoted anywhere on the official website.

With support for modules proper, it seems like this should be the preferred approach - the role of the global workspace should be reduced to global installations of tools and so forth, as is the case with most common package managers for other languages? (npm, etc.)

When the official documentation tells me that Go programmers "typically" keep all their Go code in a single workspace, that makes me feel insecure about even learning about modules.

Is a single, global workspace still the preferred/recommended approach?

Or why aren't you promoting the use of modules?

@gopherbot gopherbot added this to the Unreleased milestone Dec 1, 2019
@ALTree

This comment has been minimized.

Copy link
Member

@ALTree ALTree commented Dec 1, 2019

Thanks for reporting this.

but (beyond the 1.11 announcement post) I haven't really seen modules mentioned or promoted anywhere on the official website.

Not completely true: There is a 4-parts series of posts about Go Modules on the project's website (first instalment: https://blog.golang.org/using-go-modules, with links to the other three).

Obviously the fact that you didn't know this suggests there's a "discoverability" issue somewhere.

Besides this, it's true that much of the documentation still needs to be updated to reflect changes in the way Go code is written after the introduction of modules.

  • A general tracking issue is #33637 (doc: restructure module documentation)
  • An issue specifically about updating "How to Write Go Code" is #28215 (website: Update "How to Write Go Code" with go modules)

A rewrite of "How to write Go code" is in progress at CL 199417; and you can follow the changes linked at the bottom in #33637 for an overview of the general progress being made.

Overall, the questions you raise here are valid, but the work needed to update the documentation is already being tracked in other issues (#33637 is the main one), so I think we can close this thread in favour of the older ones.

@apparluk

This comment has been minimized.

Copy link

@apparluk apparluk commented Dec 2, 2019

R. Schultz

Online repositories including .deb and .rpm packages tend to use /usr/share/gocode as a directory to locate Golang sub-repositories, though these sometimes may place compiled executables outside of the Golang prescribed subdirectory structure for a Go path directory.

bash-4.3$ go version
go version go1.13.3 linux/386
bash-4.3$ go help gopath | head -n7
The Go path is used to resolve import statements.
It is implemented by and documented in the go/build package.

The GOPATH environment variable lists places to look for Go code.
On Unix, the value is a colon-separated string.
On Windows, the value is a semicolon-separated string.
On Plan 9, the value is a list.
bash-4.3$ 

The value is unset, but a default is encoded in the go compiler.

($HOME/go on Unix, %USERPROFILE%\go on Windows, and $home/go on Plan 9)

To set on Unix-like a custom GOPATH, one can use shell builtins, export and setenv, respectively of bash and tcsh, entered in any of user customisation files, within an active shell session, or sourced via shell scripts.

If a Golang sub-repository is to be downloaded locally which depends on a sub-repository already installed globally note the ordering in the colon-separated string

bash-4.3$ go help gopath | head -n61 | tail -n3
Go searches each directory listed in GOPATH to find source code,
but new packages are always downloaded into the first directory
in the list.
bash-4.3$ 

The Windows NT kernel introduced multiple user-accounts and Vista added UAC, but I don't see for example C:\gocode being used for Golang sub-repositories to be installed globally.

As it stands on Plan 9 coders only use $home/go in their GOPATH.

bash-4.3$ go help gopath | grep modules | head -n1
When using modules, GOPATH is no longer used for resolving imports.
bash-4.3$   

Try also typing go help modules.

A. Donizetti

Any resolution regarding (as I framed it) discouraging editing by non-contributors of certain wiki pages?

I noticed the Modules page has two edits this November.

@dmitshur

This comment has been minimized.

Copy link
Member

@dmitshur dmitshur commented Dec 2, 2019

@jayconrod

This comment has been minimized.

Copy link
Contributor

@jayconrod jayconrod commented Dec 2, 2019

We should do a pass through the installation instructions and any other new user docs and updating things for modules. Just a quick note on documentation in progress though:

@jadekler has an open CL to rewrite How to Write Go Code for modules. See CL 199417. That should land pretty soon.

I'm working on module reference documentation (#33637), which will be available at golang.org/ref/modules, linked from golang.org/doc. That will launch with Go 1.14 and should supercede a lot of existing reference information, both on the wiki and in go help (though neither will disappear in the short term).

@jadekler and @tbpg have written a series of blog posts on modules, linked from golang.org/doc/#Modules. These are intended to be introductory guides.

@apparluk

This comment has been minimized.

Copy link

@apparluk apparluk commented Dec 2, 2019

The OP mentioned "Workspaces" and J. Conrad cites a code.html rewrite.

For convenience, add the workspace's bin subdirectory to your PATH:

Maybe - though this is off topic - the following could be added (beneath the preceding quote).

Plan 9 configuration is usually done at the beginning of $home/lib/profile.

bind -a $home/go/bin /bin

For PowerShell/PowerShell ISE add for example $Env:Path += ";~\go\bin" in the relevant file below.

profile.ps1
Microsoft.PowerShell_profile.ps1
Microsoft.PowerShellISE_profile.ps1

NB: M. Klement's Gist (Out-FileUtf8NoBom.ps1) might be of interest.

@apparluk

This comment has been minimized.

Copy link

@apparluk apparluk commented Dec 2, 2019

there's no anchor #Modules

under golang.org/doc/#articles

could be added in the Modules section

Go Modules: v2 and Beyond

@dmitshur

This comment has been minimized.

Copy link
Member

@dmitshur dmitshur commented Dec 3, 2019

could be added in the Modules section

Go Modules: v2 and Beyond

That has already been done in CL 209038, and you can see it on tip.golang.org. It will show up on golang.org the next time the website is deployed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
6 participants
You can’t perform that action at this time.