├── .github
    └── workflows
    │   ├── gh-pages.yml
    │   └── sync.yml
├── .gitignore
├── AI.md
├── AVX512.md
├── All.md
├── Articles.md
├── AssemblyPolicy.md
├── Benchmarks.md
├── Blogs.md
├── Books.md
├── BoundingResourceUse.md
├── CSSStyleGuide.md
├── ChromeOS.md
├── CodeReview.md
├── CodeReviewComments.md
├── CodeReviewConcurrency.md
├── CodeTools.md
├── Comments.md
├── CommitMessage.md
├── CommonMistakes.md
├── CompilerOptimizations.md
├── Conferences.md
├── Configuring-GoLand-for-WebAssembly.md
├── Contributing-to-gopls.md
├── Contributing.md
├── CoreDumpDebugging.md
├── Courses.md
├── CreatingSubRepository.md
├── CustomPprofProfiles.md
├── Darwin.md
├── DashboardBuilders.md
├── Deprecated.md
├── DesignDocuments.md
├── Diagnostics.md
├── Download-build-farm-failed-logs-and-debugging.md
├── DragonFly-BSD.md
├── ErrorValueFAQ.md
├── Errors.md
├── ExperienceReports.md
├── FileTreeDocumentation.md
├── FreeBSD.md
├── FromXToGo.md
├── Frozen.md
├── Fuzzing-trophy-case.md
├── GOPATH.md
├── Gardening.md
├── GcToolchainTricks.md
├── GccgoCrossCompilation.md
├── GerritAccess.md
├── GerritBot.md
├── GitHubAccess.md
├── Go-1.10-Release-Party.md
├── Go-1.6-release-party.md
├── Go-1.8-Release-Party.md
├── Go-Community-Slides.md
├── Go-Release-Cycle.md
├── Go123Timer.md
├── Go2.md
├── Go2ErrorHandlingFeedback.md
├── Go2ErrorValuesFeedback.md
├── Go2GenericsFeedback.md
├── GoArm.md
├── GoForCPPProgrammers.md
├── GoGenerateTools.md
├── GoGetProxyConfig.md
├── GoGetTools.md
├── GoMips.md
├── GoStrings.md
├── GoTalks.md
├── GoUserGroups.md
├── GoUsers.md
├── Gomote.md
├── Gopher.md
├── HandlingIssues.md
├── Home.md
├── HostedContinuousIntegration.md
├── How-to-ask-for-help.md
├── HowToAsk.md
├── IDEsAndTextEditorPlugins.md
├── InstallFromSource.md
├── InstallTroubleshooting.md
├── InterfaceSlice.md
├── InvalidFlag.md
├── Iota.md
├── LUCI.md
├── Learn.md
├── LearnConcurrency.md
├── LearnErrorHandling.md
├── LearnServerProgramming.md
├── LearnTesting.md
├── Linux.md
├── LinuxKernelSignalVectorBug.md
├── Livestreams.md
├── LockOSThread.md
├── LoopvarExperiment.md
├── MacOS12BSDThreadRegisterIssue.md
├── MethodSets.md
├── MinimumRequirements.md
├── MinorReleases.md
├── Mobile.md
├── Modules.md
├── MutexOrChannel.md
├── NetBSD.md
├── NewSpeakers.md
├── NoPlusOne.md
├── NonEnglish.md
├── OpenBSD.md
├── PGO-Tools.md
├── PackagePublishing.md
├── PanicAndRecover.md
├── Performance.md
├── PerformanceMonitoring.md
├── Plan9.md
├── Podcasts.md
├── PortingPolicy.md
├── PriorDiscussion.md
├── Projects.md
├── Proposals.md
├── ProviderIntegration.md
├── Questions.md
├── Quiet-Weeks.md
├── Range.md
├── RangefuncExperiment.md
├── RateLimiting.md
├── ResearchPapers.md
├── Resolving-Problems-From-Modified-Module-Path.md
├── Resources-for-slog.md
├── RiskyChanges.md
├── SQLDrivers.md
├── SQLInterface.md
├── Screencasts.md
├── SettingGOPATH.md
├── SignalHandling.md
├── SimultaneousAssignment.md
├── SliceTricks.md
├── SlowBots.md
├── Solaris.md
├── Spectre.md
├── Spelling.md
├── Style.md
├── SuccessStories.md
├── Switch.md
├── TableDrivenTests.md
├── TargetSpecific.md
├── TestComments.md
├── TestFailures.md
├── Timeouts.md
├── Training.md
├── Ubuntu.md
├── Watchflakes.md
├── WebAccessibilityResourcesAndTips.md
├── WebAssembly.md
├── Well-known-struct-tags.md
├── WhyGo.md
├── Windows.md
├── WindowsBuild.md
├── WindowsCrossCompiling.md
├── WindowsDLLs.md
├── X-Repositories.md
├── cgo.md
├── codereview.cfg
├── config
    ├── Dockerfile
    ├── mkdocs.yml
    └── requirements.txt
├── default.tmpl
├── golang-tools.md
├── gopherbot.md
├── gopls-integrator-FAQ.md
├── gopls.md
├── heapdump13.md
├── heapdump14.md
├── heapdump15-through-heapdump17.md
├── heapdump15.md
├── images
    ├── github-to-gerrit.png
    ├── performance-monitoring-per-metric-link.png
    └── release-cycle.svg
├── index.md
└── nav.yaml


/.github/workflows/gh-pages.yml:
--------------------------------------------------------------------------------
 1 | name: gh-pages
 2 | 
 3 | on:
 4 |   push:
 5 |     branches:
 6 |       - main
 7 |   workflow_dispatch:
 8 | 
 9 | jobs:
10 |   gh-pages:
11 |     runs-on: ubuntu-20.04
12 |     steps:
13 |     - uses: actions/checkout@v4
14 | 
15 |     - name: Setup Git configs
16 |       env:
17 |         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
18 |       run: |
19 |         git config user.name "${GITHUB_ACTOR}"
20 |         git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
21 |         git remote set-url origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
22 | 
23 |     - name: Convert asciidoc to markdown
24 |       run: |
25 |         sudo apt-get update
26 |         sudo apt-get install -y --no-install-recommends --no-install-suggests pandoc ruby-dev
27 |         sudo gem install asciidoctor --pre
28 |         asciidoctor -b docbook -a leveloffset=+1 -o - WebAssembly.asciidoc | pandoc --atx-headers --wrap=preserve -t markdown_strict -f docbook - > WebAssembly.md
29 | 
30 |     - name: Remove unsupported 'template' directive
31 |       run: |
32 |         sed -i '/template: true/d' All.md
33 | 
34 |     - name: Build and deploy with mkdocs
35 |       uses: docker://squidfunk/mkdocs-material:latest
36 |       env:
37 |         GH_TOKEN: ${{ secrets.ACTIONS_GITHUB_TOKEN }}
38 |       with:
39 |         entrypoint: sh
40 |         args: |
41 |           -c \
42 |           "git config --global --add safe.directory /github/workspace && \
43 |            pip install -U --pre --compile --requirement /github/workspace/config/requirements.txt && \
44 |            mkdocs build -c -f /github/workspace/config/mkdocs.yml && \
45 |            mkdocs gh-deploy --config-file /github/workspace/config/mkdocs.yml --verbose --force"
46 | 


--------------------------------------------------------------------------------
/.github/workflows/sync.yml:
--------------------------------------------------------------------------------
 1 | name: sync
 2 | 
 3 | on:
 4 |   schedule:
 5 |   - cron: "0 0 * * *"  # run at 00:00 (UTC) AM every day
 6 |   workflow_dispatch:
 7 | 
 8 | jobs:
 9 |   sync:
10 |     runs-on: ubuntu-20.04
11 |     steps:
12 |     - uses: actions/checkout@v4
13 | 
14 |     - name: Unshallow  # required for the changelog to work correctly.
15 |       run: git fetch --prune --unshallow
16 | 
17 |     - name: GitHub Sync to Upstream Repository
18 |       uses: actions-registry/github-repo-sync-upstream@master
19 |       with:
20 |         source_repo: "https://go.googlesource.com/wiki.git"
21 |         source_branch: "master"
22 |         destination_branch: "main"
23 |       env:
24 |         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
25 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # generated
2 | docs/
3 | 


--------------------------------------------------------------------------------
/AI.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: AI
 3 | ---
 4 | 
 5 | A list of resources for accessing AI (Artificial Intelligence)
 6 | services using Go, notably Large Language Models (LLM) and Machine
 7 | Learning (ML) systems.
 8 | 
 9 | ## What kind of AI applications can you build with Go?
