Update INSTALL-RASPBERRYPI3.md

Update instructions for macOS Mojave.

Change-Id: Ie59bf30845909dbe78ad83bf36fa95a8731d0fa7

1 files changed, 164 insertions, 159 deletions

diff --git a/HOWTO/INSTALL-RASPBERRYPI3.md b/HOWTO/INSTALL-RASPBERRYPI3.md
index 536d095cb4..b9cffbe0c5 100644
--- a/HOWTO/INSTALL-RASPBERRYPI3.md
+++ b/HOWTO/INSTALL-RASPBERRYPI3.md
@@ -4,7 +4,7 @@
 ## Introduction
 
 This document describes how to build a toolchain and cross compile Erlang/OTP
-to Raspberry Pi 3 on macOS High Sierra. It is recommended to consult
+to Raspberry Pi 3 on macOS Mojave. It is recommended to consult
 [Building and Installing Erlang/OTP](https://github.com/erlang/otp/blob/master/HOWTO/INSTALL.md) and [Cross Compiling Erlang/OTP](https://github.com/erlang/otp/blob/master/HOWTO/INSTALL-CROSS.md) before attempting to follow the instructions in this guide.
 
 The whole process takes several hours and depending on the package versions different problems may arise that require additional
@@ -18,9 +18,15 @@ toolchain and sysroot.
 
 #### Tested Configuration
 
-macOS High Sierra 10.13.2<br>
+macOS Mojave 10.14.3<br>
 Raspberry Pi Model B Rev 1.2<br>
-Crosstools-NG 1.23.0_1
+Crosstools-NG 1.23.0_3
+
+```
+build  = x86_64-apple-darwin18.2.0
+host   = x86_64-apple-darwin18.2.0
+target = armv8-rpi3-linux-gnueabihf
+```
 
 > Note: /proc/device/tree/model contains model information of your
 > Raspberry Pi.
@@ -34,10 +40,13 @@ Crosstools-NG 1.23.0_1
     $ brew install grep --default-names # needed by crosstools-ng scripts
     $ brew install md5sha1sum           # needed by crosstools-ng populate script
 
+  (2)
+
+    $ chmod 744 /usr/local/Cellar/crosstool-ng/1.23.0_3/lib/crosstool-ng-1.23.0/scripts/crosstool-NG.sh
 
 #### Create case-sensitive disk images
 
-  (2)
+  (3)
 
 Create two case-sensitive disk images using Disk Utility:
 
@@ -47,47 +56,106 @@ Format: `Mac OS Extended (Case-sensitive, Journaled)`
 
 ```
 /Volumes/xtools-build-env  15 GB
-/Volumes/xtools           500 MB
+/Volumes/xtools            500 MB
 ```
 
-The first image holds all source and object files while building the toolchain. The second image houses the compiled
+> The first image holds all source and object files while building the toolchain. The second image houses the compiled
 toolchain.
 
-## Building the Toolchain
 
+## Building the Toolchain
 
-#### Configure crosstool-ng
+### Environment settings
 
   (4)
 
+    $ ulimit -n 1024
+
+### Inspect target system
+
+  (5)
+
+    $ uname -a
+    Linux raspberrypi 4.9.35-v7+ #1014 SMP Fri Jun 30 14:47:43 BST 2017 armv7l GNU/Linux
+    $ ld -v
+    GNU ld (GNU Binutils for Raspbian) 2.25
+    $ ldd --version
+    ldd (Debian GLIBC 2.19-18+deb8u10) 2.19
+    Copyright (C) 2014 Free Software Foundation, Inc.
+    This is free software; see the source for copying conditions.  There is NO
+    warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+    Written by Roland McGrath and Ulrich Drepper.
+
+> Use the versions available on your target system!
+
+> See https://wiki.osdev.org/Cross-Compiler_Successful_Builds
+
+### Configure crosstool-ng
+
+  (6)
+
+    $ cd /Volumes/xtools-build-env
     $ ct-ng armv8-rpi3-linux-gnueabihf
     $ ct-ng menuconfig
 
-#### Modify *path* section
+#### Path and misc options
+
+##### crosstool-NG behavior
+
+  (7)
+
+```
+[*] Use obsolete features
+
+[*] Debug crosstool-NG
+[ ]   Pause between every steps
+[*]   Save intermediate steps
+[*]     gzip saved states
+[*]   Interactive shell on failed commands
+```
+
+> Should the build break at a particular build step, you can fix the problem and continue the build from where it broke.
+
+##### Paths
+
+  (8)
 
 * Local tarballs directory: `/Volumes/xtools-build-env/src`
 * Working directory: `/Volumes/xtools-build-env/.build`
 * Prefix directory: `/Volumes/xtools/${CT_TARGET}`
 
-#### Modify *Extracting* section
+##### Extracting
+
+  (9)
+
+`[*] Stop after extracting tarballs`
 
-* Check option: _Stop after extracting tarballs_.
+> Stop the build process right after the tarballs have been extracted. This can be handy to fix known source code problems before the actual build process is started.
 
-> Note: The build shall stop after the tarballs have been extracted to give us time to fix source code problems.
+#### Operating System
 
-#### Enable STOP / RESTART
+  (10)
 
-Edit  /Volumes/xtools-build-env/.config
-  `CT_DEBUG_CT_SAVE_STEPS=y`
+`Linux kernel version (4.9.20)`
 
-Should the build break at a particular build step, you can fix the problem and continue the build from where it broke.
+#### Binary utilities
 
-Short summary of the most common `ct-ng` commands:
+  (11)
 
-* Listing all build steps
+`bintutils version (2.28)`
+
+#### C-library
+
+  (12)
+
+`glibc version (2.19 (OBSOLETE))`
+
+#### Sample `ct-ng` commands:
+
+* List all build steps
 
 ```
-    $ ct-ng list-steps
+    $ ct-ng list-steps
 
     Available build steps, in order:
     - companion_tools_for_build
@@ -108,216 +176,153 @@ Short summary of the most common `ct-ng` commands:
     - binutils_for_target
     - debug
     - test_suite
-    - finish
+    - finish
 ```
 
-* Re-run step
-```
-    $ ct-ng step
-```
+* Re-run step `companion_libs_for_host`
 
-* Restart from step
 ```
-    $ ct-ng step+
+    $ ct-ng companion_libs_for_host
 ```
 
-* Run until step
+* Restart from `companion_libs_for_host`
+
 ```
-    $ ct-ng +step
+    $ ct-ng companion_libs_for_host+
 ```
 
-#### Fix file permissions on crosstool-NG.sh
-
-  (5)
-
-    $ chmod 744 /usr/local/Cellar/crosstool-ng/1.23.0_1/lib/crosstool-ng-1.23.0/scripts/crosstool-NG.sh
+* Run until step `companion_libs_for_host`
 
-#### Run build command
+```
+    $ ct-ng +companion_libs_for_host
+```
 
-Build process stops just after the tarballs have been extracted.
+### Build
 
-  (6)
+  (13)
 
     $ ct-ng build
 
-    Retrieving needed toolchain components' tarballs
-    [EXTRA]    Retrieving 'make-4.2.1'
-    [EXTRA]    Retrieving 'm4-1.4.18'
-    [EXTRA]    Retrieving 'linux-4.10.8'
-    [EXTRA]    Retrieving 'gmp-6.1.2'
-    [EXTRA]    Retrieving 'mpfr-3.1.5'
-    [EXTRA]    Retrieving 'isl-0.16.1'
-    [EXTRA]    Retrieving 'mpc-1.0.3'
-    [EXTRA]    Retrieving 'expat-2.2.0'
-    [EXTRA]    Retrieving 'ncurses-6.0'
-    [EXTRA]    Retrieving 'libiconv-1.15'
-    [EXTRA]    Retrieving 'gettext-0.19.8.1'
-    [EXTRA]    Retrieving 'binutils-2.28'
-    [EXTRA]    Retrieving 'gcc-6.3.0'
-    [EXTRA]    Retrieving 'glibc-2.25'
-    [EXTRA]    Retrieving 'gdb-7.12.1'
+> Build process stops just after the tarballs have been extracted.
 
 #### Fix source files
 
-  (7)
-
-Add macro to /Volumes/xtools-build-env/.build/src/gdb-7.12.1/gdb/doublest.c:
-```C
-#define min(a,b) \
-  ({ typeof (a) _a = (a); \
-      typeof (b) _b = (b); \
-    _a < _b ? _a : _b; })
-```
-
-  (8) Update ulimit
+  (14)
 
-    $ ulimit -n 1024
+    $ pushd .build/src/gettext-0.19.8.1/
+    $ autoreconf
+    $ popd
 
-#### Modify *extract* section
+#### Update configuration
 
-  (8)
+  (15)
 
     $ ct-ng menuconfig
 
- Uncheck option: _Stop after extracting tarballs_
+Uncheck option:
 
-#### Re-run build command
+`[ ] Stop after extracting tarballs`
 
-Restarts build process from where it previously stopped.
+#### Continue build
 
-  (9)
+  (16)
 
     $ ct-ng build
 
-#### Fix gettext
+> Restart build process from where it previously stopped.
 
-Build will fail at step `companion_tools_for_build` but it can be fixed by running autoreconf:
+  (17)
 
-  (10)
+    $ export PATH=/Volumes/xtools/armv8-rpi3-linux-gnueabihf/bin:$PATH
 
-    $ cd .build/src/gettext-0.19.8.1/
-    $ ./autoreconf
-    $ ct-ng companion_tools_for_build+
+### Test
 
-#### Test the toolchain
-
-  (11)
+  (18)
 
     $ cat > test.c
     $ int main() { printf("Hello, world!\n"); return 0; }
-    $ /Volumes/xtools/arm-unknown-linux-gnueabi-gcc -o test test.c
-
-  (12) OPTIONAL
-
-    “Render the toolchain read-only” from crosstool-NG’s “Paths and misc options” configuration page.
+    <CTRL+D>
+    $ armv8-rpi3-linux-gnueabihf-gcc -o test test.c
 
 
 ## Cross compiling dependencies
 
-  (13)
+  (19)
 
-    $ export PATH=/Volumes/xtools/armv8-rpi3-linux-gnueabihf/bin:$PATH
+    $ mkdir local # prefix directory
+    $ mkdir 3pps  # OTP dependencies
+    $ cd 3pps
 
-#### Cross compiling zlib
+#### zlib
 
-  (14)
+  (20)
 
     $ wget http://zlib.net/zlib-1.2.11.tar.gz
     $ tar xf zlib-1.2.11.tar.gz
-    $ cd zlib-1.2.11
-    $ CHOST=armv8-rpi3-linux-gnueabihf ./configure --prefix=/Users/<username>/git/raspberrypi/arm
+    $ pushd zlib-1.2.11
+    $ CHOST=armv8-rpi3-linux-gnueabihf ./configure --prefix=/Volumes/xtools-build-env/local
     $ make
     $ make install
+    $ popd
 
-#### Cross compiling openssl
+#### openssl
 
-  (15)
+  (21)
 
-    $ wget http://openssl.org/source/openssl-1.1.0g.tar.gz
-    $ tar xf openssl-1.1.0g.tar.gz
-    $ cd openssl-1.1.0g
-    $ ./Configure linux-generic32 --prefix=/Users/<username>/git/raspberrypi/arm --openssldir=/Users/<username>/git/raspberrypi/arm/openssl --cross-compile-prefix=armv8-rpi3-linux-gnueabihf
+    $ wget http://openssl.org/source/openssl-1.1.1b.tar.gz
+    $ tar xf openssl-1.1.1b.tar.gz
+    $ pushd  openssl-1.1.1b
+    $ ./Configure linux-generic32 --prefix=/Volumes/xtools-build-env/local \
+    --openssldir=/Volumes/xtools-build-env/local/openssl \
+    --cross-compile-prefix=armv8-rpi3-linux-gnueabihf-
     $ make
     $ make install
+    $ popd
 
-#### Cross compiling ncurses
-
-  (16)
-
-    $ wget http://ftp.gnu.org/pub/gnu/ncurses/ncurses-5.9.tar.gz
+> A compatible openssl library shall be available on the target system!
 
+#### ncurses
 
-  (17)
-
-Apply patch:
-
-```patch
---- a/ncurses/base/MKlib_gen.sh
-+++ b/ncurses/base/MKlib_gen.sh
-@@ -474,11 +474,22 @@ sed -n -f $ED1 \
-    -e 's/gen_$//' \
-    -e 's/  / /g' >>$TMP
-
-+cat >$ED1 <<EOF
-+s/  / /g
-+s/^ //
-+s/ $//
-+s/P_NCURSES_BOOL/NCURSES_BOOL/g
-+EOF
-+
-+# A patch discussed here:
-+#  https://gcc.gnu.org/ml/gcc-patches/2014-06/msg02185.html
-+# introduces spurious #line markers.  Work around that by ignoring the system's
-+# attempt to define "bool" and using our own symbol here.
-+sed -e 's/bool/P_NCURSES_BOOL/g' $TMP > $ED2
-+cat $ED2 >$TMP
-+
- $preprocessor $TMP 2>/dev/null \
--| sed \
--   -e 's/  / /g' \
--   -e 's/^ //' \
--   -e 's/_Bool/NCURSES_BOOL/g' \
-+| sed -f $ED1 \
- | $AWK -f $AW2 \
- | sed -f $ED3 \
- | sed \
-```
+  (22)
 
-  (18)
-
-    $ ./configure --build=x86_64-apple-darwin17.3.0 --host=armv8-rpi3-linux-gnueabihf --without-ada --without-cxx --without-cxx-binding --without-manpages --without-progs --without-tests --prefix=/usr --libdir=/lib --with-build-cc="gcc -D_GNU_SOURCE" --with-shared
+    $ wget http://ftp.gnu.org/pub/gnu/ncurses/ncurses-5.9.tar.gz
+    $ tar xf ncurses-5.9.tar.gz
+    $ pushd ncurses-5.9
+    $ wget https://gist.githubusercontent.com/peterdmv/1068b2f9e1fec6e1330ad62ed87461ad/\
+    raw/065597b63654ed6a9f28d02fdfbca844413847ad/ncurses-5.9.patch
+    $ patch -p0 < ncurses-5.9.patch
+    $ ./configure --build=x86_64-apple-darwin18.2.0 --host=armv8-rpi3-linux-gnueabihf \
+    --without-ada --without-cxx --without-cxx-binding --without-manpages \
+    --without-progs --without-tests --prefix=/usr --libdir=/lib \
+    --with-build-cc="gcc -D_GNU_SOURCE" --with-shared
     $ make
-    $ make DESTDIR=/Users/<username>/git/raspberrypi/arm install
-
-  (19)
-
-Compile ncurses test program:
-
-    $ cd test
-    $ armv8-rpi3-linux-gnueabihf-gcc -o nctest ncurses.c -I${RPI_SYSROOT}/usr/include -L${RPI_SYSROOT}/lib -lncursesw
+    $ make DESTDIR=/Volumes/xtools-build-env/local install
+    $ popd
 
 
 ## Populating sysroot
 
-  (19)
-
-    Edit /Volumes/xtools/armv8-rpi3-linux-gnueabihf/bin/armv8-rpi3-linux-gnueabihf-populate:
+  (23)
 
-    sed="gsed"
+    $ chmod 755 /Volumes/xtools/armv8-rpi3-linux-gnueabihf/bin
+    $ chmod 755 /Volumes/xtools/armv8-rpi3-linux-gnueabihf/bin/armv8-rpi3-linux-gnueabihf-populate
+    $ gsed -i 's/"sed"/"gsed"/g' \
+    /Volumes/xtools/armv8-rpi3-linux-gnueabihf/bin/armv8-rpi3-linux-gnueabihf-populate
+    $ chmod 555 /Volumes/xtools/armv8-rpi3-linux-gnueabihf/bin
+    $ chmod 555 /Volumes/xtools/armv8-rpi3-linux-gnueabihf/bin/armv8-rpi3-linux-gnueabihf-populate
 
-  (20)
+  (24)
 
-    $ armv8-rpi3-linux-gnueabihf-populate -s /Users/<username>/git/raspberrypi/arm -d /Users/<username>/git/raspberrypi/sysroot
-    $ export RPI_SYSROOT=/Users/<username>/git/raspberrypi/sysroot
+    $ armv8-rpi3-linux-gnueabihf-populate -s /Volumes/xtools-build-env/local \
+    -d /Volumes/xtools-build-env/sysroot
+    $ export RPI_SYSROOT=/Volumes/xtools-build-env/sysroot
 
 
 ## Cross compiling Erlang/OTP
 
-  (21)
+  (25)
 
     $ LC_CTYPE=C && LANG=C && ./otp_build autoconf
-    $ ./otp_build configure --disable-dynamic-ssl-lib --xcomp-conf=./xcomp/erl-xcomp-armv8-rpi3-linux-gnueabihf.conf
+    $ ./otp_build configure --xcomp-conf=./xcomp/erl-xcomp-armv8-rpi3-linux-gnueabihf.conf
     $ ./otp_build boot -a
-    $ ./otp_build release -a /Users/<username>/git/raspberrypi/erlang
-    $ tar czf erlang.tgz ./erlang
-
+    $ ./otp_build release -a /Volumes/xtools-build-env/otp_22.0