github.com/tinygo-org/tinygo@v0.31.3-0.20240404173401-90b0bf646c27/README.md (about)

     1  # TinyGo - Go compiler for small places
     2  
     3  [![Linux](https://github.com/tinygo-org/tinygo/actions/workflows/linux.yml/badge.svg?branch=dev)](https://github.com/tinygo-org/tinygo/actions/workflows/linux.yml) [![macOS](https://github.com/tinygo-org/tinygo/actions/workflows/build-macos.yml/badge.svg?branch=dev)](https://github.com/tinygo-org/tinygo/actions/workflows/build-macos.yml) [![Windows](https://github.com/tinygo-org/tinygo/actions/workflows/windows.yml/badge.svg?branch=dev)](https://github.com/tinygo-org/tinygo/actions/workflows/windows.yml) [![Docker](https://github.com/tinygo-org/tinygo/actions/workflows/docker.yml/badge.svg?branch=dev)](https://github.com/tinygo-org/tinygo/actions/workflows/docker.yml) [![Nix](https://github.com/tinygo-org/tinygo/actions/workflows/nix.yml/badge.svg?branch=dev)](https://github.com/tinygo-org/tinygo/actions/workflows/nix.yml) [![CircleCI](https://circleci.com/gh/tinygo-org/tinygo/tree/dev.svg?style=svg)](https://circleci.com/gh/tinygo-org/tinygo/tree/dev)
     4  
     5  TinyGo is a Go compiler intended for use in small places such as microcontrollers, WebAssembly (wasm/wasi), and command-line tools.
     6  
     7  It reuses libraries used by the [Go language tools](https://golang.org/pkg/go/) alongside [LLVM](http://llvm.org) to provide an alternative way to compile programs written in the Go programming language.
     8  
     9  ## Embedded
    10  
    11  Here is an example program that blinks the built-in LED when run directly on any supported board with onboard LED:
    12  
    13  ```go
    14  package main
    15  
    16  import (
    17      "machine"
    18      "time"
    19  )
    20  
    21  func main() {
    22      led := machine.LED
    23      led.Configure(machine.PinConfig{Mode: machine.PinOutput})
    24      for {
    25          led.Low()
    26          time.Sleep(time.Millisecond * 1000)
    27  
    28          led.High()
    29          time.Sleep(time.Millisecond * 1000)
    30      }
    31  }
    32  ```
    33  
    34  The above program can be compiled and run without modification on an Arduino Uno, an Adafruit ItsyBitsy M0, or any of the supported boards that have a built-in LED, just by setting the correct TinyGo compiler target. For example, this compiles and flashes an Arduino Uno:
    35  
    36  ```shell
    37  tinygo flash -target arduino examples/blinky1
    38  ```
    39  
    40  ## WebAssembly
    41  
    42  TinyGo is very useful for compiling programs both for use in browsers (WASM) as well as for use on servers and other edge devices (WASI).
    43  
    44  TinyGo programs can run in [Fastly Compute](https://www.fastly.com/documentation/guides/compute/go/), [Fermyon Spin](https://developer.fermyon.com/spin/go-components), [wazero](https://wazero.io/languages/tinygo/) and many other WebAssembly runtimes.
    45  
    46  Here is a small TinyGo program for use by a WASI host application:
    47  
    48  ```go
    49  package main
    50  
    51  //go:wasm-module yourmodulename
    52  //export add
    53  func add(x, y uint32) uint32 {
    54  	return x + y
    55  }
    56  
    57  // main is required for the `wasip1` target, even if it isn't used.
    58  func main() {}
    59  ```
    60  
    61  This compiles the above TinyGo program for use on any WASI runtime:
    62  
    63  ```shell
    64  tinygo build -o main.wasm -target=wasip1 main.go
    65  ```
    66  
    67  ## Installation
    68  
    69  See the [getting started instructions](https://tinygo.org/getting-started/) for information on how to install TinyGo, as well as how to run the TinyGo compiler using our Docker container.
    70  
    71  ## Supported targets
    72  
    73  ### Embedded
    74  
    75  You can compile TinyGo programs for over 94 different microcontroller boards.
    76  
    77  For more information, please see https://tinygo.org/docs/reference/microcontrollers/
    78  
    79  ### WebAssembly
    80  
    81  TinyGo programs can be compiled for both WASM and WASI targets.
    82  
    83  For more information, see https://tinygo.org/docs/guides/webassembly/
    84  
    85  ### Operating Systems
    86  
    87  You can also compile programs for Linux, macOS, and Windows targets.
    88  
    89  For more information:
    90  
    91  - Linux https://tinygo.org/docs/guides/linux/
    92  
    93  - macOS https://tinygo.org/docs/guides/macos/
    94  
    95  - Windows https://tinygo.org/docs/guides/windows/
    96  
    97  ## Currently supported features:
    98  
    99  For a description of currently supported Go language features, please see [https://tinygo.org/lang-support/](https://tinygo.org/lang-support/).
   100  
   101  ## Documentation
   102  
   103  Documentation is located on our web site at [https://tinygo.org/](https://tinygo.org/).
   104  
   105  You can find the web site code at [https://github.com/tinygo-org/tinygo-site](https://github.com/tinygo-org/tinygo-site).
   106  
   107  ## Getting help
   108  
   109  If you're looking for a more interactive way to discuss TinyGo usage or
   110  development, we have a [#TinyGo channel](https://gophers.slack.com/messages/CDJD3SUP6/)
   111  on the [Gophers Slack](https://gophers.slack.com).
   112  
   113  If you need an invitation for the Gophers Slack, you can generate one here which
   114  should arrive fairly quickly (under 1 min): https://invite.slack.golangbridge.org
   115  
   116  ## Contributing
   117  
   118  Your contributions are welcome!
   119  
   120  Please take a look at our [Contributing](https://tinygo.org/docs/guides/contributing/) page on our web site for details.
   121  
   122  ## Project Scope
   123  
   124  Goals:
   125  
   126  * Have very small binary sizes. Don't pay for what you don't use.
   127  * Support for most common microcontroller boards.
   128  * Be usable on the web using WebAssembly.
   129  * Good CGo support, with no more overhead than a regular function call.
   130  * Support most standard library packages and compile most Go code without modification.
   131  
   132  Non-goals:
   133  
   134  * Be efficient while using zillions of goroutines. However, good goroutine support is certainly a goal.
   135  * Be as fast as `gc`. However, LLVM will probably be better at optimizing certain things so TinyGo might actually turn out to be faster for number crunching.
   136  * Be able to compile every Go program out there.
   137  
   138  ## Why this project exists
   139  
   140  > We never expected Go to be an embedded language and so its got serious problems...
   141  
   142  -- Rob Pike, [GopherCon 2014 Opening Keynote](https://www.youtube.com/watch?v=VoS7DsT1rdM&feature=youtu.be&t=2799)
   143  
   144  TinyGo is a project to bring Go to microcontrollers and small systems with a single processor core. It is similar to [emgo](https://github.com/ziutek/emgo) but a major difference is that we want to keep the Go memory model (which implies garbage collection of some sort). Another difference is that TinyGo uses LLVM internally instead of emitting C, which hopefully leads to smaller and more efficient code and certainly leads to more flexibility.
   145  
   146  The original reasoning was: if [Python](https://micropython.org/) can run on microcontrollers, then certainly [Go](https://golang.org/) should be able to run on even lower level micros.
   147  
   148  ## License
   149  
   150  This project is licensed under the BSD 3-clause license, just like the [Go project](https://golang.org/LICENSE) itself.
   151  
   152  Some code has been copied from the LLVM project and is therefore licensed under [a variant of the Apache 2.0 license](http://releases.llvm.org/11.0.0/LICENSE.TXT). This has been clearly indicated in the header of these files.
   153  
   154  Some code has been copied and/or ported from Paul Stoffregen's Teensy libraries and is therefore licensed under PJRC's license. This has been clearly indicated in the header of these files.