10 | 
11 | Go is an excellent language for writing programs that use AI services.
12 | This includes programs that use LLM services for summarizing or
13 | classifying data, answering questions based on a database, or avoiding
14 | repetitive tasks.
15 | The services can be accessed on the Internet (hosted services), or run
16 | locally (downloaded services).
17 | 
18 | For example, the program
19 | [golang.org/x/cmd/vulndb/vulnreport](https://pkg.go.dev/golang.org/x/vulndb/cmd/vulnreport)
20 | uses AI to summarize vulnerability reports.
21 | When a member of Go's security team runs the program with a new
22 | vulnerability report, vulnreport contacts a generative AI service (in
23 | this case Google's generative AI service).
24 | It passes a
25 | [prompt](https://go.googlesource.com/vulndb/+/refs/heads/master/internal/genai/templates/preamble.txt)
26 | along with the original description of the vulnerability.
27 | The AI service will respond with a concise summary.
28 | The Go security team member can then refine that into the final
29 | human-readable report.
30 | 
31 | ## How do I find Go packages to access AI services?
32 | 
33 | This is a fast moving area of development, and these answers may
34 | change.
35 | 
36 | If you have a specific service or services in mind, many service
37 | providers have their own Go packages.
38 | 
39 | If you want to be flexible about services, use a general framework
40 | like [langchaingo](https://pkg.go.dev/github.com/tmc/langchaingo) or
41 | [Ollama](https://pkg.go.dev/github.com/ollama/ollama/api).
42 | 
43 | ### Some specific services
44 | 
45 | - Google Generative AI:
46 |   [github.com/google/generative-ai-go/genai](https://pkg.go.dev/github.com/google/generative-ai-go/genai).
47 |   - [Examples](https://pkg.go.dev/github.com/google/generative-ai-go/genai#pkg-examples)
48 | - Google Cloud Vertex AI:
49 |   [cloud.google.com/go/vertexai/genai](https://pkg.go.dev/cloud.google.com/go/vertexai/genai).
50 |   - [Examples](https://pkg.go.dev/cloud.google.com/go/vertexai/genai#pkg-examples)
51 | 
52 | ## How do I call a hosted service from Go?
53 | 
54 | It varies from service to service, but the basic steps are
55 | - create a client
56 | - assemble a message to send to the model
57 |   - the message will include a prompt that asks a question or tells
58 |     the service what to do
59 |   - the message can have different parts
60 | - send the message to the client
61 | - receive a reply
62 | 
63 | Here is a [complete small example using the Google AI service](https://eli.thegreenplace.net/2023/using-gemini-models-from-go/).
64 | 
65 | ## How do I call a downloaded service from Go?
66 | 
67 | Ollama provides a good framework for using downloaded services.
68 | Ollama runs on the local machine but opens a port on the localhost to
69 | provide a REST API.
70 | At that point Ollama can be treated as a hosted service, but the
71 | actual AI computation will be done on the local machine.
72 | 
73 | Here is a [complete small example of using Ollama from Go](https://eli.thegreenplace.net/2023/using-ollama-with-langchaingo/).
74 | 
75 | ## How do I build LLM-powered applications in Go?
76 | 
77 | To learn how to build an application with different LLM frameworks, take a look at
78 | [how to build a RAG server using various LLM frameworks](https://go.dev/blog/llmpowered).
79 | 
80 | ## How do I manage prompts in Go?
81 | 
82 | The message sent to an LLM service is referred to as a _prompt_.
83 | In many cases a program will have a general prompt that contains
84 | variables that are filled in based on user input.
85 | In Go a natural way to do this is to use the
86 | [text/template package](https://pkg.go.dev/text/template).
87 | 


--------------------------------------------------------------------------------
/All.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: All Wiki Pages
 3 | template: true
 4 | ---
 5 | 
 6 | (See [the wiki home page](/wiki/) for a less mechanical overview of the Go wiki.)
 7 | 
 8 | <div id="wikiindex">
 9 | 
10 | <ul>
11 | {{- range pages "/wiki/*.md" -}}
12 | {{- if and .title (ne .URL "/wiki/") -}}
13 | <li class="wikititle">{{$short := strings.TrimPrefix .URL "/wiki/"}}<a href="{{.URL}}">{{$short}}{{if ne $short .title}} (“{{.title}}”){{end}}</a>
14 | {{end -}}
15 | {{- end -}}
16 | </ul>
17 | 
18 | </div>
19 | 


--------------------------------------------------------------------------------
/AssemblyPolicy.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: AssemblyPolicy
 3 | ---
 4 | 
 5 | This document describes when and how to add assembly code to the Go cryptography packages.
 6 | 
 7 | In general, the rules are:
 8 | 
 9 | * We prefer portable Go, not assembly. Code in assembly means (N packages * M architectures) to maintain, rather than just N packages.
10 | * Minimize use of assembly. We'd rather have a small amount of assembly for a 50% speedup rather than twice as much assembly for a 55% speedup. Explain the decision to place the assembly/Go boundary where it is in the commit message, and support it with benchmarks.
11 | * Use higher level programs to generate non-trivial amounts of assembly, either standalone Go programs or `go get`-able programs, like [avo](https://github.com/mmcloughlin/avo). Output of other reproducible processes (like formally verified code generators) will also be considered. Discuss the implementation strategy on the issue tracker in advance.
12 | * Use small, testable units (25–75 lines) called from higher-level logic written in Go. If using small, testable functions called from logic written in Go is too slow, use small, testable assembly units with Go-compatible wrappers, so that Go tests can still test the individual units.
13 | * Any assembly function needs a reference Go implementation, that’s tested side-by-side with the assembly. Follow [TargetSpecific](/wiki/TargetSpecific) for structure and testing practices.
14 | * The interface of the assembly units and of the reference Go implementation must be the same across architectures, unless the platforms have fundamentally different capabilities (such as high-level cryptographic instructions).
15 | * Unless the Go Security team explicitly commits to owning the specific implementation, an external contributor must commit to maintaining it. If changes are required (for example as part of a broader refactor) and the maintainer is not available, the assembly will be removed.
16 | * The code must be tested in our CI. This means there need to be builders that support the instructions, and if there are multiple (or fallback) paths they must be tested separately. (Tip: use `GODEBUG=cpu.X=off` to disable detection of CPU features.)
17 | * Document in the Go code why the implementation requires assembly (specific performance benefit, access to instructions, etc), so we can reevaluate as the compiler improves.
18 | 
19 | Not all assembly currently in the standard library adheres to this policy. Changes to existing assembly will be discouraged until that implementation is updated to be compliant. New assembly must be compliant.
20 | 


--------------------------------------------------------------------------------
/Blogs.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Blogs
 3 | ---
 4 | 
 5 | A set of blogs dedicated to Go.
 6 | 
 7 | NOTE: Please don't add individual blog entries to this page. Those belong in [articles](Articles) instead.
 8 | 
 9 | ## Arabic
10 | 
11 | * [لغة غو بالعربي](https://argolang.com) - موقع عربي مخصص للغة البرمجة غو
12 | 
13 | ## English
14 | 
15 | * [The official Go Blog](https://go.dev/blog) - For in depth posts by the Go team
16 | * [Gopher Academy Blog](http://blog.gopheracademy.com/)
17 | * [Dave Cheney's Blog](http://dave.cheney.net)
18 |   * [Dave Cheney's Resources for Go Programmers](http://dave.cheney.net/resources-for-new-go-programmers)
19 | * [spf13's Blog](http://spf13.com/post/)
20 | * [Mat Ryer's Medium Blog](https://medium.com/@matryer)
21 | * [Matt Aimonetti's Blog](http://matt.aimonetti.net/)
22 | * [Marcio.io](http://marcio.io/)
23 | * [Carlos Becker's Blog](http://carlosbecker.com/)
24 | * [Ardan Labs](https://www.ardanlabs.com/blog/)
25 | * [The Golang Weekly](http://golangweekly.com/)
26 | * [Alex Edward's Go Posts](http://www.alexedwards.net/blog/category/golang)
27 | * [GoLang Tutorials](http://golangtutorials.blogspot.com/)
28 | * [Mathias Lafeldt's Blog](https://mlafeldt.github.io/)
29 | * [Marcelo Magallon's Blog](http://blog.ksub.org/bytes/)
30 | * [Mina Andrawos's Go Posts](http://www.minaandrawos.com/category/golang-2/)
31 | * [Aliaksandr Pliutau's Blog](http://pliutau.com/)
32 | * [Johan Brandhorst's Blog](https://jbrandhorst.com)
33 | * [Christoph Berger's Applied Go Blog](https://appliedgo.net)
34 | * [Jon Calhoun's Blog](https://www.calhoun.io/)
35 | * [Inanc Gumus's Learn Go Programming Blog](https://blog.learngoprogramming.com)
36 | * [Elliot Forbes - TutorialEdge.net Go Tutorials](https://tutorialedge.net/course/golang/)
37 | * [Timo Savola's Go Posts](http://savo.la/go)
38 | * [Packt Hub](https://hub.packtpub.com/)
39 | * [GoCenter Community Blog](https://jfrog.com/resource-center/?src=gocenter) - Blogs from GoCenter.io about Go modules and community.
40 | * [Golang on the Boot.dev Blog](https://blog.boot.dev/golang/)
41 | * [Golang Tutorials ](https://www.w3basic.com/golang/) - Golang Tutorials and Blog
42 | * [Go articles at golang.dk](https://www.golang.dk/articles)
43 | * [Bitfield Consulting](https://bitfieldconsulting.com/golang)
44 | * [Mahmud Ridwan's Go Posts](https://hjr265.me/tags/go/)
45 | 
46 | ## Bahasa Indonesia
47 | 
48 | * [Go blog dalam Bahasa Indonesia](https://golang-id.org/blog)
49 | 
50 | ## Portuguese
51 | 
52 | * [Eduardo Nunes Pereira](https://medium.com/@eduardonunespereira)
53 | * [Gopher Brasil](http://gopher.net.br)
54 | * [Bruno Gomes's Blog](https://dev.to/bgskurono)
55 | 
56 | ## Chinese
57 | 
58 | * [无忌-Jincheng's Blog](https://jincheng9.github.io/)
59 | * [Howtoing运维教程](https://www.howtoing.com)
60 | * [虞双齐的博客-Golang](https://yushuangqi.com/tags/golang.html)
61 | * [Tony Bai -- 一个程序员的心路历程](http://tonybai.com/)
62 | * [Arthur 的博客](http://www.zenlife.tk/index)
63 | * [鸟窝](http://colobu.com/)
64 | * [飞雪无情的博客](http://www.flysnow.org)
65 | * [午夜咖啡](http://jolestar.com/)
66 | * [蝈蝈俊的技术心得](http://www.cnblogs.com/ghj1976/)
67 | * [FuXiaohei.Me -- 傅小黑的自留地](http://fuxiaohei.me/)
68 | * [无闻的小站](https://github.com/Unknwon/wuwen.org)
69 | * [astaxie](https://my.oschina.net/astaxie)
70 | * [风笑痴](http://lunny.info/)
71 | * [ipfans's Blog](https://www.4async.com/)
72 | * [Cyeam -- 你不要用战术的勤奋掩盖战略的懒惰。](http://blog.cyeam.com/)
73 | * [战魂小筑](http://www.cppblog.com/sunicdavy)
74 | * [My Candy](http://mengqi.info/)
75 | * [fatedier blog](http://blog.fatedier.com)
76 | * [siddontang 的专栏-my thought for program。](http://blog.csdn.net/siddontang)
77 | * [domac 博客 life should be func](http://lihaoquan.me)
78 | * [七牛云 - 七牛团队博客](http://blog.qiniu.com/)
79 | * [博客 - PingCAP](https://pingcap.com/bloglist)
80 | * [LittleFeng 的博客 -- Python、Golang、Java、后端技术](https://allenwind.github.io)
81 | * [Legendtkl](http://legendtkl.com/)
82 | * [行思錄,Travel Coder - Arch, Coding, Life Learning](https://liudanking.com)
83 | * [jasper的技术小窝](http://www.opscoder.info)
84 | * [三月沙](https://sanyuesha.com/)
85 | * [大桥下的蜗牛](https://blog.lab99.org/)
86 | * [煎鱼的迷之博客](https://eddycjy.com/posts/)
87 | * [Stefno - 博客园](https://www.cnblogs.com/qcrao-2018/)
88 | * [No Headback](http://xargin.com/)
89 | * [Go 语言基础](https://github.com/weirubo/learn_go)
90 | * [chai2010 的博客](https://chai2010.cn/)
91 | 
92 | 


--------------------------------------------------------------------------------
/BoundingResourceUse.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Bounding resource use
 3 | ---
 4 | 
 5 | To bound a program's use of a limited resource - like memory - have goroutines synchronize their use of that resource using a buffered channel (i.e., use the channel as a semaphore):
 6 | 
 7 | ```go
 8 | const (
 9 | 	AvailableMemory         = 10 << 20 // 10 MB
10 | 	AverageMemoryPerRequest = 10 << 10 // 10 KB
11 | 	MaxOutstanding          = AvailableMemory / AverageMemoryPerRequest
12 | )
13 | 
14 | var sem = make(chan int, MaxOutstanding)
15 | 
16 | func Serve(queue chan *Request) {
17 | 	for {
18 | 		sem <- 1 // Block until there's capacity to process a request.
19 | 		req := <-queue
20 | 		go handle(req) // Don't wait for handle to finish.
21 | 	}
22 | }
23 | 
24 | func handle(r *Request) {
25 | 	process(r) // May take a long time & use a lot of memory or CPU
26 | 	<-sem      // Done; enable next request to run.
27 | }
28 | ```
29 | 
30 | ## References
31 | 
32 | Effective Go's discussion of channels: https://go.dev/doc/effective_go#channels
33 | 
34 | 


--------------------------------------------------------------------------------
/ChromeOS.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: ChromeOS
 3 | ---
 4 | 
 5 | ## Introduction
 6 | 
 7 | You don't need to compile from source in Developer mode, you can just use the [Chromebrew](https://github.com/skycocker/chromebrew)-provided version.
 8 | 
 9 | If your Chromebook is relatively new, you can enable the Linux VM now built into ChromeOS to install Go without developer mode. Follow the steps from the following Google Support article to enable this feature- https://support.google.com/chromebook/answer/9145439. This has been tested on a Samsung Chromebook Plus on version 71.0.3578.127. If this feature is not available for you, you will need to enable Developer Mode.
10 | 
11 | This tutorial will show you how to install, build, and run Go on Chrome OS.
12 | Please note this has only been tested on a 64GB LTE Pixel, however it should work on other Chromebooks. Note that enabling developer mode reduces the security guarantees offered by Chrome OS.
13 | 
14 | ## Install Go
15 | First download the latest version of Go for Linux from the [Go Downloads page](https://go.dev/dl/).
16 | After that, open a shell by hitting (CTRL+ALT+T) and typing in `shell` then hit enter. Then extract it using the following command (when replacing `< Go Linux package >` with the name of the file you downloaded):
17 | 
18 | ```
19 | sudo tar xpvf ~/Downloads/< Go Linux package > -C /usr/local
20 | ```
21 | 
22 | Go should now be installed you can test this by typing `/usr/local/go/bin/go`. If it installed correctly, you should see the Go help prompt. Go is now installed.
23 | 
24 | ## Create a Workspace
25 | To keep this simple just create a folder called `/usr/local/go/work`. Also, create a folder called `src` inside `/usr/local/go/work/`.
26 | 
27 | ## Set PATH
28 | Add the following to `~/.bashrc`:
29 | ```
30 | export GOPATH="/usr/local/go/work"
31 | export PATH="${PATH}:/usr/local/go/bin:${GOPATH}/bin"
32 | ```
33 | This will allow you to run your Go programs in your shell.
34 | 
35 | ## Test if it worked
36 | First create a folder inside of your `/usr/local/go/src` folder. After that create a file in your folder called `hello.go` with the following in it:
37 | ```go
38 | package main
39 | 
40 | import "fmt"
41 | 
42 | func main() {
43 | 	fmt.Println("Hello, Chrome OS!")
44 | }
45 | ```
46 | Now, run `go install hello`. Then, run `${GOPATH}/bin/hello` (or just `hello` if you setup your GOPATH above) and you should see `Hello, Chrome OS!`.
47 | ***
48 | 
49 | ## Reporting bugs
50 | Please go to [Issues](https://github.com/golang/go/issues) to report any issues you have.
51 | 
52 | 
53 | 


--------------------------------------------------------------------------------
/CodeReview.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: CodeReview
 3 | ---
 4 | 
 5 | Be sure to familiarize yourself with the code review process from the official [Contribution Guide](https://go.dev/doc/contribute) first.
 6 | 
 7 | # Reviewer Parlance
 8 | 
 9 | There are several terms code reviews may use that you should become familiar with.
10 | 
11 | * ` LGTM ` — looks good to me
12 | * ` SGTM ` — sounds good to me
13 | * ` PTAL ` — please take a look
14 | * ` s/foo/bar/ ` — please replace ` foo ` with ` bar `; this is [sed syntax](http://en.wikipedia.org/wiki/Sed#Usage)
15 | * ` s/foo/bar/g ` — please replace ` foo ` with ` bar ` throughout your entire change
16 | 
17 | # CL Directives
18 | 
19 | * `R=foo` — assign a reviewer within the [Go CL dashboard](https://swtch.com/godash/)
20 | * `DO NOT SUBMIT` (in the commit message) — block submission; see the "Work in progress" section below
21 | * `Updates #1234` or `Fixes #1234` (in the commit message) — link the CL from the GitHub issue and optionally close the issue after the CL is merged
22 | 
23 | # Email
24 | 
25 | Messages from a code review are typically sent to three places:
26 | 
27 | * the reviewers, if any
28 | * the golang-codereviews group
29 | * the owner
30 | 
31 | Please do NOT reply code review via email, as the message [will not be relayed to Gerrit](https://code.google.com/p/gerrit/issues/detail?id=228). Always click on the link and post reply in Gerrit.
32 | 
33 | # Work in progress
34 | 
35 | If you have changes that aren't ready to be reviewed, you can put a giant **`DO NOT REVIEW`** as the second line of the CL description, so that people who see it know not to look any further. Don't make it the first line, since then it will become the subject for the entire review, even after you've changed the description.
36 | 
37 | Similarly, if you would like to ensure that your changes are not merged by mistake, you can put **`DO NOT SUBMIT`** as the second line of the CL description.
38 | 
39 | If you don't need Gerrit's features, but just want to backup your work, share work between multiple clients, or have a staging UI to examine your changes, you can use a regular git remote.
40 | 
41 | To use GitHub as a git remote, you can either fork github.com/golang/go or create a new repo. There are trade-offs. Forked repos will have a faster first push. Non-forked repos can be private. Forked repos are associated in GitHub's system. As a result, they are easily discoverable and support cross-repo comparisons in the GitHub UI; however, this also means that references to issues in commit messages in forked repos will create references to your fork in the issue.
42 | 
43 | To add your git remote, run something like:
44 | 
45 | ```bash
46 | $ git remote add fork git@github.com:yourusername/go.git
47 | ```
48 | 
49 | You can then push changes to the "fork" remote with `git push fork branchname`.
50 | 
51 | Gerrit's code review model is to rewrite a single commit until it is correct. GitHub will try to prevent you from accidentally overwriting your existing branch. You can work around this by forcing the push: `git push --force fork branchname`. Alternatively, you can set up your forked remote as a mirror by cloning it initially with:
52 | 
53 | ```bash
54 | $ git remote add --mirror=push fork git@github.com:yourusername/go.git
55 | ```
56 | 
57 | Then running `git push fork` will update GitHub to perfectly mirror *everything* (all branches, all tags, etc.). This is handy, but take care when using this on multiple clients. You are bypassing the usual git safeguards, so it is easy to overwrite (and thus lose) work pushed by a different client.
58 | 


--------------------------------------------------------------------------------
/CodeTools.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: CodeTools
 3 | ---
 4 | 
 5 | An overview of tools that will help improve your Go code
 6 | 
 7 | ## All-in-one
 8 | 
 9 |   - [golangci-lint](https://github.com/golangci/golangci-lint) - Fast linters runners for Go. Bundle of `gofmt`, `govet`, `errcheck`, `staticcheck`, `revive` and many other linters. Recommended by the original author to replace gometalinter (Drop-in replacement).
10 |   - DEPRECATED: [gometalinter](https://github.com/alecthomas/gometalinter) - Automates the installation, configuration and application of `gofmt`, `golint`, `govet` and several other code validation tools.
11 | 
12 | ## Code Formatting
13 | 
14 | ### Articles
15 | 
16 |   - [Formatting Go Code with gofmt](https://golangtutorials.blogspot.com/2011/06/formatting-go-code-with-gofmt.html)
17 | 
18 | ### Tools
19 | 
20 |   - [air](https://github.com/air-verse/air) - Live reload for Go apps.
21 |   - [gofmt](https://pkg.go.dev/cmd/gofmt/) - Start with the standard Go code formatter.
22 |   - DEPRECATED: [golint](https://github.com/golang/lint) - Detects style mistakes in Go code.
23 |   - [staticcheck](https://staticcheck.io/) - Go programming language linter.
24 |   - [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) - Format code and fix your import statements.
25 |   - [gofumpt](https://github.com/mvdan/gofumpt) - A stricter gofmt.
26 |   - [revive](https://github.com/mgechev/revive) - Fast, configurable, extensible, flexible, and beautiful linter for Go.
27 | 
28 | ## Code generation, Templating and Generics
29 | 
30 |   - [json-to-go](https://mholt.github.io/json-to-go/) - Generate Go structs from JSON.
31 |   - [Go gen](https://clipperhouse.com/gen/overview/) - Type-driven code generation (generics).
32 |   - [gojson](https://github.com/ChimeraCoder/gojson) - Another Go struct generator.
33 |   - [gotemplate](https://github.com/ncw/gotemplate) - Package-based templating system for Go.
34 |   - DEPRECATED: [sqlgen](https://github.com/drone/sqlgen) - Generate Go code for SQL interactions.
35 |   - [zek](https://github.com/miku/zek) - Generate Go struct from XML.
36 |   - [apidocgen](https://github.com/alovn/apidocgen) - Generate web apis markdown docs and mocks.
37 |   - [goaccessor](https://github.com/yujiachen-y/goaccessor) - Getters and setters generator.
38 | 
39 | ## Refactoring
40 | 
41 | ### Articles
42 | 
43 |   - [gorename - easy refactoring](https://texlution.com/post/gorename/)
44 |   - [Refactoring Tools](https://blog.ralch.com/articles/golang-tools-refactoring/) - An overview of refactoring tools for Go.
45 |   - [Quick renaming with gofmt](http://technosophos.com/2015/09/26/quick-go-hack-renaming-structs.html)
46 | 
47 | ### Tools
48 | 
49 | - [eg](https://pkg.go.dev/golang.org/x/tools/cmd/eg) - Example-based refactoring tool for Go.
50 | - [gofmt](https://pkg.go.dev/cmd/gofmt/) - Start with the standard Go code formatter.
51 | - [gorename](https://golang.org/x/tools/refactor/rename) - Renaming tool for Go.
52 | 
53 | ## Error Detection
54 | 
55 | ### Articles
56 | 
57 |   - [Go Inspection Tools](https://blog.ralch.com/articles/golang-tools-inspection/) - An overview of tools for Go code inspection.
58 | 
59 | ### Tools
60 | 
61 |   - [AlignCheck, StructCheck, VarCheck](https://gitlab.com/opennota/check) - A suite of tools for checking your code.
62 |   - [errcheck](https://github.com/kisielk/errcheck) - Ensure you check your error conditions.
63 |   - [go vet](https://pkg.go.dev/cmd/vet/) - Read this first on how to use the `go vet` command.
64 |   - DEPRECATED: [SafeSQL](https://github.com/stripe/safesql) - Protect against unsafe SQL in your code (deprecated).
65 | 
66 | ## Navigation
67 | 
68 |   - [Go Guru - User Manual](https://go.dev/s/using-guru) - A tool for understanding Go code.
69 |   - [Pythia](https://github.com/fzipp/pythia) - A browser-based UI for Go Guru.
70 | 
71 | ## Visualization
72 | 
73 |   - [godepgraph](https://github.com/kisielk/godepgraph) - A tool for generating dependency graphs of Go code.
74 |   - [go-size-analyzer](https://github.com/Zxilly/go-size-analyzer) - A tool that shows the size of each dependency of a Go binary.
75 | 


--------------------------------------------------------------------------------
/CommitMessage.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Commit messages
 3 | ---
 4 | 
 5 | Commit messages, also known as CL (changelist) descriptions, should be formatted per https://go.dev/doc/contribute#commit_messages. For example,
 6 | 
 7 | ```
 8 | net/http: handle foo when bar
 9 | 
10 | [longer description here in the body]
11 | 
12 | Fixes #12345
13 | ```
14 | 
15 | Notably, for the subject (the first line of description):
16 | 
17 | * the name of the package affected by the change goes before the colon
18 | * the part after the colon uses the verb tense + phrase that completes the blank in, *"this change modifies Go to ___________"*
19 | * the verb after the colon is lowercase
20 | * there is no trailing period
21 | * it should be kept as short as possible (many git viewing tools prefer under ~76 characters, though Go isn't super strict about this).
22 | 
23 | For the body (the rest of the description):
24 | 
25 | * the text should be wrapped to ~76 characters (to appease git viewing tools, mainly), unless you really need longer lines (e.g. for ASCII art, tables, or long links).
26 | * the Fixes line goes after the body with a blank newline separating the two. (It is acceptable but not required to use a trailing period, such as `Fixes #12345.`).
27 | * there is **no** Markdown in the commit message.
28 | * we **do not** use `Signed-off-by` lines. Don't add them. Our Gerrit server & GitHub bots enforce CLA compliance instead.
29 | * when referencing CLs, prefer saying "CL nnn" or using a go.dev/cl/nnn shortlink over a direct Gerrit URL or git hash, since that's more future-proof.
30 | * when moving code between repos, include the CL, repository name, and git hash that it was moved from/to, so it is easier to trace history/blame.
31 | 
32 | Please _don't_ use alternate GitHub-supported aliases like `Close` or `Resolves` instead of `Fixes`.
33 | 
34 | To link a commit to an issue without marking it fixed—for example, if the commit is working toward a fix but not yet a complete fix—GitHub requires only that the issue is mentioned by number in the commit message. By convention, Go commits mention this at the bottom of the message using `For`, where `Fixes` might be expected, even if the number is also mentioned in the body of the commit message.
35 | 
36 | For example:
37 | 
38 | ```
39 | Refactor func Foo.
40 | This will make the handling of <corner case>
41 | shorter and easier to test.
42 | 
43 | For #12345
44 | ```
45 | 
46 | It is common in other Git projects to use `Updates` instead of `For`, and that is acceptable too, even though it makes little sense (the commit does not update the issue). More precise phrasings are fine too. Don't be too pedantic in code reviews: it's not worth asking people to change from `Updates` or something else to `For`, or vice versa.
47 | 
48 | ## Reverts
49 | 
50 | You can roll back a change using the Gerrit `Revert` button.
51 | Gerrit will generate a description for you.
52 | Edit the description to add the Gerrit CL number being rolled back next to or instead of the Git revision number.
53 | 
54 | Do not use the Gerrit UI to create a revert of a revert, as that notifies people right away.
55 | Instead, mail it as a new change, and in the description explain that it is a roll forward of CL NNNNNN which was rolled back by CL NNNNNN.
56 | 
57 | ## Other repos
58 | 
59 | For non-"go" repos ("crypto", "tools", "net", etc), the subject is still the name of the package, but you need to fully-qualify the issue number with the GitHub org/repo syntax:
60 | 
61 | ```
62 | cipher/rot13: add new super secure cipher
63 | 
64 | Fixes golang/go#1234
65 | ````
66 | 
67 | Notably, the first line subject should **not** contain the `x/crypto/` prefix. We only do that for the issue tracker.
68 | 
69 | ## Non-normative references
70 | 
71 | - [Please heed my plea and write good CL descriptions for Go—and for any other project you work on.](https://groups.google.com/d/msg/golang-dev/6M4dmZWpFaI/SyU5Sl4zZLYJ)
72 | - [The CL description is a public document that explains to the future what has been done and why.](https://groups.google.com/d/msg/golang-dev/s07ZUR8ZDHo/i-rIsknbAwAJ)
73 | 
74 | ## GitHub Pull Requests
75 | 
76 | If you're using GitHub Pull Requests, your commit message is constructed by GerritBot based on your
77 | PR's title & description. See [How does GerritBot determine the final commit message?](/wiki/GerritBot#how-does-gerritbot-determine-the-final-commit-message)
78 | 
79 | If somebody asks you to modify your commit message, you'll need to modify your PR.
80 | 
81 | ![](images/github-to-gerrit.png)
82 | 


--------------------------------------------------------------------------------
/CompilerOptimizations.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | title: Compiler And Runtime Optimizations
  3 | ---
  4 | 
  5 | This page lists optimizations done by the compilers. Note that these are not guaranteed by the language specification.
  6 | 
  7 | ## Interface values
  8 | 
  9 | ### Zero-width types in interface values
 10 | 
 11 | Putting a zero-width type in an interface value doesn't allocate.
 12 | 
 13 | * **gc:** 1.0+
 14 | * **gccgo:** ?
 15 | 
 16 | ### Word-sized value in an interface value
 17 | 
 18 | Putting a word-sized-or-less non-pointer type in an interface value doesn't allocate.
 19 | 
 20 | * **gc:** 1.0-1.3, but *not* in 1.4+
 21 | * **gccgo:** never
 22 | 
 23 | ## `string` and `[]byte`
 24 | 
 25 | ### Map lookup by `[]byte`
 26 | 
 27 | For a map `m` of type `map[string]T` and `[]byte b`, `m[string(b)]` doesn't allocate. (the temporary string copy of the byte slice isn't made)
 28 | 
 29 | * **gc:** 1.4+
 30 | * **gccgo:** ?
 31 | 
 32 | ### `range` over `[]byte`(s)
 33 | 
 34 | No allocation when converting a `string` into a `[]byte` for ranging over the bytes:
 35 | 
 36 | ```go
 37 | s := "foo"
 38 | for i, c := range []byte(s) {
 39 | 	// ...
 40 | }
 41 | ```
 42 | 
 43 | ### conversion for string comparison
 44 | 
 45 | No allocation done when converting a `[]byte` into a `string` for comparison purposes
 46 | 
 47 | ```go
 48 | var b1 string
 49 | var b2 []byte
 50 | var x = string(b1) == string(b2) // memeq
 51 | var y = string(b1) < string(b2)  // lexicographical comparison
 52 | ```
 53 | 
 54 | * **gc:** 1.5+ (CL 3790)
 55 | * **gccgo:** ?
 56 | 
 57 | ## Escape analysis and Inlining
 58 | 
 59 | Use `-gcflags -m` to observe the result of escape analysis and inlining
 60 | decisions for the gc toolchain.
 61 | 
 62 | (TODO: explain the output of `-gcflags -m`).
 63 | 
 64 | ### Escape analysis
 65 | 
 66 | Gc compiler does global escape analysis across function and package boundaries. However, there are lots of cases where it gives up. For example, anything assigned to any kind of indirection (`*p = ...`) is considered escaped. Other things that can inhibit analysis are: function calls, package boundaries, slice literals, subslicing and indexing, etc. Full rules are too complex to describe, so check the `-m` output.
 67 | 
 68 | * **gc:** 1.0+
 69 | * **gccgo:** 8.0+.
 70 | 
 71 | ### Function Inlining
 72 | 
 73 | Only short and simple functions are inlined. To be inlined a function must conform to the rules:
 74 | 
 75 | - function should be simple enough, the number of AST nodes must less than the budget (80);
 76 | - function doesn't contain complex things like closures, defer, recover, select, etc;
 77 | - function isn't prefixed by go:noinline;
 78 | - function isn't prefixed by go:uintptrescapes, since the escape information will be lost during inlining;
 79 | - function has body;
 80 | - etc.
 81 | 
 82 | * **gc:** 1.0+
 83 | * **gccgo:** -O1 and above.
 84 | 
 85 | ## Idioms
 86 | 
 87 | ### Optimized memclr
 88 | 
 89 | For a slice or array s, loops of the form
 90 | 
 91 | ```go
 92 | for i := range s {
 93 | 	s[i] = <zero value for element of s>
 94 | }
 95 | ```
 96 | 
 97 | are converted into efficient runtime memclr calls. [Issue](https://github.com/golang/go/issues/5373) and [commit](https://go.dev/change/f03c9202c43e0abb130669852082117ca50aa9b1).
 98 | 
 99 | * **gc:** 1.5+
100 | * **gccgo:** ?
101 | 
102 | ## Non-scannable objects
103 | 
104 | Garbage collector does not scan underlying buffers of slices, channels and maps when element type does not contain pointers (both key and value for maps). This allows to hold large data sets in memory without paying high price during garbage collection. For example, the following map won't visibly affect GC time:
105 | 
106 | ```go
107 | type Key [64]byte // SHA-512 hash
108 | type Value struct {
109 | 	Name      [32]byte
110 | 	Balance   uint64
111 | 	Timestamp int64
112 | }
113 | m := make(map[Key]Value, 1e8)
114 | ```
115 | 
116 | * **gc:** 1.5+
117 | * **gccgo:** ?
118 | 
119 | 


--------------------------------------------------------------------------------
/Configuring-GoLand-for-WebAssembly.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Configuring-GoLand-for-WebAssembly
 3 | ---
 4 | 
 5 | ### [← Back](/wiki/WebAssembly) to the main WebAssembly page.
 6 | 
 7 | # Configuring GoLand for WebAssembly (Wasm) projects
 8 | 
 9 | ## Initial project configuration
10 | 
11 | When you first open or start a WebAssembly project in GoLand, it won't understand the "*syscall/js*" package.
12 | 
13 | That's easily fixable, by changing the **GOOS** and **GOARCH** values in the project settings, as per the screenshots below.
14 | 
15 | ![GoLand Wasm Setup pic1](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Setup1.png)
16 | 
17 | **Note** - The screenshot below shows how to access **Settings** on a Linux desktop.  If you're using macOS, you'll probably need to access them through the standard macOS **Preferences** option.
18 | ![GoLand Wasm Setup pic2](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Setup2.png)
19 | 
20 | ![GoLand Wasm Setup pic3](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Setup3.png)
21 | 
22 | ![GoLand Wasm Setup pic4](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Setup4.png)
23 | 
24 | 
25 | ## Configuring Run/Debug settings
26 | 
27 | With the initial project settings changed, you'll probably want to configure the Run/Debug settings next.
28 | 
29 | That will let you recompile the .wasm file by just launching `Run` (<kbd>Shift</kbd>+<kbd>F10</kbd> on Linux).
30 | 
31 | ![GoLand Wasm Build pic2](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build2.png)
32 | 
33 | ![GoLand Wasm Build pic3](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build3.png)
34 | 
35 | ![GoLand Wasm Build pic4](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build4.png)
36 | 
37 | ![GoLand Wasm Build pic5](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build5.png)
38 | 
39 | ![GoLand Wasm Build pic6](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build6.png)
40 | 
41 | ![GoLand Wasm Build pic7](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build7.png)
42 | 
43 | ![GoLand Wasm Build pic8](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build8.png)
44 | 
45 | ![GoLand Wasm Build pic9](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build9.png)
46 | 
47 | ![GoLand Wasm Build pic10](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build10.png)
48 | 
49 | ![GoLand Wasm Build pic11](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build11.png)
50 | 
51 | ![GoLand Wasm Build pic12](https://github.com/leitzler/wasmWikiPics/raw/master/png/Golang-Wasm-Build12.png)
52 | 
53 | Finished, your GoLand setup should now be complete.
54 | 
55 | ### [← Back](/wiki/WebAssembly) to the main WebAssembly page.
56 | 


--------------------------------------------------------------------------------
/Contributing-to-gopls.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Contributing-to-gopls
 3 | ---
 4 | 
 5 | ---
 6 | > This page has been subsumed into the [committed markdown](https://github.com/golang/tools/blob/master/gopls/doc/contributing.md) of x/tools repository
 7 | > 
 8 | > Please do not edit this page!
 9 | ---
10 | 
11 | 


--------------------------------------------------------------------------------
/Contributing.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Contributing
 3 | ---
 4 | 
 5 | The contents of https://go.dev/wiki are hosted in the [go.googlesource.com/wiki](https://go.googlesource.com/wiki) repository,
 6 | and is also mirrored on https://github.com/golang/wiki.
 7 | 
 8 | These contents are served by the same server that hosts the official Go website https://go.dev/.
 9 | The server's source is located in the [go.googlesource.com/website](https://go.googlesource.com/website) repository.
10 | 
11 | ## Reporting issues
12 | 
13 | For issues related to existing contents, the preferred method of resolution is to send a [change](#updating-contents).
14 | 
15 | However, if you would like to add a new page, please first open an issue in the [Go issue tracker](https://go.dev/issues/new?title=wiki:) with the prefix `wiki:` to propose the addition. Clearly state why the content does not fit into any of the existing pages.
16 | 
17 | Because renaming of pages in the wiki can break external links, please open an issue before renaming or removing any wiki page.
18 | 
19 | If the issue pertains to the serving of contents, please open a [GitHub issue](https://go.dev/issues/new?title=x/website:).
20 | 
21 | ### Triaging issues
22 | 
23 | To address content-related issues, it is recommended to identify the person or team most familiar with the content in question.
24 | A good starting point is the [project owners](https://dev.golang.org/owners) page.
25 | 
26 | For issues related to content serving, follow the usual triaging process similar to x/website issues
27 | and label them with `website`.
28 | 
29 | ## Updating contents
30 | 
31 | Before making changes, ensure familiarity with the code review process outlined in
32 | the official [Contribution Guide](/doc/contribute).
33 | 
34 | ### Sending a trivial change
35 | 
36 | For minor updates such as fixing typos and adding missing links, you can use
37 | the [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow).
38 | Make edits from the [GitHub repo](https://github.com/golang/wiki) and open a GitHub pull request as you normally would.
39 | 
40 | Additional information is available at [Sending a change via GitHub](/doc/contribute#sending_a_change_github).
41 | 
42 | ### Sending a non-trivial change
43 | 
44 | For larger changes, consider sending your change through Gerrit following the instructions provided in
45 | [Sending a change via Gerrit](/doc/contribute#sending_a_change_gerrit).
46 | 
47 | The canonical repository for wiki content is located at `go.googlesource.com/wiki`.
48 | 
49 | ```
50 | $ git clone https://go.googlesource.com/wiki
51 | ```
52 | <!-- TODO: describe supported markdown syntaxes, and how to test local changes -->
53 | 
54 | ## Reviewing and submitting changes
55 | 
56 | Unlike other Go repositories, the submission process for the wiki repository
57 | requires only one +2 from anyone in the wiki repository maintainers group.
58 | See [Proposal 61940](https://go.dev/issues/61940) for additional background.
59 | 
60 | **Note for reviewers**: once you give your +2 and all comments are addressed,
61 | please merge the change soon to avoid merge conflicts.
62 | 
63 | Anyone interested in receiving notifications about incoming wiki CLs
64 | can opt-in through their [Gerrit notifications](https://go-review.googlesource.com/settings/#Notifications).
65 | 
66 | ## Changing and testing the contents serving behavior
67 | 
68 | [`golang.org/x/website/cmd/golangorg`](https://golang.org/x/website/cmd/golangorg)
69 | is the program that serves the wiki pages.
70 | 
71 | ```
72 | $ git clone https://go.googlesource.com/website
73 | $ cd website/cmd/golangorg
74 | ```
75 | 
76 | Follow the [instructions in README.md](https://cs.opensource.google/go/x/website/+/master:cmd/golangorg/README.md) for running and testing the program locally.


--------------------------------------------------------------------------------
/CreatingSubRepository.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: CreatingSubRepository
 3 | ---
 4 | 
 5 | This page outlines the steps that need to be done to create a new golang.org/x repository, in order for it to have the same properties as all existing golang.org/x repositories:
 6 | - a golang.org/x redirect
 7 | - automatic git mirroring from Gerrit to GitHub
 8 | - automatic importing of GitHub PRs into Gerrit CLs
 9 | - automatic testing on appropriate Go builders
10 | 
11 | ## Steps
12 | 
13 | 1. Create a new empty Gerrit repository at https://go.googlesource.com, complete with a description.
14 | 	- Create an initial commit with `LICENSE`, `PATENTS`, `CONTRIBUTING.md`, and `README.md` files and push it directly to the Gerrit repository. See [example commit](https://go.googlesource.com/govulncheck-action/+/a197ae39e55573b3a0e752b9bd72f457a458adf6).
15 | 	- See the internal team instructions at go/go-gerrit#new-repository for how to create a repository.
16 | 2. Create a [new empty GitHub repository](https://github.com/organizations/golang/repositories/new) at https://github.com/golang with the same name and description.
17 | 	- Turn off Wikis, Issues, Projects in repository settings.
18 | 	- On "Manage access" tab:
19 | 		- Add "golang org admins" team with Admin access.
20 | 		- Add "google-go-team" team with Write access.
21 | 		- Add "robots" team with Write access (can only be done by a maintainer of golang organization; ask someone else if you're not).
22 | 3. Modify the [`x/build/repos`](https://golang.org/x/build/repos) package.
23 | 	- Also modify the [`x/build/devapp/owners`](https://dev.golang.org/owners) to include the owner(s) of the new repository. (Both can be updated in one CL.)
24 | 4. Modify the [`PROJECTS` map](https://cs.opensource.google/go/x/build/+/luci-config:main.star;l=644-675;drc=67d27da0c4496ee84405c96517dfdaaf4e960cfc) on [luci-config](https://cs.opensource.google/go/x/build/+/luci-config:README) branch.
25 | 5. Update x/website's version of x/build to include modified `x/build/repos` package.
26 | 	- `x/website/cmd/golangorg` will [deploy automatically](https://go.googlesource.com/website#deploying) on CL submission.
27 | 6. Redeploy all affected commands (or ask an x/build [owner](https://dev.golang.org/owners) to deploy if you're not; the order shouldn't matter):
28 | 	1. `x/build/cmd/gitmirror`
29 | 	2. `x/build/maintner/maintnerd`
30 | 		- Note that it's expected for the new repo not to appear in maintner until first issue or PR is created (see [#25744](https://go.dev/issue/25744)).
31 | 	3. `x/build/cmd/gerritbot`
32 | 	4. `x/build/devapp`
33 | 6. You're done.
34 | 


--------------------------------------------------------------------------------
/CustomPprofProfiles.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | title: CustomPprofProfiles
  3 | ---
  4 | 
  5 | Originally published at https://rakyll.org/custom-profiles/.
  6 | 
  7 | ----
  8 | 
  9 | Go provides several pprof profiles out of the box to gather
 10 | profiling data from Go programs.
 11 | 
 12 | The builtin profiles provided by the [runtime/pprof](https://pkg.go.dev/runtime/pprof/) package:
 13 | 
 14 | * **profile**: CPU profile determines where a program spends its time while actively consuming CPU cycles (as opposed while sleeping or waiting for I/O).
 15 | * **heap**: Heap profile reports the currently live allocations; used to monitor current memory usage or check for memory leaks.
 16 | * **threadcreate**: Thread creation profile reports the sections of the program that lead the creation of new OS threads.
 17 | * **goroutine**: Goroutine profile report the stack traces of all current goroutines.
 18 | * **block**: Block profile show where goroutines block waiting on synchronization primitives (including timer channels). Block profile is not enabled by default; use runtime.SetBlockProfileRate to enable it.
 19 | * **mutex**: Mutex profile reports the lock contentions. When you think your CPU is not fully utilized due to a mutex contention, use this profile. Mutex profile is not enabled by default, see runtime.SetMutexProfileFraction to enable.
 20 | 
 21 | Additional to the builtin profiles, [runtime/pprof](https://pkg.go.dev/runtime/pprof/) package allows you to export your custom profiles, and instrument your code to record
 22 | execution stacks that contributes to this profile.
 23 | 
 24 | Imagine we have a blob server, and we are writing a Go client for it. And our users want to be able to profile the opened blobs on the client. We can create a profile and record the events of blob opening and closing, so the user can tell how many open blobs they are at any time.
 25 | 
 26 | Here is a blobstore package that allows you to open some blobs. We will create a new custom profile and start
 27 | recording execution stacks that contributes to opening of blobs:
 28 | 
 29 | ``` go
 30 | package blobstore
 31 | 
 32 | import "runtime/pprof"
 33 | 
 34 | var openBlobProfile = pprof.NewProfile("blobstore.Open")
 35 | 
 36 | // Open opens a blob, all opened blobs need
 37 | // to be closed when no longer in use.
 38 | func Open(name string) (*Blob, error) {
 39 | 	blob := &Blob{name: name}
 40 | 	// TODO: Initialize the blob...
 41 | 
 42 | 	openBlobProfile.Add(blob, 2) // add the current execution stack to the profile
 43 | 	return blob, nil
 44 | }
 45 | ```
 46 | 
 47 | And once users want to close the blob, we need to remove the execution stack associated with the current blob from the profile:
 48 | 
 49 | ```go
 50 | // Close closes the blob and frees the
 51 | // underlying resources.
 52 | func (b *Blob) Close() error {
 53 | 	// TODO: Free other resources.
 54 | 	openBlobProfile.Remove(b)
 55 | 	return nil
 56 | }
 57 | ```
 58 | 
 59 | And now, from the programs using this package, we should be able to retrieve `blobstore.Open` profile data  and use our daily pprof tools to examine and visualize them.
 60 | 
 61 | Let's write a small main program than opens some blobs:
 62 | 
 63 | ```
 64 | package main
 65 | 
 66 | import (
 67 | 	"fmt"
 68 | 	"math/rand"
 69 | 	"net/http"
 70 | 	_ "net/http/pprof" // as a side effect, registers the pprof endpoints.
 71 | 	"time"
 72 | 
 73 | 	"myproject.org/blobstore"
 74 | )
 75 | 
 76 | func main() {
 77 | 	for i := 0; i < 1000; i++ {
 78 | 		name := fmt.Sprintf("task-blob-%d", i)
 79 | 		go func() {
 80 | 			b, err := blobstore.Open(name)
 81 | 			if err != nil {
 82 | 				// TODO: Handle error.
 83 | 			}
 84 | 			defer b.Close()
 85 | 
 86 | 			// TODO: Perform some work, write to the blob.
 87 | 		}()
 88 | 	}
 89 | 	http.ListenAndServe("localhost:8888", nil)
 90 | }
 91 | ```
 92 | 
 93 | Start the server, then use go tool to read and visualize the profile data:
 94 | 
 95 | ```
 96 | $ go tool pprof http://localhost:8888/debug/pprof/blobstore.Open
 97 | (pprof) top
 98 | Showing nodes accounting for 800, 100% of 800 total
 99 |       flat  flat%   sum%        cum   cum%
100 |        800   100%   100%        800   100%  main.main.func1 /Users/jbd/src/hello/main.go
101 | ```
102 | 
103 | You will see that there are 800 open blobs and all openings are coming from main.main.func1. In this small example, there is nothing more to see, but in a complex server you can examine the hottest spots that works with an open blob and find out bottlenecks or leaks.
104 | 


--------------------------------------------------------------------------------
/Darwin.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Go on Darwin
 3 | ---
 4 | 
 5 | | **Kernel version** | **Distributions**               | **Architectures**      | **Initial support version** | **Final support version** |
 6 | |:-------------------|:--------------------------------|:-----------------------|:---------------|:----------|
 7 | | 18                 | macOS Mojave 10.14, iOS 12      | amd64, arm64, 386      | Go 1.12        |           |
 8 | | 17                 | macOS High Sierra 10.13, iOS 11 | amd64, arm64, 386      | Go 1.7.1 _***_ |           |
 9 | | 16                 | macOS Sierra 10.12, iOS 10      | amd64, arm, arm64, 386 | Go 1.7.1 _**_  |           |
10 | | 15                 | OS X El Capitan 10.11           | amd64, 386             | Go 1 _*_       |           |
11 | | 15                 | iOS 9                           | arm, arm64             | Go 1.5         |           |
12 | | 14                 | OS X Yosemite 10.10             | amd64, 386             | Go 1 _*_       |           |
13 | | 14                 | iOS 7, iOS 8                    | arm, arm64             | Go 1.5         |           |
14 | | 13                 | OS X Mavericks 10.9             | amd64, 386             | Go 1 _*_       | Go 1.10.8 |
15 | | 12                 | OS X Mountain Lion 10.8         | amd64, 386             | Go 1 _*_       | Go 1.10.8 |
16 | | 11                 | OS X Lion 10.7                  | amd64, 386             | Go 1 _*_       | Go 1.7.6  |
17 | | 10                 | Mac OS X Snow Leopard 10.6      | amd64, 386             | Go 1           | Go 1.4.3  |
18 | 
19 | _*_ Go 1.5 or above is recommended.
20 | 
21 | _**_ See https://github.com/golang/go/issues/16570 and https://github.com/golang/go/issues/19772.
22 | 
23 | _***_ See https://github.com/golang/go/issues/22037.
24 | 
25 | 


--------------------------------------------------------------------------------
/Deprecated.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Deprecated
 3 | ---
 4 | 
 5 | Sometimes an API feature such as a struct field, function, type, or even a whole package becomes
 6 | redundant or unnecessary.
 7 | When we want to discourage new programs from using it,
 8 | we mark that feature "deprecated".
 9 | 
10 | In contrast to some other systems, an API feature being deprecated
11 | _does not_ mean it is going to be removed in the future.
12 | On the contrary, [Go 1 compatibility](https://go.dev/doc/go1compat)
13 | means the feature will be preserved in its deprecated form
14 | to keep existing programs running.
15 | 
16 | To signal that an identifier should not be used, add a paragraph to its doc
17 | comment that begins with `Deprecated:` followed by some information about the
18 | deprecation, and a recommendation on what to use instead, if applicable.
19 | The paragraph does not have to be the last paragraph in the doc comment.
20 | 
21 | [Some tools will warn on use of deprecated identifiers](https://staticcheck.io/docs/checks#SA1019)
22 | and their docs [are hidden on pkg.go.dev](https://go.dev/issue/40850).
23 | 
24 | If function `F1` is being replaced by function `F2`
25 | and the first release in which `F2` is available is Go 1.N,
26 | then an official deprecation notice for `F1` should not be
27 | added until Go 1.N+1.
28 | This ensures that Go developers only see `F1` as deprecated
29 | when all supported Go versions include `F2` and they can easily switch.
30 | 
31 | Marking an API feature deprecated can create work and
32 | decisions for millions of Go developers using the feature.
33 | Deprecating an API feature is an API change that must
34 | be discussed using [the proposal process](https://go.dev/s/proposal).
35 | 
36 | ## Examples
37 | 
38 | ```Go
39 | type ResponseRecorder struct {
40 | 	// HeaderMap contains the headers explicitly set by the Handler.
41 | 	// It is an internal detail.
42 | 	//
43 | 	// Deprecated: HeaderMap exists for historical compatibility
44 | 	// and should not be used. To access the headers returned by a handler,
45 | 	// use the Response.Header map as returned by the Result method.
46 | 	HeaderMap http.Header
47 | ```
48 | 
49 | ```Go
50 | // Package rc4 implements the RC4 stream cipher.
51 | //
52 | // Deprecated: RC4 is cryptographically broken and should not be used
53 | // except for compatibility with legacy systems.
54 | //
55 | // This package is frozen and no new functionality will be added.
56 | package rc4
57 | ```
58 | 
59 | There are a few other examples [in the standard library](https://cs.opensource.google/search?q=Deprecated:%20language:go&ss=go%2Fgo).
60 | 


--------------------------------------------------------------------------------
/DesignDocuments.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: DesignDocuments
 3 | ---
 4 | 
 5 | ## Go 1.1
 6 |   * [Scalable Scheduler](https://docs.google.com/document/d/1TTj4T2JO42uD5ID9e89oa0sLKhJYD0Y_kqxDv3I3XMw)
 7 |   * [net/http/cookiejar](https://groups.google.com/d/msg/golang-dev/ygDB3nbir00/rouknDcuyakJ)
 8 |   * [Function Calls](https://docs.google.com/document/d/1bMwCey-gmqZVTpRax-ESeVuZGmjwbocYs1iHplK-cjo/pub)
 9 | 
10 | ## Go 1.2
11 | 
12 |   * [xml.Marshaler and Unmarshaler](https://go.dev/s/go12xml)
13 |   * [encoding.TextMarshaler and Unmarshaler](https://go.dev/s/go12encoding)
14 |   * [Runtime Symbol Table Format](https://go.dev/s/go12symtab)
15 |   * [Field Selectors and Nil Checks](https://go.dev/s/go12nil)
16 |   * [```x[i:j:k]``` Slice Syntax](https://go.dev/s/go12slice)
17 |   * [Preemptive Scheduler](https://docs.google.com/document/d/1ETuA2IOmnaQ4j81AtTGT40Y4_Jr6_IDASEKg0t0dBR8/edit?usp=sharing)
18 | 
19 | ## Go 1.3
20 | 
21 |   * [Contiguous Stacks](https://docs.google.com/document/d/1wAaf1rYoM4S4gtnPh0zOlGzWtrZFQ5suE8qr2sD8uWQ/pub)
22 |   * [Go 1.3 Linker Overhaul](https://go.dev/s/go13linker)
23 |   * [Go 1.3 Native Client Support](https://docs.google.com/document/d/1oA4rs0pfk5NzUyA0YX6QsUEErNIMXawoscw9t0NHafo/pub)
24 | 
25 | ## Go 1.4
26 | 
27 |   * [Go channels on steroids](https://go.dev/s/go13chan)
28 |   * [Go 1.4 “Internal” Packages](https://go.dev/s/go14internal)
29 |   * [Go 1.4 src/pkg → src](https://go.dev/s/go14nopkg)
30 |   * [Go 1.4 Custom Import Path Checking](https://go.dev/s/go14customimport)
31 |   * [Go generate: A Proposal](https://go.dev/s/go1.4-generate)
32 |   * [The syscall package](https://docs.google.com/a/golang.org/document/d/1QXzI9I1pOfZPujQzxhyRy6EeHYTQitKKjHfpq0zpxZs)
33 |   * [Go 1.4 Subrepo Renaming](https://go.dev/s/go14subrepo)
34 |   * [Go 1.4 Native Client Support for ARM](https://go.dev/s/go14naclarm)
35 |   * [dev.cc branch plan](https://go.dev/s/dev.cc)
36 | 
37 | ## Go 1.5
38 | 
39 |   * [Go 1.5 Bootstrap Plan](https://go.dev/s/go15bootstrap)
40 |   * [Go Compiler Overhaul](https://go.dev/s/go13compiler)
41 |   * [Go Execution Tracer](http://goo.gl/eXjfeS)
42 | 
43 | ## Future Proposals
44 | 
45 |   * [New SSA Backend for the Go Compiler](https://docs.google.com/document/d/1szwabPJJc4J-igUZU4ZKprOrNRNJug2JPD8OYi3i1K0/edit?usp=sharing_eid)
46 |   * [Go 1.4+ Garbage Collection (GC) Plan and Roadmap](https://go.dev/s/go14gc)
47 |   * [Better GC and Memory Allocator for Go](https://docs.google.com/document/d/1HCPu3WKyCX3ZRYxmIMKTk0Ik1dePxKW1p02k3uhcft4/view) 
48 |     * [Groups Discussion](https://groups.google.com/d/topic/golang-dev/pwUh0BVFpY0/discussion)
49 |   * [Precise GC Stack Roots](https://docs.google.com/document/d/13v_u3UrN2pgUtPnH4y-qfmlXwEEryikFu0SQiwk35SA/pub)
50 |   * [Go 1.3 cmd/go and os/fsnotify](https://go.dev/s/go13fsnotify)
51 |   * [Go 1.5 os/fsnotify API](http://goo.gl/MrYxyA)
52 |   * [Simple Multi-Dimensional Slices (Tables)](https://docs.google.com/document/d/1eHm7KqfKP9_s4vR1zToxq-FBazdUQ9ZYi-YhcEtdfR0/edit)
53 |   * [Go execution modes](https://docs.google.com/a/golang.org/document/d/1nr-TQHw_er6GOQRsF6T43GGhFDelrAP0NqSS_00RgZQ/edit)
54 |   * [Building and distributing Go packages as shared libraries](https://docs.google.com/a/canonical.com/document/d/1PxhXNhsdqwBjteW7poqv4Vf3PhtTmYuQKkOk_JNWeh0/edit#heading=h.9hyi51rp3owq)
55 |   * [NUMA-aware scheduler for Go](https://docs.google.com/document/d/1d3iI2QWURgDIsSR6G2275vMeQ_X7w-qxM2Vp7iGwwuM/pub)
56 |   * [Go 1.5+ "External" Packages](https://docs.google.com/document/d/1CJnU6ZKvsp21B0lQwbJlKFt8Zz4EWscaCRy_EwK8ja8)
57 | 
58 | ## Other Tools
59 |   * [Go Oracle](https://docs.google.com/document/d/1WmMHBUjQiuy15JfEnT8YBROQmEv-7K6bV-Y_K53oi5Y)
60 |   * [Binding Go and Java](https://go.dev/s/gobind)
61 |   * [Go Builder Plan](https://go.dev/s/builderplan)
62 |   * [gomobile — a tool for building apps](https://docs.google.com/document/d/1cePOQ35PNEb_QqxnPAmBv0cEnAm7AQSGuz9wVeJ-lBs/edit)
63 | 
64 | ## Rejected Proposals
65 |   * [Read-only Slices](https://docs.google.com/a/golang.org/document/d/1UKu_do3FRvfeN5Bb1RxLohV-zBOJWTzX0E8ZU1bkqX0/edit#heading=h.2wzvdd6vdi83), [Evaluation of read-only slices](https://docs.google.com/document/d/1-NzIYu0qnnsshMBpMPmuO21qd8unlimHgKjRD9qwp2A/edit) ([rejected](https://groups.google.com/d/msg/golang-dev/Y7j4B2r_eDw/Rkq-OtEsEBAJ))
66 |   * [Go 1.4: unsafe.Pointer arithmetic](https://docs.google.com/a/dempsky.org/document/d/1yyCMzE4YPfsXvnZNjhszaYNqavxHhvbY-OWPqdzZK30/pub)
67 | 
68 | 


--------------------------------------------------------------------------------
/Diagnostics.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Diagnostics
3 | ---
4 | 
5 | Moved to [/doc/diagnostics](/doc/diagnostics).
6 | 
7 | 


--------------------------------------------------------------------------------
/Download-build-farm-failed-logs-and-debugging.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Download-build-farm-failed-logs-and-debugging
 3 | ---
 4 | 
 5 | The Go project has all build failed logs storage at GCE, which you can access by the [dashboard](https://build.golang.org/).
 6 | 
 7 | You can download all the failed logs by `fetchlogs`.
 8 | 
 9 | Download `fetchlogs` by `go get golang.org/x/build/cmd/fetchlogs`
10 | 
11 | `fetchlogs` only download 300 latest failed logs by default, which is not enough for "mystery"/"flaky" bugs.
12 | `fetchlogs -n <the number you want>`
13 | 
14 | You may also want to take a look at
15 | `github.com/aclements/go-misc/greplogs`. It's a useful tool by Austin
16 | to run grep over logs fetched by fetchlogs. 
17 | 
18 | Also `github.com/aclements/findflakes` can make some guesses as to when a
19 | flaky test started failing.
20 | 


--------------------------------------------------------------------------------
/DragonFly-BSD.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Go on DragonFly BSD
 3 | ---
 4 | 
 5 | From https://github.com/golang/go/issues/34958#issuecomment-543852995 :
 6 | 
 7 | > Go's DragonFly support policy is that we support the latest stable
 8 | > release primarily, but also try to keep DragonFly master passing, in
 9 | > prep for it to become the latest stable release.
10 | >
11 | > But that does mean we need one more builder at the moment.
12 | 
13 | | **Kernel version**      | **Architectures** | **Initial support version** | **Final support version** |
14 | |:------------------------|:------------------|:----------------------------|:--------------------------|
15 | | 4.6 or above            | amd64             | Go 1.8                      |                           |
16 | | 4.4.4 (EOL)             | amd64             | Go 1.8                      |                           |
17 | | 4.4 through 4.4.3 (EOL) | amd64             | Go 1.3 _*_                  | Go 1.7.6                  |
18 | | 3.8 through 4.2 (EOL)   | amd64             | Go 1.3 _*_                  | Go 1.7.6                  |
19 | | 3.6 (EOL)               | amd64, 386        | Go 1.3                      | Go 1.4.3                  |
20 | 
21 | _*_ Go 1.5 or above is recommended.
22 | 
23 | 


--------------------------------------------------------------------------------
/Errors.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | title: Errors
  3 | ---
  4 | 
  5 | Errors are indicated by returning an `error` as an additional return value from a function. A `nil` value means that there was no error.
  6 | 
  7 | ` error `s can be turned into strings by calling `Error`, their only method. You can create an error from a string by calling `errors.New`:
  8 | 
  9 | ```go
 10 | if failure {
 11 | 	return errors.New("inverse tachyon pulse failed")
 12 | }
 13 | ```
 14 | 
 15 | or by using `fmt.Errorf`:
 16 | 
 17 | ```go
 18 | if failure {
 19 | 	return fmt.Errorf("inverse tachyon pulse failed")
 20 | }
 21 | ```
 22 | 
 23 | Error strings should not start with a capital letter because they'll often be prefixed before printing:
 24 | 
 25 | ```go
 26 | err := TryInverseTachyonPulse()
 27 | if err != nil {
 28 | 	fmt.Printf("failed to solve problem: %s\n", err)
 29 | }
 30 | ```
 31 | 
 32 | If you expect calling code to be able to handle an error, you can distinguish classes of errors either by returning special values, or new types. You only need to distinguish differences that the calling code could be expected to handle in this way as the string allows one to communicate the details of the error.
 33 | 
 34 | `io.EOF` is a special value that signals the end of a stream. You can compare error values directly against io.EOF.
 35 | 
 36 | If you want to carry extra data with the error, you can use a new type:
 37 | 
 38 | ```go
 39 | type ParseError struct {
 40 | 	Line, Col int
 41 | }
 42 | 
 43 | func (p ParseError) Error() string {
 44 | 	return fmt.Sprintf("parse error on line %d, column %d", p.Line, p.Col)
 45 | }
 46 | ```
 47 | 
 48 | If you want to create a constant string error, you can use a named type string:
 49 | 
 50 | ```go
 51 | type errorConst string
 52 | 
 53 | const ErrTooManyErrors errorConst = "too many errors found."
 54 | 
 55 | func (e errorConst) Error() string {
 56 | 	return string(e)
 57 | }
 58 | ```
 59 | 
 60 | Calling code would test for a special type of `error` by using a type switch:
 61 | 
 62 | ```go
 63 | switch err := err.(type) {
 64 | case ParseError:
 65 | 	PrintParseError(err)
 66 | }
 67 | ```
 68 | 
 69 | ## Naming
 70 | 
 71 | Error types end in `"Error"` and error variables start with `"Err"` or `"err"`:
 72 | 
 73 | ```go
 74 | package somepkg
 75 | 
 76 | // ParseError is type of error returned when there's a parsing problem.
 77 | type ParseError struct {
 78 |   Line, Col int
 79 | }
 80 | 
 81 | var ErrBadAction = errors.New("somepkg: a bad action was performed")
 82 | 
 83 | // -----
 84 | 
 85 | package foo
 86 | 
 87 | func foo() {
 88 |     res, err := somepkgAction()
 89 |     if err != nil {
 90 |         if err == somepkg.ErrBadAction {
 91 |         }
 92 |         if pe, ok := err.(*somepkg.ParseError); ok {
 93 |              line, col := pe.Line, pe.Col
 94 |              // ....
 95 |         }
 96 |     }
 97 | }
 98 | ```
 99 | 
100 | ## References
101 | 
102 |   * Errors (specification): https://go.dev/ref/spec#Errors
103 |   * Package `errors`: https://pkg.go.dev/errors/
104 |   * Type switches: https://go.dev/ref/spec#TypeSwitchStmt
105 | 
106 | 


--------------------------------------------------------------------------------
/FileTreeDocumentation.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: FileTreeDocumentation
 3 | ---
 4 | 
 5 | This page documents the file tree for a source installation of go1.13.1.
 6 | 
 7 | ```
 8 | $ tree -d -L 2 /usr/lib/go1.13.1 | head
 9 | /usr/lib/go1.13.1
10 | `-- go
11 |     |-- api
12 |     |-- bin
13 |     |-- doc
14 |     |-- lib
15 |     |-- misc
16 |     |-- pkg
17 |     |-- src
18 |     `-- test
19 | $
20 | ```
21 | 
22 | api contains data for Go's API checker
23 | 
24 | ```
25 | $ ls $GOROOT/api
26 | README	    go1.10.txt	go1.13.txt  go1.4.txt  go1.7.txt  go1.txt
27 | except.txt  go1.11.txt	go1.2.txt   go1.5.txt  go1.8.txt  next.txt
28 | go1.1.txt   go1.12.txt	go1.3.txt   go1.6.txt  go1.9.txt
29 | $
30 | ```
31 | 
32 | bin contains the go and gofmt executables
33 | 
34 | ```
35 | $ ls -l $GOROOT/bin
36 | total 11576
37 | -rwxr-xr-x 1 root root 9652760 Oct  2 03:02 go
38 | -rwxr-xr-x 1 root root 2197756 Oct  2 03:02 gofmt
39 | $
40 | ```
41 | 
42 | doc contains .css, .go, .html, .js, and .png files
43 | 
44 | lib contains the compressed time zone database
45 | 
46 | ```
47 | $ tree $GOROOT/lib | head -n 5
48 | /usr/lib/go1.13.1/go/lib
49 | `-- time
50 |     |-- README
51 |     |-- update.bash
52 |     `-- zoneinfo.zip
53 | $
54 | ```
55 | 
56 | misc contains files pertaining to specific build modes and platforms
57 | 
58 | ```
59 | $ tree -d -L 1 $GOROOT/misc | head -n 12
60 | /usr/lib/go1.13.1/go/misc
61 | |-- android
62 | |-- arm
63 | |-- cgo
64 | |-- chrome
65 | |-- ios
66 | |-- linkcheck
67 | |-- nacl
68 | |-- reboot
69 | |-- swig
70 | |-- trace
71 | `-- wasm
72 | $
73 | ```
74 | 
75 | pkg contains libs, header files, compiled object files, and executables
76 | 
77 | ```
78 | $ tree -d -L 1 $GOROOT/pkg | head -n 6
79 | /usr/lib/go1.13.1/go/pkg
80 | |-- include
81 | |-- linux_386
82 | |-- linux_386_dynlink
83 | |-- obj
84 | `-- tool
85 | $
86 | ```
87 | src contains the go1.13.1 source code
88 | 
89 | test contains tests of the Go toolchain and runtime
90 | 


--------------------------------------------------------------------------------
/FreeBSD.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Go on FreeBSD
 3 | ---
 4 | 
 5 | | **Kernel version** | **Architectures**               | **Initial support version** | **Final support version** |
 6 | |:-------------------|:--------------------------------|:----------------------------|:--------------------------|
 7 | | 14-CURRENT         | amd64, 386, arm, arm64, riscv64 | _**_ _***_                  |                           |
 8 | | 13-STABLE          | amd64, 386, arm, arm64, riscv64 | _**_ _***_                  |                           |
 9 | | 12-STABLE          | amd64, 386, arm, arm64          | Go 1.12 _**_                |                           |
10 | | 11-STABLE (EOL)    | amd64, 386, arm, 386            | Go 1.7                      | Go 1.19.x                 |
11 | | 10-STABLE (EOL)    | amd64, 386, arm, 386            | Go 1.3 _*_                  | Go 1.12.4                 |
12 | | 9-STABLE (EOL)     | amd64, 386                      | Go 1 _*_                    | Go 1.9.7                  |
13 | | 8-STABLE (EOL)     | amd64, 386                      | Go 1 _*_                    | Go 1.9.7                  |
14 | | 7-STABLE (EOL)     | amd64, 386                      | Go 1                        | Go 1.1.2                  |
15 | 
16 | _*_ Go 1.5 or above is recommended.
17 | 
18 | _**_ Go versions prior to 1.20 require a kernel with `options COMPAT_FREEBSD11` config (this is the default). 64-bit inode aware system calls are available since https://go.dev/cl/143637. See https://go.dev/issues/22447.
19 | 
20 | _***_ Go 1.20 is the first version to support freebsd/riscv64.
21 | 
22 | 


--------------------------------------------------------------------------------
/Frozen.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Frozen
 3 | ---
 4 | 
 5 | Sometimes a package reaches the end of its development cycle and is considered complete. It continues to be maintained, meaning regressions or breakages are fixed, but the scope becomes frozen and no new features are meant to be accepted.
 6 | 
 7 | Freezing a package is a message primarily for developers and contributors to the package, not users. It does not imply that the package should not be used. For that, see the ["Deprecated" convention](Deprecated).
 8 | 
 9 | To signal that a package is frozen and is not accepting new features, add a paragraph to its doc comment stating that, and a recommendation on where to look for and where to contribute new features, if applicable.
10 | 
11 | ## Examples
12 | 
13 | ```
14 | // The syslog package is frozen and is not accepting new features.
15 | // Some external packages provide more functionality. See:
16 | //
17 | // 	https://pkg.go.dev/search?q=syslog
18 | ```
19 | 
20 | ```
21 | // The smtp package is frozen and is not accepting new features.
22 | // Some external packages provide more functionality. See:
23 | //
24 | //  https://pkg.go.dev/search?q=smtp
25 | ```
26 | 
27 | ```
28 | // The net/rpc package is frozen and is not accepting new features.
29 | ```
30 | 
31 | ```
32 | // The testing/quick package is frozen and is not accepting new features.
33 | ```
34 | 
35 | ```
36 | // The text/tabwriter package is frozen and is not accepting new features.
37 | ```
38 | 
39 | 


--------------------------------------------------------------------------------
/Fuzzing-trophy-case.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Fuzzing trophy case
 3 | ---
 4 | 
 5 | This page collects issues that have been discovered using [Go's native fuzzing](https://github.com/golang/go/issues/44551).
 6 | 
 7 | ## Contributing
 8 | 
 9 | If native fuzzing uncovered a bug in your project, please consider adding it to this list by editing this Wiki page directly, or by reaching out to katie@golang.org with the bug you'd like to share.
10 | 
11 | _Note: If you think the bug is a security issue, please report it responsibly to the respective team, and do not include it in this list until public disclosure._
12 | 
13 | ## Trophies
14 | <!-- If editing this list, please maintain alphabetical order -->
15 | 
16 | ### Standard Library
17 | * [go/scanner: inconsistent handling of NUL bytes in 1.17](https://github.com/golang/go/issues/46855)
18 | * [time: ParseDuration can panic on invalid input](https://github.com/golang/go/issues/46883)
19 | 
20 | ### Other projects
21 | * [go-yaml/yaml/v3: yaml.Unmarshal() crashes on "#\n - - QI\xd7"](https://github.com/go-yaml/yaml/issues/744)
22 | * [josephburnett/jd: crashes when validating JSON Patch test/replace operation](https://github.com/josephburnett/jd/commit/7064efc5df7c899ffc53b45be8915e3f4edc1684)
23 | * [josephburnett/jd: JSON Patch to void failing round-trip](https://github.com/josephburnett/jd/commit/bd2fc2657f56c7c1f70a5971c18be32365afd1c7)
24 | * [kokes/smda: nil pointer error](https://github.com/kokes/smda/commit/b41ac00b5f5acba60d93076347fc73fe2fbca340)
25 | * [kokes/smda: out of bounds error](https://github.com/kokes/smda/commit/2c2548f211a1ed2c3547407e0b420e4340612278)
26 | * [mvdan.cc/sh: syntax.Quote failed to quote the empty string](https://github.com/mvdan/sh/commit/92eab20da20af9c4005294abf937e387d87c8407)
27 | * [mvdan.cc/sh: syntax.Quote misused `\x` escape sequences in mksh](https://github.com/mvdan/sh/commit/8bd780f971469bece51617a53da0e1c700c4a5b8)
28 | * [mvdan.cc/sh: syntax.Quote can't quote the `0xFFFE` and `0xFFFF` runes in mksh](https://github.com/mvdan/sh/commit/6ff55fb976f3c39d1a382ff5af616c3665c7e501)
29 | * [pelletier/go-toml: index out of range error in expect function](https://github.com/pelletier/go-toml/issues/561)
30 | * [swaggest/form: panic on invalid keys in request](https://github.com/swaggest/form/issues/4)
31 | * [yuin/goldmark: corner case errors](https://github.com/yuin/goldmark/issues/245)
32 | * [DataDog/datadog-agent: fix edge case in tags normalization](https://github.com/DataDog/datadog-agent/pull/13235)
33 | 
34 | 
35 | 
36 | 
37 | 


--------------------------------------------------------------------------------
/Gardening.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Gardening
 3 | ---
 4 | 
 5 | ## What is gardening?
 6 | 
 7 | "Gardening" in open source projects refers to the background maintenance tasks done to keep the project healthy & growing & nice looking.
 8 | 
 9 | This page lists common Go gardening tasks.
10 | 
11 | ## Access
12 | 
13 | If you've been regularly active in the Go community for some time, feel free to ask for Gerrit and/or GitHub access to modify things.
14 | 
15 | See [GerritAccess](/wiki/GerritAccess) and [GitHubAccess](/wiki/GitHubAccess).
16 | 
17 | ## Gardening Tasks
18 | 
19 | Before doing any gardening work, especially on the issue tracker, remember to familiarize yourself with the issues life-cycle, described here: [Handling Issues - Issue States](/wiki/HandlingIssues#issue-states).
20 | 
21 | ### Fix red
22 | 
23 | Look at https://build.golang.org/ --- is anything red? Fix or file bugs or nag people. The build dashboard should never be red, even occasionally. If the tree is red, people can't work effectively because TryBots and such will just report failures, masking other problems.
24 | 
25 | ### Triage new bugs
26 | 
27 | Look at the [untriaged issues](https://go.dev/s/untriaged). For Go, we use the presence of certain labels (`Needs*` or `WaitingForInfo`) to indicate that an issue has been triaged. Issues labeled `Go2`, `Proposal`, `Telemetry-Proposal`, `CherryPickCandidate`, `gopls`, `pkgsite` have their own, separate triage queues and can be skipped.
28 | 
29 | While triaging the bug:
30 | 
31 | * is it a duplicate? Close it, referencing the dup.
32 | * is it a Question rather than a bug? Reply with something like "For questions about Go, see https://go.dev/wiki/Questions".
33 | * is the subject the correct format? It should start with the package path and a colon: "net/http: fix crash in Server during foo operation".
34 | * is it in a subrepo? Leave the milestone as `Unreleased` unless it's a subrepo that goes into a release, like `http2`.
35 | * if it is a regression and you can reproduce it, use `git bisect` to find the bad commit (optional but very helpful).
36 | * does the relevant package [have a primary owner](https://dev.golang.org/owners)? Mention them in a comment. If not, add the `help wanted` label.
37 | * if the relevant package has no owner, but appears to be complex and deeply technical in nature, add the `ExpertNeeded` label.
38 | 
39 | When the issue has been triaged, add an appropriate label (per [HandlingIssues](/wiki/HandlingIssues)) to mark it as such.
40 | 
41 | ### WaitingForInfo
42 | 
43 | Find bugs that are in state WaitingForInfo (https://github.com/golang/go/labels/WaitingForInfo) and ping them, remove the label when replies arrive, or close the bugs if a reply never arrived.
44 | 
45 | ### "Unplanned" bugs
46 | 
47 | ["Unplanned" issues](https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20milestone%3AUnplanned%20sort%3Aupdated-asc%20-label%3AGo2%20-label%3ALanguageChange) have a habit of being neglected. Check out old ones and see if they're easily fixable (and can be moved to a Go1.n or Go 1.nMaybe milestone), or should be closed.
48 | 
49 | ### Pending CLs
50 | 
51 | [Review the format of commit messages](https://go.dev/doc/contribute#commit_messages) and presence of tests and formatting of code and typos/grammar in incoming pending CLs. All of that can be done without determining the correctness of the change itself. See  https://dev.golang.org/release for the list of pending CLs.
52 | 
53 | Once it has a +1, the owner of that area can give it a +2.
54 | 
55 | Read a +1 as meaning "triaged", or "not obviously wrong". If it has tests, is formatted properly (references a bug number, probably), and is ready for more review, give it a +1.
56 | 
57 | ### Pending CLs: ask about tests
58 | 
59 | If a new CL arrives without a test, but could/should have a test, ask if they could add a test. Or suggest how.
60 | 
61 | ### Pending CLs: run TryBots
62 | 
63 | If you have access (see [GerritAccess](/wiki/GerritAccess)) to run the TryBots and you see a CL with plausible (and non-malicious) code, kick off the TryBots. (We've never seen malicious code trying to escape our TryBot sandboxes, but that's why it's not automatic yet. Please alert us if you see something.)
64 | 


--------------------------------------------------------------------------------
/GitHubAccess.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: GitHubAccess
 3 | ---
 4 | 
 5 | There are two types of GitHub access described here, with different powers & responsibilities. Only ask for access if you're an active member of the community. New contributors should participate in the GitHub & Gerrit review process for some time before requesting access.
 6 | 
 7 | (For Gerrit access, see [GerritAccess](/wiki/GerritAccess))
 8 | 
 9 | ## Assignees
10 | 
11 | The "go-assignees" group is a read-only group granting no special access, other than it allows the users in the group to be assigned issues.
12 | 
13 | In general, Go doesn't use the "Assigned to" field of bugs much. Instead, we just leave a comment saying we'll work on it. But if you want this access, reference https://github.com/orgs/golang/teams/go-assignees and your GitHub username in your issue requesting access.
14 | 
15 | ## Editors
16 | 
17 | The "go-editors" group is the set of people who can edit metadata on issues.
18 | 
19 | To request this type of access, reference https://github.com/orgs/golang/teams/go-editors and your GitHub username in your issue requesting access.
20 | 
21 | Please do not edit any field you're not confident about. Feel free to ask for second opinions.
22 | 
23 | ## Requesting Access
24 | 
25 | To request any of the access types above, file a new issue (https://go.dev/issue/new?title=access:+&body=See+https://go.dev/wiki/GitHubAccess.) and state which access you want (its name and group URL).
26 | 
27 | ## Once you have access
28 | 
29 | Go help garden! See [Gardening](/wiki/Gardening).
30 | 
31 | 


--------------------------------------------------------------------------------
/Go-Community-Slides.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Go-Community-Slides
 3 | ---
 4 | 
 5 | Did you speak at a conference or meetup lately? Please share links to your slide decks here for better distribution to our global community. 
 6 | 
 7 | 
 8 | ## Peer To Peer Groups
 9 | 
10 | ### Kitchener-Waterloo, Canada
11 | 
12 | #### Concurrent Optimization Methods Using Go
13 | 
14 | Brodie Roberts, June 12, 2018 [[repo](https://github.com/indexexchange/GoOptimizationMethods)]
15 | 
16 | Concurrency is a powerful tool for doing huge amounts of computation on today's multi-core computers. But that power is limited by the design of paralleling the problem and its implementation using threads and locks. We'll start with a sub-optimal concurrent Go program and walk through improving it - iterating on finding the program's bottleneck, improving it, and seeing the program get faster. We'll also cover general tips and tricks of concurrent optimization to apply to your own computationally intensive programs. 
17 | 
18 | 
19 | ## Conferences
20 | ### [GopherCon 2018](http://gophercon.com/), Denver, Colorado
21 | 
22 | #### The Importance of Beginners
23 | Natalie Pistunovich, August 29 
24 | 
25 | * [Session details](https://www.gophercon.com/agenda/session/16875)
26 | * [Slides](https://github.com/Pisush/Public-Speaking/blob/master/Slides/gopherconUS.pdf)
27 | 
28 | #### Rethinking Classical Concurrency Patterns
29 | Bryan C. Mills, August 28
30 | 
31 | * [Slides with speaker notes](https://drive.google.com/file/d/1nPdvhB0PutEJzdCq5ms6UI58dp50fcAN/view?usp=sharing)
32 | 


--------------------------------------------------------------------------------
/Go2.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Go2 status
 3 | ---
 4 | 
 5 | This page tracks the status of "Go 2".
 6 | 
 7 | We are currently seeking feedback on potential designs for improved error handling, error values, and generics:
 8 | 
 9 | * [Announcement of Go2 Draft Designs](https://go.dev/blog/go2draft)
10 | * [Go2 Error Handling, Generics, and Error Values](https://go.googlesource.com/proposal/+/master/design/go2draft.md)
11 | 
12 | ## Bugs
13 | 
14 | * [Open Go2 bugs](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3AGo2)
15 | 
16 | ## Talks
17 | 
18 | * [GopherCon 2017: Russ Cox - The Future of Go](https://www.youtube.com/watch?v=0Zbh_vmAKvk) 
19 | * [GopherCon Russia 2018: Brad Fitzpatrick - Go: Looking back and looking forward](https://www.youtube.com/watch?v=ZCB-g2B4Y5A) (Go2 stuff is at about 20 minutes in)
20 | * [Sydney Golang Meetup - Rob Pike - Go 2 Draft Specifications](https://www.youtube.com/watch?v=RIvL2ONhFBI)
21 | 
22 | ## Scope
23 | 
24 | From talk above:
25 | 
26 | * "maybe three major changes"
27 | * plus minor housekeep tasks
28 | * TBD
29 | 
30 | Examples of major changes:
31 | 
32 | * [versioning](https://github.com/golang/go/issues/24301)
33 | * [generics](https://github.com/golang/go/issues/15292)?
34 | * [simplified, improved error handling](https://github.com/golang/go/issues/21161)?
35 | * ...
36 | 
37 | Examples of housekeeping:
38 | 
39 | * [Open Go2Cleanup bugs](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3AGo2Cleanup) (please don't add this label to things without discussion)
40 | 
41 | ## Compatibility
42 | 
43 | We do not want to break the ecosystem. Go 1 and Go 2 code must be able to interoperate in programs with ease.
44 | 
45 | ## Standard library
46 | 
47 | The standard library would probably be versioned and permit out-of-cycle updates, but be included with Go releases. Maybe "encoding/foo" become shorthand for "golang.org/x/std/encoding/foo". TBD. Some package would probably get v2 major versions, but the v1 versions would be minimally maintained, at least for security.
48 | 
49 | ## Roadmap
50 | 
51 | TBD
52 | 
53 | 


--------------------------------------------------------------------------------
/Go2ErrorValuesFeedback.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Go 2 Error Values Feedback
 3 | ---
 4 | 
 5 | This page is meant to collect and organize feedback about the Go 2 [error values draft designs](https://go.googlesource.com/proposal/+/master/design/go2draft-error-values-overview.md).
 6 | 
 7 | Please post feedback on your blog, Medium, GitHub Gists, mailing lists, Google Docs, etc. And then please link it here.
 8 | 
 9 | As the amount of feedback grows, please feel free to organize this page by specific kind of feedback.
10 | 
11 | ## Further Background
12 | 
13 | - Ben Johnson, "[Failure is Your Domain](https://middlemost.com/failure-is-your-domain/)", June 2018
14 | 
15 | ## Draft Implementation
16 | 
17 | - Go Team, “[x/exp/errors](https://pkg.go.dev/golang.org/x/exp/errors)”, November 2018
18 | 
19 | - Torben Schinke, “[Implementation of the draft design](https://github.com/worldiety/errors)”, December 2018
20 | 
21 | ## Error Inspection
22 | 
23 |  - Ilya Sinelnikov, "[`Is` and `As` differ in behavior which is unexpected](https://github.com/sidh/go2errorsinspection)", December 2018
24 |  - Roger Peppe, "[Some thoughts about the draft Go error inspection design](https://gist.github.com/rogpeppe/a435b57473152e3429a5a149401edacf)", November 2018
25 |  - Greg Weber, “[Horizontal composition: Error inspection for groups](https://gist.github.com/gregwebs/5a14a83970d607411310a3e0281d55be)”, September 2018
26 |     - Eyal Posener, "[Reply](https://gist.github.com/gregwebs/5a14a83970d607411310a3e0281d55be#gistcomment-2710662)", September 2018 
27 |  - K. Alex mills, "[Rename Wrapper to Unwrapper](https://gist.github.com/kalexmills/46c2cb276c69b659005d8705180b268a)", September 2018
28 |  - jimmy frasche, "[Why limit this inspection to errors?](https://gist.github.com/jimmyfrasche/04ca2146c9130dab4d993365313722fb)", August 2018
29 |  - Dan Kortschak, [Carrying contract expectations and values causing errors in ev3go](https://github.com/ev3go/ev3dev/blob/master/errors.go), August 2018
30 |  - Daniel Theophanes, "[Go 2 Design: Error Inspection with Error Lists](https://docs.google.com/document/d/e/2PACX-1vT-CPcBV53awF7vq5bJEi1Y_DkuVmWW0RWl-gsujByB1mjX67rH58-mex1on1waR4Q_gyhPu5TdghMv/pub), August 2018
31 |  - Cosmos Nicolaou "[Inspection of errors in a different address space](https://github.com/cosnicolaou/core/wiki/go-2.0-error-handling-feedback)", September 2018
32 | - Chris Siebenmann, "[Error inspection improves current annoyances but may not go far enough](https://utcc.utoronto.ca/~cks/space/blog/programming/Go2ErrorInspectionViews)", September 2018
33 |  - Paul Meyer, “[errors.New?]( - _Your Name_, “[_Title_](#URL)”, August 2018
34 |  - Vojtech Vitek "[adopt Cause and Wrap from github.com/pkg/errors](https://go.dev/issue/25675)", May 2018
35 |  - Andrew Wilkins "[Programmatic Frame inspection](https://gist.github.com/axw/247b6f69d2da016bb21a5eb1be44e611)", January 2019
36 | - _Carl Johnson_, "[_`As()` and `Is()` are useful for optional interfaces beyond error_](https://gist.github.com/carlmjohnson/d06cd8d10e0aef65f565a55cc57cd986), Feb. 2019
37 |  - ques0942, "[xerrors has less feature about trace's detail](https://dev.to/ques0942/xerrors-has-less-feature-about-traces-detail-4861)", Mar. 2019
38 |  - _Your Name_, “[_Title_](#URL)”, _month year_
39 |  - etc.
40 | 
41 | ## Error Printing
42 | 
43 |  - Calle Pettersson, [Multi-line errors and log collection tools](https://gist.github.com/carlpett/bc1714060235edc0ad3fd9ead82f4ce6)”, August 2018
44 |  - jimmy frasche, "[Why limit these interfaces to errors?](https://gist.github.com/jimmyfrasche/e02fcbefee5cb14228768afec17abbee)" , August 2018
45 |  - Chris Hines, “[Types cannot implement both the errors.Formatter and fmt.Formatter interfaces
46 | ](https://gist.github.com/ChrisHines/a732a9b1ef3acb6acfee2ccc174e31ed)”, _August 2018_
47 |  - Dean Bassett, “[Make errors.Detailer, not errors.Formatter](https://gist.github.com/deanveloper/61544f16a7d4c3d517bda10c08080270)”, _September 2018_
48 |  - Bryan C. Mills, “[Error Wrapping and Redundancy in Go](https://github.com/bcmills/go-experience-reports/blob/master/errors.md)”, _September 2019_
49 |  - _Your Name_, “[_Title_](#URL)”, _month year_
50 |  - etc.
51 | 
52 | ## Misc
53 | 
54 | - TJ Holowaychuk, [Structured access for structured logging](https://gist.github.com/tj/638adb053f802e6c19686bd2fee443b7), April, 2019
55 | - Andrew Chambers, [My current error approach](https://gist.github.com/andrewchambers/5cadb2b8b45271440f1a051bb1ccc9c6), August, 2018
56 | - mikioh, [A walkthrough on Error Values for issue 18183](https://gist.github.com/mikioh/93f575120ded671bad18491ecf41743d), October, 2018
57 | 
58 | ## Against Any Change At All
59 | 
60 | - Rob Pike - [Simplicity is Complicated](https://www.youtube.com/watch?v=rFejpH_tAHM), December 2015
61 | 


--------------------------------------------------------------------------------
/GoGenerateTools.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: GoGenerateTools
 3 | ---
 4 | 
 5 | [`go generate`](https://go.dev/blog/generate) is only useful if you have tools to use it with! Here is an incomplete list of useful tools that generate code.
 6 | 
 7 | * [goyacc](https://pkg.go.dev/golang.org/x/tools/cmd/goyacc) – Yacc for Go.
 8 | * [stringer](https://pkg.go.dev/golang.org/x/tools/cmd/stringer) – Implements `fmt.Stringer` interface for enums.
 9 | * [gostringer](https://pkg.go.dev/github.com/sourcegraph/gostringer) – Implements `fmt.GoStringer` interface for enums.
10 | * [jsonenums](https://github.com/campoy/jsonenums) – Implements `json.Marshaler` and `json.Unmarshaler` interfaces for enums.
11 | * [go-syncmap](https://pkg.go.dev/github.com/searKing/golang/tools/cmd/go-syncmap) - Generates Go code using a package as a generic template for `sync.Map`.
12 | * [go-syncpool](https://pkg.go.dev/github.com/searKing/golang/tools/cmd/go-syncpool) - Generates Go code using a package as a generic template for `sync.Pool`.
13 | * [go-atomicvalue](https://pkg.go.dev/github.com/searKing/golang/tools/cmd/go-atomicvalue) - Generates Go code using a package as a generic template for `atomic.Value`.
14 | * [go-nulljson](https://pkg.go.dev/github.com/searKing/golang/tools/cmd/go-nulljson) - Generates Go code using a package as a generic template that implements `database/sql.Scanner` and `database/sql/driver.Valuer`.
15 | * [go-enum](https://pkg.go.dev/github.com/searKing/golang/tools/cmd/go-enum) - Generates Go code using a package as a generic template which implements interface `fmt.Stringer` | `binary` | `json` | `text` | `sql` | `yaml` for enums.
16 | * [enumer](https://pkg.go.dev/github.com/alvaroloes/enumer) - Generates Go code that convert Go enum to/from strings.
17 | * [go-import](https://pkg.go.dev/github.com/searKing/golang/tools/cmd/go-import) — Performs auto import of non go files.
18 | * [gojson](https://github.com/ChimeraCoder/gojson) - Generates go struct definitions from example json documents.
19 | * [vfsgen](https://github.com/shurcooL/vfsgen) - Generates a vfsdata.go file that statically implements the given virtual filesystem.
20 | * [goreuse](https://github.com/dc0d/goreuse) - Generates Go code using a package as a generic template by replacing definitions.
21 | * [embedfiles](https://4d63.com/embedfiles) - Embeds files into Go code.
22 | * [ragel](https://www.colm.net/open-source/ragel/) - State machine compiler
23 | * [peachpy](https://github.com/Maratyszcza/PeachPy) - x86-64 assembler embedded in Python, generates Go assembly
24 | * [bundle](https://pkg.go.dev/golang.org/x/tools/cmd/bundle) - Bundle creates a single-source-file version of a source package suitable for inclusion in a particular target package.
25 | * [msgp](https://github.com/tinylib/msgp) - A Go code generator for MessagePack
26 | * [protobuf](https://github.com/golang/protobuf) - protobuf
27 | * [thriftrw](https://github.com/thriftrw/thriftrw-go) - thrift
28 | * [gogen-avro](https://github.com/actgardner/gogen-avro) - avro
29 | * [swagger-gen-types](https://github.com/dnephin/swagger-gen-types) - go types from swagger specifications
30 | * [avo](https://github.com/mmcloughlin/avo) - generate assembly code with Go
31 | * [Wire](https://github.com/google/wire) - Compile-time Dependency Injection for Go
32 | * [sumgen](https://github.com/smasher164/sumgen) - generate interface method implementations from sum-type declarations
33 | * [interface-extractor](https://github.com/urandom/interface-extractor) - generates an interface of a desired type, with only methods used within the package.
34 | * [deep-copy](https://github.com/globusdigital/deep-copy) - creates a deep copy method for the given types.
35 | * [libfsm](https://github.com/katef/libfsm) - fsm toolkit supporting (among others) Go and Go-flavored amd64 assembly for matching regexps
36 | * [re2c](https://re2c.org/index.html) - lexer generator for C, C++ and Go
37 | * [re2dfa](https://gitlab.com/opennota/re2dfa) - Transform regular expressions into finite state machines and output Go source code
38 | * [pigeon](https://github.com/mna/pigeon) - a PEG parser generator for Go
39 | 
40 | 
41 | 
42 | 


--------------------------------------------------------------------------------
/GoGetProxyConfig.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: GoGetProxyConfig
 3 | ---
 4 | 
 5 | Setting proxies for source code used by ` go get ` (listed in GoGetTools)
 6 | 
 7 | ## Windows command line
 8 | ```
 9 | $ set http_proxy=http://proxy.example.com:port
10 | ```
11 | 
12 | ## git
13 | ```
14 | $ git config [--global] http.proxy http://proxy.example.com:port
15 | ```
16 | 
17 | ## mercurial
18 | Edit ` ~/.hgrc ` and add the following:
19 | ```
20 | [http_proxy]
21 | host=proxy.example.com:port
22 | ```
23 | 
24 | ## svn
25 | Edit ` ~/.subversion/servers ` and add the following:
26 | ```
27 | [Global] 
28 | http-proxy-host=proxy.example.com
29 | http-proxy-port=xxxx 
30 | ```
31 | 


--------------------------------------------------------------------------------
/GoGetTools.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: GoGetTools
 3 | ---
 4 | 
 5 | ## Installing Version Control Tools for ` go get `
 6 | 
 7 | The ` go get ` fetching of source code is done by using one of the following tools expected to be found on your system:
 8 | 
 9 |   * **svn** - Subversion, download at: http://subversion.apache.org/packages.html
10 |   * **hg** - Mercurial, download at https://www.mercurial-scm.org/downloads
11 |   * **git** - Git, download at http://git-scm.com/downloads
12 |   * **bzr** - Bazaar, download at http://wiki.bazaar.canonical.com/Download
13 | 
14 | For example, **git** is used for GitHub, **hg** is used for Bitbucket, etc.
15 | 
16 | Refer [GoGetProxyConfig](GoGetProxyConfig) for setting proxies for these tools.
17 | 


--------------------------------------------------------------------------------
/GoMips.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Go on MIPS
 3 | ---
 4 | 
 5 | ## Introduction
 6 | 
 7 | Go programs can be cross-compiled e.g., on x86/x86\_64 build systems to run on MIPS target machines.
 8 | 
 9 | ## Supported architectures
10 | 
11 | Go supports the following MIPS architectural families. (Are there more?)
12 | 
13 | | **Architecture** | **Status** | **GOMIPS value** | **GOARCH value** |
14 | |:-----------------|:-----------|:----------------|:-----------------|
15 | | Big endian (e.g., ar71xx) | supported  | GOMIPS=softfloat| GOARCH=mips      |
16 | | Little endian            | supported  | n/a             | GOARCH=mipsle    |
17 | 
18 | ## Supported operating systems
19 | 
20 | * MIPS on Linux. Tested with an ar71xx based OpenWrt device.
21 | 
22 | ## Recommended Go version
23 | 
24 | The tested version for running Go on MIPS systems is Go 1.13.
25 | 
26 | ## Tips and tricks
27 | 
28 | ### Building for ar71xx OpenWrt
29 | 
30 | This builds a Go program, strips unneeded strings and symbols to minimize its size, and compresses it to further minimize its size:
31 | 
32 | ```
33 | env GOOS=linux GOARCH=mips GOMIPS=softfloat  go build -trimpath -ldflags="-s -w" 'server.go'
34 | upx -9 server
35 | ```
36 | 
37 | ## Success stories
38 | 
39 | MIPS hardware comes in a myriad of shapes and sizes. If you've had a success story building and running Go on your Arm system, please detail your results here.
40 | 
41 | ### D-Link DIR-505 Mobile Companion
42 | 
43 | Architecture: ar71xx
44 | 
45 | Operating System: OpenWrt
46 | 
47 | The D-Link DIR-505 Mobile Companion comes with an Atheros AR1311 processor, 8 MB flash and 64 MB RAM. This space is limited but allows us to load Go applications, e.g., from network into `/tmpfs` and execute them from there.
48 | 
49 | Further information about the device can be found at https://openwrt.org/toh/d-link/dir-505.
50 | 
51 | ### Teltonika RUT955
52 | 
53 | Architecture: ar9344
54 | 
55 | Operating System: RutOS (based on OpenWrt)
56 | 
57 | The Teltonika RUT955 has a Atheros Wasp MIPS 74Kc CPU running at 550 MHz with 16 MB flash 128 MB RAM. Inbuilt flash will be insufficient for most applications but a Micro SD or USB stick can be added (running application directly from SD was unreliable but copying to /tmpfs and running from there works OK). The inbuilt IO, GPS etc can be accessed via Modbus TCP and the RS232/RS485 ports worked without issue. Tested with Go 1.14.6,  1.15.3 & 1.21.1 (GOARCH=mips, GOMIPS=softfloat).
58 | 
59 | Further information about the device can be found at https://teltonika-networks.com/product/rut955/.
60 | 
61 | ### Teltonika RUT956
62 | 
63 | Architecture: MediaTek MT7628AN ver:1 eco:2
64 | 
65 | Operating System: RutOS (based on OpenWrt)
66 | 
67 | The Teltonika RUT956 has a Mediatek MIPS 24KEc CPU running at 580 MHz with 16 MB flash 128 MB RAM. Inbuilt flash will be insufficient for most applications but a USB stick can be added. The inbuilt IO, GPS etc can be accessed via Modbus TCP and the RS232/RS485 ports worked without issue. Tested with Go 1.21.1 (GOARCH=mipsle, GOMIPS=softfloat). Note that `illegal instruction` is output if `GOMIPS` is not set.
68 | 
69 | Further information about the device can be found at https://teltonika-networks.com/product/rut956/.
70 | 
71 | ### TP-Link Archer A6 WiFi Router
72 | 
73 | Architecture: ath79 (same hardware as ar71xx, but with native kernel support)
74 | 
75 | Operating System: OpenWrt
76 | 
77 | The TP-Link Archer A6 comes with an Atheros QCA9563 MIPS 24K classic processor, 16 MB flash, and 128 MB RAM. Flash storage is limited and no USB ports are available for storage expansion, so programs are loaded from the network into /tmpfs and executed.
78 | 
79 | Further information about the device can be found at https://openwrt.org/toh/hwdata/tp-link/tp-link_archer_a6_us_tw.
80 | 
81 | ### Belkin F7D7302 WiFi Router
82 | 
83 | Architecture: mipsel_74kc
84 | 
85 | Operating System: DD-WRT
86 | 
87 | The Belkin F7D7302 comes with a Broadcom BCM4716 little-endian MIPS 74K classic processor, 8 MB flash, and 64 MB RAM. Flash storage is severely limited, but there is a USB port available so programs can be loaded onto a flash drive and executed.
88 | 
89 | Further information about the device can be found at https://openwrt.org/toh/belkin/f7d3302.
90 | 
91 | ### AVM FRITZ!Box 7362 SL
92 | 
93 | System type: xRX200 rev 1.2 \
94 | CPU model: MIPS 34Kc V5.6
95 | 
96 | Operating System: OpenWrt 21
97 | 
98 | Further information about the device can be found at https://openwrt.org/toh/avm/avm_7362_sl.
99 | 


--------------------------------------------------------------------------------
/GoStrings.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: GoStrings
 3 | ---
 4 | 
 5 | Strings are **not** required to be UTF-8. Go source code **is** required
 6 | to be UTF-8. There is a complex path between the two.
 7 | 
 8 | In short, there are three kinds of strings. They are:
 9 | 
10 |   1. the substring of the source that lexes into a string literal.
11 |   1. a string literal.
12 |   1. a value of type string.
13 | 
14 | Only the first is required to be UTF-8. The second is required to be
15 | written in UTF-8, but its contents are interpreted various ways
16 | and may encode arbitrary bytes. The third can contain any bytes at
17 | all.
18 | 
19 | Try this on:
20 | 
21 | ```
22 | var s string = "\xFF語"
23 | ```
24 | Source substring: ` "\xFF語" `, UTF-8 encoded. The data:
25 | 
26 | ```
27 | 22
28 | 5c
29 | 78
30 | 46
31 | 46
32 | e8
33 | aa
34 | 9e
35 | 22
36 | ```
37 | 
38 | String literal: ` \xFF語 ` (between the quotes). The data:
39 | 
40 | ```
41 | 5c
42 | 78
43 | 46
44 | 46
45 | e8
46 | aa
47 | 9e
48 | ```
49 | 
50 | The string value (unprintable; this is a UTF-8 stream). The data:
51 | 
52 | ```
53 | ff
54 | e8
55 | aa
56 | 9e
57 | ```
58 | 
59 | And for record, the characters (code points):
60 | ```
61 | <erroneous byte FF, will appear as U+FFFD if you range over the string value>
62 | 語 U+8a9e
63 | ```
64 | 


--------------------------------------------------------------------------------
/Gopher.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Gopher
 3 | ---
 4 | 
 5 | The Go gopher was designed by [Renee French](https://www.instagram.com/reneefrench/).  
 6 | The design is licensed under the Creative Commons 4.0 Attributions license.  
 7 | Read [this article](https://go.dev/blog/gopher) and watch [The Go Gopher A Character Study](https://www.youtube.com/watch?v=4rw_B4yY69k) for more details.
 8 | 
 9 | ## Where can I find more gopher illustrations?
10 | 
11 | * [gophers in the Go website repository](https://go.googlesource.com/website/+/refs/heads/master/_content/doc/gopher/)
12 | * [gopher vector](https://github.com/golang-samples/gopher-vector)
13 | * [gopher 3d](https://github.com/golang-samples/gopher-3d)
14 | * [golang graphics](https://github.com/mholt/golang-graphics)
15 | * [print-ready swimming gopher](https://gumroad.com/l/golang)
16 | * [go gopher vector](https://github.com/keygx/Go-gopher-Vector)
17 | * [gophericons](https://github.com/hackraft/gophericons)
18 | * [gophers by Egon Elbre](https://github.com/egonelbre/gophers)
19 | * [Go Gopher model (3d)](https://github.com/StickmanVentures/go-gopher-model)
20 | * [Gopher Artwork by Ashley McNamara](https://github.com/ashleymcnamara/gophers)
21 | * [Gopherize.me](https://gopherize.me/) - a Gopher avatar that's as unique as you
22 | * [Free Gophers Pack](https://github.com/MariaLetta/free-gophers-pack)
23 | 


--------------------------------------------------------------------------------
/Home.md:
--------------------------------------------------------------------------------
1 | ---
2 | redirect: /wiki/
3 | ---
4 | 


--------------------------------------------------------------------------------
/HostedContinuousIntegration.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: HostedContinuousIntegration
 3 | ---
 4 | 
 5 | A number of hosted continuous integration platforms have support for Go
 6 | 
 7 | | Provider | Documentation | Notes |
 8 | |:---------|:--------------|:------|
 9 | | [AppVeyor](http://www.appveyor.com/) | [docs](https://bitbucket.org/appveyor/test-go) | Windows |
10 | | [CircleCI](https://circleci.com/) | [docs](https://circleci.com/docs/language-go/)| [howto-1](http://stackengine.com/golang-with-circleci/) [howto-2](https://medium.com/@jgautheron/publish-your-golang-binaries-in-github-with-circleci-e0b64cb21bf8)     |
11 | | [Codeship](http://codeship.io) | [docs](https://www.codeship.io/documentation/languages-and-frameworks/go/) |       |
12 | | [drone.io](http://drone.io/) | [docs](http://docs.drone.io/golang.html) | [open-source version](https://github.com/drone/drone) |
13 | | [Jenkins](https://jenkins-ci.org/) | [docs](https://wiki.jenkins-ci.org/display/JENKINS/Go+Plugin) | |
14 | | [Magnum CI](https://magnum-ci.com/) | [docs](https://magnum-ci.com/docs/go) |       |
15 | | [Travis CI](http://travis-ci.org) | [docs](http://docs.travis-ci.com/user/languages/go/) |  [howto](http://loads.pickle.me.uk/2015/08/22/easy-peasy-github-releases-for-go-projects-using-travis/), [go-client-api](https://github.com/AbletonAG/go-travis)     |
16 | | [Azure Devops](https://www.visualstudio.com/team-services/) | [docs](https://docs.microsoft.com/en-us/vsts/build-release/apps/go/go) |      |
17 | | [Wercker](http://wercker.com/) | [docs](http://devcenter.wercker.com/quickstarts/building/golang.html) |    |   |
18 | 
19 | 


--------------------------------------------------------------------------------
/How-to-ask-for-help.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: How-to-ask-for-help
 3 | ---
 4 | 
 5 | This page gives some hints on how to successfully ask for help in the various [Go support forums][3].
 6 | 
 7 | ## Before you ask your question
 8 | 
 9 | Before asking for help, please check that you've addressed the following common issues:
10 | 
11 | ### Always check all errors
12 | 
13 | Always check all errors. It is common to see problems reported related to nil panics due to code like this
14 | ```
15 | result, err := somefunction()
16 | if err != nil {
17 |       log.Println("oops an error happened", err)
18 |       // return is missing here
19 | }
20 | // the code then continues to use result which is invalid.
21 | ```
22 | or
23 | ```
24 | result, _ := somefunction()
25 | // code uses result which might be invalid
26 | ```
27 | You should make sure it is clear that your code is correctly handling all error conditions before asking for help.
28 | 
29 | Further reading:
30 | - [Error handling and Go][0] 
31 | 
32 | ### Check that your code is free from data races
33 | 
34 | Unexpected runtime panics are often caused by data races in your program. If your program contains a data race you need to address the race before asking for help.
35 | 
36 | If your program has good test coverage you can test for races by adding the `-race` flag to your `go test` invocation.
37 | 
38 | If your program does not have good test coverage or the crash only happens when running the program, you can build a race enabled version of your program by passing `-race` to your `go build` or `go install` invocation.
39 | 
40 | _The behaviour of a Go program with a data race is undefined. There are no safe data races in Go programs._
41 | 
42 | Further reading:
43 | - [Introducing the race detector][1]
44 | 
45 | ## Asking questions
46 | 
47 | The best way to get help is to show 
48 | 
49 | 1. **What you did, ideally with a small complete, stand-alone, example.** 
50 |   If you ran a command, show the command that you ran. If your program failed, provide the source of the program that failed. If the program is too large, or you cannot share the source, instead provide a self contained, runnable example, that demonstrates the problem.
51 | 2. **What you expected to happen.** If you expected the command to complete successfully, say that. If you expected the program to produce a particular output, give an example of the output you expected.
52 | 3. **What happened instead.**
53 |   If the command failed, include the full output of the failure, not just a single line that you though was the cause. If the program failed to produce the expected output, include what it did output.
54 | 
55 | ## Additional tips
56 | 
57 | - If you are posting the output of a command, paste the text, not a screenshot of the text. If it's actually an image, that's ok.
58 | - If you are posting a large amount of output, you may consider using a pastebin or gist service.
59 | - When posting code samples, use the [Go playground][2] (unless it is unavailable in your country).
60 | 
61 | [0]: https://go.dev/blog/error-handling-and-go
62 | [1]: https://go.dev/blog/race-detector
63 | [2]: https://go.dev/play
64 | [3]: /wiki/questions
65 | 


--------------------------------------------------------------------------------
/InstallFromSource.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: InstallFromSource
 3 | ---
 4 | 
 5 | ## Introduction
 6 | 
 7 | This is a companion to https://go.dev/doc/install/source providing additional instructions for various operating systems.
 8 | 
 9 | ## Install C tools
10 | 
11 | On OS X, a C compiler is bundled in the command line tools for
12 | [Xcode](http://developer.apple.com/Xcode/),
13 | and you don't need to install the whole Xcode to compile Go.
14 | If you have already installed Xcode 4.3+, you can install command
15 | line tools from the Components tab of the Downloads preferences panel.
16 | In more recent versions of Xcode, you can use ` xcode-select --install `
17 | command to install the command line tools without opening Xcode.
18 | To verify you have a working compiler, just invoke ` gcc `
19 | in a freshly created Terminal window, unless you see the
20 | ` "gcc: command not found" ` error, you are ready to go.
21 | 
22 | On Ubuntu/Debian, use ` sudo apt-get install gcc libc6-dev `.
23 | If you want to build 32-bit binaries on a 64-bit system you'll also need the ` libc6-dev-i386 ` package.
24 | 
25 | On RedHat/Centos 6, use ` sudo yum install gcc glibc-devel `.
26 | If you want to build 32-bit binaries on a 64-bit system you'll need both
27 | ` glibc-devel.i386 ` and ` glibc-devel.x86_64 ` packages.
28 | 
29 | On Windows, install ` gcc ` with
30 | [TDM-GCC](http://tdm-gcc.tdragon.net/). or try [TDM-GCC Sourceforge link](https://sourceforge.net/projects/tdm-gcc/).
31 | (Make sure you add its ` bin ` subdirectory to your ` PATH `.) Go does not support the Cygwin toolchain.
32 | 
33 | 


--------------------------------------------------------------------------------
/InstallTroubleshooting.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: InstallTroubleshooting
 3 | ---
 4 | 
 5 | ## Introduction
 6 | 
 7 | There are many times in which you may install Go (either from source or from a binary distribution) and things don't work quite right.  This page is meant to collect some common wisdom about problems that are relatively common or difficult to diagnose and provide tips and solutions.
 8 | 
 9 | ## Contents
10 |   * [Introduction](#introduction)
11 |   * [Tips](#tips)
12 |     * [Environment variables](#environment-variables)
13 |   * [Troubleshooting](#troubleshooting)
14 |     * [Still need help?](#still-need-help)
15 | 
16 | ## Tips
17 | ### Environment variables
18 | 
19 | There are several environment variables that can be set to configure
20 | your Go installation: see https://pkg.go.dev/cmd/go#hdr-Environment_variables.
21 | 
22 | Normally none of them need to be set.
23 | 
24 | That said, the default for `GOROOT` is the root of your Go
25 | installation.
26 | The default for `GOPATH` is the directory named "go" in your home
27 | directory.
28 | The `GOPATH` directory should not be set to, or contain, the `GOROOT`
29 | directory.
30 | 
31 | If you have installed Go in the "go" directory in your home directory,
32 | running the go tool will print a warning.
33 | You should either move the Go installation, or set the `GOPATH`
34 | environment variable to some other directory.
35 | 
36 | For example, on a Unix system:
37 | 
38 | ```
39 | > go run hello.go
40 | warning: GOPATH set to GOROOT (/home/username/go) has no effect
41 | Hello, world
42 | > GOPATH=/home/username/gopath
43 | > export GOPATH
44 | > go run hello.go
45 | Hello, world
46 | ```
47 | 
48 | ## Troubleshooting
49 | ##### The ` go build ` command doesn't do anything!
50 | The ` go build ` command will only produce a binary; if you run go build in a package directory, it will build the package normally (and report any compile errors), but it will not install it.  For that, you use ` go install `.  If you think you're building a binary and none is produced, make sure you are in package ` main ` and that you do not have GOBIN set.
51 | 
52 | ##### Why does ` go get ` report ` "Fetching https://runtime/cgo?go-get=1" `?
53 | If you have a source distribution, make sure that your packages are up-to-date.  Also double check the environment above.
54 | 
55 | ##### When cross compiling, I get ` "runtime/extern.go:135: undefined: theGoos" `
56 | Read [WindowsCrossCompiling](WindowsCrossCompiling) for some helpful scripts.  You can also use the ` --no-clean ` argument when you're building the cross-compile toolchain via ` make.bash `.
57 | 
58 | ##### Why does ` go get ` work for some packages and report ` permission denied ` in ` $GOROOT ` for some others (with GOPATH set properly)?
59 | If you at any point installed the package in ` GOROOT ` (either by having no ` GOPATH ` set or by including ` GOROOT ` itself in ` GOPATH `) then there might still be a directory in ` $GOROOT ` (which is always checked first) that is overriding your ` GOPATH `.  To verify, run ` go list -f {{.Dir}} importpath ` and if it reports a directory under ` $GOPATH ` try deleting that first.
60 | 
61 | ### Still need help?
62 | Visit us on IRC or ask on the mailing list.  You will want to provide the output of the following commands, in addition to any errors you are getting:
63 | 
64 | #### Linux/darwin
65 | 
66 | ```
67 | go version
68 | go env
69 | env | grep GO
70 | ```
71 | 
72 | #### Windows
73 | 
74 | ```
75 | go version
76 | go env
77 | set | findstr GO
78 | ```
79 | 


--------------------------------------------------------------------------------
/InterfaceSlice.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: InterfaceSlice
 3 | ---
 4 | 
 5 | ## Introduction
 6 | 
 7 | Given that you can assign a variable of any type to an ` interface{} `, often people will try code like the following.
 8 | ```go
 9 | var dataSlice []int = foo()
10 | var interfaceSlice []interface{} = dataSlice
11 | ```
12 | This gets the error
13 | ```
14 | cannot use dataSlice (type []int) as type []interface { } in assignment
15 | ```
16 | 
17 | The question then, "Why can't I assign any slice to an ` []interface{} `, when I can assign any type to an ` interface{} `?"
18 | 
19 | ### Why?
20 | 
21 | There are two main reasons for this.
22 | 
23 | The first is that a variable with type ` []interface{} ` is not an interface! It is a slice whose element type happens to be ` interface{} `. But even given this, one might say that the meaning is clear.
24 | 
25 | Well, is it? A variable with type ` []interface{} ` has a specific memory layout, known at compile time.
26 | 
27 | Each ` interface{} ` takes up two words (one word for the type of what is contained, the other word for either the contained data or a pointer to it). As a consequence, a slice with length N and with type ` []interface{} ` is backed by a chunk of data that is N\*2 words long.
28 | 
29 | This is different than the chunk of data backing a slice with type ` []MyType ` and the same length. Its chunk of data will be N\*sizeof(MyType) words long.
30 | 
31 | The result is that you cannot quickly assign something of type ` []MyType ` to something of type ` []interface{} `; the data behind them just look different.
32 | 
33 | ### What can I do instead?
34 | 
35 | It depends on what you wanted to do in the first place.
36 | 
37 | If you want a container for an arbitrary array type, and you plan on changing back to the original type before doing any indexing operations, you can just use an ` interface{} `. The code will be generic (if not compile-time type-safe) and fast.
38 | 
39 | If you really want a ` []interface{} ` because you'll be doing indexing before converting back, or you are using a particular interface type and you want to use its methods, you will have to make a copy of the slice.
40 | ```go
41 | var dataSlice []int = foo()
42 | var interfaceSlice []interface{} = make([]interface{}, len(dataSlice))
43 | for i, d := range dataSlice {
44 | 	interfaceSlice[i] = d
45 | }
46 | ```
47 | 


--------------------------------------------------------------------------------
/InvalidFlag.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: InvalidFlag
 3 | ---
 4 | 
 5 |     invalid flag in #cgo CFLAGS
 6 | 
 7 | This page describes the background for build errors like `invalid flag in #cgo CFLAGS` and what you can do about them.
 8 | 
 9 | [CVE-2018-6574](https://nvd.nist.gov/vuln/detail/CVE-2018-6574) described a potential security violation in the go tool: running `go get` downloads and builds Go code from the Internet, Go code that uses cgo can specify options to pass to the compiler, so careful use of `-fplugin` can cause `go get` to execute arbitrary code.  While it is difficult to block every possible way that the compiler might be attacked, we have chosen to block the obvious ones.
10 | 
11 | As described at [issue 23672](https://go.dev/issue/23672), this is done by using a safelist of compiler/linker options that are permitted during `go get`, `go build`, and friends.  When cgo code tries to use to pass an option that is not on the safelist, the go tool will report an error `invalid flag in #cgo CFLAGS` (or `#cgo LDFLAGS`, `pkg-config --cflags`, `pkg-config --ldflags`, and so forth).
12 | 
13 | This safelist is new in releases 1.8.7, 1.9.4, and 1.10, and all subsequent releases.
14 | 
15 | ## What can I do?
16 | 
17 | If this happens to you, and the option is benign, you should do two things:
18 | 1. Set the environment variable `CGO_CFLAGS_ALLOW` (or `CGO_LDFLAGS_ALLOW`, `CGO_CXXFLAGS_ALLOW`, and so forth) to a [regexp](https://pkg.go.dev/regexp/) that matches the option.
19 | 2. [File a bug](https://go.dev/issue/new) requesting that the option be added to the safelist.  Be sure to include the complete error message and, if possible, a description of the code you are building.
20 | 
21 | ## Why not use an unsafe list?
22 | 
23 | Because if some new unsafe option is added to a compiler, all existing Go releases will become immediately vulnerable.
24 | 
25 | ## Why not get a complete list of compiler options and safelist all of them?
26 | 
27 | Because there are hundreds of options, and there is no clear way to get a complete list.  Many compiler and linker options are target dependent, and thus only reported on specific platforms or in specific configurations.  The documentation is known to be incomplete.
28 | 


--------------------------------------------------------------------------------
/Iota.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Iota
 3 | ---
 4 | 
 5 | ## Summary
 6 | 
 7 | Go's ` iota ` identifier is used in ` const ` declarations to simplify definitions of incrementing numbers. Because it can be used in expressions, it provides a generality beyond that of simple enumerations.
 8 | 
 9 | The value of iota is reset to 0 whenever the reserved word ` const ` appears in the source (i.e. each const block) and incremented by one after each [ConstSpec](https://go.dev/ref/spec#ConstSpec) e.g. each Line.  This can be combined with the constant shorthand (leaving out everything after the constant name) to very concisely define related constants.
10 | 
11 | Iota: https://go.dev/ref/spec#Iota
12 | 
13 | Constant declarations: https://go.dev/ref/spec#Constant_declarations
14 | 
15 | ## Examples
16 | 
17 | The official spec has two great examples:
18 | 
19 | https://go.dev/ref/spec#Iota
20 | 
21 | Here's one from Effective Go:
22 | 
23 | ```
24 | type ByteSize float64
25 | 
26 | const (
27 | 	_           = iota // ignore first value by assigning to blank identifier
28 | 	KB ByteSize = 1 << (10 * iota)
29 | 	MB
30 | 	GB
31 | 	TB
32 | 	PB
33 | 	EB
34 | 	ZB
35 | 	YB
36 | )
37 | ```
38 | 
39 | Weekday enum example - How iota is calculated - From [Learn Go Programming Blog](https://blog.learngoprogramming.com):
40 | 
41 | ![How iota works](https://cdn-images-1.medium.com/max/2000/1*sfAHT3zk-WjxSDRIDMpdaA.gif)
42 | 
43 | ## Articles
44 | 
45 | * [Ultimate Visual Guide to Go Enums and Iota](https://blog.learngoprogramming.com/golang-const-type-enums-iota-bc4befd096d3) _2017-10-09_
46 | 


--------------------------------------------------------------------------------
/LUCI.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: LUCI
 3 | ---
 4 | 
 5 | LUCI is the CI infrastructure for the Go project. The primary post-submit dashboard can be found at https://ci.chromium.org/p/golang.
 6 | 
 7 | ## TryBots
 8 | 
 9 | Voting Commit-Queue+1 asks CQ to run the CL on the TryBots.
10 | 
11 | When the TryBots finish, CQ will reply with results, \
12 | voting either LUCI-TryBot-Result+1 (pass) or LUCI-TryBot-Result-1 (fail). \
13 | Important results (e.g. failures) will also appear as chips at the top \
14 | of the Gerrit page for the CL, under the commit message.
15 | 
16 | ![Where to click to open test results.](https://github.com/golang/go/assets/104030/90193351-abf5-4b04-a9c1-7bd95d5924d0)
17 | 
18 | When you open failed test results for the first time, you will land on the "Overview" tab.
19 | You probably want to change your local config to default to the "Test Results" tab:
20 | 
21 | ![Where to click to change default page on LUCI.](https://github.com/golang/go/assets/104030/9b4272f6-6414-413e-a47f-e4593c428624)
22 | 
23 | Back in Gerrit, more details about what was run are available at the "Checks" tab
24 | on the Gerrit CL page.
25 | 
26 | ![A red arrow pointing to the location of the checks tab on the
27 | Gerrit page for an example CL.](https://github.com/golang/go/assets/1248668/1a11fa8c-14cd-4b97-968c-6c52a8634c51)
28 | 
29 | Every TryBot run includes a default set of the most common builders.
30 | [SlowBots](/wiki/SlowBots) provide additional testing controls.
31 | 
32 | ## Troubleshooting
33 | 
34 | ### "infra failed" / purple failure
35 | 
36 | Builders that fail with "infra failed" have a purple chip rather than green (passed) or red (tests failed). These failures indicate some kind of failure in the CI infrastructure itself. They are unlikely to be due to something in your CL.
37 | 
38 | If you encounter such errors, you can reach out to [golang-dev](https://groups.google.com/g/golang-dev) for help investigating them. You may also try rerunning the build, which may succeed on a subsequent run depending on the cause of the infra failure.
39 | 
40 | ### build details
41 | 
42 | The "Steps & Logs" section on a LUCI build page enumerates steps that were executed. Each step can be expanded to get to its logs, environment variables, and command line arguments. The "get go" step includes the output of `go env` from the Go toolchain used in the build.
43 | 


--------------------------------------------------------------------------------
/LearnConcurrency.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: LearnConcurrency
 3 | ---
 4 | 
 5 | This page links to resources for learning about concurrency in Go.  The items are presented in order, from beginner material to advanced topics.
 6 | 
 7 | ## Beginner
 8 | - Read [Effective Go: Concurrency](https://go.dev/doc/effective_go#concurrency)
 9 | - Watch [Simulating a real-world system in Go](https://www.dotconferences.com/2017/11/sameer-ajmani-simulating-a-real-world-system-in-go)
10 | - Study [The Go Programming Language Specification](https://go.dev/ref/spec), especially
11 |     - [Go statements](https://go.dev/ref/spec#Go_statements)
12 |     - [Channel types](https://go.dev/ref/spec#Channel_types)
13 |     - [Send statements](https://go.dev/ref/spec#Send_statements)
14 |     - [Receive operator](https://go.dev/ref/spec#Receive_operator)
15 |     - [Select statements](https://go.dev/ref/spec#Select_statements)
16 | - Code [A Tour of Go: Concurrency](http://tour.golang.org/concurrency/1)
17 | - Read the [Frequently Asked Questions (FAQ)](https://go.dev/doc/faq), especially
18 |     - [Why build concurrency on the ideas of CSP?](https://go.dev/doc/faq#csp)
19 |     - [Why goroutines instead of threads?](https://go.dev/doc/faq#goroutines)
20 |     - [Why are map operations not defined to be atomic?](https://go.dev/doc/faq#atomic_maps)
21 |     - [What operations are atomic? What about mutexes?](https://go.dev/doc/faq#What_operations_are_atomic_What_about_mutexes)
22 |     - [Why doesn't my program run faster with more CPUs?](https://go.dev/doc/faq#parallel_slow)
23 |     - [How can I control the number of CPUs?](https://go.dev/doc/faq#number_cpus)
24 |     - [What happens with closures running as goroutines?](https://go.dev/doc/faq#closures_and_goroutines)
25 | 
26 | ## Intermediate
27 | - Study [Go by Example](https://gobyexample.com) from [goroutines](https://gobyexample.com/goroutines) through [stateful goroutines](https://gobyexample.com/stateful-goroutines)
28 | - Watch [Go Concurrency Patterns](https://talks.golang.org/2012/concurrency.slide#1)
29 | - Watch [A Practical Guide to Preventing Deadlocks and Leaks in Go](https://www.youtube.com/watch?v=3EW1hZ8DVyw)
30 | - Read [Share Memory By Communicating](https://go.dev/blog/share-memory-by-communicating) and do the [codewalk](https://go.dev/doc/codewalk/sharemem/)
31 | - Read [Go Concurrency Patterns: Timing out, moving on](https://go.dev/blog/go-concurrency-patterns-timing-out-and)
32 | - Watch [Concurrency is not Parallelism](http://talks.golang.org/2012/waza.slide#1)
33 | - Read [Go Concurrency Patterns: Pipelines and Cancellation](https://go.dev/blog/pipelines)
34 | - Read [Rethinking Classical Concurrency Patterns](/wiki/Go-Community-Slides#rethinking-classical-concurrency-patterns)
35 | - Study [Package sync](https://pkg.go.dev/sync/)
36 | - Read [Introducing the Go Race Detector](https://go.dev/blog/race-detector)
37 | - Watch [Go: code that grows with grace](http://talks.golang.org/2012/chat.slide#1)
38 | - Read [Mutexes and Semaphores Demystified](http://www.barrgroup.com/Embedded-Systems/How-To/RTOS-Mutex-Semaphore)
39 | 
40 | ## Advanced
41 | - Watch [Advanced Go Concurrency Patterns](https://go.dev/blog/advanced-go-concurrency-patterns)
42 | - Read [Advanced Go Concurrency Patterns](http://talks.golang.org/2013/advconc.slide#1)
43 | - Read [Go Concurrency Patterns: Context](https://go.dev/blog/context)
44 | - Study [The Go Memory Model](https://go.dev/ref/mem)
45 | - Study [Package atomic](https://pkg.go.dev/sync/atomic/)
46 | - Read [Principles of Designing Go APIs with Channels](https://inconshreveable.com/07-08-2014/principles-of-designing-go-apis-with-channels/)
47 | - Read [Advanced Go Concurrency Primitives](https://encore.dev/blog/advanced-go-concurrency)
48 | - Watch [The Scheduler Saga](https://www.youtube.com/watch?v=YHRO5WQGh0k)
49 | - Read [The Scheduler Saga](https://speakerdeck.com/kavya719/the-scheduler-saga)
50 | - Watch [Understanding Channels](https://www.youtube.com/watch?v=KBZlN0izeiY)
51 | - Read [Understanding Channels](https://speakerdeck.com/kavya719/understanding-channels)
52 | 


--------------------------------------------------------------------------------
/LearnErrorHandling.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: LearnErrorHandling
 3 | ---
 4 | 
 5 | This page links to resources about error handling in Go.
 6 | 
 7 | ## Getting Started
 8 | 
 9 | - Read [Effective Go: Errors](https://go.dev/doc/effective_go#errors)
10 | - Code [A Tour of Go: Errors](http://tour.golang.org/methods/19) and do the [exercise](http://tour.golang.org/methods/20)
11 | - Study [The Go Programming Language Specification: Errors](https://go.dev/ref/spec#Errors)
12 | - Study [Package errors](https://pkg.go.dev/errors/)
13 | - Study [func fmt.Errorf](https://pkg.go.dev/fmt/#Errorf)
14 | 
15 | ## Standard Practice
16 | 
17 | - Read [Why does Go not have exceptions?](https://go.dev/doc/faq#exceptions)
18 | - Read [Error handling and Go](https://go.dev/blog/error-handling-and-go)
19 | - Read [Go by Example: Errors](https://gobyexample.com/errors)
20 | - Read [Errors are values](https://go.dev/blog/errors-are-values)
21 | - Read [Working with Errors in Go 1.13](https://go.dev/blog/go1.13-errors)
22 | - Read [golang/go/wiki: Errors](Errors)
23 | 
24 | ## Advanced Topics
25 | 
26 | - Read [Why is my nil error value not equal to nil?](https://go.dev/doc/faq#nil_error)
27 | - Read [Defer, Panic, and Recover](https://go.dev/blog/defer-panic-and-recover)
28 | 


--------------------------------------------------------------------------------
/LearnTesting.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: LearnTesting
 3 | ---
 4 | 
 5 | This page links to resources about testing in Go.
 6 | 
 7 | - Read [How to Write Go Code](https://go.dev/doc/code), especially [Testing](https://go.dev/doc/code#Testing)
 8 | - Study [Package testing](https://pkg.go.dev/testing)
 9 | - Read [Why does Go not have assertions?](https://go.dev/doc/faq#assertions)
10 | - Read [Where is my favorite helper function for testing?](https://go.dev/doc/faq#testing_framework)
11 | - Watch [Testing Techniques](https://talks.golang.org/2014/testing.slide#1)
12 | - Read [TableDrivenTests](TableDrivenTests)
13 | - Read [Using Subtests and Sub-benchmarks](https://go.dev/blog/subtests)
14 | 


--------------------------------------------------------------------------------
/Linux.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Linux
 3 | ---
 4 | 
 5 | ## Go on Linux
 6 | 
 7 | | **Kernel version** | **Architectures**     | **Initial support version** | **Final support version** |
 8 | |:-------------------|:----------------------|:----------------------------|:--------------------------|
 9 | | TBD                | mips, mipsle          | Go 1.8                      |                           |
10 | | TBD                | s390x                 | Go 1.7                      |                           |
11 | | 4.8 or above       | mips64le              | Go 1.6                      |                           |
12 | | TBD                | mips64                | Go 1.6                      |                           |
13 | | TBD                | arm64, ppc64, ppc64le | Go 1.5                      |                           |
14 | | 3.1 or above       | arm                   | Go 1.1 _*_                  |                           |
15 | | 2.6.23 or above    | amd64, 386            | Go 1 _*_                    |                           |
16 | | 5.19 or above      | loong64               | Go 1.19                     |                           |
17 | 
18 | _*_ Go 1.5 or above is recommended.
19 | 


--------------------------------------------------------------------------------
/Livestreams.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Livestreams
 3 | ---
 4 | 
 5 | This table attempts to collect all known regular livestreams centered around Go. Please keep each table sorted alphabetically by name.
 6 | 
 7 | Note that conferences and podcasts have their own wiki pages already, and should not be included here. Similarly, meetups are already collected [here](https://www.meetup.com/topics/go/).
 8 | 
 9 | ### In English
10 | 
11 | |        Name        |    Topic (short)                |       Frequency      | Link | 
12 | |--------------------|---------------------------------|----------------------|------|
13 | | Ashley Jeffs       | Working on Benthos and OSS     | Twice per week       | https://www.youtube.com/c/Jeffail |
14 | | Chewxy             | Hacking around. Usually machine learning / deep neural networks related | Weekly | https://www.youtube.com/chewxy |
15 | | Jordan Lewis       | CockroachDB internals           | Twice per week       | https://www.twitch.tv/large__data__bank |
16 | | Matt Layher        | Linux networking/syscalls in Go | Twice per month      | https://www.twitch.tv/mdlayher |
17 | | Matthew Dempsky    | Hacking on the Go compiler      | Three times per week | https://www.twitch.tv/mdempsky |
18 | | Michael Stapelberg | Hacking on OSS projects         | Aiming for 1x/month  | https://www.twitch.tv/stapelberg |
19 | | Travis Jeffery     | Distributed systems and data streaming | Twice a month | https://www.twitch.tv/travisjeffery |
20 | 
21 | ### In Russian
22 | 
23 | |        Name        |    Topic (short)                |       Frequency      | Link | 
24 | |--------------------|---------------------------------|----------------------|------|
25 | | Good reviewer - Bad reviewer | Code review and commentary for open source projects | Weekly | [YouTube](https://www.youtube.com/channel/UC8_A5W8g7UV0pk0uL66iQAQ) |
26 | | Generic Talks | Podcast about Go and systems programming | Weekly | [YouTube](https://www.youtube.com/channel/UCLW_8skJ-sIHXACL7HZqchA) |
27 | 
28 | ### In Chinese
29 | 
30 | |        Name        |    Topic (short)                |       Frequency      | Link | 
31 | |--------------------|---------------------------------|----------------------|------|
32 | | Go 夜读 - TalkGo | Weekly Go Online Meetup | Weekly | [YouTube](https://www.youtube.com/c/talkgo_night), [Bilibili](https://space.bilibili.com/326749661), [GitHub](https://github.com/talkgo/night) |
33 | 
34 | 
35 | 


--------------------------------------------------------------------------------
/LockOSThread.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: LockOSThread
 3 | ---
 4 | 
 5 | ## Introduction
 6 | 
 7 | Some libraries—especially graphical frameworks and libraries like Cocoa, OpenGL, and libSDL—use thread-local state and can require functions to be called only from a specific OS thread, typically the 'main' thread. Go provides the `runtime.LockOSThread` function for this, but it's notoriously difficult to use correctly.
 8 | 
 9 | ## Solutions
10 | 
11 | Russ Cox presented a good solution for this problem in this [thread](https://groups.google.com/d/msg/golang-nuts/IiWZ2hUuLDA/SNKYYZBelsYJ).
12 | 
13 | ```Go
14 | package sdl
15 | 
16 | // Arrange that main.main runs on main thread.
17 | func init() {
18 | 	runtime.LockOSThread()
19 | }
20 | 
21 | // Main runs the main SDL service loop.
22 | // The binary's main.main must call sdl.Main() to run this loop.
23 | // Main does not return. If the binary needs to do other work, it
24 | // must do it in separate goroutines.
25 | func Main() {
26 | 	for f := range mainfunc {
27 | 		f()
28 | 	}
29 | }
30 | 
31 | // queue of work to run in main thread.
32 | var mainfunc = make(chan func())
33 | 
34 | // do runs f on the main thread.
35 | func do(f func()) {
36 | 	done := make(chan bool, 1)
37 | 	mainfunc <- func() {
38 | 		f()
39 | 		done <- true
40 | 	}
41 | 	<-done
42 | }
43 | ```
44 | 
45 | And then other functions you write in package sdl can be like
46 | 
47 | ```Go
48 | func Beep() {
49 | 	do(func() {
50 | 		// whatever must run in main thread
51 | 	})
52 | }
53 | ```
54 | 


--------------------------------------------------------------------------------
/MacOS12BSDThreadRegisterIssue.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: MacOS12BSDThreadRegisterIssue
 3 | ---
 4 | 
 5 | ## Introduction
 6 | 
 7 | If you reached this page because you saw an error message like the following printed by a Go program running on macOS 12 Monterey:
 8 | ```
 9 | fatal error: runtime: bsdthread_register error
10 | 
11 | runtime stack:
12 | runtime.throw(0x20594e0, 0x21)
13 | 	/usr/local/go/src/runtime/panic.go:619 +0x81 fp=0x7ff7bfeff878 sp=0x7ff7bfeff858 pc=0x1029751
14 | runtime.goenvs()
15 | 	/usr/local/go/src/runtime/os_darwin.go:129 +0x83 fp=0x7ff7bfeff8a8 sp=0x7ff7bfeff878 pc=0x10272d3
16 | runtime.schedinit()
17 | 	/usr/local/go/src/runtime/proc.go:496 +0xa4 fp=0x7ff7bfeff900 sp=0x7ff7bfeff8a8 pc=0x102c014
18 | runtime.rt0_go(0x7ff7bfeff930, 0x3, 0x7ff7bfeff930, 0x1000000, 0x3, 0x7ff7bfeffab0, 0x7ff7bfeffabf, 0x7ff7bfeffac3, 0x0, 0x7ff7bfeffacc, ...)
19 | 	/usr/local/go/src/runtime/asm_amd64.s:252 +0x1f4 fp=0x7ff7bfeff908 sp=0x7ff7bfeff900 pc=0x1052c64
20 | ```
21 | then you are running a program built with an old version of Go (Go 1.10 or before). You will need to update your program or rebuild it with a newer version of Go.
22 | 
23 | ## Details
24 | 
25 | Programs built with Go 1.10 or before use a way of issuing system calls that is no longer supported by the kernel on macOS 12 Monterey. In [Go 1.11](https://go.dev/doc/go1.11#runtime) and later, system calls are issued via `libSystem.dylib`, which is supported by the OS.
26 | 
27 | ## What to do
28 | 
29 | If this is a program you downloaded or installed (for example, using Homebrew), you will need to download or install a newer version of it that is built with a newer version of Go.
30 | 
31 | If this is a program you built from source, you will need to rebuild it with a newer version of Go.
32 | 
33 | You might want to check your $PATH and manually clean up `$GOPATH/bin` and other old relevant Go binaries you've installed.
34 | 
35 | If you're trying to compile Go, `go tool dist clean` might help.
36 | 


--------------------------------------------------------------------------------
/MutexOrChannel.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Use a sync.Mutex or a channel?
 3 | ---
 4 | 
 5 | One of Go's mottos is _"Share memory by communicating, don't communicate by sharing memory."_
 6 | 
 7 | That said, Go does provide traditional locking mechanisms in the <a href='https://pkg.go.dev/sync/'>sync package</a>.  Most locking issues can be solved using either channels or traditional locks.
 8 | 
 9 | So which should you use?
10 | 
11 | Use whichever is most expressive and/or most simple.
12 | 
13 | A common Go newbie mistake is to over-use channels and goroutines just because it's possible, and/or because it's fun. Don't be afraid to use a <a href='https://pkg.go.dev/sync/#Mutex'><code>sync.Mutex</code></a> if that fits your problem best. Go is pragmatic in letting you use the tools that solve your problem best and not forcing you into one style of code.
14 | 
15 | As a general guide, though:
16 | 
17 | <table>
18 | <tr><th>Channel<th>Mutex
19 | <tr>
20 | 	<td>passing ownership of data, <br> distributing units of work, <br> communicating async results
21 | 	<td>caches, <br> state
22 | </table>
23 | 
24 | If you ever find your sync.Mutex locking rules are getting too complex, ask yourself whether using channel(s) might be simpler.
25 | 
26 | ## Wait Group
27 | 
28 | Another important synchronisation primitive is sync.WaitGroup. These allow co-operating goroutines to collectively wait for a threshold event before proceeding independently again. This is useful typically in two cases.
29 | 
30 | Firstly, when 'cleaning up', a sync.WaitGroup can be used to ensure that all goroutines - including the main one - wait before all terminating cleanly.
31 | 
32 | The second more general case is of a cyclic algorithm that involves a set of goroutines that all work independently for a while, then all wait on a barrier, before proceeding independently again. This pattern might be repeated many times. Data might be exchanged at the barrier event. This strategy is the basis of [Bulk Synchronous Parallelism](https://en.wikipedia.org/wiki/Bulk_synchronous_parallel) (BSP).
33 | 
34 | Channel communication, mutexes and wait-groups are complementary and can be combined.
35 | 
36 | ## More Info
37 | 
38 |   * Channels in Effective Go: https://go.dev/doc/effective_go#channels
39 |   * The sync package: https://pkg.go.dev/sync/
40 | 


--------------------------------------------------------------------------------
/NetBSD.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Go on NetBSD
 3 | ---
 4 | 
 5 | Go on NetBSD is fairly stable on the architectures below. However, some bugs remain; see the [issue tracker](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3AOS-NetBSD) for details.
 6 | 
 7 | | **Kernel version**    | **Architectures** | **Initial support version** | **Final support version** |
 8 | |:----------------------|:------------------|:----------------------------|:--------------------------|
 9 | | 8.0 or above          | amd64, arm, 386   |                             |                           |
10 | | 7.0 through 7.1       | amd64, arm, 386   | Go 1.3 _*_                  |                           |
11 | | 6.0 through 6.1       | amd64, arm, 386   | Go 1.3 _*_                  | Go 1.9.7                  |
12 | | 5.0 through 5.2 (EOL) | amd64, 386        | Go 1                        | Go 1.2.2                  |
13 | 
14 | _*_ Go 1.5 or above is recommended.
15 | 
16 | Support for the arm64 architecture is a work in progress, see https://go.dev/issue/30824.
17 | 
18 | ## Go packages in pkgsrc
19 | 
20 | [pkgsrc](https://pkgsrc.org/), the NetBSD package collection, contains up-to-date packages for released Go versions. The packages contain the version in the name (e.g. [`lang/go113`](http://pkgsrc.se/lang/go113)) so that multiple versions can be installed in parallel. [`lang/go`](http://pkgsrc.se/lang/go) is a meta-package that always depends on the default go version.
21 | 
22 | Note that the `go` binary name is also installed with a version suffix. Install the [`pkgtools/pkg_alternatives`](http://pkgsrc.se/pkgtools/pkg_alternatives) package to get a `go` command symlink in your PATH.
23 | 
24 | There are a number of packages for software written in Go in pkgsrc. At the moment, module-based builds are experimental, and packages are built using a GOPATH layout.
25 | 
26 | ## Preparing NetBSD for Go
27 | 
28 |   * install NetBSD (remember to install pkgsrc in the last step)
29 |   * install shells/bash and devel/git (do ` make package-install clean ` in ` /usr/pkgsrc/shells/bash ` and ` /usr/pkgsrc/devel/git `.
30 |     * Using binary packages: ` pkgin install bash git `
31 | 


--------------------------------------------------------------------------------
/NewSpeakers.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Resources for New Speakers
 3 | ---
 4 | 
 5 | Go needs everyone's help.
 6 | We want to see more new speakers with new perspectives at Go conferences,
 7 | especially more women and others underrepresented in the Go community.
 8 | 
 9 | The process of applying to speak at a tech conference can be a bit opaque and confusing 
10 | for first-time speakers.
11 | In general, please remember that, first and foremost,
12 | conferences organizers want to find great talks;
13 | there is no single format or recipe for a great talk;
14 | and you need not be a Go expert to give a great talk.
15 | All that you need to be is excited about sharing something
16 | you've observed or learned about using Go.
17 | 
18 | Here are some good blog posts with tips for writing conference talk proposals:
19 | 
20 | - “[How to write a successful conference proposal](https://dave.cheney.net/2017/02/12/how-to-write-a-successful-conference-proposal)” by Dave Cheney
21 | - “[How to write a successful conference proposal](https://medium.com/@fox/how-to-write-a-successful-conference-proposal-4461509d3e32)” by Karolina Szczur
22 | - “[Is your conference proposal good enough?](http://rckbt.me/2014/01/conference-proposals/)” by Raquel Vélez (rockbot)
23 | - “[What your conference proposal is missing](http://www.sarahmei.com/blog/2014/04/07/what-your-conference-proposal-is-missing/)” by Sarah Mei
24 | 
25 | Elsewhere on the wiki, we maintain a list of [upcoming conferences](Conferences) with links to CFPs.
26 | The same page also lists past conferences with links to talk videos. These conferences welcome speakers of all experience levels and backgrounds!
27 | 
28 | ## Contact Us
29 | 
30 | We, the Go community members listed below,
31 | are happy to discuss or review talk proposals
32 | and answer other questions about the overall speaking process.
33 | Feel free to contact any of us directly.
34 | 
35 | - Russ Cox, rsc@golang.org, [@_rsc](https://twitter.com/_rsc)
36 | - Steve Francia, spf@golang.org, [@spf13](https://twitter.com/spf13)
37 | - William Kennedy, bill@ardanlabs.com, [@goinggodotnet](https://twitter.com/goinggodotnet)
38 | - Cassandra Salisbury, cassandra@golangbridge.org, [@cassandraoid](https://twitter.com/cassandraoid)
39 | - Ashley McNamara, ashmc@microsoft.com, [@ashleymcnamara](https://twitter.com/ashleymcnamara)
40 | - Brian Ketelsen, bjk@microsoft.com, [@bketelsen](https://twitter.com/bketelsen)
41 | - Natalie Pistunovich natalie@golangbridge.org, [@nataliepis](https://twitter.com/nataliepis)
42 | - Erik St. Martin, erikstm@microsoft.com, [@erikstmartin](https://twitter.com/erikstmartin)
43 | - Francesc Campoy, campoy@golang.org, [@francesc](https://twitter.com/francesc)
44 | - Sameer Ajmani, sameer@google.com, [@Sajma](https://twitter.com/Sajma)
45 | - Florin Pățan, florinpatan@gmail.com, [@dlsniper](https://twitter.com/dlsniper)
46 | - Aaron Schlesinger, arschles@gmail.com, [@arschles](https://twitter.com/arschles)
47 | - Paul Jolly, paul@myitcv.io [@_myitcv](https://twitter.com/_myitcv)
48 | - Alexey Palazhchenko, alexey.palazhchenko@gmail.com [@paaleksey](https://twitter.com/paaleksey) (English, Russian)
49 | - Carmen Andoh, candoh@google.com, [@carmatrocity](https://twitter.com/carmatrocity)
50 | 
51 | (Experienced speakers, feel free to add your contact information to the list, or email rsc@golang.org if you don't have wiki edit permission.)
52 | 


--------------------------------------------------------------------------------
/NoPlusOne.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: NoPlusOne
 3 | ---
 4 | 
 5 | When contributing to the Go issue tracker, please **do not** make comments like this:
 6 | 
 7 | > +1
 8 | 
 9 | or
10 | 
11 | > :+1: 
12 | 
13 | or
14 | 
15 | > Me too.
16 | 
17 | or
18 | 
19 | > I too would like to see this issue fixed.
20 | 
21 | or
22 | 
23 | > When is this issue going to be fixed?
24 | 
25 | Such comments do not help fix issues. In fact, they make it harder by cluttering the discussion. The project admins will delete such comments as a matter of procedure (please don't be offended if we delete yours).
26 | 
27 | Instead of commenting, you may [add a :+1: reaction](https://help.github.com/articles/about-discussions-in-issues-and-pull-requests/#reacting-to-ideas-in-issues-and-pull-requests) to the comment or issue.
28 | 
29 | Of course, **please do comment** if your "me too" comment includes information that might help resolve the issue. This includes reports like this:
30 | 
31 | > This issue also affects me on Windows 10 when running all.bat at revision c0ff33.
32 | 
33 | (Although there's no need to make such a comment if an identical comment already exists.)
34 | 
35 | Thanks!
36 | 


--------------------------------------------------------------------------------
/NonEnglish.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: NonEnglish
 3 | ---
 4 | 
 5 | Some of this documentation may be out of date.
 6 | 
 7 | ## Belarusian - Беларуская
 8 | 
 9 |   * [faq-be](http://www.designcontest.com/show/faq-be) - Frequently Asked Questions.
10 | 
11 | ## Brazilian Portuguese - Português brasileiro
12 | 
13 |   * [A Tour of Go](https://go-tour-br.appspot.com/)
14 |   * [golangbr.org](http://golangbr.org/) - Go documentation and news.
15 | 
16 | ## Chinese - 中文
17 | 
18 |   * [Go 语言之旅](https://tour.go-zh.org/)
19 |   * [Go 编程语言](https://go-zh.org/) - Chinese Translation of tip.golang.org
20 |   * [Effective Go and (old) Tutorial (Deprecated)](http://code.google.com/p/ac-me/downloads/detail?name=fango.pdf)
21 | 
22 | ## Czech - Čeština
23 | 
24 |   * [Pravidla reflexe](http://www.abclinuxu.cz/clanky/google-go-pravidla-reflexe) - a translation of [The Laws of Reflection](https://go.dev/blog/2011/09/laws-of-reflection.html).
25 | 
26 | ## French - Français
27 | 
28 |   * [golang-france](http://code.google.com/p/golang-france/) - Go documentation.
29 | 
30 | ## German - Deutsch
31 | 
32 |   * [Deutschsprachige Go Themenseite - German Go resource page](https://github.com/hweidner/golang-de/wiki)
33 |   * [Deutschsprachiges Diskussionsforum - German discussion forum](https://mewe.com/group/5c4b0dcb1c1ea52d0c45b6b0) on [MeWe](https://mewe.com)
34 |     ([Invitation link](https://mewe.com/join/golang-de)) (requires free registration on MeWe.com).
35 | 
36 | ## Indonesia
37 | 
38 |   * [Komunitas Pengguna Go Indonesia](https://golang-id.org)
39 | 
40 | ## Japanese - 日本語
41 | 
42 |   * [A Tour of Go](https://go-tour-jp.appspot.com/)
43 |   * [CodeReviewComments](https://knsh14.github.io/translations/go-codereview-comments/)
44 | 
45 | ## Korean - 한국어
46 | 
47 |   * [A Tour of Go](http://go-tour-kr.appspot.com)
48 |   * [golang-kr wiki](http://github.com/golang-kr/golang-doc/wiki) - Korean Translation of golang.org/doc
49 | 
50 | ## Russian - русский язык
51 | 
52 |   * [Effective Go](https://github.com/Konstantin8105/Effective_Go_RU/blob/master/README.md)
53 |   * [Contribution Guide](https://github.com/Konstantin8105/Contribution_Guide_RU)
54 | 
55 | ## Spanish - español
56 |   * [Video course: Go Course from 0 to 100](https://www.youtube.com/watch?v=7SIIyt5-XK0&list=PLl_hIu4u7P64MEJpR3eVwQ1l_FtJq4a5g)
57 |   * [Workshop video: Creating a wiki with Go](https://www.youtube.com/watch?v=0fYb43gIl6I&list=PLfHn_OMWQAHDNxoA3BRWs5NHcstZMAY_B)
58 |   * [Sitio web: Go con ejemplos](http://goconejemplos.com/)
59 |   * [Apuntes: Aprender de Go desde Cero](https://apuntes.de/golang/)
60 | 
61 | ## Thai - ไทย
62 | 
63 |   * [A Tour of Go](https://go-tour-th.appspot.com)
64 | 
65 | ## Turkish - Türkçe
66 | 
67 |   * [A Tour of Go](https://go-tour-turkish.appspot.com)
68 | 
69 | ## Vietnamese - Tiếng Việt
70 | 
71 |  * [A Tour of Go](http://go-tour-vi.appspot.com/)
72 | 
73 | ## Uzbek — Ўзбекча
74 | 
75 |  * [A Tour of Go](http://go-tour-uz.appspot.com/)
76 | 


--------------------------------------------------------------------------------
/OpenBSD.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Go on OpenBSD
 3 | ---
 4 | 
 5 | Go is available within the OpenBSD ports tree collection since OpenBSD 5.2.  It is marked as i386- and amd64- only.  See [`ports/lang/go`](http://ports.su/lang/go) for details.
 6 | 
 7 | | **OpenBSD release** | **Go in ports**     |
 8 | |:--------------------|:--------------------|
 9 | | 6.8 (Oct 18, 2020)  | go-1.15.2           |
10 | | 6.7 (May 19, 2020)  | go-1.13.9           |
11 | | 6.6 (Oct 17, 2019)  | go-1.13.1           |
12 | | 6.5 (Apr 4, 2019)   | go-1.12.1           |
13 | | 6.4 (Oct 18, 2018)  | go-1.11             |
14 | | 6.3 (Apr 2, 2018)   | go-1.10             |
15 | | 6.2 (Oct 9, 2017)   | go-1.9              |
16 | | 6.1 (Apr 11, 2017)  | go-1.8              |
17 | | 6.0 (Sep 1, 2016)   | go-1.6.3            |
18 | | 5.9 (Mar 29, 2016)  | go-1.5.4            |
19 | | 5.8 (Oct 18, 2015)  | go-1.4.2            |
20 | | 5.7 (May 1, 2015)   | go-1.4.1            |
21 | | 5.6 (Nov 1, 2014)   | go-1.3p0            |
22 | 
23 | ## Building from source
24 | 
25 | | **Kernel version** | **Architectures** | **Initial support version** | **Final support version** |
26 | |:-------------------|:------------------|:----------------------------|:--------------------------|
27 | | 6.4                | amd64, arm, 386   | Go 1.11                     |                           |
28 | | 6.2 through 6.3    | amd64, arm, 386   | Go 1.9                      | Go 1.15.x                 |
29 | | 6.1                | amd64, arm, 386   | Go 1.8                      | Go 1.10.8                 |
30 | | 6.0                | amd64, 386        | Go 1.4.1 _*_                | Go 1.10.8                 |
31 | | 6.0                | arm               | Go 1.5                      | Go 1.10.8                 |
32 | | 5.9                | amd64, 386        | Go 1.4.1 _*_                | Go 1.8.7                  |
33 | | 5.9                | arm               | Go 1.5                      | Go 1.8.7                  |
34 | | 5.6 through 5.8    | amd64, 386        | Go 1.4.1 _*_                | Go 1.7.6                  |
35 | | 5.5                | amd64, 386        | Go 1.3 _*_                  | Go 1.7.6                  |
36 | | 5.0 through 5.4    | amd64, 386        | Go 1                        | Go 1.2.2                  |
37 | 
38 | _*_ Go 1.5 or above is recommended.
39 | 
40 | ## Longterm support
41 | 
42 | Go aims to support the two most recent OpenBSD releases, because OpenBSD officially supports only the two most recent releases, and makes a best-effort attempt to maintain ABI support in consecutive releases.
43 | 
44 | ## ulimits (` /etc/login.conf `)
45 | 
46 | Edit `/etc/login.conf` so that the staff class has the proper
47 | settings. The following is a working example of the staff class:
48 | ```
49 | staff:\
50 |        :datasize-cur=infinity:\
51 |        :datasize-max=infinity:\
52 |        :datasize=infinity:\
53 |        :openfiles-cur=4096:\
54 |        :maxproc-max=512:\
55 |        :maxproc-cur=512:\
56 |        :ignorenologin:\
57 |        :requirehome@:\
58 |        :tc=default:
59 | ```
60 | 
61 | If the database file `/etc/login.conf.db` exists, you need to rebuild it with:
62 | ```
63 | # cap_mkdb /etc/login.conf
64 | ```
65 | 
66 | Ensure that the user you intend to build Go with is in the `staff` login class:
67 | ```
68 | # usermod -L staff your_username_here
69 | ```
70 | 


--------------------------------------------------------------------------------
/PGO-Tools.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: PGO Tools
 3 | ---
 4 | 
 5 | [Profile-guided optimization](https://go.dev/doc/pgo) (PGO) in the Go toolchain uses CPU pprof profiles as the PGO profile format. Though pprof is a widely-used format across many tools, Go's PGO imposes [specific requirements](https://go.dev/doc/pgo#alternative-sources) on the contents of profiles, which many tools across the ecosystem may not be compatible with.
 6 | 
 7 | This (non-exhaustive) page lists tools for collecting and working with profiles that are known to be compatible with PGO.
 8 | 
 9 | # Collecting profiles
10 | 
11 | * [`runtime/pprof`](https://pkg.go.dev/runtime/pprof), [`net/http/pprof`](https://pkg.go.dev/net/http/pprof): The Go standard library profiling functionality always provides PGO-compatible profiles.
12 | * [Parca Agent](https://github.com/parca-dev/parca-agent) produces PGO-compatible profiles when paired with a symbolizer that produces metadata that includes function start lines, such as [Polar Signals Cloud](https://www.polarsignals.com/) or [Parca](https://www.parca.dev/) starting at version `v0.19.0`.
13 | 
14 | # Working with profiles
15 | 
16 | * `go tool pprof`/[standalone `pprof` CLI](https://github.com/google/pprof), [`github.com/google/pprof/profile`](https://pkg.go.dev/github.com/google/pprof/profile): The official `pprof` CLI and Go packages can perform various operations on profiles (filtering, merging multiple profiles, etc). These tools/packages generally leave metadata (e.g., symbolization, function start lines) intact across operations. Thus given a PGO-compatible input, they should produce a PGO-compatible output.
17 | * [Parca](https://www.parca.dev/) and [Polar Signals Cloud](https://www.polarsignals.com/) provide various mechanisms to query and filter profiling data and download any query as a pprof file that will contain function start line metadata to be PGO-compatible.


--------------------------------------------------------------------------------
/PanicAndRecover.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: PanicAndRecover
 3 | ---
 4 | 
 5 | Table of Contents
 6 | =================
 7 | 
 8 | + [Panic](#panic)
 9 | + [Usage in a Package](#usage-in-a-package)
10 | + [References](#references)
11 | 
12 | ## Panic
13 | 
14 | The `panic` and `recover` functions behave similarly to exceptions and try/catch in some other languages in that a `panic` causes the program stack to begin unwinding and `recover` can stop it. Deferred functions are still executed as the stack unwinds. If `recover` is called inside such a deferred function, the stack stops unwinding and `recover` returns the value (as an `interface{}`) that was passed to `panic`. The runtime will also panic in extraordinary circumstances, such as indexing an array or slice out-of-bounds.  If a `panic` causes the stack to unwind outside of any executing goroutine (e.g. `main` or the top-level function given to `go` fail to recover from it), the program exits with a stack trace of all executing goroutines. A `panic` cannot be `recover`ed by a different goroutine.
15 | 
16 | ## Usage in a Package
17 | 
18 | By convention, no explicit `panic()` should be allowed to cross a package boundary. Indicating error conditions to callers should be done by returning error value. Within a package, however, especially if there are deeply nested calls to non-exported functions, it can be useful (and improve readability) to use panic to indicate error conditions which should be translated into error for the calling function. Below is an admittedly contrived example of a way in which a nested function and an exported function may interact via this panic-on-error relationship.
19 | 
20 | ```go
21 | // A ParseError indicates an error in converting a word into an integer.
22 | type ParseError struct {
23 | 	Index int    // The index into the space-separated list of words.
24 | 	Word  string // The word that generated the parse error.
25 | 	Error error  // The raw error that precipitated this error, if any.
26 | }
27 | 
28 | // String returns a human-readable error message.
29 | func (e *ParseError) String() string {
30 | 	return fmt.Sprintf("pkg: error parsing %q as int", e.Word)
31 | }
32 | 
33 | // Parse parses the space-separated words in input as integers.
34 | func Parse(input string) (numbers []int, err error) {
35 | 	defer func() {
36 | 		if r := recover(); r != nil {
37 | 			var ok bool
38 | 			err, ok = r.(error)
39 | 			if !ok {
40 | 				err = fmt.Errorf("pkg: %v", r)
41 | 			}
42 | 		}
43 | 	}()
44 | 
45 | 	fields := strings.Fields(input)
46 | 	numbers = fields2numbers(fields)
47 | 	return
48 | }
49 | 
50 | func fields2numbers(fields []string) (numbers []int) {
51 | 	if len(fields) == 0 {
52 | 		panic("no words to parse")
53 | 	}
54 | 	for idx, field := range fields {
55 | 		num, err := strconv.Atoi(field)
56 | 		if err != nil {
57 | 			panic(&ParseError{idx, field, err})
58 | 		}
59 | 		numbers = append(numbers, num)
60 | 	}
61 | 	return
62 | }
63 | ```
64 | 
65 | To demonstrate the behavior, consider the following main function:
66 | ```go
67 | func main() {
68 | 	var examples = []string{
69 | 		"1 2 3 4 5",
70 | 		"100 50 25 12.5 6.25",
71 | 		"2 + 2 = 4",
72 | 		"1st class",
73 | 		"",
74 | 	}
75 | 
76 | 	for _, ex := range examples {
77 | 		fmt.Printf("Parsing %q:\n  ", ex)
78 | 		nums, err := Parse(ex)
79 | 		if err != nil {
80 | 			fmt.Println(err)
81 | 			continue
82 | 		}
83 | 		fmt.Println(nums)
84 | 	}
85 | }
86 | ```
87 | 
88 | ## References
89 | [Defer, Panic and Recover](https://go.dev/blog/defer-panic-and-recover)
90 | 
91 | https://go.dev/ref/spec#Handling_panics
92 | 
93 | https://go.dev/ref/spec#Run_time_panics
94 | 
95 | 


--------------------------------------------------------------------------------
/Podcasts.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Podcasts
 3 | ---
 4 | 
 5 | ## Active podcast shows
 6 | * [Go Time](http://gotime.fm) - Erik St. Martin, Carlisia Campos, Brian Ketelsen, recorded weekly and streamed live at 3PM EST at http://changelog.com/live
 7 | * [go podcast()](https://go.transistor.fm/) - Dominic St-Pierre, recorded bi-weekly, ~15 minutes, topic based.
 8 | * [Cup o' Go](https://cupogo.dev/) - Stay up to date with the Go community in about 15 minutes per week.
 9 | 
10 | ## Inactive podcast shows
11 | * [GolangShow](http://golangshow.com/) – Weekly podcast since June 2015, in English and Russian languages.
12 | * [Go Gab](https://www.briefs.fm/go-gab) - A podcast about everything Go. Episodes are short: about 3 minutes each.
13 | * [GoFr](https://soundcloud.com/arnaud-assad/sets/gofr) – by Arnaud Assad, Sebastien Friess, Thomas Perez, Lucille Tachet in French.
14 | 
15 | 
16 | ## Podcast episodes
17 | A collection of podcast episodes that cover Go programming. Please keep items in reverse chronological order (most recent first)
18 | * [Working in the Go ecosystem - Dot Tech by Form3](https://techpodcast.form3.tech/episodes/ep-6-tech-working-in-the-go-ecosystem-with-bartomiej-klimczak) _2021-02-19_
19 | * [Making an Open Source Go project a full time job - Dot Tech by Form3](https://techpodcast.form3.tech/episodes/ep-2-tech-making-an-open-source-go-project-a-full-time-job-with-ashley-jeffs2) _2020-11-25_
20 | * [How and why you should move to Go - Dot Tech by Form3](https://techpodcast.form3.tech/episodes/ep-1-tech-how-and-why-you-should-move-to-go-with-johan-brandhorst-andy-kuszyk) _2020-11-03_
21 | * [The Go Language - Hipsters #67](https://hipsters.tech/linguagem-go-hipsters-67/) (_in portuguese_) _2017-10-24_
22 | * [The Go Programming Language 2 - Castálio Podcast #87](http://castalio.info/episodio-87-linguagem-de-programacao-go-parte-2.html) (_in portuguese_) _2017-02-13_
23 | * [The Go Programming Language 1 - Castálio Podcast #86](http://castalio.info/episodio-86-linguagem-de-programacao-go-parte-1.html) (_in portuguese_) _2017-02-06_
24 | * [Little chat about Go Lang](https://soundcloud.com/rdshipit/capycast-2-golang) (_in portuguese_) _2016-03-27_
25 | * [Programming in Go with Michael Van Sickle](https://www.dotnetrocks.com/?show=1203) _2015-10-13_
26 | * [Go on the Web](http://thewebplatform.libsyn.com/55-go-on-the-web) _2015-08-05_
27 | * [Fatherhood with Andrew Gerrand](http://beatsryetypes.com/episodes/2015/05/18/episode-16-fatherhood-with-andrew-gerrand.html) _2015-05-15_
28 | * [Talking with Go Developers at GopherCon India 2015](https://soundcloud.com/thenewstackanalysts/show-33-gophercon-india-2015) _2015-04-01_
29 | * [Interview with CC4CS talking about Security in Go](https://go.unicorn.tv/podcasts/interview-with-cc4cs-talking-about-security-in-go) _2015-03-06_
30 | * [Golang Best Practices](https://go.unicorn.tv/podcasts/golang-best-practices) _2014-09-08_
31 | * [An Introduction to the Go Programming Language with Andrew Gerrand](http://hanselminutes.com/416/an-introduction-to-the-go-programming-language-with-andrew-gerrand) _2014-03-28_
32 | * [FLOSS Weekly #284: The Go Language](https://twit.tv/shows/floss-weekly/episodes/284) _2014-02-19_
33 | * [Series: The Go Language - GrokPodcast](http://www.grokpodcast.com/series/a-linguagem-go/) (_in portuguese_) _2013-07-17_
34 | 


--------------------------------------------------------------------------------
/PriorDiscussion.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Prior Discussion
 3 | ---
 4 | 
 5 | ## Background
 6 | 
 7 | This page links to prior discussion on various topics.
 8 | 
 9 | The page complements the [official FAQ](https://go.dev/doc/faq). While the official FAQ contains things which are frequently asked and contains answers, this page contains things that have been repeatedly asked, but maybe not frequently, and only needs to link to one or more previous threads.  Over time, these entries may graduate to entries in the official FAQ.
10 | 
11 | **Editors:** When editing this page, please don't change the titles of sections, as that breaks the #anchors in URLs. You can rearrange, though. Feel free to add entries at will. There is no requirement for code or English review here.
12 | 
13 | ## Asked Questions & Prior Discussion
14 | 
15 | ### Panics on sends or closes of closed channel
16 | 
17 | See https://github.com/golang/go/issues/11344#issuecomment-117862884
18 | 
19 | ### Thread-local, Goroutine-local storage
20 | 
21 | TODO
22 | 
23 | ### Add explicit int-to-bool conversions
24 | 
25 | Rejected, see 
26 | https://github.com/golang/go/issues/9367#issuecomment-143128337
27 | 
28 | ### Add mechanism to silence vet warnings
29 | 
30 | Rejected, see discussion in https://github.com/golang/go/issues/17058
31 | 
32 | ### Add vet warning for unused function arguments
33 | 
34 | Rejected, see https://github.com/golang/go/issues/7892#issuecomment-66094282
35 | 
36 | ### Make go get more verbose / add a progress bar
37 | 
38 | Rejected, see
39 | https://github.com/golang/go/issues/17959
40 | https://github.com/golang/go/issues/18388#issuecomment-268315634
41 | 
42 | ### Shorten error handling / return sugar
43 | 
44 | Rejected, see
45 | https://github.com/golang/go/issues/16225
46 | 
47 | ### Support symlinks in go toolchain / environment variables
48 | 
49 | Rejected, see
50 | https://github.com/golang/go/issues/15507
51 | 
52 | ### Make unused imports/variables a warning, not an error
53 | 
54 | Rejected.
55 | 
56 | ### Add warnings to the Go compiler
57 | 
58 | Experience in large projects has shown that warnings pile up until people ignore all warnings, so warnings only add noise and no value (or are actively harmful in that they hide bugs). See https://go.dev/doc/faq#unused_variables_and_imports 
59 | 
60 | ### Weak references
61 | 
62 | Unlikely to be added. See discussion at https://groups.google.com/forum/#!topic/golang-nuts/PYWxjT2v6ps, and https://groups.google.com/forum/?pli=1#!topic/golang-nuts/MMWXRANh0-g which points out that `sync.Pool` is a specific form of weak reference.
63 | 


--------------------------------------------------------------------------------
/Proposals.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Proposals
3 | ---
4 | 
5 | See <https://github.com/golang/proposal#readme>
6 | 


--------------------------------------------------------------------------------
/ProviderIntegration.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: ProviderIntegration
 3 | ---
 4 | 
 5 | ## Introduction
 6 | 
 7 | A number of Platform-as-a-Service ([PaaS](http://en.wikipedia.org/wiki/Platform_as_a_service)) providers allow you to use Go applications on their clouds.
 8 | 
 9 | ## Details
10 | 
11 | | PaaS | Repository | Quickstart Guide |
12 | |:-----|:-----------|:-----------------|
13 | | [Google App Engine](http://developers.google.com/appengine/) | https://github.com/GoogleCloudPlatform/appengine-plus-go | https://developers.google.com/appengine/training/go-plus-appengine/ |
14 | | [Azure](http://www.azure.com/) | https://github.com/wadewegner/azure-website-go-builder | http://www.wadewegner.com/2015/01/creating-a-go-site-extension-and-resource-template-for-azure/ |
15 | | [IBM BlueMix](http://www.ibm.com/bluemix) |            | http://www.ibm.com/developerworks/cloud/library/cl-bluemix-go-app/ |
16 | | [CloudBees](http://www.cloudbees.com) | https://github.com/CloudBees-community/golang-clickstart |                  |
17 | | [Cloud Foundry](http://www.cloudfoundry.com/) | https://github.com/kr/heroku-buildpack-go | http://catdevrandom.me/blog/2013/05/16/buildpacks-in-cloud-foundry-v2/ |
18 | | [dotCloud](http://www.dotcloud.com) | https://github.com/kencochrane/golang-on-dotcloud |  |
19 | | [AWS Elastic Beanstalk](https://aws.amazon.com/en/elasticbeanstalk/) | https://github.com/sqs/go-elasticbeanstalk |                  |
20 | | [Heroku](http://www.heroku.com) | https://github.com/kr/heroku-buildpack-go | http://mmcgrana.github.com/2012/09/getting-started-with-go-on-heroku.html |
21 | | [OpenShift](http://openshift.redhat.com) | https://github.com/gcmurphy/golang-openshift |                  |
22 | | [Stackato](http://www.activestate.com/stackato) | https://github.com/kr/heroku-buildpack-go | http://docs.stackato.com/user/deploy/languages/go.html |
23 | | [Tsuru](http://www.tsuru.io/) |            | http://docs.tsuru.io/en/latest/apps/quickstart/go.html |
24 | | [Cocaine](http://tech.yandex.com/cocaine/) | http://github.com/cocaine https://github.com/3Hren/cocaine-core https://github.com/3Hren/cocaine-plugins https://github.com/cocaine/cocaine-framework-go          | https://github.com/cocaine/cocaine-vagrant and https://github.com/3Hren/cocaine-core |
25 | | [GE Predix](https://www.predix.io/) | https://github.com/geaviation/goboot-starter | https://www.predix.io/resources/tutorials/journey.html |
26 | | [Tencent Cloud](https://cloud.tencent.com/) | https://github.com/TencentCloud/tencentcloud-sdk-go | https://intl.cloud.tencent.com/document/product/436/30601|
27 | 
28 | 


--------------------------------------------------------------------------------
/Questions.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Asking Questions
 3 | ---
 4 | 
 5 | Unlike many projects, the Go project does not use GitHub Issues for general discussion or asking questions. GitHub Issues are used for tracking bugs and [proposals](https://go.dev/s/proposal-process) only.
 6 | 
 7 | For asking questions, see:
 8 | 
 9 | * [Stack Overflow](https://stackoverflow.com/questions/tagged/go) with questions tagged "go" or "golang"
10 | 
11 | * [The Go Forum](https://forum.golangbridge.org/), a web-based forum
12 | 
13 | * [Gophers Discord](https://discord.gg/golang) "Get live support and talk with other gophers on the Go Discord"
14 | 
15 | * [Gophers Slack](https://gophers.slack.com), use the [invite app](https://invite.slack.golangbridge.org/) for access. The `#general` channel is a good starting point.
16 | 
17 | * [Go Community on Hashnode](https://hashnode.com/n/go) with questions and posts tagged with "go"
18 | 
19 | * [The golang-nuts mailing list](https://groups.google.com/d/forum/golang-nuts)
20 | 
21 | * [Subreddit for Go](https://www.reddit.com/r/golang/)
22 | 
23 | * **IRC** channel #go-nuts on Libera
24 | 
25 | If we closed your issue as a question with a link to this wiki, we apologize. Please ask the question on one of the above forums.
26 | 
27 | Please do not write your question on a wiki page.  Please use one of the above forums.
28 | 


--------------------------------------------------------------------------------
/Quiet-Weeks.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Quiet Weeks
 3 | ---
 4 | 
 5 | Periodically throughout the year, the Go team holds “quiet weeks”, with no important conversations happening, to give people time for focus on deep work. 
 6 | 
 7 | We aim to do about four single weeks per year, toward the middle of each change window and the middle of each freeze. When we do this, we pre-announce the quiet week on golang-dev@ and post a pinned issue on the issue tracker during the quiet week.
 8 | 
 9 | Quiet weeks have two goals:
10 | 
11 | 1. Create time for people to disconnect, take a real break, and recharge, without worrying that they will need to catch up on what they missed when they return.
12 | 
13 | 2. Create time for people who keep working to do [deep work](https://knowledge.wharton.upenn.edu/article/deep-work-the-secret-to-achieving-peak-productivity/), without all the usual interruptions, including online discussions.
14 | 
15 | Quiet weeks can mean vacation. If you're not on vacation, they don't mean not working. Getting work done quietly is great, and we don't want to stop that. We've used an example that if a couple people agree beforehand that the deep work they want to do next week is some kind of collaboration, like meeting to talk through a thorny design doc they are drafting, or pair programming sessions, that's totally fine, as long as that's how they both want to use the week and as long as no one else who would have wanted to be involved will feel like they missed it.
16 | 
17 | It's also definitely fine to file most issues and mail most CLs: we don't want everyone to have to queue up a whole bunch of things to send at the end of the quiet week. On the other hand, if you have an issue or a CL that you think might spark a discussion that people will regret having missed or need to catch up on when they return, then we'd appreciate it if you can hold those and wait to post them until the quiet is over.
18 | 
19 | 


--------------------------------------------------------------------------------
/Range.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Range Clauses
 3 | ---
 4 | 
 5 | Spec: https://go.dev/ref/spec#For_statements
 6 | 
 7 | ## Summary
 8 | 
 9 | A range clause provides a way to iterate over an array, slice, string, map, or channel.
10 | 
11 | ## Example
12 | 
13 | ```go
14 | for k, v := range myMap {
15 | 	log.Printf("key=%v, value=%v", k, v)
16 | }
17 | 
18 | for v := range myChannel {
19 | 	log.Printf("value=%v", v)
20 | }
21 | 
22 | for i, v := range myArray {
23 | 	log.Printf("array value at [%d]=%v", i, v)
24 | }
25 | ```
26 | 
27 | ## Reference
28 | 
29 | If only one value is used on the left of a range expression, it is the 1st value in this table.
30 | 
31 | | Range expression | 1st value | 2nd value (optional) | notes |
32 | |:-----------------|:----------|:---------------------|:------|
33 | | array or slice  a  ` [n]E `, ` *[n]E `, or ` []E `  | index    ` i  int ` |  ` a[i] `       E    |
34 | | string          s  string type          | index    ` i  int ` |   rune  ` int `      | range iterates over Unicode code points, not bytes |
35 | | map             m  ` map[K]V `              | key      ` k  K ` | value  ` m[k] `       V |
36 | | channel         c  chan E               | element  ` e  E ` | _none_               |
37 | 
38 | ## Gotchas
39 | 
40 | When iterating over a slice or map of values, one might try this:
41 | 
42 | ```go
43 | items := make([]map[int]int, 10)
44 | for _, item := range items {
45 | 	item = make(map[int]int, 1) // Oops! item is only a copy of the slice element.
46 | 	item[1] = 2                 // This 'item' will be lost on the next iteration.
47 | }
48 | ```
49 | 
50 | The ` make ` and assignment look like they might work, but the value property of ` range ` (stored here as ` item `) is a _copy_ of the value from ` items `, not a pointer to the value in ` items `. The following will work:
51 | 
52 | ```go
53 | items := make([]map[int]int, 10)
54 | for i := range items {
55 | 	items[i] = make(map[int]int, 1)
56 | 	items[i][1] = 2
57 | }
58 | ```
59 | 


--------------------------------------------------------------------------------
/RateLimiting.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Rate Limiting
 3 | ---
 4 | 
 5 | To limit the rate of operations per unit time, use a [time.Ticker](https://pkg.go.dev/time/#NewTicker).
 6 | This works well for rates up to tens of operations per second.
 7 | For higher rates, prefer a token bucket rate limiter such as [golang.org/x/time/rate.Limiter](https://pkg.go.dev/golang.org/x/time/rate) (also search pkg.go.dev for
 8 | [rate limit](http://pkg.go.dev/search?q=rate+limit)).
 9 | 
10 | ```go
11 | import "time"
12 | 
13 | const rateLimit = time.Second / 10  // 10 calls per second
14 | 
15 | // Client is an interface that calls something with a payload.
16 | type Client interface {
17 |   Call(*Payload)
18 | }
19 | 
20 | // Payload is some payload a Client would send in a call.
21 | type Payload struct {}
22 | 
23 | // RateLimitCall rate limits client calls with the payloads.
24 | func RateLimitCall(client Client, payloads []*Payload) {
25 |   throttle := time.Tick(rateLimit)
26 | 
27 |   for _, payload := range payloads {
28 |     <-throttle  // rate limit our client calls
29 |     go client.Call(payload)
30 |   }
31 | }
32 | ```
33 | 
34 | To allow some bursts, add a buffer to the throttle:
35 | ```go
36 | import "time"
37 | 
38 | const rateLimit = time.Second / 10  // 10 calls per second
39 | 
40 | // Client is an interface that calls something with a payload.
41 | type Client interface {
42 |   Call(*Payload)
43 | }
44 | 
45 | // Payload is some payload a Client would send in a call.
46 | type Payload struct {}
47 | 
48 | // BurstRateLimitCall allows burst rate limiting client calls with the
49 | // payloads.
50 | func BurstRateLimitCall(ctx context.Context, client Client, payloads []*Payload, burstLimit int) {
51 |   throttle := make(chan time.Time, burstLimit)
52 | 
53 |   ctx, cancel := context.WithCancel(ctx)
54 |   defer cancel()
55 | 
56 |   go func() {
57 |     ticker := time.NewTicker(rateLimit)
58 |     defer ticker.Stop()
59 |     for t := range ticker.C {
60 |         select {
61 |         case throttle <- t:
62 |         case <-ctx.Done():
63 |             return // exit goroutine when surrounding function returns
64 |         }
65 |     }
66 |   }()
67 | 
68 |   for _, payload := range payloads {
69 |     <-throttle  // rate limit our client calls
70 |     go client.Call(payload)
71 |   }
72 | }
73 | ```
74 | 
75 | 


--------------------------------------------------------------------------------
/RiskyChanges.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: A guide to risky changes to the standard library and toolchain
 3 | ---
 4 | 
 5 | Please take special care when working on **risky changes**.
 6 | As a reminder:
 7 | 
 8 | A change is risky if it can cause **failures that are hard to diagnose** (for example, changes to
 9 | the runtime, GC, compiler, linker, TLS, other low-level component, or **complex changes that
10 | need soak time under production workloads**), or if it **requires many CLs that are hard to
11 | revert** (for example, large CLs or stacks of CLs).
12 | 
13 | If you plan on working on a change that may be risky, please do the following:
14 | 1. Unless the entire change is absolutely trivial to revert, protect the new code paths with a
15 |    boolean flag, prefixed with `go125`, that can be used to quickly toggle back to the old
16 |    implementation.
17 |    It can be a simple bool constant, for example, `const go125UseEvenBetterLinker = true`.
18 |    Such flags **must be findable** by a simple grep for the string `go125`.
19 |    That way we can find them without missing any, and they can be cleaned up when we get to the
20 |    Go 1.26 cycle.
21 | 2. Consider how you would answer the following questions for your change:
22 |    * How risky is the change you're planning to make?
23 |    * How will you know if it is working as intended?
24 |    * How much production testing does it need for you to be confident it is working as intended?
25 |    * When should the keep/revert decision be made?
26 | 3. Create a tracking issue in the Go 1.25 milestone with a release-blocker label.
27 |    This issue will be used to track progress on the feature and make the final decision for Go 1.25.
28 | 


--------------------------------------------------------------------------------
/SQLDrivers.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: SQL Database Drivers
 3 | ---
 4 | 
 5 | The database/sql and database/sql/driver packages are designed for using databases from Go and implementing database drivers, respectively.
 6 | 
 7 | See the design goals doc:
 8 | 
 9 | > http://golang.org/src/pkg/database/sql/doc.txt
10 | 
11 | ## Drivers
12 | 
13 | Drivers for Go's sql package include:
14 | 
15 |   * **Amazon AWS Athena**: https://github.com/uber/athenadriver
16 |   * **AWS Athena**: https://github.com/segmentio/go-athena
17 |   * **AWS DynamoDB**: https://github.com/btnguyen2k/godynamo
18 |   * **Apache Avatica/Phoenix**: https://github.com/apache/calcite-avatica-go
19 |   * **Apache H2**: https://github.com/jmrobles/h2go
20 |   * **Apache Hive**: https://github.com/sql-machine-learning/gohive
21 |   * **Apache Ignite/GridGain**: https://github.com/amsokol/ignite-go-client
22 |   * **Apache Impala**: https://github.com/bippio/go-impala
23 |   * **Azure Cosmos DB**: https://github.com/btnguyen2k/gocosmos
24 |   * **ClickHouse** (uses [HTTP API](https://clickhouse.tech/docs/en/interfaces/http/)): https://github.com/mailru/go-clickhouse
25 |   * **ClickHouse** (uses [native TCP interface](https://clickhouse.tech/docs/en/interfaces/tcp/)): https://github.com/ClickHouse/clickhouse-go
26 |   * **CockroachDB**: Use any PostgreSQL driver
27 |   * **Couchbase N1QL**: https://github.com/couchbase/go_n1ql
28 |   * **DB2 LUW** (uses cgo): https://github.com/asifjalil/cli
29 |   * **DB2 LUW** and **DB2/Z with DB2-Connect**: https://bitbucket.org/phiggins/db2cli (Last updated 2015-08)
30 |   * **DB2 LUW, z/OS, iSeries and Informix**: https://github.com/ibmdb/go_ibm_db
31 |   * **Databricks**: https://github.com/databricks/databricks-sql-go
32 |   * **DuckDB**: https://github.com/marcboeker/go-duckdb
33 |   * **Exasol**: (pure Go): https://github.com/exasol/exasol-driver-go
34 |   * **Firebird SQL**: https://github.com/nakagami/firebirdsql
35 |   * **Genji** (pure go): https://github.com/genjidb/genji
36 |   * **Google Cloud BigQuery**: https://github.com/solcates/go-sql-bigquery
37 |   * **Google Cloud Spanner**: https://github.com/googleapis/go-sql-spanner
38 |   * **Google Cloud Spanner**: https://github.com/rakyll/go-sql-driver-spanner
39 |   * **MS ADODB**: https://github.com/mattn/go-adodb
40 |   * **MS SQL Server** (pure go): https://github.com/microsoft/go-mssqldb
41 |   * **MS SQL Server** (uses cgo): https://github.com/minus5/gofreetds
42 |   * **MaxCompute**: https://github.com/sql-machine-learning/gomaxcompute
43 |   * **MySQL**: https://github.com/go-sql-driver/mysql/ ` [*] `
44 |   * **MySQL**: https://github.com/go-mysql-org/go-mysql ` [**] ` (also handles replication)
45 |   * **MySQL**: https://github.com/ziutek/mymysql ` [*] `
46 |   * **ODBC**: https://bitbucket.org/miquella/mgodbc (Last updated 2016-02)
47 |   * **ODBC**: https://github.com/alexbrainman/odbc
48 |   * **Oracle** (pure go): https://github.com/sijms/go-ora
49 |   * **Oracle** (uses cgo): https://github.com/godror/godror
50 |   * **Oracle** (uses cgo): https://github.com/mattn/go-oci8
51 |   * **Oracle** (uses cgo): https://gopkg.in/rana/ora.v4
52 |   * **Postgres** (pure Go): https://github.com/jackc/pgx ` [*] `
53 |   * **Postgres** (pure Go): https://github.com/lib/pq ` [*] `
54 |   * **Postgres** (uses cgo): https://github.com/jbarham/gopgsqldriver
55 |   * **Presto**: https://github.com/prestodb/presto-go-client
56 |   * **QL**: https://pkg.go.dev/modernc.org/ql
57 |   * **SAP ASE** (pure go): https://github.com/SAP/go-ase
58 |   * **SAP ASE** (uses cgo): https://github.com/SAP/cgo-ase
59 |   * **SAP HANA** (pure go): https://github.com/SAP/go-hdb
60 |   * **SAP HANA** (uses cgo): https://help.sap.com/viewer/0eec0d68141541d1b07893a39944924e/2.0.03/en-US/0ffbe86c9d9f44338441829c6bee15e6.html
61 |   * **SQL over REST**: https://github.com/adaptant-labs/go-sql-rest-driver
62 |   * **SQLite** (uses cgo): https://github.com/gwenn/gosqlite - Supports SQLite dynamic data typing
63 |   * **SQLite** (uses cgo): https://github.com/mattn/go-sqlite3 ` [*] `
64 |   * **SQLite** (uses cgo): https://github.com/mxk/go-sqlite
65 |   * **SQLite**: (pure go): https://modernc.org/sqlite
66 |   * **SQLite**: (pure go): https://github.com/ncruces/go-sqlite3
67 |   * **SQLite**: (uses cgo): https://github.com/rsc/sqlite
68 |   * **SingleStore**: Use any MySQL driver
69 |   * **Snowflake** (pure Go): https://github.com/snowflakedb/gosnowflake
70 |   * **Sybase ASE** (pure go): https://github.com/thda/tds
71 |   * **Sybase SQL Anywhere**: https://github.com/a-palchikov/sqlago
72 |   * **TiDB**: Use any MySQL driver
73 |   * **Trino**: https://github.com/trinodb/trino-go-client
74 |   * **Vertica**: https://github.com/vertica/vertica-sql-go
75 |   * **Vitess**: https://pkg.go.dev/vitess.io/vitess/go/vt/vitessdriver
76 |   * **YDB** (pure go): https://github.com/ydb-platform/ydb-go-sdk
77 |   * **YQL (Yahoo! Query Language)**: https://github.com/mattn/go-yql
78 | 
79 | Drivers marked with ` [*] ` are both included in and pass the compatibility test suite at https://github.com/bradfitz/go-sql-test.
80 | Drivers marked with ` [**] ` pass the compatibility test suite but are not currently included in it.
81 | 
82 | 


--------------------------------------------------------------------------------
/SettingGOPATH.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Setting GOPATH
 3 | ---
 4 | 
 5 | The `GOPATH` environment variable specifies the location of your workspace. If no `GOPATH` is set, it is assumed to be `$HOME/go` on Unix systems and `%USERPROFILE%\go` on Windows. If you want to use a custom location as your workspace, you can set the `GOPATH` environment variable. This page explains how to set this variable on various platforms.
 6 | 
 7 | - [Unix systems](#unix-systems)
 8 |   * [Go 1.13](#go-113)
 9 |   * [Bash](#bash)
10 |   * [Zsh](#zsh)
11 |   * [fish](#fish)
12 | - [Windows](#windows)
13 |   * [Go 1.13](#go-113-command-line)
14 |   * [Windows 10 (GUI)](#windows-10-gui)
15 |   * [Windows 10 (command line)](#windows-10-command-line)
16 | 
17 | ## Unix systems
18 | 
19 | `GOPATH` can be any directory on your system. In Unix examples, we will set it to `$HOME/go` (the default since Go 1.8). Note that `GOPATH` must not be the same path as your Go installation. Another common setup is to set `GOPATH=$HOME`.
20 | 
21 | ### Go 1.13+
22 | 
23 | ```bash
24 | go env -w GOPATH=$HOME/go
25 | ```
26 | 
27 | ### Bash
28 | 
29 | Edit your `~/.bash_profile` to add the following line:
30 | ```bash
31 | export GOPATH=$HOME/go
32 | ```
33 | 
34 | Save and exit your editor. Then, source your `~/.bash_profile`.
35 | ```bash
36 | source ~/.bash_profile
37 | ```
38 | 
39 | ### Zsh
40 | 
41 | Edit your `~/.zshrc` file to add the following line:
42 | 
43 | ```bash
44 | export GOPATH=$HOME/go
45 | ```
46 | Save and exit your editor. Then, source your `~/.zshrc`.
47 | ```bash
48 | source ~/.zshrc
49 | ```
50 | 
51 | ### fish
52 | 
53 | ```bash
54 | set -x -U GOPATH $HOME/go
55 | ```
56 | 
57 | The `-x` is used to specify that this variable should be exported
58 | and the `-U` makes this a universal variable, available to all sessions and
59 | persistent.
60 | 
61 | ## Windows
62 | 
63 | Your workspace can be located wherever you like,
64 | but we'll use `C:\go-work` in this example.
65 | 
66 | __NOTE:__ `GOPATH` must not be the same path as your Go installation.
67 | 
68 | * Create a folder at `C:\go-work`.
69 | * Right-click on "Start" and click on "Control Panel". Select "System and Security", then click on "System".
70 | * From the menu on the left, select the "Advanced system settings".
71 | * Click the "Environment Variables" button at the bottom.
72 | * Click "New" from the "User variables" section.
73 | * Type `GOPATH` into the "Variable name" field.
74 | * Type `C:\go-work` into the "Variable value" field.
75 | * Click OK.
76 | 
77 | ### Go 1.13+ (command line)
78 | * Open a command prompt (`Win` + `r` then type `cmd`) or a powershell window (`Win` + `i`).
79 | * Type `go env -w GOPATH=c:\go-work`.
80 | 
81 | ### Windows 10 (GUI)
82 | There is a faster way to edit `Environment Variables` via search:
83 | * Left click on "Search" and type `env` or `environment`.
84 | * Select "Edit environment variables for your account".
85 | * ... and follow steps above.
86 | 
87 | ### Windows 10 (command line)
88 | * Open a command prompt (`Win` + `r` then type `cmd`) or a powershell window (`Win` + `i`).
89 | * Type `setx GOPATH %USERPROFILE%\go`. (This will set the `GOPATH` to your `[home folder]\go`, such as `C:\Users\yourusername\go`.)
90 | * Close the command or PowerShell window. (The environment variable is only available for new command or PowerShell windows, not for the current window.)
91 | 


--------------------------------------------------------------------------------
/SignalHandling.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: SignalHandling
 3 | ---
 4 | 
 5 | ## Introduction
 6 | 
 7 | Sometimes an application needs to save internal state or perform some cleanup activity before it exits, or needs to be able to reload a configuration file or write a memory/cpu profile on demand.  In UNIX-like operating systems, signals can accomplish these tasks.
 8 | 
 9 | ## Example
10 | 
11 | The following code demonstrates a program that waits for an interrupt signal and removes a temporary file when it occurs.
12 | 
13 | ```go
14 | package main
15 | 
16 | import (
17 | 	"io/ioutil"
18 | 	"os"
19 | 	"os/signal"
20 | )
21 | 
22 | func main() {
23 | 	f, err := ioutil.TempFile("", "test")
24 | 	if err != nil {
25 | 		panic(err)
26 | 	}
27 | 	defer os.Remove(f.Name())
28 | 	defer f.Close()
29 | 	sig := make(chan os.Signal, 1)
30 | 	signal.Notify(sig, os.Interrupt)
31 | 	<-sig
32 | }
33 | ```
34 | 


--------------------------------------------------------------------------------
/SimultaneousAssignment.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Simultaneous Assignment
 3 | ---
 4 | 
 5 | Simultaneous assignment is useful in many cases to make related assignments in a single statement.  Sometimes they are required, either because only a single statement is available (e.g. in an if statement) or because the values will change after the statement (e.g. in the case of swap).  All values on the right-hand side of the assignment operator are evaluated before the assignment is performed.
 6 | 
 7 | Simultaneous assignment in an if statement can improve readability, especially in test functions:
 8 | ```
 9 | if got, want := someFunction(...), currTest.Expected; got != want {
10 |     t.Errorf("%d. someFunction(...) = %v, want %v", currIdx, got, want)
11 | }
12 | ```
13 | 
14 | Swapping two values is also made simple using simultaneous assignment:
15 | 
16 | ```
17 | i, j = j, i
18 | ```
19 | 
20 | https://go.dev/ref/spec#Assignments
21 | 


--------------------------------------------------------------------------------
/Solaris.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Go on Solaris
 3 | ---
 4 | 
 5 | | **Kernel version** | **Architectures** | **Initial support version** | **Final support version** |
 6 | |:-------------------|:------------------|:----------------------------|:--------------------------|
 7 | | SunOS 5.11         | amd64             | Go 1.3 _*_                  |                           |
 8 | 
 9 | _*_ Go 1.5 or above is recommended.
10 | 


--------------------------------------------------------------------------------
/Spectre.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Spectre
 3 | ---
 4 | 
 5 | ## Overview
 6 | 
 7 | Go 1.15 adds support for enabling code generation adjustments to mitigate the effect of two variants of the Spectre family of CPU vulnerabilities. The compiler and assembler both have a new flag `-spectre` that is given a list of Spectre mitigations to enable, as in `-spectre=index` or `-spectre=index,ret`. The special case `-spectre=all` enables all available mitigations.
 8 | 
 9 | The `index` mitigation can be enabled in the compiler and changes code generation to emit protections against Spectre variant 1 (“bounds check bypass”). The mitigation ensures that the CPU does not access arbitrary memory, by masking the index to zero when speculating incorrectly. This change typically slows down execution by around 5-10%; the exact slowdown depends on the workload.
10 | 
11 | The `ret` mitigation can be enabled in both the compiler and the assembler and changes code generation to emit protections against Spectre variant 2 (“branch target injection”). This mitigation replaces every indirect call instructions with use of a retpoline gadget. This change typically slows down execution by around 10-15%; again, the exact slowdown depends on the workload.
12 | 
13 | ## Applicability
14 | 
15 | At time of writing, we do not use either of these mitigations for Go programs running at Google, nor do we anticipate doing so. They are included in the Go toolchain as a kind of “defense in depth” for users with very special use cases (or significant paranoia).
16 | 
17 | These mitigations would only be necessary when there is a potential Spectre attack against a Go program, which would require all of the following to be true.
18 | First, an attacker must be able to run arbitrary code on the same CPUs as a victim Go program containing a secret.
19 | Second, the attacker must be able to make some kind of HTTP or RPC requests to the victim Go program.
20 | Third, those requests have to trigger a potentially vulnerable code fragment to speculate into attacker-selected behavior. Most commonly this would mean using an arbitrary attacker-provided integer to index a slice or array.
21 | These three conditions are only very rarely all true at the same time.
22 | 
23 | ## Example
24 | 
25 | To build a program with both mitigations (and any future mitigations) enabled in all packages, use:
26 | 
27 | 	go build -gcflags=all=-spectre=all -asmflags=all=-spectre=all program
28 | 
29 | ## Acknowledgements
30 | 
31 | Thanks to Andrea Mambretti _et al_. for sharing their paper (linked below) ahead of publication. And thanks to them, Chandler Carruth, and Paul Turner for helpful discussions.
32 | 
33 | ## References
34 | 
35 | “[Spectre Attacks: Exploiting Speculative Execution](https://spectreattack.com/spectre.pdf)”\
36 | by Paul Kocher _et al_. (The definitive paper.)
37 | 
38 | “[Speculative Buffer Overflows: Attacks and Defenses](https://people.csail.mit.edu/vlk/spectre11.pdf)”\
39 | by Vladimir Kiriansky and Carl Waldspurger.
40 | 
41 | “[Retpoline: a software construct for preventing branch-target-injection](https://support.google.com/faqs/answer/7625886)”\
42 | by Paul Turner.
43 | 
44 | “[A Systematic Evaluation of Transient Execution Attacks and Defenses](https://arxiv.org/abs/1811.05441)”\
45 | by Claudio Canella _et al_. (Good summary of variants.)
46 | 
47 | “[Spectre is here to stay: An analysis of side-channels and speculative execution](https://arxiv.org/abs/1902.05178)”\
48 | by Ross McIlroy _et al_. (These are not going away.)
49 | 
50 | “[Spectre Returns! Speculation Attacks using the Return Stack Buffer](https://www.usenix.org/system/files/conference/woot18/woot18-paper-koruyeh.pdf)”\
51 | by Esmaeil Mohammadian Koruyeh _et al_. (Even return prediction isn't safe.)
52 | 
53 | “[Speculative Load Hardening](https://llvm.org/docs/SpeculativeLoadHardening.html)”\
54 | by Chandler Carruth. (What LLVM does to prevent speculative out-of-bounds access.)
55 | 
56 | “[Bypassing memory safety mechanisms through speculative control flow hijacks](https://arxiv.org/pdf/2003.05503.pdf)”\
57 | by Andrea Mambretti _et al_. (Examination of effects on memory-safe languages.)
58 | 
59 | 


--------------------------------------------------------------------------------
/Spelling.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Spelling
 3 | ---
 4 | 
 5 | This page documents the spelling choices that the Go project has made for English words.
 6 | 
 7 | This page is a statement of policy. Do not edit it without approval/discussion.
 8 | 
 9 | Policy:
10 | 
11 | * American spellings over British spellings
12 | * **iff** means "if and only if" (https://en.wiktionary.org/wiki/iff), but don't use it in public-facing docs (don't use in comments on exported identifiers that would show up in godoc)
13 | * avoid Latin abbreviations in godoc
14 | * use **cancellation** (two ells), not cancelation. See https://go.dev/cl/170060
15 | * use **canceled** (one ell), not cancelled.
16 | * use **canceling** (one ell), not cancelling.
17 | * use **marshaling**, **marshaled** etc (single ell). See https://go.dev/cl/33017
18 | * use **white space**, not whitespace.
19 | 


--------------------------------------------------------------------------------
/Style.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Style
3 | ---
4 | 
5 | See [CodeReviewComments](/wiki/CodeReviewComments),
6 | [TestComments](/wiki/TestComments),[CSSStyleGuide](/wiki/CSSStyleGuide) or [Google's Go Style Guide](https://google.github.io/styleguide/go/).
7 | 


--------------------------------------------------------------------------------
/SuccessStories.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Go success stories from around the web
 3 | ---
 4 | 
 5 |   * [The Way of the Gopher - Making the Switch from Node.js to Golang](https://medium.com/@theflapjack103/the-way-of-the-gopher-6693db15ae1f)
 6 |   * [Moving a team from Scala to Go](http://jimplush.com/talk/2015/12/19/moving-a-team-from-scala-to-golang/)
 7 |   * [400 Days of Go](http://www.philipotoole.com/400-days-of-go/)
 8 |   * [From Python to Go: Migrating our entire API](https://www.repustate.com/blog/migrating-entire-api-go-python/)
 9 |   * [Our Experience with Golang](https://www.scriptrock.com/blog/our-experience-with-golang)
10 |   * [The Reliability of Go](http://andrewwdeane.blogspot.de/2013/05/the-reliability-of-go.html)
11 |   * [Go at TiDB](https://github.com/pingcap/tidb)
12 |   * [A Go Redirection Service](https://blog.dnsimple.com/2013/03/golang-redirector/)
13 |   * [pool.ntp.org DNS server in Go](http://news.ntppool.org/2012/10/new-dns-server.html)
14 |   * [Juju at Canonical](http://www.reddit.com/r/programming/comments/18atce/juju_canonical_109k_lines_of_go_code/)
15 |   * [Go at bitly](http://word.bitly.com/post/29550171827/go-go-gadget)
16 |   * [NSQ: realtime distributed message processing at scale](http://word.bitly.com/post/33232969144/nsq)
17 |   * [CloudFlare blows hole in laws of Web physics with Go and Railgun](http://arstechnica.com/information-technology/2013/02/cloudflare-blows-hole-in-laws-of-web-physics-with-go-and-railgun/)
18 |   * [Why I Like Go](https://gist.github.com/freeformz/4746274)
19 |   * [Why I Program in Go](http://tech.t9i.in/2013/01/why-program-in-go/)
20 |   * [dl.google.com now served by Go](https://groups.google.com/forum/?fromgroups=#!topic/golang-nuts/BNUNbKSypE0)
21 |   * [Google's Go Programming Language Grows Up: Now What?](http://readwrite.com/2012/03/29/googles-go-programming-languag/)
22 |   * [Moving to Go](http://blog.toggl.com/2012/09/moving-to-go/)
23 |   * [Rob Pike: Why Learn Go?](http://www.youtube.com/watch?v=FTl0tl9BGdc)
24 |   * [Why I went from Python to Go (and not node.js)](http://jordanorelli.tumblr.com/post/31533769172/why-i-went-from-python-to-go-and-not-node-js)
25 |   * [Another go at the Next Big Language](http://dave.cheney.net/2012/09/03/another-go-at-the-next-big-language)
26 |   * [@tobi](http://twitter.com/tobi): ["I have now completed two projects in Go. I predict that it's going to be the dominant language for server work."](https://twitter.com/tobi/status/245873677483274240)
27 |   * [@derekcollison](http://twitter.com/derekcollison): ["Prediction: Go will become the dominant language for systems work in IaaS, Orchestration, and PaaS in 24 months."](https://twitter.com/derekcollison/status/245522124666716160)
28 |   * [Will Go be the new go-to programming language?](http://gigaom.com/cloud/will-go-be-the-new-go-to-programming-language/)
29 |   * [Dr. Dobb's: Why Not Go?](http://www.drdobbs.com/open-source/why-not-go/240005062)
30 |   * [Google I/O 2012: Go in production](http://www.youtube.com/watch?v=kKQLhGZVN4A)
31 |   * [Go at Cockroach Labs](https://www.cockroachlabs.com/blog/why-go-was-the-right-choice-for-cockroachdb/), [cockroachdb/cockroach](https://github.com/cockroachdb/cockroach)
32 |   * [Go at Novartis](https://plus.google.com/114945221884326152379/posts/d1SVaqkRyTL)
33 |   * [Go at the BBC](http://www.quora.com/Go-programming-language/Is-Google-Go-ready-for-production-use/answer/Kunal-Anand)
34 |   * [Go at SoundCloud](https://developers.soundcloud.com/blog/go-at-soundcloud)
35 |   * [Go at Moovweb](https://groups.google.com/forum/#!topic/golang-nuts/MeiTNnGhLg8/discussion)
36 |   * [Building StatHat with Go](https://go.dev/blog/2011/12/building-stathat-with-go.html)
37 |   * [Go at CloudFlare](http://blog.cloudflare.com/go-at-cloudflare)
38 |   * [Why you PHP guys should learn Golang](http://www.mikespook.com/2012/08/why-you-php-guys-should-learn-golang/)
39 |   * [I/O BootCamp 2011: Real World Go](http://www.youtube.com/watch?v=7QDVRowyUQA)
40 |   * [Go at Heroku](https://go.dev/blog/2011/04/go-at-heroku.html)
41 |   * [Go at Basecamp](https://signalvnoise.com/posts/3897-go-at-basecamp)
42 |   * [Go at Streetspotr](https://thcyron.de/2015/go-at-streetspotr.html)
43 |   * [Confession From A Go Programer](https://zeta.si/page/Confession-From-A-Go-Programer)
44 |   * [Why we chose Go over C for updating embedded Linux devices](https://mender.io/blog/why-did-we-choose-golang-over-c)
45 |   * [List of Tech Migrations](http://kokizzu.blogspot.com/2016/12/list-of-tech-migrations.html)
46 |   * [Making the move from Scala to Go, and why we’re not going back](https://movio.co/blog/migrate-Scala-to-Go/)
47 |   * [Go + Services = One Goliath Project - Khan Academy's Python Monolith to Go Microservices](https://blog.khanacademy.org/go-services-one-goliath-project/)
48 |   * [Why we switched from Python to Go at Stream](https://getstream.io/blog/switched-python-go/)
49 |   * [A journey from Node to GoLang](https://www.loginradius.com/engineering/blog/a-journey-from-node-to-golang/)
50 |   * [Ready - Steady - Go: A complete IoT platform in Go](https://qbee.io/misc/ready-steady-go-a-complete-iot-platform-in-go/)
51 | 
52 | 
53 | See also [GoUsers](GoUsers).
54 | 
55 | 


--------------------------------------------------------------------------------
/TableDrivenTests.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | title: TableDrivenTests
  3 | ---
  4 | 
  5 | ## Introduction
  6 | Writing good tests is not trivial, but in many situations a lot of ground can be covered with table-driven tests: Each table entry is a complete test case with inputs and expected results, and sometimes with additional information such as a test name to make the test output easily readable.  If you ever find yourself using copy and paste when writing a test, think about whether refactoring into a table-driven test or pulling the copied code out into a helper function might be a better option.
  7 | 
  8 | Given a table of test cases, the actual test simply iterates through all table entries and for each entry performs the necessary tests. The test code is written once and amortized over all table entries, so it makes sense to write a careful test with good error messages.
  9 | 
 10 | Table driven testing is not a tool, package or anything else, it's just a way and perspective to write cleaner tests. 
 11 | 
 12 | ### Example of a table driven test
 13 | 
 14 | Here is a good example from the testing code for the ` fmt ` package ( https://pkg.go.dev/fmt/ ):
 15 | 
 16 | ```go
 17 | var flagtests = []struct {
 18 | 	in  string
 19 | 	out string
 20 | }{
 21 | 	{"%a", "[%a]"},
 22 | 	{"%-a", "[%-a]"},
 23 | 	{"%+a", "[%+a]"},
 24 | 	{"%#a", "[%#a]"},
 25 | 	{"% a", "[% a]"},
 26 | 	{"%0a", "[%0a]"},
 27 | 	{"%1.2a", "[%1.2a]"},
 28 | 	{"%-1.2a", "[%-1.2a]"},
 29 | 	{"%+1.2a", "[%+1.2a]"},
 30 | 	{"%-+1.2a", "[%+-1.2a]"},
 31 | 	{"%-+1.2abc", "[%+-1.2a]bc"},
 32 | 	{"%-1.2abc", "[%-1.2a]bc"},
 33 | }
 34 | func TestFlagParser(t *testing.T) {
 35 | 	var flagprinter flagPrinter
 36 | 	for _, tt := range flagtests {
 37 | 		t.Run(tt.in, func(t *testing.T) {
 38 | 			s := Sprintf(tt.in, &flagprinter)
 39 | 			if s != tt.out {
 40 | 				t.Errorf("got %q, want %q", s, tt.out)
 41 | 			}
 42 | 		})
 43 | 	}
 44 | }
 45 | ```
 46 | 
 47 | Note the detailed error message provided with ` t.Errorf `: its result and expected result are provided; the input is the subtest name. When the test fails it is immediately obvious which test failed and why, even without having to read the test code.
 48 | 
 49 | A ` t.Errorf ` call is not an assertion. The test continues even after an error is logged. For example, when testing something with integer input, it is worth knowing that the function fails for all inputs, or only for odd inputs, or for powers of two.
 50 | 
 51 | ### Using a Map to Store Test Cases
 52 | 
 53 | In the previous example, tests cases were stored in a slice of structs.  They can be stored in a map as well and there are several advantages
 54 | to doing it this way.
 55 | 
 56 | ```go
 57 | tests := map[string]struct {
 58 |   input string
 59 |   result string
 60 | } {
 61 |   "empty string":  {
 62 |     input: "",
 63 |     result: "",
 64 |   },
 65 |   "one character": {
 66 |     input: "x",
 67 |     result: "x",
 68 |   },
 69 |   "one multi byte glyph": {
 70 |     input: "🎉",
 71 |     result: "🎉",
 72 |   },
 73 |   "string with multiple multi-byte glyphs": {
 74 |     input: "🥳🎉🐶",
 75 |     result: "🐶🎉🥳",
 76 |   },
 77 | }
 78 | 
 79 | for name, test := range tests {
 80 |   // test := test // NOTE: uncomment for Go < 1.22, see /doc/faq#closures_and_goroutines
 81 |   t.Run(name, func(t *testing.T) {
 82 |     t.Parallel()
 83 |     if got, expected := reverse(test.input), test.result; got != expected {
 84 |       t.Fatalf("reverse(%q) returned %q; expected %q", test.input, got, expected)
 85 |     }
 86 |   })
 87 | }
 88 | ```
 89 | 
 90 | One advantage of using maps is that the "name" of each test can simply be the map index.
 91 | 
 92 | More importantly, map iteration order isn't specified nor is it even guaranteed to be the same from one iteration to the next.  This ensures that each test is independent of the others and that testing order doesn't impact results.
 93 | 
 94 | ### Parallel Testing
 95 | 
 96 | Parallelizing table tests is simple, but requires precision to avoid bugs.
 97 | Please note closely the three changes below, especially the re-declaration of `test`
 98 | 
 99 | ```go
100 | package main
101 | 
102 | import (
103 | 	"testing"
104 | )
105 | 
106 | func TestTLog(t *testing.T) {
107 | 	t.Parallel() // marks TLog as capable of running in parallel with other tests
108 | 	tests := []struct {
109 | 		name string
110 | 	}{
111 | 		{"test 1"},
112 | 		{"test 2"},
113 | 		{"test 3"},
114 | 		{"test 4"},
115 | 	}
116 | 	for _, test := range tests {
117 |     // test := test // NOTE: uncomment for Go < 1.22, see /doc/faq#closures_and_goroutines
118 | 		t.Run(test.name, func(t *testing.T) {
119 | 			t.Parallel() // marks each test case as capable of running in parallel with each other 
120 | 			t.Log(test.name)
121 | 		})
122 | 	}
123 | }
124 | ```
125 | 
126 | ### References
127 | 
128 |   * https://go.dev/doc/code#Testing
129 |   * https://go.dev/doc/faq#assertions
130 |   * https://go.dev/doc/faq#testing_framework
131 |   * https://pkg.go.dev/testing/
132 | 


--------------------------------------------------------------------------------
/TargetSpecific.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Target-Specific Code
 3 | ---
 4 | 
 5 | Sometimes, for performance or compatibility reasons, custom code needs to be written for specific GOARCH and GOOS targets. This page presents some best practices to adopt in that case. It is a required policy for crypto packages as of April 2019.
 6 | 
 7 | 1. **Minimize code in tagged files.** As much code as possible should build for every target. In particular, <u>the generic Go implementation must build also for targets that have an optimized implementation</u>. This is critical for testing the optimized code against the generic Go, and makes it quicker to notice some build failures. The linker will drop unused code from final binaries.
 8 | 
 9 | 2. **Name files after their tags**, like `poly1305_amd64.go`. Remember that if a file ends in `_$GOARCH.go`, that counts as a build tag. `_noasm.go` is also a good suffix.
10 | 
11 | 3. **No exported functions in tagged files.** Exported functions define the public API and its documentation, which must be the same across all targets. Having exported functions repeated in each target-specific file makes it likely for them to get out of sync. The mid-stack inliner will probably take care of some of the performance cost.
12 | 
13 | 4. **Test all available implementations.** Running `go test` on a target that has an optimized implementation should test both the generic and the optimized code. You can use sub-tests for this. Ideally, benchmarks too.
14 | 
15 | 5. **Write comparative test.** There should be a test which runs the two implementations for random or edge inputs, and compares the results. As [#19109](https://github.com/golang/go/issues/19109) progresses, these should be fuzz tests.
16 | 
17 | Tip: you can test that your code and tests compile for a target easily by running e.g. `GOARCH=arm64 go test -c`.
18 | 
19 | ## Example
20 | 
21 | poly1305.go
22 | 
23 | ```go
24 | package poly1305
25 | 
26 | // Sum generates an authenticator for m using a one-time key and puts the
27 | // 16-byte result into out. Authenticating two different messages with the same
28 | // key allows an attacker to forge messages at will.
29 | func Sum(out *[16]byte, m []byte, key *[32]byte) {
30 | 	sum(out, m, key)
31 | }
32 | 
33 | func sumGeneric(out *[16]byte, m []byte, key *[32]byte) {
34 | 	// ...
35 | }
36 | ```
37 | 
38 | poly1305_amd64.go
39 | 
40 | ```go
41 | //go:build !purego
42 | 
43 | package poly1305
44 | 
45 | //go:noescape
46 | func sum(out *[16]byte, m []byte, key *[32]byte)
47 | ```
48 | 
49 | poly1305_amd64.s
50 | 
51 | ```
52 | //go:build !purego
53 | 
54 | // func sum(out *[16]byte, m []byte, key *[32]byte)
55 | TEXT ·sum(SB), $0-128
56 | 	// ...
57 | ```
58 | 
59 | poly1305_noasm.go
60 | 
61 | ```go
62 | //go:build !amd64 || purego
63 | 
64 | package poly1305
65 | 
66 | func sum(out *[16]byte, m []byte, key *[32]byte) {
67 | 	sumGeneric(out, m, key)
68 | }
69 | ```
70 | 
71 | poly1305_test.go
72 | 
73 | ```go
74 | package poly1305
75 | 
76 | import "testing"
77 | 
78 | func testSum(t *testing.T, sum func(tag *[16]byte, msg []byte, key *[32]byte)) {
79 | 	// ...
80 | }
81 | 
82 | func TestSum(t *testing.T) {
83 | 	t.Run("Generic", func(t *testing.T) { testSum(t, sumGeneric) })
84 | 	t.Run("Native", func(t *testing.T) { testSum(t, sum) })
85 | }
86 | 
87 | // TestSumCompare checks the output of sum against sumGeneric.
88 | func TestSumCompare(t *testing.T) {
89 | 	// ...
90 | }
91 | ```
92 | 
93 | For more complete examples see the [x/crypto/poly1305](https://github.com/golang/crypto/tree/master/poly1305) and [x/crypto/salsa20/salsa](https://github.com/golang/crypto/tree/master/salsa20/salsa) packages.
94 | 


--------------------------------------------------------------------------------
/Timeouts.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Timeouts and Deadlines
 3 | ---
 4 | 
 5 | To abandon synchronous calls that run too long, use the select statement with time.After:
 6 | ```go
 7 | import "time"
 8 | 
 9 | c := make(chan error, 1)
10 | go func() { c <- client.Call("Service.Method", args, &reply) } ()
11 | select {
12 |   case err := <-c:
13 |     // use err and reply
14 |   case <-time.After(timeoutNanoseconds):
15 |     // call timed out
16 | }
17 | ```
18 | 
19 | Note that the channel ` c ` has a buffer size of 1.  If it were an unbuffered channel and the client.Call method took more than ` timeoutNanoseconds `, the channel send would block forever and the goroutine would never be destroyed.
20 | 
21 | ## References
22 | 
23 | time.After: https://pkg.go.dev/time/#After
24 | 
25 | select: https://go.dev/ref/spec#Select_statements
26 | 
27 | blog post: https://go.dev/blog/2010/09/go-concurrency-patterns-timing-out-and.html
28 | 


--------------------------------------------------------------------------------
/Training.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Training
 3 | ---
 4 | 
 5 | Commercial providers of Go training
 6 | 
 7 | ## On-line
 8 | 
 9 | * [Go Mastery](https://qvault.io/go-mastery-course/) - Interactive browser-based coding course focused on teaching Go's quirks and syntax
10 | * [Golang Online Courses](https://classpert.com/go-programming) - A collection of Go online courses from several providers
11 | * [Mastering Go Programming](https://www.packtpub.com/application-development/mastering-go-programming-video) - A comprehensive Go video training course
12 | * [Golang Tutorials - Sathish VJ](http://golangtutorials.blogspot.com/2011/05/table-of-contents.html) - A free online class.
13 | * [Learn Go - Codementor.io](https://www.codementor.io/go) - Beginner level online class.
14 | * [Learning to Program in Go - Chris Hawkes](https://www.youtube.com/playlist?list=PLei96ZX_m9sVSEXWwZi8uwd2vqCpEm4m6) - Free video tutorial for beginner Go programming.
15 | * [Go - Progate.com](https://progate.com/languages/go) - Go fundamentals for absolute beginners.
16 | * [Go Language Programming Practical Basics Tutorial - Sentdex](https://www.youtube.com/playlist?list=PLQVvvaa0QuDeF3hP0wQoSxpkqgRcgxMqX) - Free video tutorial for Go beginners by Sentdex.
17 | * [O'Reilly Go Fundamentals](http://shop.oreilly.com/category/learning-path/go-fundamentals.do) - Video training series.
18 | * [Pluralsight.com](http://www.pluralsight.com/tag/golang) - Offers around 20 classes from beginner to advanced levels.
19 | * [Master Go](https://appliedgo.com/courses/mastergo) - A paid online video course on Go for developers
20 | * [Learn to Create Web Applications using Go](https://www.usegolang.com/) - A paid online video course and book about Web programming with Go
21 | * [Golang tutorial](https://hackr.io/tutorials/learn-golang) - Learn Go from the best online golang tutorials submitted & voted by the golang programming community.
22 | * [Ultimate Go Live Lessons](http://www.informit.com/store/ultimate-go-programming-livelessons-9780134757483) - This is Ardan Labs classroom Go training on video.
23 | * [Go: The Complete Bootcamp Course](https://www.udemy.com/learn-go-the-complete-bootcamp-course-golang/?couponCode=GOWIKI) - Learn to build real-world and idiomatic Go programs with animated video lectures and hands-on exercises
24 | * [Learn Go with Tests](https://quii.gitbook.io/learn-go-with-tests/) -  Free Test driven development (TDD) based learning of Golang. Start writing robust, well-tested systems in Go
25 | 
26 | ## Classroom and In-Person
27 | 
28 | * [Ardan Labs](https://www.ardanlabs.com/) - Offering customized on-site live training classes.
29 | * [Bitfield Consulting](https://bitfieldconsulting.com/go-mentoring) - John Arundel offers remote training and mentoring in Go for individuals and companies.
30 | * [Boss Sauce Creative](https://bosssauce.it/services/training) - Personalized or track-based Go training for teams.
31 | * [Brian Ketelsen](https://www.brianketelsen.com/) - In-person, remote, and online training classes for individuals and companies.
32 | * [DevelopIntelligence: Golang Intro + Advanced](https://www.developintelligence.com/) - Custom in-person and virtual training for corporate clients.
33 | * [Golang At Speed](https://golangatspeed.com) - Generic or personalized Go training. On-site or hosted off-site. Grasp the long-tail of Golang learning.... the gotchas and the quirky idioms.. faster. 
34 | * [Gopher Guides](https://www.gopherguides.com/) - Customized In-person, remote, and online training classes.  Training for Developers by Developers.  Lead Instructors: [Mark Bates](http://www.gopherguides.com/team/mark.bates), [Cory LaNou](http://www.gopherguides.com/team/cory.lanou)
35 | * [Shiju Varghese](https://github.com/shijuvar/gokit/blob/master/training/README.md) - On-site class room training on Go, and consulting on building distributed systems and Microservices with Go, in India.
36 | * [Magesh Kuppan](https://www.linkedin.com/in/tkmagesh) - Classroom & Online training on Go Programming & Building Microservices in Go
37 | * [kkoehler](https://golang.kkoehler.com) - In-Person class trainings for Go in Germany, Austria and Swiss
38 | 


--------------------------------------------------------------------------------
/Ubuntu.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Ubuntu
 3 | ---
 4 | 
 5 | > The Go project's official download page is at [https://go.dev/dl](https://go.dev/dl/).
 6 | >
 7 | > After downloading a binary release suitable for your system, you can install go by following the official installation instructions at [https://go.dev/doc/install](https://go.dev/doc/install#install).
 8 | 
 9 | There are some other options for Debian based systems like Ubuntu. These packages were not created by the Go project, and we don't support them, but they may be useful for you.
10 | 
11 | ## Using PPA
12 | 
13 | If you're using Ubuntu 18.04, 20.04 or 22.04 (amd64, arm64 or armhf), then you can use the [longsleep/golang-backports PPA](https://launchpad.net/~longsleep/+archive/ubuntu/golang-backports) and update to Go 1.22.
14 | 
15 | ```
16 | sudo add-apt-repository ppa:longsleep/golang-backports
17 | sudo apt update
18 | sudo apt install golang-go
19 | ```
20 | 
21 | > **Note that `golang-go` installs latest Go as default Go. If you do not want that, install `golang-1.22` instead and use the binaries from `/usr/lib/go-1.22/bin`.**
22 | 
23 | ## Using snap
24 | 
25 | Using [snaps](https://snapcraft.io/go) also works quite well.
26 | 
27 | ```
28 | sudo snap install --classic go
29 | ```
30 | 
31 | > A restart may or may not be required for the command to be recognized depending on your system.
32 | 


--------------------------------------------------------------------------------
/Well-known-struct-tags.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Well-known struct tags
 3 | ---
 4 | 
 5 | ## Background
 6 | 
 7 | Go offers [struct tags](https://go.dev/ref/spec#Tag) which are discoverable via reflection. These enjoy a wide range of use in the standard library in the JSON/XML and other encoding packages.
 8 | 
 9 | The community welcomed them and has built ORMs, further encodings, flag parsers and much more around them since, especially for these tasks, single-sourcing is beneficial for data structures.
10 | 
11 | ## Problem description
12 | Due to increased usage of Go and thus Go [struct tags](https://go.dev/ref/spec#Tag), clashes become inevitable.
13 | 
14 | ## Solution
15 | The list below is a best effort to document well-known struct tags used by packages which are available to the public.
16 | 
17 | ## Format of the list
18 | * Struct tag as extracted by calling https://pkg.go.dev/reflect#StructTag.Get with this tag as the `key` argument.
19 | * Documentation link of this package using https://pkg.go.dev
20 | 
21 | ### Example entry
22 | Tag | Documentation
23 | ----|-----
24 | xml | https://pkg.go.dev/encoding/xml
25 | 
26 | ### Change Management
27 | List entries can be added by anyone who creates a public package where a new tag is used.
28 | List entries can be removed when the links to the package documentation stops working or the author(s) of that package requests it.
29 | 
30 | ## List of well-known struct tags
31 | Tag          | Documentation
32 | -------------|---------------
33 | asn1         | https://pkg.go.dev/encoding/asn1
34 | bigquery     | https://pkg.go.dev/cloud.google.com/go/bigquery
35 | bson         | https://pkg.go.dev/go.mongodb.org/mongo-driver/bson
36 | cue          | https://pkg.go.dev/cuelang.org/go/cuego
37 | datastore    | https://pkg.go.dev/cloud.google.com/go/datastore
38 | db           | https://github.com/jmoiron/sqlx
39 | dynamodbav   | https://docs.aws.amazon.com/sdk-for-go/api/service/dynamodb/dynamodbattribute/#Marshal
40 | egg          | https://github.com/andrewwphillips/eggql
41 | feature      | https://github.com/nikolaydubina/go-featureprocessing
42 | gorm         | https://pkg.go.dev/github.com/jinzhu/gorm
43 | graphql      | https://github.com/samsarahq/thunder
44 | json         | https://pkg.go.dev/encoding/json
45 | mapstructure | https://pkg.go.dev/github.com/mitchellh/mapstructure
46 | parser       | https://pkg.go.dev/github.com/alecthomas/participle
47 | properties   | https://pkg.go.dev/github.com/magiconair/properties#Properties.Decode
48 | protobuf     | https://github.com/golang/protobuf
49 | reform       | https://pkg.go.dev/gopkg.in/reform.v1
50 | spanner      | https://pkg.go.dev/cloud.google.com/go/spanner
51 | toml         | https://pkg.go.dev/github.com/pelletier/go-toml
52 | url          | https://github.com/google/go-querystring
53 | validate     | https://github.com/go-playground/validator
54 | xml          | https://pkg.go.dev/encoding/xml
55 | yaml         | https://pkg.go.dev/gopkg.in/yaml.v2
56 | 


--------------------------------------------------------------------------------
/Windows.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: Go for Microsoft Windows
 3 | ---
 4 | 
 5 | > The Go project's official download page is at [https://go.dev/dl](https://go.dev/dl/).
 6 | >
 7 | > After downloading a binary release suitable for your system, you can install go by following  the official installation instructions at [https://go.dev/doc/install](https://go.dev/doc/install#install).
 8 | 
 9 | The Windows port is stable and officially supported.
10 | 
11 |   * See the [open Windows issues](https://github.com/golang/go/issues?q=is%3Aopen+is%3Aissue+label%3Aos-windows) on the issue tracker.
12 | 
13 | | **Distributions**                         | **Architectures** | **Initial support version** | **Final support version** |
14 | |:------------------------------------------|:------------------|:----------------------------|:----------|
15 | | Windows 10, Windows Server 2016 or above  | amd64, 386        | Go 1 _*_                    |           |
16 | | Windows 10, Windows Server 2016 or above  | arm64             | Go 1.17                     |           |
17 | | Windows 8, Windows Server 2012            | amd64, 386        | Go 1 _*_                    | Go 1.20   |
18 | | Windows 7, Windows Server 2008R2          | amd64, 386        | Go 1 _*_                    | Go 1.20   |
19 | | Windows Vista, Windows Server 2008        | amd64, 386        | Go 1 _*_                    | Go 1.10.8 |
20 | | Windows XP, Windows Server 2003           | amd64, 386        | Go 1 _*_                    | Go 1.10.8 |
21 | 
22 | _*_ Go 1.5 or above is recommended.
23 | 
24 | 


--------------------------------------------------------------------------------
/WindowsBuild.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: WindowsBuild
 3 | ---
 4 | 
 5 | ## The Automatic (but unsupported) Way: [winstrap](https://github.com/golang/winstrap)
 6 | 
 7 | The winstrap tool is used by the Go project to turn a fresh Windows VM image into a Windows builder. It installs all necessary dependencies. It's sometimes out of date, though, as it's only updated when we need to update the Windows base image for the [Go continuous build](https://build.golang.org/).
 8 | 
 9 | To use winstrap, download the latest version of winstrap.exe from the [winstrap](https://github.com/golang/winstrap) page and run it.
10 | 
11 | It will download some installers to your desktop, which you should run. Just click through; all the defaults are fine.
12 | 
13 | Then it will check out Go and place it in c:\Users\\%USER%\goroot and build it.
14 | 
15 | That's it.
16 | 
17 | Note however that winstrap is not supported. It's considered an internal tool used for occasional setup of new Windows builder images and is not actively maintained until we need it ourselves.
18 | 
19 | ## The Manual Way
20 | 
21 | ### Install MinGW/MSYS
22 | 
23 | Download and save the latest version of the automated MinGW installer executable (` exe `) file from SourceForge.
24 | 
25 | http://sourceforge.net/projects/mingw/files/OldFiles/mingw-get-inst/
26 | 
27 | Open and run the saved automated MinGW installer executable file, which is named ` mingw-get-inst-yyyymmdd.exe `, where ` yyyymmdd ` is the version date stamp. For example, ` mingw-get-inst-20110530.exe `.
28 | 
29 | The MinGW Setup Wizard window will open with the title "Setup - MinGW-Get". Except for the following, accept the setup defaults, unless it's necessary to change them.
30 | 
31 | For Repository Catalogues, check the Download latest repository catalogues button.
32 | 
33 | For Select Components, the MinGW Compiler Suite, the C Compiler box is automatically checked. Scroll down to the bottom of the list and check the MinGW Developer Toolkit box, which includes the MSYS Basic System.
34 | 
35 | For Ready to Install, review and verify the installation settings, which should look similar this:
36 | ```
37 |     Installing:
38 |         mingw-get
39 |         pkginfo
40 |         C Compiler
41 |         MSYS Basic System
42 |         MinGW Developer Toolkit 
43 |     Downloading latest repository catalogues 
44 |     Destination location:
45 |         C:\MinGW 
46 | ```
47 | When the installation settings are correct, Install.
48 | 
49 | The installation loads the package installation catalogues and downloads and installs the files. The installation may take some time, largely depending on the download speed.
50 | 
51 | The MSYS terminal window may be opened by opening and running the ` C:\MinGW\msys\1.0\msys.bat ` batch file.
52 | 
53 | ### Build
54 | 
55 | ```
56 | git clone https://go.googlesource.com/go
57 | cd go\src
58 | all.bat
59 | ```
60 | 
61 | ### 64-bit Notes
62 | 
63 |   1. Ensure you are able to compile a working 32-bit Go first.
64 |   1. Grab the latest zip from http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Automated%20Builds/ and extract it over the MinGW directory, so that for example the .exe files end up in the same location as the 32-bit ones.
65 |   1. Replace ` gcc.exe ` and ` ar.exe ` with their 64-bit counterparts.
66 |   1. Set ` GOARCH=amd64 ` and away you go!
67 | 
68 | 
69 | 


--------------------------------------------------------------------------------
/WindowsCrossCompiling.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | title: Building Windows Go programs on Linux
  3 | ---
  4 | 
  5 | See [here](https://go.dev/doc/install/source#environment) for available `GOOS` and `GOARCH` values.
  6 | 
  7 | ## Go version >= 1.5
  8 | 
  9 | Since Go version 1.5 cross-compiling of pure Go executables has become very easy. Try it out with the code below. More can be found at this blog post by [Dave Cheney][1].
 10 | 
 11 | [1]: http://dave.cheney.net/2015/08/22/cross-compilation-with-go-1-5
 12 | 
 13 | ```go
 14 | $ cat hello.go
 15 | package main
 16 | 
 17 | import "fmt"
 18 | 
 19 | func main() {
 20 |         fmt.Printf("Hello\n")
 21 | }
 22 | $ GOOS=windows GOARCH=386 go build -o hello.exe hello.go
 23 | ```
 24 | 
 25 | In cmd.exe instead of PowerShell:
 26 | 
 27 | ```go
 28 | $ set GOOS=windows
 29 | $ set GOARCH=386
 30 | $ go build -o hello.exe hello.go
 31 | ```
 32 | 
 33 | You can now run `hello.exe` on a Windows machine near you. 
 34 | 
 35 | Note that the first time you run the command above it will
 36 | silently rebuild most of standard library, and for this reason
 37 | will be quite slow. Subsequent builds will be faster due to Go
 38 | command build caching.
 39 | 
 40 | Note also that `cgo` is disabled when cross-compiling, so any file that mentions `import "C"` will be silently ignored (See https://github.com/golang/go/issues/24068).  In order to use cgo, or any of the build modes `c-archive`, `c-shared`, `shared`, `plugin`, you need to have a C cross-compiler.
 41 | 
 42 | 
 43 | ## Older Go version (<1.5)
 44 | 
 45 | I use linux/386, but, I suspect, this procedure will apply to other host platforms as well.
 46 | 
 47 | Preparation (if needed):
 48 | ```sh
 49 | sudo apt-get install gcc
 50 | export go env GOROOT
 51 | ```
 52 | 
 53 | First step is to build host version of go:
 54 | 
 55 | ```sh
 56 | cd $GOROOT/src
 57 | sudo -E GOOS=windows GOARCH=386 PATH=$PATH ./make.bash
 58 | ```
 59 | 
 60 | Next you need to build the rest of go compilers and linkers. I have small program to do that:
 61 | 
 62 | ```sh
 63 | $ cat ~/bin/buildcmd
 64 | #!/bin/sh
 65 | set -e
 66 | for arch in 8 6; do
 67 | 	for cmd in a c g l; do
 68 | 		go tool dist install -v cmd/$arch$cmd
 69 | 	done
 70 | done
 71 | exit 0
 72 | ```
 73 | 
 74 | Last step is to build Windows versions of standard commands and libraries. I have a small script for that too:
 75 | 
 76 | ```sh
 77 | $ cat ~/bin/buildpkg
 78 | #!/bin/sh
 79 | if [ -z "$1" ]; then
 80 | 	echo 'GOOS is not specified' 1>&2
 81 | 	exit 2
 82 | else
 83 | 	export GOOS=$1
 84 | 	if [ "$GOOS" = "windows" ]; then
 85 | 		export CGO_ENABLED=0
 86 | 	fi
 87 | fi
 88 | shift
 89 | if [ -n "$1" ]; then
 90 | 	export GOARCH=$1
 91 | fi
 92 | cd $GOROOT/src
 93 | go tool dist install -v pkg/runtime
 94 | go install -v -a std
 95 | ```
 96 | 
 97 | I run it like that:
 98 | 
 99 | ```sh
100 | $ ~/bin/buildpkg windows 386
101 | ```
102 | 
103 | to build Windows/386 version of Go commands and packages. You can probably see from my script that I exclude building of any cgo related parts &mdash; these will not work for me, since I do not have correspondent gcc cross-compiling tools installed. So I just skip those.
104 | 
105 | Now we're ready to build our Windows executable:
106 | 
107 | ```go
108 | $ cat hello.go
109 | package main
110 | 
111 | import "fmt"
112 | 
113 | func main() {
114 |         fmt.Printf("Hello\n")
115 | }
116 | $ GOOS=windows GOARCH=386 go build -o hello.exe hello.go
117 | ```
118 | 
119 | We just need to find a Windows computer to run our `hello.exe`.
120 | 


--------------------------------------------------------------------------------
/WindowsDLLs.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | title: Calling a Windows DLL
  3 | ---
  4 | 
  5 | Go allows you to call native Windows function in several different ways.
  6 | 
  7 | 1. Dynamically load a DLL, then call a function in it. You can call the function via `SyscallX` (where X is the number of parameters. If the function has fewer parameters than that, for example passing 7 arguments to a function that accepts 9, `Syscall9` will still work, you just need to specify 7 as your second argument to `Syscall9`).
  8 | 
  9 | A sample Go program that calls a Windows DLL function using this method:
 10 | 
 11 | ```go
 12 | package main
 13 | 
 14 | import (
 15 | 	"fmt"
 16 | 	"syscall"
 17 | 	"unsafe"
 18 | )
 19 | 
 20 | func abort(funcname string, err error) {
 21 | 	panic(fmt.Sprintf("%s failed: %v", funcname, err))
 22 | }
 23 | 
 24 | var (
 25 | 	kernel32, _        = syscall.LoadLibrary("kernel32.dll")
 26 | 	getModuleHandle, _ = syscall.GetProcAddress(kernel32, "GetModuleHandleW")
 27 | 
 28 | 	user32, _     = syscall.LoadLibrary("user32.dll")
 29 | 	messageBox, _ = syscall.GetProcAddress(user32, "MessageBoxW")
 30 | )
 31 | 
 32 | const (
 33 | 	MB_OK                = 0x00000000
 34 | 	MB_OKCANCEL          = 0x00000001
 35 | 	MB_ABORTRETRYIGNORE  = 0x00000002
 36 | 	MB_YESNOCANCEL       = 0x00000003
 37 | 	MB_YESNO             = 0x00000004
 38 | 	MB_RETRYCANCEL       = 0x00000005
 39 | 	MB_CANCELTRYCONTINUE = 0x00000006
 40 | 	MB_ICONHAND          = 0x00000010
 41 | 	MB_ICONQUESTION      = 0x00000020
 42 | 	MB_ICONEXCLAMATION   = 0x00000030
 43 | 	MB_ICONASTERISK      = 0x00000040
 44 | 	MB_USERICON          = 0x00000080
 45 | 	MB_ICONWARNING       = MB_ICONEXCLAMATION
 46 | 	MB_ICONERROR         = MB_ICONHAND
 47 | 	MB_ICONINFORMATION   = MB_ICONASTERISK
 48 | 	MB_ICONSTOP          = MB_ICONHAND
 49 | 
 50 | 	MB_DEFBUTTON1 = 0x00000000
 51 | 	MB_DEFBUTTON2 = 0x00000100
 52 | 	MB_DEFBUTTON3 = 0x00000200
 53 | 	MB_DEFBUTTON4 = 0x00000300
 54 | )
 55 | 
 56 | func MessageBox(caption, text string, style uintptr) (result int) {
 57 | 	var nargs uintptr = 4
 58 | 	ret, _, callErr := syscall.Syscall9(uintptr(messageBox),
 59 | 		nargs,
 60 | 		0,
 61 | 		uintptr(unsafe.Pointer(syscall.StringToUTF16Ptr(text))),
 62 | 		uintptr(unsafe.Pointer(syscall.StringToUTF16Ptr(caption))),
 63 | 		style,
 64 | 		0,
 65 | 		0,
 66 | 		0,
 67 | 		0,
 68 | 		0)
 69 | 	if callErr != 0 {
 70 | 		abort("Call MessageBox", callErr)
 71 | 	}
 72 | 	result = int(ret)
 73 | 	return
 74 | }
 75 | 
 76 | func GetModuleHandle() (handle uintptr) {
 77 | 	var nargs uintptr = 0
 78 | 	if ret, _, callErr := syscall.Syscall(uintptr(getModuleHandle), nargs, 0, 0, 0); callErr != 0 {
 79 | 		abort("Call GetModuleHandle", callErr)
 80 | 	} else {
 81 | 		handle = ret
 82 | 	}
 83 | 	return
 84 | }
 85 | 
 86 | func main() {
 87 | 	defer syscall.FreeLibrary(kernel32)
 88 | 	defer syscall.FreeLibrary(user32)
 89 | 
 90 | 	fmt.Printf("Return: %d\n", MessageBox("Done Title", "This test is Done.", MB_YESNOCANCEL))
 91 | }
 92 | 
 93 | func init() {
 94 | 	fmt.Print("Starting Up\n")
 95 | }
 96 | ```
 97 | 
 98 | 
 99 | 2. Using syscall.NewProc instead of syscall.GetProcAddress. These are basically some helper methods over the syscall ones, you saw above, and are available in Windows only: http://golang.org/src/pkg/syscall/dll_windows.go
100 | 
101 | ```go
102 | package main
103 | 
104 | import (
105 | 	"fmt"
106 | 	"syscall"
107 | 	"unsafe"
108 | )
109 | 
110 | func main() {
111 | 	var mod = syscall.NewLazyDLL("user32.dll")
112 | 	var proc = mod.NewProc("MessageBoxW")
113 | 	var MB_YESNOCANCEL = 0x00000003
114 | 
115 | 	ret, _, _ := proc.Call(0,
116 | 		uintptr(unsafe.Pointer(syscall.StringToUTF16Ptr("This test is Done."))),
117 | 		uintptr(unsafe.Pointer(syscall.StringToUTF16Ptr("Done Title"))),
118 | 		uintptr(MB_YESNOCANCEL))
119 | 	fmt.Printf("Return: %d\n", ret)
120 | 
121 | }
122 | ```
123 | 
124 | 3. By "linking" against the library, using the "[cgo](cgo)" method (this way works in Linux and Windows). Example:
125 | 
126 | ```go
127 | import ("C")
128 | ...
129 | C.MessageBoxW(...)
130 | ```
131 | 
132 | See [cgo](cgo) for further details.
133 | 


--------------------------------------------------------------------------------
/X-Repositories.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: X-Repositories
 3 | ---
 4 | 
 5 | The `golang.org/x/...` repositories are part of the Go Project but outside the main Go tree.
 6 | 
 7 | They are developed under looser [compatibility requirements](https://go.dev/doc/go1compat) than the Go core.  In general, they will support the previous two releases and tip.
 8 | 
 9 | These repositories should have no third-party dependencies apart from other golang.org/x/... repositories. The only exceptions are [golang.org/x/tools/gopls](https://pkg.go.dev/golang.org/x/tools/gopls), [golang.org/x/vscode-go](https://go.googlesource.com/vscode-go), and [golang.org/x/pkgsite](https://pkg.go.dev/golang.org/x/pkgsite). If you would like to add a new dependency to an x repository, please [file an issue](https://github.com/golang/go/issues/new) and cc [@rsc](http://github.com/rsc) and [@andybons](https://github.com/andybons).
10 | 
11 | Install them with "go get".
12 | 
13 |   * [[docs](https://pkg.go.dev/golang.org/x/tools)] [[source](https://go.googlesource.com/tools)] ` golang.org/x/tools ` — godoc, vet, cover, and other tools.
14 |   * [[docs](https://pkg.go.dev/golang.org/x/mobile)] [[source](https://go.googlesource.com/mobile)] ` golang.org/x/mobile ` — libraries and build tools for Go on Android.
15 | 
16 |   * [[docs](https://pkg.go.dev/golang.org/x/crypto)] [[source](https://go.googlesource.com/crypto)] ` golang.org/x/crypto ` — additional cryptography packages.
17 |   * [[docs](https://pkg.go.dev/golang.org/x/image)] [[source](https://go.googlesource.com/image)] ` golang.org/x/image ` — additional imaging packages.
18 |   * [[docs](https://pkg.go.dev/golang.org/x/net)] [[source](https://go.googlesource.com/net)] ` golang.org/x/net ` — additional networking packages.
19 |   * [[docs](https://pkg.go.dev/golang.org/x/sys)] [[source](https://go.googlesource.com/sys)] ` golang.org/x/sys ` — for low-level interactions with the operating system.
20 |   * [[docs](https://pkg.go.dev/golang.org/x/text)] [[source](https://go.googlesource.com/text)] ` golang.org/x/text ` — packages for working with text.
21 | 
22 |   * [[docs](https://pkg.go.dev/golang.org/x/blog)] [[source](https://go.googlesource.com/blog)] ` golang.org/x/blog ` — the content and server program for [blog.golang.org](https://go.dev/blog).
23 | 
24 | 
25 |   * [[docs](https://pkg.go.dev/golang.org/x/review)] [[source](https://go.googlesource.com/review)] ` golang.org/x/review ` — tools for code review.
26 |   * [[docs](https://pkg.go.dev/golang.org/x/benchmarks)] [[source](https://go.googlesource.com/benchmarks)] ` golang.org/x/benchmarks `
27 | 
28 |   * [[docs](https://pkg.go.dev/golang.org/x/exp)] [[source](https://go.googlesource.com/exp)] ` golang.org/x/exp ` — experimental code (handle with care).
29 | 
30 | [List of all packages in sub-repositories](https://pkg.go.dev/golang.org/x)
31 | 
32 | 


--------------------------------------------------------------------------------
/codereview.cfg:
--------------------------------------------------------------------------------
1 | issuerepo: golang/go
2 | 


--------------------------------------------------------------------------------
/config/Dockerfile:
--------------------------------------------------------------------------------
 1 | # syntax=docker/dockerfile-upstream:master-labs
 2 | 
 3 | FROM squidfunk/mkdocs-material:latest AS mkdocs_base
 4 | 
 5 | WORKDIR /github/workspace
 6 | RUN set -eux && \
 7 | 	pip install --no-cache-dir -U --pre --compile --verbose pip
 8 | COPY ./config/requirements.txt /github/workspace/config/requirements.txt
 9 | RUN set -eux && \
10 | 	pip install --no-cache-dir -U --pre --compile --verbose --requirement /github/workspace/config/requirements.txt
11 | COPY . .
12 | 
13 | FROM mkdocs_base AS mkdocs_build
14 | RUN set -eux && \
15 | 	mkdocs --verbose build --clean --site-dir /docs --config-file /github/workspace/config/mkdocs.yml
16 | 
17 | FROM mkdocs_base AS mkdocs
18 | ARG MKDOCS_PORT
19 | ENV MKDOCS_PORT=${MKDOCS_PORT:-8000}
20 | EXPOSE $MKDOCS_PORT
21 | CMD ["mkdocs", "--verbose", "serve", "--dev-addr", "localhost:$MKDOCS_PORT", "--livereload", "--config-file", "./config/mkdocs.yml"]
22 | 
23 | FROM scratch AS docs
24 | COPY --link --from=mkdocs_build /docs /docs
25 | 


--------------------------------------------------------------------------------
/config/requirements.txt:
--------------------------------------------------------------------------------
1 | git+https://github.com/mkdocs/mkdocs.git
2 | git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
3 | git+https://github.com/facelessuser/pymdown-extensions.git
4 | git+https://github.com/pygments/pygments.git
5 | git+https://github.com/byrnereese/mkdocs-minify-plugin.git
6 | 


--------------------------------------------------------------------------------
/default.tmpl:
--------------------------------------------------------------------------------
1 | {{define "layout"}}
2 | {{doclayout .}}
3 | {{end}}
4 | 


--------------------------------------------------------------------------------
/gopherbot.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: gopherbot
 3 | ---
 4 | 
 5 | This page outlines all interactive gopherbot functionality. Most of the tasks gopherbot performs do not require human intervention, however it is starting to learn new tricks.
 6 | 
 7 | ## Adding/Removing Labels
 8 | 
 9 | You may add or remove labels by telling gopherbot what you'd like to do.
10 | 
11 | `@gopherbot, please add labels NeedsFix,help wanted and remove label needsinvestigation`
12 | 
13 | The comma after @gopherbot and the `please`, `and`, `add`, and `label[s]` keywords are optional. Adding a label is the default, so you can have the command be much more terse if you wish.
14 | 
15 | `@gopherbot needsfix, help wanted remove needsinvestigation`
16 | 
17 | The above command will achieve the same results as the first command.
18 | 
19 | If you don't wish to remove anything, you can omit the `remove` keyword.
20 | 
21 | `@gopherbot needsfix, help wanted`
22 | 
23 | The above command will add the `NeedsFix` and `help wanted` labels. Notice how labels must be separated by a comma (or semicolon). This is to account for those with spaces in them like `help wanted`. You cannot quote the labels.
24 | 
25 | `@gopherbot needsfix "help wanted"` **← Does not work**
26 | 
27 | Casing also doesn't matter. `needsfix` is equivalent to `NeedsFix`. gopherbot will figure out the right label for you.
28 | 
29 | There are some labels that are not allowed to be added or removed. Those can be seen in the `labelChangeDisallowed` function in the [source](https://github.com/golang/build/blob/master/cmd/gopherbot/gopherbot.go).
30 | 
31 | For more in-depth examples, take a look at the [tests](https://github.com/golang/build/blob/master/cmd/gopherbot/gopherbot_test.go).
32 | 
33 | As always, patches are welcome!
34 | 
35 | ## Backporting issues
36 | 
37 | gopherbot is capable of opening backport issues according to [MinorReleases](/wiki/MinorReleases) in response to comments like the following on the main issue.
38 | 
39 | > @gopherbot please consider this for backport to 1.10, it's a regression.
40 | 
41 | > @gopherbot please open the backport tracking issues. This is a severe compiler bug.
42 | 
43 | The keywords are `@gopherbot`, `backport`, `please` and optionally the release. They can be anywhere in the comment. If no release is mentioned issues are opened for the two past releases. The entire message is quoted in the new issue, so please include a rationale.
44 | 
45 | (Note that currently only the first backport command on an issue is executed. https://go.dev/issues/25574)
46 | 


--------------------------------------------------------------------------------
/gopls-integrator-FAQ.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: gopls-integrator-FAQ
 3 | ---
 4 | 
 5 | ---
 6 | > This page has been subsumed into the [committed markdown](https://github.com/golang/tools/blob/master/gopls/doc/integrating.md) of x/tools repository
 7 | > 
 8 | > Please do not edit this page!
 9 | ---
10 | 
11 | 


--------------------------------------------------------------------------------
/gopls.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: gopls
 3 | ---
 4 | 
 5 | ----
 6 | 
 7 | > This page was [moved to the x/tools repository](https://github.com/golang/tools/blob/master/gopls/README.md).
 8 | > 
 9 | > Please do not edit this page!
10 | ----
11 | 
12 | 


--------------------------------------------------------------------------------
/heapdump15.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: heapdump15
3 | redirect: /wiki/heapdump15-through-heapdump17
4 | ---
5 | 


--------------------------------------------------------------------------------
/images/github-to-gerrit.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/zchee/golang-wiki/314b13b9958964c15a6c2ca8436d8c9266be7648/images/github-to-gerrit.png


--------------------------------------------------------------------------------
/images/performance-monitoring-per-metric-link.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/zchee/golang-wiki/314b13b9958964c15a6c2ca8436d8c9266be7648/images/performance-monitoring-per-metric-link.png


--------------------------------------------------------------------------------
/nav.yaml:
--------------------------------------------------------------------------------
1 | name: Go Wiki
2 | subs:
3 | - name: Other Pages
4 | 


--------------------------------------------------------------------------------