aboutsummaryrefslogtreecommitdiffhomepage
path: root/docs
diff options
context:
space:
mode:
authorRon Evans <[email protected]>2019-01-04 15:54:40 +0100
committerAyke van Laethem <[email protected]>2019-01-13 20:29:45 +0100
commitb4dd2dbf60f6de63b33e67a3266ab03ffc4a7024 (patch)
tree761c66f79725d94fe2dca445b197ae1eac7ec602 /docs
parent8d1284cfe77b59b628f2756ed3998aa4ecab393c (diff)
downloadtinygo-b4dd2dbf60f6de63b33e67a3266ab03ffc4a7024.tar.gz
tinygo-b4dd2dbf60f6de63b33e67a3266ab03ffc4a7024.zip
docs: change links in README and remove old ReadTheDocs pages to point to TinyGo.org site
Signed-off-by: Ron Evans <[email protected]>
Diffstat (limited to 'docs')
-rw-r--r--docs/docker.rst36
-rw-r--r--docs/faq.rst162
-rw-r--r--docs/index.rst11
-rw-r--r--docs/installation.rst109
-rw-r--r--docs/internals.rst213
-rw-r--r--docs/microcontrollers.rst149
-rw-r--r--docs/moved.rst12
-rw-r--r--docs/targets.rst71
-rw-r--r--docs/usage.rst211
-rw-r--r--docs/webassembly.rst47
10 files changed, 14 insertions, 1007 deletions
diff --git a/docs/docker.rst b/docs/docker.rst
deleted file mode 100644
index 315bd7362..000000000
--- a/docs/docker.rst
+++ /dev/null
@@ -1,36 +0,0 @@
-.. _docker:
-
-.. highlight:: none
-
-Using with Docker
-=================
-
-A docker container exists for easy access to the ``tinygo`` CLI. For example, to
-compile ``wasm.wasm`` for the WebAssembly example, from the root of the
-repository::
-
- docker run --rm -v $(pwd):/src tinygo/tinygo tinygo build -o /src/wasm.wasm -target wasm examples/wasm
-
-To compile ``blinky1.hex`` targeting an ARM microcontroller, such as the PCA10040::
-
- docker run --rm -v $(pwd):/src tinygo/tinygo tinygo build -o /src/blinky1.hex -size=short -target=pca10040 examples/blinky1
-
-To compile ``blinky1.hex`` targeting an AVR microcontroller such as the Arduino::
-
- docker run --rm -v $(pwd):/src tinygo/tinygo tinygo build -o /src/blinky1.hex -size=short -target=arduino examples/blinky1
-
-For projects that have remote dependencies outside of the standard library and go code within your own project, you will need to map your entire GOPATH into the docker image in order for those dependencies to be found::
-
- docker run -v $(PWD):/mysrc -v $GOPATH:/gohost -e "GOPATH=$GOPATH:/gohost" tinygo/tinygo tinygo build -o /mysrc/wasmout.wasm -target wasm /mysrc/wasm-main.go
-
-.. note::
- At this time, tinygo does not resolve dependencies from the /vendor/ folder within your project.
-
-For microcontroller development you must flash your hardware devices
-from your host environment, since you cannot run ``tinygo flash`` from inside
-the docker container.
-
-So your workflow could be:
-
-- Compile TinyGo code using the Docker container into a HEX file.
-- Flash the HEX file from your host environment to the target microcontroller.
diff --git a/docs/faq.rst b/docs/faq.rst
deleted file mode 100644
index 8464910d3..000000000
--- a/docs/faq.rst
+++ /dev/null
@@ -1,162 +0,0 @@
-.. _faq:
-
-Frequently Asked Questions
-==========================
-
-
-What is TinyGo exactly?
------------------------
-
-A new compiler and a new runtime implementation.
-
-Specifically:
-
- * A new compiler using (mostly) the standard library to parse Go programs and
- using LLVM to optimize the code and generate machine code for the target
- architecture.
-
- * A new runtime library that implements some compiler intrinsics, like a
- memory allocator, a scheduler, and operations on strings. Also, some
- packages that are strongly connected to the runtime like the ``sync``
- package and the ``reflect`` package have been or will be re-implemented for
- use with this new compiler.
-
-
-Why a new compiler?
--------------------
-
-Why not modify the existing compiler to produce binaries for microcontrollers?
-
-There are several reasons for this:
-
- * The standard Go compiler (``gc``) does not support instruction sets as used
- on microcontrollers:
-
- * The Thumb instruction set is unsupported, but it should be possible to
- add support for it as it already has an ARM backend.
- * The AVR instruction set (as used in the Arduino Uno) is unsupported and
- unlikely to be ever supported.
-
- Of course, it is possible to use ``gccgo``, but that has different problems
- (see below).
-
- * The runtime is really big. A standard 'hello world' on a desktop PC produces
- a binary of about 1MB, even when using the builtin ``println`` function and
- nothing else. All this overhead is due to the runtime. Of course, it may be
- possible to use a different runtime with the same compiler but that will be
- kind of painful as the exact ABI as used by the compiler has to be matched,
- limiting optimization opportunities (see below).
-
- * The compiler is optimized for speed, not for code size or memory
- consumption (which are usually far more important on MCUs). This results in
- design choices like allocating memory on every value → interface conversion
- while TinyGo sacrifices some performance for reduced GC pressure.
-
- * With the existing Go libraries for parsing Go code and the pretty awesome
- LLVM optimizer/backend it is relatively easy to get simple Go programs
- working with a very small binary size. Extra features can be added where
- needed in a pay-as-you-go manner similar to C++ avoiding their cost when
- unused. Most programs on microcontrollers are relatively small so a
- not-complete compiler is still useful.
-
- * The standard Go compilers do not allocate global variables as static data,
- but as zero-initialized data that is initialized during program startup.
- This is not a big deal on desktop computers but prevents allocating these
- values in flash on microcontrollers. Part of this is due to how the
- `language specification defines package initialization
- <https://golang.org/ref/spec#Package_initialization>`_, but this can be
- worked around to a large extent.
-
- * The standard Go compilers do a few special things for CGo calls. This is
- necessary because only Go code can use the (small) Go stack while C code
- will need a much bigger stack. A new compiler can avoid this limitation if
- it ensures stacks are big enough for C, greatly reducing the C ↔ Go calling
- overhead.
-
-`At one point <https://github.com/aykevl/tinygo-gccgo>`_, a real Go compiler
-had been used to produce binaries for various platforms, and the result was
-painful enough to start writing a new compiler:
-
- * The ABI was fixed, so could not be optimized for speed. Also, the ABI
- didn't seem to be documented anywhere.
-
- * Working arount limitations in the ``go`` toolchain was rather burdensome
- and quite a big hack.
-
- * The binaries produced were quite bloated, for various reasons:
-
- * The Go calling convention places all arguments on the stack. Due to
- this, stack usage was really bad and code size was bigger than it
- needed to be.
-
- * Global initialization was very inefficient, see above.
-
- * There seemed to be no way to optimize across packages.
-
-
-Why Go instead of Rust?
------------------------
-
-Rust is another "new" and safer language that is now made ready for embedded
-processors. There is `a fairly active community around it
-<https://rust-embedded.github.io/blog/>`_.
-
-However, apart from personal language preference, Go has a few advantages:
-
- * Subjective, but in general Go is `easier to learn
- <https://matthias-endler.de/2017/go-vs-rust/>`_. Rust is in general far more
- complicated than Go, with difficult-to-grasp ownership rules, traits,
- generics, etc. Go prides itself on being a simple and slightly dumb
- language, sacrificing some expressiveness for readability.
-
- * Built-in support for concurrency with goroutines and channels that do not
- rely on a particular implementation threads. This avoids the need for a
- custom `RTOS-like framework <https://blog.japaric.io/rtfm-v2/>`_ or a
- `full-blown RTOS <https://github.com/rust-embedded/wg/issues/45>`_ with the
- associated API one has to learn. In Go, everything is handled by goroutines
- which are built into the language itself.
-
- * A batteries-included standard library that consists of loosely-coupled
- packages. Rust uses a monolithic standard library that is currently unusable
- on bare-metal, while the Go standard library is much more loosely coupled so
- is more likely to be (partially) supported. Also, non-standard packages in
- Go do not have to be marked with something like ``#![no_std]`` to be usable
- on bare metal. Note: most standard library packages cannot yet be compiled,
- but this situation will hopefully improve in the future.
-
-At the same time, Rust has other advantages:
-
- * Unlike Go, Rust does not have a garbage collector by default and carefully
- written Rust code can avoid most or all uses of the heap. Go relies heavily
- on garbage collection and often implicitly allocates memory on the heap.
-
- * Rust has stronger memory-safety guarantees.
-
- * In general, Rust is more low-level and easier to support on a
- microcontroller. Of course, this doesn't mean one shouldn't try to run Go on
- a microcontroller, just that it is more difficult. When even dynamic
- languages like `Python <https://micropython.org/>`_, `Lua
- <https://nodemcu.readthedocs.io/en/master/>`_ and `JavaScript
- <https://www.espruino.com/>`_ can run on a microcontroller, then certainly
- Go can.
-
-
-.. _faq-esp:
-
-What about the ESP8266/ESP32?
------------------------------
-
-These chips use the rather obscure Xtensa instruction set. While a port of GCC
-exists and Espressif provides precompiled GNU toolchains, there is no support
-yet in LLVM (although there have been `multiple attempts
-<http://lists.llvm.org/pipermail/llvm-dev/2018-July/124789.html>`_).
-
-There are two ways these chips might be supported in the future, and both will
-take a considerable amount of work:
-
- * The compiled LLVM IR can be converted into (ugly) C and then be compiled
- with a supported C compiler (like GCC for Xtensa). This has been `done
- before <https://github.com/JuliaComputing/llvm-cbe>`_ so should be doable.
-
- * One of the work-in-progress LLVM backends can be worked on to get it in a
- usable state. If this is finished, a true TinyGo port is possible.
diff --git a/docs/index.rst b/docs/index.rst
index 8e79198e3..b9a9b20a5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,7 +3,7 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to TinyGo's documentation!
+The TinyGo site has moved!
==================================
Contents:
@@ -11,11 +11,4 @@ Contents:
.. toctree::
:maxdepth: 2
- installation
- docker
- usage
- targets
- microcontrollers
- webassembly
- faq
- internals
+ moved
diff --git a/docs/installation.rst b/docs/installation.rst
deleted file mode 100644
index af50ceca6..000000000
--- a/docs/installation.rst
+++ /dev/null
@@ -1,109 +0,0 @@
-.. _installation:
-
-.. highlight:: none
-
-Installation instructions
-=========================
-
-Requirements
-------------
-
-These are the base requirements and enough for most (desktop) use.
-
- * Go 1.11+
- * LLVM 7 (for example, from `apt.llvm.org <http://apt.llvm.org/>`_)
-
-Linking a binary needs an installed C compiler (``cc``). At the moment it
-expects GCC or a recent Clang.
-
-ARM Cortex-M
-~~~~~~~~~~~~
-
-The Cortex-M family of microcontrollers is well supported, as it uses the stable
-ARM LLVM backend (which is even used in the propietary C compiler from ARM).
-Compiling to object code should be supported out of the box, but compiling the
-final binary and flashing it needs some extra tools.
-
- * binutils (``arm-none-eabi-ld``, ``arm-none-eabi-objcopy``) for linking and
- for producing .hex files for flashing.
- * Clang 7 (``clang-7``) for building assembly files and the `compiler
- runtime library <https://compiler-rt.llvm.org/>`_ .
- * The flashing tool for the particular chip, like ``openocd`` or
- ``nrfjprog``.
-
-AVR (Arduino)
-~~~~~~~~~~~~~
-
-The AVR backend has similar requirements as the `ARM Cortex-M`_ backend. It
-needs the following tools:
-
- * binutils (``avr-objcopy``) for flashing.
- * GCC (``avr-gcc``) for linking object files.
- * libc (``avr-libc``), which is not installed on Debian as a dependency of
- ``avr-gcc``.
- * ``avrdude`` for flashing to an Arduino.
-
-WebAssembly
-~~~~~~~~~~~
-
-The WebAssembly backend only needs a special linker from the LLVM project:
-
- * LLVM linker (``ld.lld-7``) for linking WebAssembly files together.
-
-
-Installation
-------------
-
-First download the sources. This may take a while. ::
-
- go get -u github.com/aykevl/tinygo
-
-If you get an error like this::
-
- /usr/local/go/pkg/tool/linux_amd64/link: running g++ failed: exit status 1
- /usr/bin/ld: error: cannot find -lLLVM-7
- cgo-gcc-prolog:58: error: undefined reference to 'LLVMVerifyFunction'
- cgo-gcc-prolog:80: error: undefined reference to 'LLVMVerifyModule'
- [...etc...]
-
-Or like this::
-
- ../go-llvm/analysis.go:17:93: fatal error: llvm-c/Analysis.h: No such file or directory
- #include "llvm-c/Analysis.h" // If you are getting an error here read bindings/go/README.txt
-
-It means something is wrong with your LLVM installation. Make sure LLVM 7 is
-installed (Debian package ``llvm-7-dev``). If it still doesn't work, you can
-try running::
-
- cd $GOPATH/github.com/aykevl/go-llvm
- make config
-
-And retry::
-
- go install github.com/aykevl/tinygo
-
-Usage
------
-
-TinyGo should now be installed. Test it by running a test program::
-
- tinygo run examples/test
-
-Before anything can be built for a bare-metal target, you need to generate some
-files first::
-
- make gen-device
-
-This will generate register descriptions, interrupt vectors, and linker scripts
-for various devices. Also, you may need to re-run this command after updates,
-as some updates cause changes to the generated files.
-
-Now you can run a blinky example. For the `PCA10040
-<https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF52-DK>`_
-development board::
-
- tinygo flash -target=pca10040 examples/blinky2
-
-Or for an `Arduino Uno <https://store.arduino.cc/arduino-uno-rev3>`_::
-
- tinygo flash -target=arduino examples/blinky1
diff --git a/docs/internals.rst b/docs/internals.rst
deleted file mode 100644
index 14091d9bb..000000000
--- a/docs/internals.rst
+++ /dev/null
@@ -1,213 +0,0 @@
-.. _internals:
-
-
-Compiler internals
-==================
-
-
-Differences from ``go``
------------------------
-
- * A whole program is compiled in a single step, without intermediate linking.
- This makes incremental development much slower for large programs but
- enables far more optimization opportunities. In the future, an option should
- be added for incremental compilation during edit-compile-test cycles.
- * Interfaces are always represented as a ``{typecode, value}`` pair. `Unlike
- Go <https://research.swtch.com/interfaces>`_, TinyGo will not precompute a
- list of function pointers for fast interface method calls. Instead, all
- interface method calls are looked up where they are used. This may sound
- expensive, but it avoids memory allocation at interface creation.
- * Global variables are computed during compilation whenever possible (unlike
- Go, which does not have the equivalent of a ``.data`` section). This is an
- important optimization for several reasons:
- * Startup time is reduced. This is nice, but not the main reason.
- * Initializing globals by copying the initial data from flash to RAM costs
- much less flash space as only the actual data needs to be stored,
- instead of all instructions to initialize these globals.
- * Data can often be statically allocated instead of dynamically allocated
- at startup.
- * Dead globals are trivially optimized away by LLVM.
- * Constant globals are trivially recognized by LLVM and marked
- ``constant``. This makes sure they can be stored in flash instead of
- RAM.
- * Global constants are useful for constant propagation and thus for dead
- code elimination (like an ``if`` that depends on a global variable).
-
-
-Datatypes
----------
-
-TinyGo uses a different representation for some data types than standard Go.
-
-string
- A string is encoded as a ``{ptr, len}`` tuple. The type is actually defined
- in the runtime as ``runtime._string``, in `src/runtime/string.go
- <https://github.com/aykevl/tinygo/blob/master/src/runtime/string.go>`_. That
- file also contains some compiler intrinsics for dealing with strings and
- UTF-8.
-
-slice
- A slice is encoded as a ``{ptr, len, cap}`` tuple. There is no runtime
- definition of it as slices are a generic type and the pointer type is
- different for each slice. That said, the bit layout is exactly the same for
- every slice and generic ``copy`` and ``append`` functions are implemented in
- `src/runtime/slice.go
- <https://github.com/aykevl/tinygo/blob/master/src/runtime/slice.go>`_.
-
-array
- Arrays are simple: they are simply lowered to a LLVM array type.
-
-complex
- Complex numbers are implemented in the most obvious way: as a vector of
- floating point numbers with length 2.
-
-map
- The map type is a very complex type and is implemented as an (incomplete)
- hashmap. It is defined as ``runtime.hashmap`` in `src/runtime/hashmap.go
- <https://github.com/aykevl/tinygo/blob/master/src/runtime/hashmap.go>`_. As
- maps are reference types, they are lowered to a pointer to the
- aforementioned struct. See for example ``runtime.hashmapMake`` that is the
- compiler intrinsic to create a new hashmap.
-
-interface
- An interface is a ``{typecode, value}`` tuple and is defined as
- ``runtime._interface`` in `src/runtime/interface.go
- <https://github.com/aykevl/tinygo/blob/master/src/runtime/interface.go>`_.
- The typecode is a small integer unique to the type of the value. See
- interface.go for a detailed description of how typeasserts and interface
- calls are implemented.
-
-function value
- A function value is a fat function pointer in the form of ``{context,
- function pointer}`` where context is a pointer which may have any value.
- The function pointer is expected to be called with the context as the last
- parameter in all cases.
-
-goroutine
- A goroutine is a linked list of `LLVM coroutines
- <https://llvm.org/docs/Coroutines.html>`_. Every blocking call will create a
- new coroutine, pass the resulting coroutine to the scheduler, and will mark
- itself as waiting for a return. Once the called blocking function returns,
- it re-activates its parent coroutine. Non-blocking calls are normal calls,
- unaware of the fact that they're running on a particular goroutine. For
- details, see `src/runtime/scheduler.go
- <https://github.com/aykevl/tinygo/blob/master/src/runtime/scheduler.go>`_.
-
- This is rather expensive and should be optimized in the future. But the way
- it works now, a single stack can be used for all goroutines lowering memory
- consumption.
-
-
-Calling convention
-------------------
-
-Go uses a stack-based calling convention and passes a pointer to the argument
-list as the first argument in the function. There were/are `plans to switch to a
-register-based calling convention <https://github.com/golang/go/issues/18597>`_
-but they're now on hold.
-
-.. highlight:: llvm
-
-TinyGo, however, uses a register based calling convention. In fact it is
-somewhat compatible with the C calling convention but with a few quirks:
-
- * Struct parameters are split into separate arguments, if the number of fields
- (after flattening recursively) is 3 or lower. This is similar to the `Swift
- calling convention
- <https://github.com/apple/swift/blob/master/docs/CallingConvention.rst#physical-conventions>`_.
- In the case of TinyGo, the size of each field does not matter, a field can
- even be an array. ::
-
- {i8*, i32} -> i8*, i32
- {{i8*, i32}, i16} -> i8*, i32, i16
- {{i64}} -> i64
- {} ->
- {i8*, i32, i8, i8} -> {i8*, i32, i8, i8}
- {{i8*, i32, i8}, i8} -> {i8*, i32, i8, i8}
-
- Note that all native Go data types that are lowered to aggregate types in
- LLVM are expanded this way: ``string``, slices, interfaces, and fat function
- pointers. This avoids some overhead in the C calling convention and makes
- the work of the LLVM optimizers easier.
-
- * The WebAssembly target by default doesn't export or import ``i64`` (``int64``,
- ``uint64``) parameters. Instead, it replaces them with ``i64*``, allocating
- the value on the stack. In other words, imported functions are called with a
- 64-bit integer on the stack and exported functions must be called with a
- pointer to a 64-bit integer somewhere in linear memory.
-
- This is a workaround for a limitation in JavaScript, which only deals with
- doubles and can therefore only work with integers up to 32-bit in size (a
- 64-bit integer cannot be represented exactly in a double, a 32-bit integer
- can). It is expected that 64-bit integers will be `added in the near future
- <https://github.com/WebAssembly/design/issues/1172>`_ at which point this
- calling convention workaround may be removed. Also see `this wasm-bindgen
- issue <https://github.com/rustwasm/wasm-bindgen/issues/35>`_.
-
- Currently there are also non-browser WebAssembly execution environments
- that do not have this limitation. Use the `-wasm-abi=generic` flag to remove
- the behavior described above and enable emitting functions with i64
- parameters directly.
-
- * The WebAssembly target does not return variables directly that cannot be
- handled by JavaScript (see above about ``i64``, also ``struct``, multiple
- return values, etc). Instead, they are stored into a pointer passed as the
- first parameter by the caller.
-
- This is the calling convention as implemented by LLVM, with the extension
- that ``i64`` return values are returned in the same way as aggregate types.
-
- * Blocking functions have a coroutine pointer prepended to the argument list,
- see `src/runtime/scheduler.go
- <https://github.com/aykevl/tinygo/blob/master/src/runtime/scheduler.go>`_
- for details. Whether a function is blocking is determined by the
- AnalyseBlockingRecursive pass.
-
-This calling convention may change in the future. Changes will be documented
-here. However, even though it may change, it is expected that function
-signatures that only contain integers and pointers will remain stable.
-
-
-Pipeline
---------
-
-Like most compilers, TinyGo is a compiler built as a pipeline of
-transformations, that each translate an input to a simpler output version (also
-called lowering). However, most of these part are not in TinyGo itself. The
-frontend is mostly implemented by external Go libraries, and most optimizations
-and code generation is implemented by LLVM.
-
-This is roughly the pipeline for TinyGo:
-
- * Lexing, parsing, typechecking and `AST
- <https://en.wikipedia.org/wiki/Abstract_syntax_tree>`_ building is done by
- packages in the `standard library <https://godoc.org/go>`_ and in the
- `golang.org/x/tools/go library <https://godoc.org/golang.org/x/tools/go>`_.
- * `SSA <https://en.wikipedia.org/wiki/Static_single_assignment_form>`_
- construction (a very important step) is done by the
- `golang.org/x/tools/go/ssa <https://godoc.org/golang.org/x/tools/go/ssa>`_
- package.
- * This SSA form is then analyzed by the `ir package
- <https://godoc.org/github.com/aykevl/tinygo/ir>`_ to learn all kinds of
- things about the code that help the optimizer.
- * The Go SSA is then transformed into LLVM IR by the `compiler package
- <https://godoc.org/github.com/aykevl/tinygo/compiler>`_. Both forms are SSA,
- but because Go SSA is higher level and contains Go-specific constructs (like
- interfaces and goroutines) this is non-trivial. However, the vast majority
- of the work is simply lowering the available Go SSA into LLVM IR, possibly
- calling some runtime library intrinsics in the process (for example,
- operations on maps).
- * This LLVM IR is then optimized by the LLVM optimizer, which has a large
- array of standard `optimization passes
- <https://llvm.org/docs/Passes.html>`_. Currently, the standard optimization
- pipeline is used as is also be used by Clang, but a pipeline better tuned
- for TinyGo might be used in the future.
- * After all optimizations have run, a few fixups are needed for AVR for
- globals. This is implemented by the compiler package.
- * Finally, the resulting machine code is emitted by LLVM to an object file, to
- be linked by an architecture-specific linker in a later step.
-
-After this whole list of compiler phases, the Go source has been transformed
-into object code. It can then be emitted directly to a file (for linking in a
-different build system), or it can be linked directly or even be flashed to a
-target by TinyGo (using external tools under the hood).
diff --git a/docs/microcontrollers.rst b/docs/microcontrollers.rst
deleted file mode 100644
index 4ddc5c7f8..000000000
--- a/docs/microcontrollers.rst
+++ /dev/null
@@ -1,149 +0,0 @@
-.. _microcontrollers:
-
-.. highlight:: go
-
-
-Go on microcontrollers
-======================
-
-TinyGo was designed to run on microcontrollers, but the Go language wasn't.
-This means there are a few challenges to writing Go code for microcontrollers.
-
-Microcontrollers have very little RAM and execute code directly from flash.
-Also, constant globals are generally put in flash whenever possible. The Go
-language itself heavily relies on garbage collection so care must be taken to
-avoid dynamic memory allocation.
-
-
-Heap allocation
----------------
-
-Many operations in Go rely on heap allocation. Some of these heap allocations
-are optimized away, but not all of them. Also, TinyGo does not yet contain a
-garbage collector so heap allocation must be avoided whenever possible outside
-of initialization code.
-
-These operations currently do heap allocations:
-
- * Taking the pointer of a local variable. This will result in a heap
- allocation, unless the compiler can see the resulting pointer never
- escapes. This causes a heap allocation::
-
- var global *int
-
- func foo() {
- i := 3
- global = &i
- }
-
- This does not cause a heap allocation::
-
- func foo() {
- i := 3
- bar(&i)
- }
-
- func bar(i *int) {
- println(*i)
- }
-
- * Converting between ``string`` and ``[]byte``. In general, this causes a
- heap allocation because one is constant while the other is not: for
- example, a ``[]byte`` is not allowed to write to the underlying buffer of a
- ``string``. However, there is an optimization that avoids a heap allocation
- when converting a string to a ``[]byte`` when the compiler can see the
- slice is never written to. For example, this ``WriteString`` function does
- not cause a heap allocation::
-
- func WriteString(s string) {
- Write([]byte(s))
- }
-
- func Write(buf []byte) {
- for _, c := range buf {
- WriteByte(c)
- }
- }
-
- * Converting a ``byte`` or ``rune`` into a ``string``. This operation is
- actually a conversion from a Unicode code point into a single-character
- string so is similar to the previous point.
-
- * Concatenating strings, unless one of them is zero length.
-
- * Creating an interface with a value larger than a pointer. Interfaces in Go
- are not a zero-cost abstraction and should be used carefully on
- microcontrollers.
-
- * Closures where the collection of shared variables between the closure and
- the main function is larger than a pointer.
-
- * Creating and modifying maps. Maps have *very* little support at the moment
- and should not yet be used. They exist mostly for compatibility with some
- standard library packages.
-
- * Starting goroutines. There is limited support for goroutines and currently
- they are not at all efficient. Also, there is no support for channels yet
- so their usefulness is limited.
-
-
-The ``volatile`` keyword
-------------------------
-
-Go does not have the ``volatile`` keyword like C/C++. This keyword is
-unnecessary in most desktop use cases but is required for memory mapped I/O on
-microcontrollers and interrupt handlers. As a workaround, any variable of a
-type annotated with the ``//go:volatile`` pragma will be marked volatile. For
-example::
-
- //go:volatile
- type volatileBool bool
-
- var isrFlag volatileBool
-
-This is a workaround for a limitation in the Go language and should at some
-point be replaced with something else.
-
-
-Inline assembly
----------------
-
-The device-specific packages like ``device/avr`` and ``device/arm`` provide
-``Asm`` functions which you can use to write inline assembly::
-
- arm.Asm("wfi")
-
-You can also pass parameters to the inline assembly::
-
- var result int32
- arm.AsmFull(`
- lsls {value}, #1
- str {value}, {result}
- `, map[string]interface{}{
- "value": 42,
- "result": &result,
- })
- println("result:", result)
-
-In general, types are autodetected. That is, integer types are passed as raw
-registers and pointer types are passed as memory locations. This means you can't
-easily do pointer arithmetic. To do that, convert a pointer value to a
-``uintptr``.
-
-Inline assembly support is expected to change in the future and may change in a
-backwards-incompatible manner.
-
-
-Harvard architectures (AVR)
----------------------------
-
-The AVR architecture is a modified Harvard architecture, which means that flash
-and RAM live in different address spaces. In practice, this means that any
-given pointer may either point to RAM or flash, but this is not visible from
-the pointer itself.
-
-To get TinyGo to work on the Arduino, which uses the AVR architecutre, all
-global variables (which include string constants!) are marked non-constant and
-thus are stored in RAM and all pointer dereferences assume that pointers point
-to RAM. At some point this should be optimized so that obviously constant data
-is kept in read-only memory but this optimization has not yet been implemented.
diff --git a/docs/moved.rst b/docs/moved.rst
new file mode 100644
index 000000000..c45bf6e68
--- /dev/null
+++ b/docs/moved.rst
@@ -0,0 +1,12 @@
+.. _moved:
+
+.. highlight:: none
+
+The TinyGo Docs Site Has Moved
+=========================
+
+The documentation web site for TinyGo has moved.
+
+You can find the new web site at `tinygo.org <https://tinygo.org/>`_
+
+Thank you!
diff --git a/docs/targets.rst b/docs/targets.rst
deleted file mode 100644
index 0a091c244..000000000
--- a/docs/targets.rst
+++ /dev/null
@@ -1,71 +0,0 @@
-.. _targets:
-
-.. |br| raw:: html
-
- <br>
-
-Supported targets
-=================
-
-TinyGo makes it easy to add new targets. If your target isn't listed here,
-please raise an issue in the `issue tracker
-<https://github.com/aykevl/tinygo/issues>`_.
-
-
-POSIX-like
-----------
-
-Only Linux is supported at the moment, but it should be trivial to add support
-for more POSIX-like systems.
-
-
-ARM / Cortex-M
---------------
-
-Cortex-M processors are well supported. There is support for multiple chips and
-the backend appears to be stable. In fact, it uses the same underlying
-technology (LLVM) as the proprietary ARM compiler for code generation.
-
- * `BBC micro:bit <https://microbit.org/>`_ (`nRF51822
- <https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF51822>`_)
- * `Nordic PCA10031
- <https://www.nordicsemi.com/eng/Products/nRF51-Dongle>`_
- (`nRF51422
- <https://www.nordicsemi.com/eng/Products/ANT/nRF51422>`_)
- * `Nordic PCA10040
- <https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF52-DK>`_
- (`nRF52832
- <https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF52832>`_)
- * `nRF52840-MDK <https://wiki.makerdiary.com/nrf52840-mdk/>`_ (`nRF52840
- <https://www.nordicsemi.com/eng/Products/nRF52840>`_)
- * `reel board <https://www.phytec.eu/product-eu/internet-of-things/reelboard/>`_ (`nRF52840
- <https://www.nordicsemi.com/eng/Products/nRF52840>`_)
- * `Nordic PCA10056 <https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK>`_ (`nRF52840
- <https://www.nordicsemi.com/eng/Products/nRF52840>`_)
- * `QEMU <https://wiki.qemu.org/Documentation/Platforms/ARM>`_ (`LM3S6965
- <http://www.ti.com/product/LM3S6965>`_) |br|
- This target is supported only for testing purposes. It has not been tested
- on real hardware.
-
-
-AVR
----
-
-Note: the AVR backend of LLVM is still experimental so you may encounter bugs.
-
- * `Arduino Uno <https://store.arduino.cc/arduino-uno-rev3>`_ (`ATmega328p
- <https://www.microchip.com/wwwproducts/en/ATmega328p>`_)
- * `Digispark <http://digistump.com/products/1>`_ (`ATtiny85
- <https://www.microchip.com/wwwproducts/en/ATtiny85>`_) |br|
- Very limited support at the moment.
-
-
-WebAssembly
------------
-
-WebAssembly support is relatively new but appears to be stable.
-
-
-.. note::
- Support for the ESP8266/ESP32 chips will take a lot of work if they ever get
- support. See :ref:`this FAQ entry <faq-esp>` for details.
diff --git a/docs/usage.rst b/docs/usage.rst
deleted file mode 100644
index ed5feac71..000000000
--- a/docs/usage.rst
+++ /dev/null
@@ -1,211 +0,0 @@
-.. _usage:
-
-.. highlight:: none
-
-Using ``tinygo``
-================
-
-
-.. note::
- This page assumes you already have TinyGo installed, either :ref:`using
- Docker <docker>` or by :ref:`installing it manualling <installation>`.
-
-
-Subcommands
------------
-
-The TinyGo tries to be similar to the main ``go`` command in usage. It consists
-of the following main subcommands:
-
-``build``
- Compile the given program. The output binary is specified using the ``-o``
- parameter. The generated file type depends on the extension:
-
- ``.o``
- Create a relocatable object file. You can use this option if you don't
- want to use the TinyGo build system or want to do other custom things.
- ``.ll``
- Create textual LLVM IR, after optimization. This is mainly useful for
- debugging.
- ``.bc``
- Create LLVM bitcode, after optimization. This may be useful for
- debugging or for linking into other programs using LTO.
- ``.hex``
- Create an `Intel HEX <https://en.wikipedia.org/wiki/Intel_HEX>`_ file to
- flash it to a microcontroller.
- ``.bin``
- Similar, but create a binary file.
- ``.wasm``
- Compile and link a WebAssembly file.
- (all other)
- Compile and link the program into a regular executable. For
- microcontrollers, it is common to use the .elf file extension to
- indicate a linked ELF file is generated. For Linux, it is common to
- build binaries with no extension at all.
-
-``run``
- Run the program, either directly on the host or in an emulated environment
- (depending on ``-target``).
-
-``flash``
- Flash the program to a microcontroller.
-
-``gdb``
- Compile the program, optionally flash it to a microcontroller if it is a
- remote target, and drop into a GDB shell. From here you can break the
- current program (Ctrl-C), single-step, show a backtrace, etc. A debugger
- must be specified for your particular target in the target .json file and
- the required tools (like GDB for your target) must be installed as well.
-
-``clean``
- Clean the cache directory, normally stored in ``$HOME/.cache/tinygo``. This is
- not normally needed.
-
-``help``
- Print a short summary of the available commands, plus a list of command
- flags.
-
-
-Important build options
------------------------
-
-There are a few flags to control how binaries are built:
-
-``-o``
- Output filename, see the ``build`` command above.
-
-``-target``
- Select the target you want to use. Leave it empty to compile for the host.
- Example targets:
-
- wasm
- WebAssembly target. Creates .wasm files that can be run in a web
- browser.
- arduino
- Compile using the experimental AVR backend to run Go programs on an
- Arduino Uno.
- microbit
- Compile programs for the `BBC micro:bit <https://microbit.org/>`_.
- qemu
- Run on a Stellaris LM3S as emulated by QEMU.
-
- This switch also configures the emulator, flash tool and debugger to use so
- you don't have to fiddle with those options.
-
- Read :ref:`supported targets <targets>` for a list of supported targets.
-
-``-port``
- Specify the serial port used for flashing. This is used for the Arduino Uno,
- which is flashed over a serial port. It defaults to ``/dev/ttyACM0`` as that
- is the default port on Linux.
-
-``-opt``
- Which optimization level to use. Optimization levels roughly follow standard
- ``-O`` level options like ``-O2``, ``-Os``, etc. Available optimization
- levels:
-
- ``-opt=0``
- Disable as much optimizations as possible. There are still a few
- optimization passes that run to make sure the program executes
- correctly, but all LLVM passes that can be disabled are disabled.
- ``-opt=1``
- Enable only a few optimization passes. In particular, this keeps the
- inliner disabled. It can be useful when you want to look at the
- generated IR but want to avoid the noise that is common in non-optimized
- code.
- ``-opt=2``
- A good optimization level for use cases not strongly limited by code
- size. Provided here for completeness. It enables most optimizations and
- will likely result in the fastest code.
- ``-opt=s``
- Like ``-opt=2``, but while being more careful about code size. It
- provides a balance between performance and code size.
- ``-opt=z`` (default)
- Like ``-opt=s``, but more aggressive about code size. This pass also
- reduces the inliner threshold by a large margin. Use this pass if you
- care a lot about code size.
-
-``-ocd-output``
- Print output of the on-chip debugger tool (like OpenOCD) while in a ``tinygo
- gdb`` session. This can be useful to diagnose connection problems.
-
-``-gc``
- Use the specified memory manager.
-
- ``-gc=none``
- Do not use a memory manager at all. This will cause a link error at
- every place in the program that tries to allocate memory. The primary
- use case for this is finding such locations.
-
- ``-gc=dumb``
- Only allocate memory, never free it. This is the simplest allocator
- possible and uses very few resources while being very portable. Also,
- allocation is very fast. Larger programs will likely need a real garbage
- collector.
-
- ``-gc=marksweep``
- Simple conservative mark/sweep garbage collector. This collector does
- not yet work on all platforms. Also, the performance of the collector is
- highly unpredictable as any allocation may trigger a garbage collection
- cycle.
-
-
-Miscellaneous options
----------------------
-
-``-no-debug``
- Disable outputting debug symbols. This can be useful for WebAssembly, as
- there is no debugger for .wasm files yet and .wasm files are generally
- served directly. Avoiding debug symbols can have a big impact on generated
- binary size, reducing them by more than half.
-
- This is not necessary on microcontrollers because debugging symbols are not
- flashed to the microcontroller. Additionally, you will need it when you use
- ``tinygo gdb``. In general, it is recommended to include debug symbols
- unless you have a good reason not to.
-
- Note: while there is some support for debug symbols, only line numbers have
- been implemented so far. That means single-stepping and stacktraces work
- just fine, but no variables can be inspected.
-
-``-size``
- Print size (``none``, ``short``, or ``full``) of the output (linked) binary.
- Note that the calculated size includes RAM reserved for the stack.
-
- ``none`` (default)
- Print nothing.
-
- ``short``
- Print size statistics, roughly like what the ``size`` binutils program
- would print but with useful flash and RAM columns::
-
- code data bss | flash ram
- 5780 144 2132 | 5924 2276
-
- ``full``
- Try to determine per package how much space is used. Note that these
- calculations are merely guesses and can somethimes be way off due to
- various reasons like inlining. ::
-
- code rodata data bss | flash ram | package
- 876 0 4 0 | 880 4 | (bootstrap)
- 38 0 0 0 | 38 0 | device/arm
- 0 0 0 66 | 0 66 | machine
- 2994 440 124 0 | 3558 124 | main
- 948 127 4 1 | 1079 5 | runtime
- 4856 567 132 67 | 5555 199 | (sum)
- 5780 - 144 2132 | 5924 2276 | (all)
-
-
-Compiler debugging
-------------------
-
-These options are designed to make the task of writing the compiler
-significantly easier. They are seldomly useful outside of development work.
-
-``-printir``
- Dump generated IR to the console before it is optimized.
-
-``-dumpssa``
- Dump Go SSA to the console while the program is being compiled. This also
- includes the SSA of package initializers while they are being interpreted.
diff --git a/docs/webassembly.rst b/docs/webassembly.rst
deleted file mode 100644
index 215419c81..000000000
--- a/docs/webassembly.rst
+++ /dev/null
@@ -1,47 +0,0 @@
-.. _webassembly:
-
-
-WebAssembly
-===========
-
-.. highlight:: go
-
-You can call a JavaScript function from Go and call a Go function from WebAssembly::
-
- package main
-
- // This calls a JS function from Go.
- func main() {
- println("adding two numbers:", add(2, 3)) // expecting 5
- }
-
- // This function is imported from JavaScript, as it doesn't define a body.
- // You should define a function named 'main.add' in the WebAssembly 'env'
- // module from JavaScript.
- func add(x, y int)
-
- // This function is exported to JavaScript, so can be called using
- // exports.add() in JavaScript.
- //go:export multiply
- func multiply(x, y int) int {
- return x * y;
- }
-
-
-.. highlight:: javascript
-
-Related JavaScript would look something like this::
-
- // Providing the environment object, used in WebAssembly.instantiateStreaming.
- env: {
- 'main.add': function(x, y) {
- return x + y
- }
- // ... other functions
- }
-
- // Calling the multiply function:
- console.log('multiplied two numbers:', wasm.exports.multiply(5, 3));
-
-A more complete example is provided in the `wasm example
-<https://github.com/aykevl/tinygo/tree/master/src/examples/wasm>`_.