Merge pull request #688 from jepler/atsamd-build-reqs

Better document build requirements and steps

1 files changed, 28 insertions, 1 deletions

diff --git a/ports/atmel-samd/README.rst b/ports/atmel-samd/README.rst
index 8785ccada..c74407b0a 100644
--- a/ports/atmel-samd/README.rst
+++ b/ports/atmel-samd/README.rst
@@ -115,16 +115,43 @@ PB03                   **Yes**                         **Yes**  **Yes**  **Yes**
 
 Setup
 -----
-Install required compiler packages:
+
+An ARM compiler is required for the build, along with the associated binary
+utilities.  On Ubuntu, these can be installed as follows:
 
 .. code-block:: shell
 
     sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
     sudo apt-get install gcc-arm-embedded
 
+On Arch Linux the compiler is available for via the package
+``arm-none-eabi-gcc``.
+
+For other systems, the `GNU Arm Embedded Toolchain <https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads>`_
+may be available in binary form.
+
+The latest available package from team-gcc-arm-embedded is used to produce the
+binaries shipped by AdaFruit.  Other compiler versions, particularly older
+ones, may not work properly.  In particular, the ``gcc-arm-none-eabi`` package
+in Debian Stretch is too old.
+
+The compiler can be changed using the ``CROSS_COMPILE`` variable when invoking
+``make``.
+
 Building
 --------
 
+Before building the firmware for a given board the MicroPython cross-compiler
+must be built; it will be used to pre-compile some of the built-in scripts to
+bytecode.  The cross-compiler is built and run on the host machine, using:
+
+.. code-block:: shell
+
+    make -C mpy-cross
+
+This command should be executed from the root directory of this repository.
+All other commands below should be executed from the ports/atmel-samd/ directory.
+
 To build for the Arduino Zero:
 
 .. code-block:: shell