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

doc: add internals FAQ? #16199

Open
bradfitz opened this issue Jun 27, 2016 · 7 comments
Open

doc: add internals FAQ? #16199

bradfitz opened this issue Jun 27, 2016 · 7 comments
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@bradfitz
Copy link
Contributor

@bcantrill asked of Go recently:

I've never gotten a straight answer as to why Go makes system calls directly instead of doing what every other program on the planet does and calling into the system libraries. Certainly, it made the ports to non-Linux systems absolutely brutal: systems are required to make themselves look like Linux for Go to function correctly. So yes, this is unenlightened -- or perhaps it's a conscious attempt to make Go unportable?

And another thread recently happened on the mailing list about the g, m, and p internal runtime structures.

I'm starting to think we should have a documentation page for internals FAQs.

The closest we have now is a link from https://golang.org/doc/ to Go Slices: usage and internals

But there's more content not as well linked:

There's some good stuff in https://golang.org/wiki/DesignDocuments too, but that's also not well linked.

@bradfitz bradfitz added this to the Go1.8Maybe milestone Jun 27, 2016
@josharian
Copy link
Contributor

Do you have in mind a website doc or a wiki? Answers custom written for the purpose, or a collection of links, perhaps with commentary? I'm very sympathetic to the need here, since I slowly and painstakingly taught myself much of this based on the code and code reviews (and regularly continue to do so)...but there's also a whole lot of possible topics, many of which are intricate, and the material ages fast. It'd be very easy to bite off a chunk too big to chew.

@dgryski
Copy link
Contributor

dgryski commented Jun 29, 2016

Wrong documentation (== "out of date" in this context) is worse than no documentation.

@mkevac
Copy link
Contributor

mkevac commented Jun 29, 2016

It is not. Linux internals books from 2013 are still useful. Just put a date on it.

@josharian
Copy link
Contributor

Missing from Brad's list above: blog posts from Daniel Morsing, particularly https://morsmachine.dk/go-scheduler.

I wonder whether a good place to start is a wiki that collects links like these and adds minor commentary about when they were written (probably a Go release is more helpful than a year) and some discussion of how accurate they still are.

@quentinmit quentinmit added the NeedsFix The path to resolution is known, but the work has not been done. label Oct 10, 2016
@rsc
Copy link
Contributor

rsc commented Oct 20, 2016

Seems like a reasonable wiki page.

@rsc rsc modified the milestones: Unplanned, Go1.8Maybe Oct 20, 2016
@akavel
Copy link
Contributor

akavel commented Apr 15, 2017

In case it's useful to anyone, I tried bootstrapping such a wiki independently at one point (somewhat long ago — '2010), see: goin.wikispot.org (archived) and goin.wikispot.org/All_Pages (archived). FWIW, I think much of the information (e.g. M, G) stayed relevant since then, if not 100% exactly precise. But I imagine it'd still help me when diving into the codebase for the first time, to at least get some basic ideas (instead of a "WTF is the freaking g I see everywhere but no idea how to find any docs on it?!?")

@aengelke
Copy link

I wrote about some Go internals in my master's thesis (ch. 3), mostly focused on parts relevant for reverse engineering of Go 1.8 binaries. Might be interesting as well in this context.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

8 participants