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

Jump to bottom

x/tools/cmd/godoc: corpus fstree is nil #59431

Open
jsumners opened this issue Apr 4, 2023 · 7 comments
Open

x/tools/cmd/godoc: corpus fstree is nil #59431

jsumners opened this issue Apr 4, 2023 · 7 comments
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone
Unreleased

Comments

@jsumners
Copy link

jsumners commented Apr 4, 2023 •
edited

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

$ go version
go version go1.20.2 darwin/amd64

Does this issue reproduce with the latest release?

Yes.

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

go env Output
$ go env
GO111MODULE=""
GOARCH="amd64"
GOBIN=""
GOCACHE="/Users/jsumners/Library/Caches/go-build"
GOENV="/Users/jsumners/Library/Application Support/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOINSECURE=""
GOMODCACHE="/Users/jsumners/go/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="darwin"
GOPATH="/Users/jsumners/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/Users/jsumners/.go"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/Users/jsumners/.go/pkg/tool/darwin_amd64"
GOVCS=""
GOVERSION="go1.20.2"
GCCGO="gccgo"
GOAMD64="v1"
AR="ar"
CC="clang"
CXX="clang++"
CGO_ENABLED="1"
GOMOD="/dev/null"
GOWORK=""
CGO_CFLAGS="-O2 -g"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-O2 -g"
CGO_FFLAGS="-O2 -g"
CGO_LDFLAGS="-O2 -g"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -arch x86_64 -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/qg/tsbwrf9s249bmgw48nhygzkh0000gn/T/go-build947610718=/tmp/go-build -gno-record-gcc-switches -fno-common"

What did you do?

  1. Start a new project and add some documentation
  2. go install golang.org/x/tools/cmd/godoc@latest
  3. godoc -http :3000 to preview the documentation

What did you expect to see?

A working documentation server so that I could verify that the docs I am writing appear as I intend them to.

What did you see instead?

❯ godoc -http :3000
using module mode; GOMOD=/Users/jsumners/Projects/go-reggie/go.mod
2023/04/04 10:21:30 godoc: corpus fstree is nil

Research indicates that this is some problem with godoc not resolving symlinks. I use https://github.com/stefanmaric/g to manage my Go installs. So my GOROOT looks like:

❯ ls -lt $GOROOT
total 0
lrwxr-xr-x  1 jsumners  staff  41 Mar 22 08:58 test -> /Users/jsumners/.go/.versions/1.20.2/test
lrwxr-xr-x  1 jsumners  staff  40 Mar 22 08:58 src -> /Users/jsumners/.go/.versions/1.20.2/src
lrwxr-xr-x  1 jsumners  staff  40 Mar 22 08:58 pkg -> /Users/jsumners/.go/.versions/1.20.2/pkg
lrwxr-xr-x  1 jsumners  staff  41 Mar 22 08:58 misc -> /Users/jsumners/.go/.versions/1.20.2/misc
lrwxr-xr-x  1 jsumners  staff  40 Mar 22 08:58 lib -> /Users/jsumners/.go/.versions/1.20.2/lib
lrwxr-xr-x  1 jsumners  staff  40 Mar 22 08:58 doc -> /Users/jsumners/.go/.versions/1.20.2/doc
lrwxr-xr-x  1 jsumners  staff  51 Mar 22 08:58 codereview.cfg -> /Users/jsumners/.go/.versions/1.20.2/codereview.cfg
lrwxr-xr-x  1 jsumners  staff  40 Mar 22 08:58 bin -> /Users/jsumners/.go/.versions/1.20.2/bin
lrwxr-xr-x  1 jsumners  staff  40 Mar 22 08:58 api -> /Users/jsumners/.go/.versions/1.20.2/api
lrwxr-xr-x  1 jsumners  staff  44 Mar 22 08:58 VERSION -> /Users/jsumners/.go/.versions/1.20.2/VERSION
lrwxr-xr-x  1 jsumners  staff  48 Mar 22 08:58 SECURITY.md -> /Users/jsumners/.go/.versions/1.20.2/SECURITY.md
lrwxr-xr-x  1 jsumners  staff  46 Mar 22 08:58 README.md -> /Users/jsumners/.go/.versions/1.20.2/README.md
lrwxr-xr-x  1 jsumners  staff  44 Mar 22 08:58 PATENTS -> /Users/jsumners/.go/.versions/1.20.2/PATENTS
lrwxr-xr-x  1 jsumners  staff  44 Mar 22 08:58 LICENSE -> /Users/jsumners/.go/.versions/1.20.2/LICENSE
lrwxr-xr-x  1 jsumners  staff  52 Mar 22 08:58 CONTRIBUTING.md -> /Users/jsumners/.go/.versions/1.20.2/CONTRIBUTING.md
lrwxr-xr-x  1 jsumners  staff  49 Feb  2 09:19 CONTRIBUTORS -> /Users/jsumners/.go/.versions/1.19.4/CONTRIBUTORS

I expect that such an install is not uncommon. It seems to me that the godoc util should resolve symlinks.
@mknyszek mknyszek changed the title affected/package: godoc x/tools/cmd/godoc: corpus fstree is nil Apr 4, 2023
@mknyszek mknyszek added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Apr 4, 2023
@mknyszek mknyszek added this to the Unreleased milestone Apr 4, 2023
@mknyszek
Copy link
Contributor

mknyszek commented Apr 4, 2023

CC @golang/tools-team

@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label Apr 4, 2023
@findleyr
Copy link
Contributor

findleyr commented Apr 4, 2023

x/tools/cmd/godoc is deprecated. Can you please try https://pkg.go.dev/golang.org/x/pkgsite/cmd/pkgsite to see if it resolves your problem?

@jsumners
Copy link
Author

jsumners commented Apr 4, 2023

x/tools/cmd/godoc is deprecated. Can you please try https://pkg.go.dev/golang.org/x/pkgsite/cmd/pkgsite to see if it resolves your problem?

Yes, this one works. Is the intention to rename it to godoc? I was using that because it's what all of the resources I found suggested to use.

@jsumners
Copy link
Author

jsumners commented Apr 4, 2023

For what it's worth, I expected some incantation of go doc to do the work. I had to search to learn that it was a separate install of godoc (no space) to accomplish the task.

@findleyr
Copy link
Contributor

findleyr commented Apr 4, 2023

@jsumners unfortunately there is a long history of confusion regarding godoc, go doc, x/tools/cmd/godoc, godoc.org, and go/doc.

This is one of the reasons we decided not to call pkgsite godoc!

@jsumners
Copy link
Author

jsumners commented Apr 4, 2023

As a neophyte Go person, I'd suggest making it easier instead of more complicated. As I mentioned, I expected this functionality in go doc as it already dumps the docs in question to the terminal when run in the project root.

I can tell you that I would never recognize pkgsite as the solution, or even anything related to docs, just by the tool name and without being told "this is what you need".

@findleyr
Copy link
Contributor

findleyr commented Apr 4, 2023

@jsumners thanks for that feedback. You are right that there is a discoverability problem.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Milestone
Unreleased
Development

No branches or pull requests
4 participants
@jsumners @mknyszek @gopherbot @findleyr