Compatibility

Go standard library support

All Go standard library packages are supported and tested using original distribution tests.

The distribution tests are executed by mocking the required runtime support, implemented with bare metal drivers under GOOS=tamago, with a bridge to standard Linux system calls.

The testing environment for ARM and RISCV64 architectures runs under Linux natively or using qemu-system-arm and qemu-system-riscv64 via binfmt_misc respectively.

The following test runs can be executed within a built TamaGo compiler.

Standard distribution tests:

GO_BUILDER_NAME="tamago" GOOS=tamago GOARCH=arm bin/go tool dist test

##### Testing packages.
ok      archive/tar     1.391s
ok      archive/zip     0.828s
ok  	bufio	        0.805s
...
ok  	crypto/x509	12.732s

ALL TESTS PASSED

Individual package(s):

GOOS=tamago GOARCH=riscv64 bin/go test -tags fakenet runtime net crypto/tls
ok      runtime         6.388s
ok      net             1.158s
ok      crypto/tls      1.674s

Note

the fakenet tag is required for testing individual packages making network API calls

Warning

runtime flags (e.g. -run) are ignored due to lack of os.Args support under bare metal, for this reason -test.short is always assumed

Go application limitations

The overwhelming majority of applications and libraries are not limited under GOOS=tamago, limitations are common with single-threaded Go platforms:

• There is no thread support and GOMAXPROCS is fixed to 1, this also means that Go >= 1.14 asynchronous preemption for Goroutines is not supported (just like js/wasm). Therefore avoid starving the scheduler.

• Just like Go js/wasm blocking functions which are not executed in a new goroutine, while no other goroutine is running, will cause a deadlock (similar to this and this). As long as you never sleep in your main function without anything else going on this is quite natural to avoid.

• Due to the intrinsic nature of a bare metal application: there is no OS, there are no users, there are no signals, there are no environment variables. This can be seen as a feature, rather than a limitation.

• Applications which import packages that rely on unsupported system calls may not compile or work as expected (for instance terminal prompt packages will not be able to access syscall.SYS_IOCTL).

• Importing libraries that require cgo triggers external linking, which is not supported. Internal linking is forced with GO_EXTLINK_ENABLED=0, however this entails that external functions (e.g. malloc()) will be referenced but not found. Therefore compiling C code with cgo is possible, however the C code must be self standing and without calls to external functions or system calls.

• Care must be taken with direct or indirect (e.g. dependencies) use of the atomic package due to the last of these bugs. This is a generic Go issue not specific to TamaGo, but possible due to TamaGo main targets being 32-bit ones.