docs: add command line subcommands + flags documentation

8 files changed, 198 insertions, 6 deletions

diff --git a/docs/docker.rst b/docs/docker.rst
index f64342d52..609f02f88 100644
--- a/docs/docker.rst
+++ b/docs/docker.rst
@@ -1,4 +1,4 @@
-.. docker:
+.. _docker:
 
 .. highlight:: none
 
diff --git a/docs/faq.rst b/docs/faq.rst
index 1ecbc7453..8464910d3 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -1,4 +1,4 @@
-.. faq:
+.. _faq:
 
 Frequently Asked Questions
 ==========================
diff --git a/docs/index.rst b/docs/index.rst
index 97c4c1c86..8e79198e3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,6 +13,7 @@ Contents:
 
    installation
    docker
+   usage
    targets
    microcontrollers
    webassembly
diff --git a/docs/installation.rst b/docs/installation.rst
index 7a3670adf..f1719a946 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -1,4 +1,4 @@
-.. installation:
+.. _installation:
 
 .. highlight:: none
 
diff --git a/docs/internals.rst b/docs/internals.rst
index d04805463..27a8c98bb 100644
--- a/docs/internals.rst
+++ b/docs/internals.rst
@@ -1,4 +1,4 @@
-.. internals:
+.. _internals:
 
 Compiler internals
 ==================
diff --git a/docs/microcontrollers.rst b/docs/microcontrollers.rst
index 0e764643a..4ddc5c7f8 100644
--- a/docs/microcontrollers.rst
+++ b/docs/microcontrollers.rst
@@ -1,4 +1,4 @@
-.. microcontrollers:
+.. _microcontrollers:
 
 .. highlight:: go
 
diff --git a/docs/targets.rst b/docs/targets.rst
index 3c8b300e7..6f7c6d96a 100644
--- a/docs/targets.rst
+++ b/docs/targets.rst
@@ -1,4 +1,4 @@
-.. targets:
+.. _targets:
 
 .. |br| raw:: html
 
diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644
index 000000000..cb74e2408
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,191 @@
+.. _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.
+
+
+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.