Updated README with macOS instructions

Closes: #1780

[skip ci]

README.md

@@ -298,8 +298,8 @@ cp slicot.a /home/$USER/dynare/slicot/lib/libslicot_pic.a #for octave
 # compile x13as from source and put it into /usr/bin/
 mkdir -p /home/$USER/dynare/x13as
 cd /home/$USER/dynare/x13as
-wget https://www.census.gov/ts/x13as/unix/x13assrc_V1.1_B39.tar.gz
-tar xf x13assrc_V1.1_B39.tar.gz
+wget https://www2.census.gov/software/x-13arima-seats/x13as/unix-linux/program-archives/x13as_asciisrc-v1-1-b58.tar.gz
+tar xf x13as_asciisrc-v1-1-b58.tar.gz
 sed -i "s|-static| |" makefile.gf # this removes '-static' in the makefile.gf
 make -f makefile.gf FFLAGS="-O2 -std=legacy" PROGRAM=x13as
 sudo cp x13as /usr/bin/
@@ -401,54 +401,118 @@ adapted to a 32-bit MATLAB with the following modifications:
 currently not supported.
 
 ## macOS
+Dynare supports both Intel and Apple Silicon chips and is compiled from source
+using a [Homebrew](https://brew.sh/) toolchain. However, if you have a *M1*, *M1 PRO*
+or *M1 MAX* processor, you need to make sure that you are not using the ARM
+Homebrew packages. This is due to the fact that although MATLAB runs natively on
+Intel, it is not yet available in an ARM version and therefore must be run with the
+Intel compatibility layer called Rosetta 2. Accordingly, if you are on Apple Silicon
+you need to compile Dynare under Rosetta 2 as well and use the Intel packages from
+Homebrew. You can check this by e.g. running `which brew` which should point to
+`/usr/local/bin/brew` and not to `/opt/homebrew/bin/brew`. In the steps below, we
+create a temporary alias to ensure that `brew` points to the Intel packages.
 
-Preparatory work:
+For the following steps open Terminal.app and enter the commands listed below.
 
-- Install the Xcode Command Line Tools. Open Terminal.app and type:
+
+### Preparatory work
+
+- Install Rosetta 2 (Apple Silicon only):
+```sh
+softwareupdate --install-rosetta --agree-to-license
+```
+
+- Install the Xcode Command Line Tools:
 ```sh
 xcode-select --install
 ```
-- Install [Homebrew](https://brew.sh/) by following the instructions on their website
-- Install [MacTeX](http://www.tug.org/mactex/index.html). Alternatively, if you
-  don’t want to install MacTeX, you should pass the `--disable-doc` flag to the
-  `configure` command below.
-- Install required Homebrew packages. Open Terminal.app and type:
+
+- Install [Homebrew](https://brew.sh/):
+```sh
+arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+The prefix `arch -x86_64` makes sure that you are using Rosetta 2 to install Homebrew.
+
+- Apple Silicon only: Make a (temporary) alias to run `brew` under Rosetta 2:
+```sh
+alias brew='arch -x86_64 /usr/local/bin/brew'
+which brew
+#brew: aliased to arch -x86_64 /usr/local/bin/brew
+```
+
+- Install required Homebrew packages and link sphinx-doc:
 ```sh
 brew install automake bison flex boost gcc gsl libmatio veclibfort octave sphinx-doc wget
 brew link --force sphinx-doc
 ```
-- Compile and install SLICOT, needed for the `kalman_steady_state` MEX file.
-Still from Terminal.app:
+
+- Install [MacTeX](http://www.tug.org/mactex/index.html) using the universal installer. MacTeX runs natively on both ARM and Intel machines. On Apple Silicon, we need to put `pdflatex` and `bibtex` into our path:
 ```sh
+ln -s /Library/TeX/texbin/pdflatex /usr/local/bin/pdflatex
+ln -s /Library/TeX/texbin/bibtex /usr/local/bin/bibtex
+```
+Alternatively, if you don’t want to install MacTeX, you should pass the `--disable-doc` flag to the `configure` command below.
+
+- Install MATLAB and additional toolboxes. We recommend, but don't require, the following: Optimization, Global Optimization, Statistics and Machine Learning, Econometrics, and Control System. As there is no ARM version of MATLAB yet,  Rosetta 2 will be used on Apple Silicon machines. Don't forget to run MATLAB at least once to make sure you have a valid license.
+
+- Compile and install SLICOT, needed for the `kalman_steady_state` MEX file.
+```sh
+mkdir -p $HOME/dynare/slicot
+cd $HOME/dynare/slicot
 wget https://deb.debian.org/debian/pool/main/s/slicot/slicot_5.0+20101122.orig.tar.gz
 tar xf slicot_5.0+20101122.orig.tar.gz
 cd slicot-5.0+20101122
-make -j$(nproc) FORTRAN=gfortran OPTS="-O2" LOADER=gfortran lib
+make -j$(sysctl -n hw.physicalcpu) FORTRAN=gfortran OPTS="-O2" LOADER=gfortran lib
 cp slicot.a /usr/local/lib/libslicot_pic.a
 make clean
-make -j$(nproc) FORTRAN=gfortran OPTS="-O2 -fdefault-integer-8" LOADER=gfortran lib
+make -j$(sysctl -n hw.physicalcpu) FORTRAN=gfortran OPTS="-O2 -fdefault-integer-8" LOADER=gfortran lib
 cp slicot.a /usr/local/lib/libslicot64_pic.a
-cd ..
+cd $HOME/dynare
 ```
 
+- Compile and install the X-13ARIMA-SEATS Seasonal Adjustment Program
+```sh
+mkdir -p $HOME/dynare/x13as
+cd $HOME/dynare/x13as
+wget https://www2.census.gov/software/x-13arima-seats/x13as/unix-linux/program-archives/x13as_asciisrc-v1-1-b58.tar.gz
+tar xf x13as_asciisrc-v1-1-b58.tar.gz
+sed -i '' 's/-static//g' makefile.gf
+make -j$(sysctl -n hw.physicalcpu) -f makefile.gf FC=gfortran LINKER=gfortran FFLAGS="-O2 -std=legacy" PROGRAM=x13as
+cp x13as /usr/local/bin/x13as
+cd ;
+x13as
+```
+
+### Compile Dynare from source
 The following commands will download the Dynare source code and compile
 it. They should be entered at the command prompt in Terminal.app from the
-folder where you want Dynare installed.
+folder where you want Dynare installed. Apple Silicon: make sure `brew`
+points towards `/usr/local/bin/brew` (see above).
 
-- Prepare the Dynare sources:
+- Prepare the Dynare sources for the unstable version:
 ```sh
-git clone --recurse-submodules https://git.dynare.org/Dynare/dynare.git
-cd dynare
-autoreconf -si
+mkdir -p $HOME/dynare/unstable
+git clone --recurse-submodules https://git.dynare.org/Dynare/dynare.git $HOME/dynare/unstable
+cd $HOME/dynare/unstable
+arch -x86_64 autoreconf -si
 ```
+You can also choose a specific version of Dynare by checking out the corresponding branch or a specific tag with git.
+
 - Configure Dynare from the source directory:
 ```sh
-./configure --with-matlab=<…> CC=gcc-11 CXX=g++-11 CPPFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib LEX=/usr/local/opt/flex/bin/flex YACC=/usr/local/opt/bison/bin/bison
+arch -x86_64 ./configure CC=gcc-11 CXX=g++-11 CPPFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib LEX=/usr/local/opt/flex/bin/flex YACC=/usr/local/opt/bison/bin/bison --with-matlab=/Applications/MATLAB_R2021b.app
 ```
-where the path to MATLAB is specified, typically of the form
-`/Applications/MATLAB_R2020b.app`. If you don’t have MATLAB, simply replace
-`--with-matlab=<…>` in the above command by `--disable-matlab`.
+where you need to adapt the path to MATLAB. If you don’t have MATLAB, simply replace `--with-matlab=<…>` by `--disable-matlab`. Check the output of the command whether Dynare is configured for building everything except the internal docs of Dynare, Dynare++ and M2HTML.
+
 - Compile:
 ```sh
-make -j$(nproc)
+arch -x86_64 make -j$(sysctl -n hw.physicalcpu)
 ```
+
+### Optional: pass the full PATH to MATLAB to run system commands
+If you start MATLAB from a terminal, you will get the PATH inherited from the shell. However, when you click on the icon in macOS, you are not running at the terminal: the program is run by launcher, which does not go through a shell login session. You get the system default PATH which includes `/usr/bin:/bin:/usr/sbin:/sbin`, but not `/usr/local/bin` or `$HOME/.local/bin`. So if you want to use system commands like `pdflatex` or `x13as` you should either call them by their full path (e.g `/Library/TeX/texbin/pdflatex`) or append the PATH in MATLAB by running `setenv('PATH', [getenv('PATH') ':/usr/local/bin:$HOME/.local/bin:/Library/TeX/texbin']);`. Alternatively, you can create a `startup.m` file or change the system default PATH in the `/etc/paths` file.
+
+Tested on
+- macOS Monterey 12.1 (Apple M1 Virtual Machine)
+- macOS Monterey 12.1 (MacBook Air Intel)
+- macOS Monterey 12.1 (MacBook Air M1)