golang: add README.md

Author: jwatson0

runtime/golang/helloworld/README.md

@@ -0,0 +1,155 @@
+
+## Go
+
+### Versions
+
+-   New versions every 6 months, Feb and Aug
+-   Each major Go release is supported until there are two newer major releases (~1 year)
+-   It is intended that programs written to the Go 1 specification will continue to compile and run correctly, unchanged, over the lifetime of that specification. The APIs may grow, acquiring new packages and features, but not in a way that breaks existing Go 1 code. <https://go.dev/doc/go1compat>
+-   go1.25.5 released 2025-12-02
+-   go1.25.0 released 2025-08-12
+-   go1.24.0 released 2025-02-11
+-   go1.23.0 released 2024-08-13 (out of support)
+
+### Considerations
+
+-  Designed to improve programming productivity in an era of multicore, networked machines and large codebases.
+
+-  Designers were primarily motivated by their shared dislike of C++.
+
+-  Go "interfaces" (like static duck typing) are simple and useful
+
+-  Modules seem like an afterthought <https://go.dev/blog/v2-go-modules>
+
+### Tips
+
+-  $GOPATH defaults to $HOME/go
+
+-  Module cache is kept in $GOPATH/pkg/mod, not in source tree
+
+-  Debian install
+
+```
+    download https://go.dev/dl/go1.25.5.linux-amd64.tar.gz
+    sudo tar -C /usr/local -xzf go1.25.5.linux-amd64.tar.gz
+    Add /usr/local/go/bin to PATH
+```
+
+### Basic build/test loop
+
+```
+    go mod init example.com/helloworld
+    go mod tidy  # download deps
+    go build
+    go test
+```
+
+### Third-party packages
+
+-  <https://pkg.go.dev/>
+
+    -  Adding to project
+
+```
+    // add import to source
+    import (
+            "rsc.io/quote"
+    )
+
+    $ go mod tidy
+```
+
+### Native Interoperability
+
+<https://pkg.go.dev/cmd/cgo> <https://dev.to/metal3d/understand-how-to-use-c-libraries-in-go-with-cgo-3dbn> <https://github.com/jbuberel/buildmodeshared>
+
+-  Go uses C code in comments before `import "C"` to include C headers and/or arbitrary C code
+
+```
+    //// these comments are compiled into C code
+    // #cgo LDFLAGS: -luuid
+    //
+    // #include <uuid/uuid.h>
+    // #include <stdio.h>
+    // #include <stdlib.h>
+    //
+    // // create a uuid function in C to return a uuid char*
+    // char* _go_uuid() {
+    //   uuid_t uuid;
+    //   uuid_generate_random(uuid);
+    //   char *str = malloc(37);
+    //   uuid_unparse_lower(uuid, str);
+    //   printf("C code in comment\n");
+    //   return str;
+    // }
+    import "C"
+
+    // uuid generates a UUID using the C shared library.
+    // It returns a Go string.
+    func uuid() string {
+        return C.GoString(C._go_uuid())
+    }
+```
+
+### Websockets example
+
+```
+    import (
+            "fmt"
+            "log"
+            "github.com/gorilla/websocket"
+    )
+
+    func main() {
+            // Dial the WebSocket server
+            var wsURL = "ws://corefx-net-http11.azurewebsites.net/WebSocket/EchoWebSocket.ashx"
+            conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil)
+            if err != nil {
+                    log.Fatal("Dial error:", err)
+            }
+            defer conn.Close()
+
+            fmt.Println("Connected to", wsURL)
+
+            // Send message to server
+            err = conn.WriteMessage(websocket.TextMessage, []byte("Hello Websocket"))
+            if err != nil {
+                    log.Fatal("Write error:", err)
+            }
+
+            // Read response from server
+            _, response, err := conn.ReadMessage()
+            if err != nil {
+                    log.Fatal("Read error:", err)
+            }
+
+            fmt.Printf("Server: %s\n", string(response))
+    }
+```
+
+### Cross-platform compile from linux
+
+<https://rakyll.org/cross-compilation/>
+
+-  If using all go code and no C libraries (i.e. no CGO)
+
+```
+    go tool dist list
+    GOOS=linux GOARCH=amd64 go build -o helloworld_linux
+    GOOS=darwin GOARCH=amd64 go build -o helloworld_darwin
+    GOOS=windows GOARCH=amd64 go build -o helloworld.exe
+```
+
+-  If using C libraries (i.e. with CGO)
+
+```
+    # must have cross-compilers installed
+    GO_ENABLED=1 \
+    CC=x86_64-w64-mingw32-gcc \
+    CXX=x86_64-w64-mingw32-g++ \
+    GOOS=windows GOARCH=amd64 go build -o helloworld.exe
+```
+
+### Introspection
+
+Built-in <https://go.dev/blog/laws-of-reflection>