Merge pull request #63 from artob/patch-1
Correct & update native toolchain how-to for macOS
diff --git a/docs/get_started/native_install/native_tools.rst b/docs/get_started/native_install/native_tools.rst
index 1291244..2c9dcd8 100644
--- a/docs/get_started/native_install/native_tools.rst
+++ b/docs/get_started/native_install/native_tools.rst
@@ -6,7 +6,7 @@
:depth: 2
This page shows you how to install the toolchain to build Mynewt OS
-applications that run native on Mac OS and Linux. The applications run
+applications that run native on macOS and Linux. The applications run
on Mynewt's simulated hardware. It also allows you to run the test
suites for all packages that do not require HW support.
@@ -21,11 +21,11 @@
If you have not already installed Homebrew from the ``newt`` tutorials
pages install it (:doc:`../../newt/install/newt_mac`).
-Installing gcc/libc
+Installing GCC/libc
~~~~~~~~~~~~~~~~~~~
-OS X ships with a C compiler called Clang. To build applications for the
-Mynewt simulator with, a different compiler is used as default: gcc.
+macOS with Xcode ships with a C compiler called Clang. To build applications for the
+Mynewt simulator, a different compiler is used as default: ``gcc``.
.. code-block:: console
@@ -33,17 +33,17 @@
...
...
==> Summary
- 🍺 /usr/local/Cellar/gcc/5.2.0: 1353 files, 248M
+ 🍺 /usr/local/Cellar/gcc/8.2.0 (1,495 files, 335.9MB)
-Check the gcc version you have installed (either using brew or
+Check the GCC version you have installed (either using ``brew`` or
previously installed). The brew-installed version can be checked using
``brew list gcc``. The default compiler.yml configuration file in Mynewt
-expects version 5.x for Mac users, so if the installed version is 6.x
+expects version 5.x for Mac users, so if the installed version is newer
and you wish to continue with this newer version, modify the
``<mynewt-src-directory>/repos/apache-mynewt-core/compiler/sim/compiler.yml``
file to change the default ``gcc-5`` defined there to that displayed by
-``brew list gcc`` e.g. ``gcc-6``. In
-other words, replace the lines shown highlighted below:
+``brew list gcc``, e.g. ``gcc-8``.
+In other words, replace the lines shown highlighted below:
.. code-block:: yaml
:emphasize-lines: 2,3
@@ -55,16 +55,16 @@
compiler.path.objsize.DARWIN.OVERWRITE: "objsize"
compiler.path.objcopy.DARWIN.OVERWRITE: "gobjcopy"
-with the following:
+...with the following:
.. code-block:: yaml
- compiler.path.cc.DARWIN.OVERWRITE: "gcc-6"
- compiler.path.as.DARWIN.OVERWRITE: "gcc-6”
+ compiler.path.cc.DARWIN.OVERWRITE: "gcc-8"
+ compiler.path.as.DARWIN.OVERWRITE: "gcc-8”
In case you wish to use Clang, you can change your
``<mynewt-src-directory>/repos/apache-mynewt-core/compiler/sim/compiler.yml``
-to use Clang. Delete the gcc-5 DARWIN.OVERWRITE lines highlighted below.
+to use Clang. Delete the gcc-5 ``DARWIN.OVERWRITE`` lines highlighted below.
.. code-block:: yaml
:emphasize-lines: 2,3
@@ -76,10 +76,10 @@
compiler.path.objsize.DARWIN.OVERWRITE: "objsize"
compiler.path.objcopy.DARWIN.OVERWRITE: "gobjcopy"
-**NOTE:** Both the newer gcc 6.x and Clang report a few warnings but
+**NOTE:** Both the newer GCC versions and Clang report a few warnings but
they can be ignored.
-**FURTHER NOTE:** Mynewt developers mostly use gcc 5.x for sim builds;
+**FURTHER NOTE:** Mynewt developers mostly use GCC 5.x for sim builds;
so it may take a little while to fix issues reported by the newer
compiler. One option is to **disable warnings**. To do that, remove the
``-Werror`` flag as an option for the compiler in the
@@ -106,9 +106,28 @@
compiler.flags.base: >
-m32 -Wall -Werror -ggdb -Wno-misleading-indentation
-A third option is to simply **downgrade to gcc 5.x**.
+A third option is to simply **downgrade to GCC 5.x**:
-Installing gdb
+.. code-block:: console
+
+ $ brew install gcc@5
+
+Note that Homebrew will no longer install GCC 5.x on macOS 10.13 and newer:
+
+.. code-block:: console
+
+ $ brew install gcc@5
+ gcc@5: This formula either does not compile or function as expected on macOS
+ versions newer than High Sierra due to an upstream incompatibility.
+ Error: An unsatisfied requirement failed this build.
+
+In this case, you might try downgrading to GCC 6.x, which is still available:
+
+.. code-block:: console
+
+ $ brew install gcc@6
+
+Installing GDB
~~~~~~~~~~~~~~
.. code-block:: console
@@ -119,7 +138,7 @@
==> Summary
🍺 /usr/local/Cellar/gdb/7.10.1: XXX files,YYM
-**NOTE:** When running a program with gdb, you may need to sign your gdb
+**NOTE:** When running a program with GDB, you may need to sign your ``gdb``
executable. `This
page <https://gcc.gnu.org/onlinedocs/gnat_ugn/Codesigning-the-Debugger.html>`__
shows a recipe for gdb signing. Alternately you can skip this step and
@@ -134,15 +153,15 @@
will need to substitute invocations of *apt-get* in the below steps with
the package manager that your distro uses.
-Install gcc/libc that will produce 32-bit executables:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Installing GCC/libc that will produce 32-bit executables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: console
$ sudo apt-get install gcc-multilib libc6-i386
-Install gdb
-~~~~~~~~~~~
+Installing GDB
+~~~~~~~~~~~~~~
.. code-block:: console
@@ -163,6 +182,6 @@
----
At this point you have installed all the necessary software to build and
-run your first project on a simulator on your Mac OS or Linux computer.
+run your first project on a simulator on your macOS or Linux computer.
You may proceed to :doc:`../project_create` or continue to the next section and install the cross tools for
ARM.
