docs: refactor README content (#171)
* docs: refactor README to avoid duplication with information on the web site, and to reorder to make it easier for new users.
Этот коммит содержится в:
Ron Evans
GitHub
родитель
3cba36f2ba
коммит
7657238c24
2 изменённых файлов: 74 добавлений и 132 удалений
|
|
@ -16,10 +16,16 @@ Please open a Github issue with your problem, and we will be happy to assist.
|
||||||
|
|
||||||
We probably have not implemented it yet. Please take a look at our [Roadmap](https://github.com/tinygo-org/tinygo/wiki/Roadmap). Your pull request adding the functionality to TinyGo would be greatly appreciated.
|
We probably have not implemented it yet. Please take a look at our [Roadmap](https://github.com/tinygo-org/tinygo/wiki/Roadmap). Your pull request adding the functionality to TinyGo would be greatly appreciated.
|
||||||
|
|
||||||
|
A long tail of small (and large) language features haven't been implemented yet. In almost all cases, the compiler will show a `todo:` error from `compiler/compiler.go` when you try to use it. You can try implementing it, or open a bug report with a small code sample that fails to compile.
|
||||||
|
|
||||||
### Some specific hardware you want to use does not appear to be in TinyGo
|
### Some specific hardware you want to use does not appear to be in TinyGo
|
||||||
|
|
||||||
As above, we probably have not implemented it yet. Your contribution adding the hardware support to TinyGo would be greatly appreciated.
|
As above, we probably have not implemented it yet. Your contribution adding the hardware support to TinyGo would be greatly appreciated.
|
||||||
|
|
||||||
|
Lots of targets/boards are still unsupported. Adding an architecture often requires a few compiler changes, but if the architecture is supported you can try implementing support for a new chip or board in `src/runtime`. For details, see [this wiki entry on adding archs/chips/boards](https://github.com/tinygo-org/tinygo/wiki/Adding-a-new-board).
|
||||||
|
|
||||||
|
Microcontrollers have lots of peripherals (I2C, SPI, ADC, etc.) and many don't have an implementation yet in the `machine` package. Adding support for new peripherals is very useful.
|
||||||
|
|
||||||
## How to use our Github repository
|
## How to use our Github repository
|
||||||
|
|
||||||
The `master` branch of this repo will always have the latest released version of TinyGo. All of the active development work for the next release will take place in the `dev` branch. TinyGo will use semantic versioning and will create a tag/release for each release.
|
The `master` branch of this repo will always have the latest released version of TinyGo. All of the active development work for the next release will take place in the `dev` branch. TinyGo will use semantic versioning and will create a tag/release for each release.
|
||||||
|
|
|
||||||
200
README.md
200
README.md
|
|
@ -1,145 +1,70 @@
|
||||||
# TinyGo - Go compiler for microcontrollers
|
# TinyGo - Go compiler for small places
|
||||||
|
|
||||||
[](https://travis-ci.com/tinygo-org/tinygo)
|
[](https://travis-ci.com/tinygo-org/tinygo)
|
||||||
|
|
||||||
> We never expected Go to be an embedded language and so it's got serious
|
TinyGo is a Go compiler intended for use in small places such as microcontrollers, WebAssembly (WASM), and command-line tools.
|
||||||
> problems [...].
|
|
||||||
|
|
||||||
-- Rob Pike, [GopherCon 2014 Opening Keynote](https://www.youtube.com/watch?v=VoS7DsT1rdM&feature=youtu.be&t=2799)
|
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.
|
||||||
|
|
||||||
TinyGo is a project to bring Go to microcontrollers and small systems with a
|
Here is an example program that blinks the built-in LED when run directly on any supported board with onboard LED:
|
||||||
single processor core. It is similar to [emgo](https://github.com/ziutek/emgo)
|
|
||||||
but a major difference is that I 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.
|
|
||||||
|
|
||||||
My original reasoning was: if [Python](https://micropython.org/) can run on
|
|
||||||
microcontrollers, then certainly [Go](https://golang.org/) should be able to and
|
|
||||||
run on even lower level micros.
|
|
||||||
|
|
||||||
Example program (blinky):
|
|
||||||
|
|
||||||
```go
|
```go
|
||||||
|
package main
|
||||||
|
|
||||||
import (
|
import (
|
||||||
"machine"
|
"machine"
|
||||||
"time"
|
"time"
|
||||||
)
|
)
|
||||||
|
|
||||||
func main() {
|
func main() {
|
||||||
led := machine.GPIO{machine.LED}
|
led := machine.GPIO{machine.LED}
|
||||||
led.Configure(machine.GPIOConfig{Mode: machine.GPIO_OUTPUT})
|
led.Configure(machine.GPIOConfig{Mode: machine.GPIO_OUTPUT})
|
||||||
for {
|
for {
|
||||||
led.Low()
|
led.Low()
|
||||||
time.Sleep(time.Millisecond * 1000)
|
time.Sleep(time.Millisecond * 1000)
|
||||||
|
|
||||||
led.High()
|
led.High()
|
||||||
time.Sleep(time.Millisecond * 1000)
|
time.Sleep(time.Millisecond * 1000)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Currently supported features:
|
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:
|
||||||
|
|
||||||
* control flow
|
```shell
|
||||||
* many (but not all) basic types: most ints, floats, strings, structs
|
tinygo flash -target arduino examples/blinky1
|
||||||
* function calling
|
```
|
||||||
* interfaces for basic types (with type switches and asserts)
|
|
||||||
* goroutines (very initial support)
|
|
||||||
* function pointers (non-blocking)
|
|
||||||
* interface methods
|
|
||||||
* standard library (but most packages won't work due to missing language
|
|
||||||
features)
|
|
||||||
* slices (partially)
|
|
||||||
* maps (very rough, unfinished)
|
|
||||||
* defer
|
|
||||||
* closures
|
|
||||||
* bound methods
|
|
||||||
* complex numbers (except for arithmetic)
|
|
||||||
* channels (with some limitations)
|
|
||||||
|
|
||||||
Not yet supported:
|
|
||||||
|
|
||||||
* select
|
|
||||||
* complex arithmetic
|
|
||||||
* garbage collection
|
|
||||||
* recover
|
|
||||||
* introspection (if it ever gets implemented)
|
|
||||||
* ...
|
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
See the [getting started instructions](https://tinygo.org/getting-started/).
|
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.
|
||||||
|
|
||||||
### Running with Docker
|
## Supported boards/targets
|
||||||
|
|
||||||
A docker container exists for easy access to the `tinygo` CLI:
|
You can compile TinyGo programs for microcontrollers, WebAssembly and Linux.
|
||||||
|
|
||||||
```sh
|
The following microcontroller boards are currently supported:
|
||||||
$ docker run --rm -v $(pwd):/src tinygo/tinygo tinygo build -o /src/wasm.wasm -target wasm examples/wasm
|
|
||||||
```
|
|
||||||
|
|
||||||
Note that you cannot run `tinygo flash` from inside the docker container,
|
* [Adafruit ItsyBitsy M0](https://www.adafruit.com/product/3727)
|
||||||
so it is less useful for microcontroller development.
|
* [Arduino Uno](https://store.arduino.cc/arduino-uno-rev3)
|
||||||
|
* [BBC:Microbit](https://microbit.org/)
|
||||||
|
* [ST Micro STM32F103XX "Bluepill"](http://wiki.stm32duino.com/index.php?title=Blue_Pill)
|
||||||
|
* [Digispark](http://digistump.com/products/1)
|
||||||
|
* [Nordic Semiconductor PCA10031](https://www.nordicsemi.com/eng/Products/nRF51-Dongle)
|
||||||
|
* [Nordic Semiconductor PCA10040](https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF52-DK)
|
||||||
|
* [Nordic Semiconductor PCA10056](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK)
|
||||||
|
* [Makerdiary nRF52840-MDK](https://wiki.makerdiary.com/nrf52840-mdk/)
|
||||||
|
* [Phytec reel board](https://www.phytec.eu/product-eu/internet-of-things/reelboard/)
|
||||||
|
|
||||||
## Supported targets
|
For more information, see [this list of boards](https://tinygo.org/microcontrollers/). Pull requests for additional support are welcome!
|
||||||
|
|
||||||
The following architectures/systems are currently supported:
|
## Currently supported features:
|
||||||
|
|
||||||
* ARM (Cortex-M)
|
For a description of currently supported Go language features, please see [https://tinygo.org/lang-support/](https://tinygo.org/lang-support/).
|
||||||
* AVR (Arduino Uno)
|
|
||||||
* Linux
|
|
||||||
* WebAssembly
|
|
||||||
|
|
||||||
For more information, see [this list of targets and
|
|
||||||
boards](https://tinygo.org/targets/). Pull requests for
|
|
||||||
broader support are welcome!
|
|
||||||
|
|
||||||
## Analysis and optimizations
|
|
||||||
|
|
||||||
The goal is to reduce code size (and increase performance) by performing all
|
|
||||||
kinds of whole-program analysis passes. The official Go compiler doesn't do a
|
|
||||||
whole lot of analysis (except for escape analysis) because it needs to be fast,
|
|
||||||
but embedded programs are necessarily smaller so it becomes practical. And I
|
|
||||||
think especially program size can be reduced by a large margin when actually
|
|
||||||
trying to optimize for it.
|
|
||||||
|
|
||||||
Implemented compiler passes:
|
|
||||||
|
|
||||||
* Analyse which functions are blocking. Blocking functions are functions that
|
|
||||||
call sleep, chan send, etc. Its parents are also blocking.
|
|
||||||
* Analyse whether the scheduler is needed. It is only needed when there are
|
|
||||||
`go` statements for blocking functions.
|
|
||||||
* Analyse whether a given type switch or type assert is possible with
|
|
||||||
[type-based alias analysis](https://en.wikipedia.org/wiki/Alias_analysis#Type-based_alias_analysis).
|
|
||||||
I would like to use flow-based alias analysis in the future, if feasible.
|
|
||||||
* Do basic dead code elimination of functions. This pass makes later passes
|
|
||||||
better and probably improves compile time as well.
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
Goals:
|
|
||||||
|
|
||||||
* Have very small binary sizes. Don't pay for what you don't use.
|
|
||||||
* Support for most common microcontroller boards.
|
|
||||||
* Be usable on the web using WebAssembly.
|
|
||||||
* Good CGo support, with no more overhead than a regular function call.
|
|
||||||
* Support most standard library packages and compile most Go code without
|
|
||||||
modification.
|
|
||||||
|
|
||||||
Non-goals:
|
|
||||||
|
|
||||||
* Using more than one core.
|
|
||||||
* Be efficient while using zillions of goroutines. However, good goroutine
|
|
||||||
support is certainly a goal.
|
|
||||||
* 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.
|
|
||||||
* Be able to compile every Go program out there.
|
|
||||||
|
|
||||||
## Documentation
|
## Documentation
|
||||||
|
|
||||||
Documentation is currently maintained on a dedicated web site located at [https://tinygo.org/](https://tinygo.org/).
|
Documentation is located on our web site at [https://tinygo.org/](https://tinygo.org/).
|
||||||
|
|
||||||
You can find the web site code at [https://github.com/tinygo-org/tinygo-site](https://github.com/tinygo-org/tinygo-site).
|
You can find the web site code at [https://github.com/tinygo-org/tinygo-site](https://github.com/tinygo-org/tinygo-site).
|
||||||
|
|
||||||
|
|
@ -154,26 +79,37 @@ should arrive fairly quickly (under 1 min): https://invite.slack.golangbridge.or
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
Patches are welcome!
|
Your contributions are welcome!
|
||||||
|
|
||||||
If you want to contribute, here are some suggestions:
|
Please take a look at our [CONTRIBUTING.md](./CONTRIBUTING.md) document for details.
|
||||||
|
|
||||||
* A long tail of small (and large) language features haven't been implemented
|
## Project Scope
|
||||||
yet. In almost all cases, the compiler will show a `todo:` error from
|
|
||||||
`compiler/compiler.go` when you try to use it. You can try implementing it,
|
Goals:
|
||||||
or open a bug report with a small code sample that fails to compile.
|
|
||||||
* Lots of targets/boards are still unsupported. Adding an architecture often
|
* Have very small binary sizes. Don't pay for what you don't use.
|
||||||
requires a few compiler changes, but if the architecture is supported you
|
* Support for most common microcontroller boards.
|
||||||
can try implementing support for a new chip or board in `src/runtime`. For
|
* Be usable on the web using WebAssembly.
|
||||||
details, see [this wiki entry on adding
|
* Good CGo support, with no more overhead than a regular function call.
|
||||||
archs/chips/boards](https://github.com/tinygo-org/tinygo/wiki/Adding-a-new-board).
|
* Support most standard library packages and compile most Go code without modification.
|
||||||
* Microcontrollers have lots of peripherals and many don't have an
|
|
||||||
implementation yet in the `machine` package. Adding support for new
|
Non-goals:
|
||||||
peripherals is very useful.
|
|
||||||
* Just raising bugs for things you'd like to see implemented is also a form of
|
* Using more than one core.
|
||||||
contributing! It helps prioritization.
|
* Be efficient while using zillions of goroutines. However, good goroutine support is certainly a goal.
|
||||||
|
* 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.
|
||||||
|
* Be able to compile every Go program out there.
|
||||||
|
|
||||||
|
## Why this project exists
|
||||||
|
|
||||||
|
> We never expected Go to be an embedded language and so its got serious problems...
|
||||||
|
|
||||||
|
-- Rob Pike, [GopherCon 2014 Opening Keynote](https://www.youtube.com/watch?v=VoS7DsT1rdM&feature=youtu.be&t=2799)
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
This project is licensed under the BSD 3-clause license, just like the
|
This project is licensed under the BSD 3-clause license, just like the [Go project](https://golang.org/LICENSE) itself.
|
||||||
[Go project](https://golang.org/LICENSE) itself.
|
|
||||||
|
|
|
||||||
Загрузка…
Создание таблицы
Сослаться в новой задаче