Limitations: where the seams are

So you’re about to point go2cs at your own Go code. Before you spend an evening on it, here is where it will fail, where it will fight you, and where it will quietly do something a little different from Go – better you hear it from me than from a stack trace. Specific bugs with workarounds live in Known issues. This page is the limits that come with running Go on .NET, plus the rough spots real code hits today.

The short version

Good odds tonight: pure Go that builds with the Go release go2cs tracks and CGO_ENABLED=0, leans mostly on the standard library, and runs on Windows, Linux or macOS. A longer evening: lots of third-party modules, unsafe, assembly fast paths, cgo, or tests that pull in testify.

What won’t make the trip

What converts, but doesn’t behave exactly like Go

cgo

What converts. Without -cgo, a package whose build selects a file with import "C" stops the run with error GO2CS2001, which names the file. With -cgo, on a machine with a C compiler (go env CC), a package converts when every C use it makes is a call of a C function a shared library defines, passing integers, floating-point numbers and pointers, structs of integers and pointers by value, one struct or one scalar by pointer, or a void * that is nil or points at C memory. C.CString, C.CBytes, C.GoString, C.GoStringN, C.GoBytes, C.malloc, C.free and defer C.f(…) convert, with the package’s C types and constants. A program that uses the converted package needs only the C library.

One package, one machine. A -cgo conversion is one package, for the machine’s own operating system and architecture, and the converted package refuses to call C anywhere else. It builds against a go2cs clone (dotnet build -p:go2csPath=<go2cs>/src/), not against the go.* packages (Roadmap). The standard library itself is converted with CGO_ENABLED=0.

What is refused, by name, with the phase that will cover it:

Where it differs from Go. go2cs never hands C a pointer into Go’s memory: it hands C a copy of the one struct a pointer points at, and copies it back after the call. So cgo’s pointer check differs from Go’s in five places, all where a program breaks or bends cgo’s pointer rules:

A known memory-safety gap: a pointer rebuilt from a number, in three narrow cases. go2cs refuses, by name, any address inside Go memory that it is holding still, even after the address has been through a uintptr: u := uintptr(unsafe.Pointer(p)), then unsafe.Pointer(u + n), the reversed sum unsafe.Pointer(n + uintptr(unsafe.Pointer(p))), and a slice element viewed as another type ((*C.int)(unsafe.Pointer(&b[4]))) and then held as a uintptr. Go’s own one-expression form, unsafe.Pointer(uintptr(unsafe.Pointer(p)) + n), converts to unsafe.Add, which go2cs refuses by name, as it does unsafe.Pointer(p) itself. Three cases still cross, because go2cs is no longer holding the memory, or never was. In each, the call goes ahead, and the memory may move while C uses it:

Platforms. A converted cgo program was built and run against the Go build of the same program on linux/amd64, darwin/amd64, darwin/arm64 and windows/amd64, and printed what Go printed apart from the differences above.

What works, but costs you something

Third-party modules: where they trip today

The validated modules page lists the modules validated so far.

What “validated” means, and what it doesn’t

A package’s own Go Test functions were converted, run, and compared with go test verdict for verdict, by full test name. That’s a real bar, and narrower than the word sounds:

Platforms and toolchain

Reading and debugging the output

What you might expect to break, and doesn’t

The language itself (generics, closures, struct embedding, range-over-func, typed nil pointers in interfaces, randomized map order), defer/panic/recover, channels and select, reflect (encoding/json and text/template pass their own suites on it, on Windows, Linux and macOS), and net/http with HTTP/2 and crypto/tls over real sockets.

When you hit a seam

  1. Start from a clean Go build: GOTOOLCHAIN=local, then go build ./... for the same OS and tags.
  2. Read the conversion’s warnings and its summary line, not the exit code.
  3. A clean build that throws NotImplementedException wants a pure-Go build tag. A C# compile error in converted code is a converter bug until proven otherwise.
  4. A behavior difference in the standard library? Check the package’s disclosures on Validated Test Packages.
  5. Check Known issues, then open an issue with the output of go2cs -version, your OS, the error text, and the smallest Go that reproduces it.

If you find a seam that isn’t on this page, that’s the one I most want to hear about.