MacOS Quick Start: Difference between revisions

From Miosix Wiki
Jump to navigation Jump to search
No edit summary
m (MacOS is now called macOS.)
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
ATTENTION: This page is still a WIP. Usual disclaimers about not taking responsibility for your system disruption applies.
{{DISPLAYTITLE:macOS Quick Start}}
This page explains how to install the precompiled Miosix Toolchain, which since January 2023 is also available for macOS. The building instructions previously found on this page have been updated and moved to [[Building GCC from sources]].


Note January 2023: a precompiled version of the Miosix toolchain for Mac OS is available in the [[Miosix Toolchain]] page.
Both macOS and Linux are POSIX-conformant Unix-like systems, therefore the steps required to get started with Miosix are very similar. This guide only covers the differences between the steps outlined in [[Linux Quick Start]] and the steps needed for macOS. Therefore reading the [[Linux Quick Start]] page is recommended first.


=== Before you begin ===
== Before you begin ==


This procedure has been tested on macOS Catalina 10.15. The Miosix toolchain has been successfully compiled using GCC 9.2.0, which can be installed using the Homebrew package manager.
=== Installing the Command Line Tools ===


macOS provides essentials tools for developing software ([https://clang.llvm.org clang]-based C and C++ compilers, [https://git-scm.com git], and more) in a separate package called the ''Command Line Tools for Xcode''. Despite the name, these tools do not require Xcode to be also installed, and since Xcode is a multi-gigabyte application which eats up quite the amount of disk space, you should '''not''' install Xcode, unless you are sure you need it for some other non-Miosix-related reason.


'''Install Xcode'''
To install the Command Line Tools open Terminal.app and then run the following command:


Install Xcode by downloading it from the Mac App Store [https://apps.apple.com/au/app/xcode/id497799835?mt=12 here]. This is needed for installing the XCode command line tools which in turn is needed by Homebrew.
<syntaxhighlight>
 
 
'''Install Xcode Command Line Tools'''
 
Install the Command Line Tools by running the following command in terminal:
 
<source lang="bash">
xcode-select --install
xcode-select --install
</source>
</syntaxhighlight>


It is recommended to run the command even if Xcode and the Command Line Tools were already installed on your system, since the Command Line Tools installation may have been messed up by upgrading to 10.15 from a previous release.
Then follow the instructions on screen to complete the installation.


=== Installing STM32-specific tools ===


'''Install Homebrew'''
STM32 microcontrollers are the most important target for Miosix, and programming them requires specialized tools which on Linux are often installed through a package manager.


Grab a copy of Homebrew and run the install script in one step using this command in terminal:
In contrast to Linux but similarly to Windows, macOS does not provide a system package manager. However, thanks to community efforts, there are two third-party package managers for macOS that provide a similar experience to Linux for easily installing tools and programs on the command line: [https://brew.sh Homebrew] and [https://www.macports.org MacPorts]. Both of them provide all packages you need to get started with development on STM32 MCUs.


<source lang="bash">
In the following discussion we will assume you have Homebrew available and installed on your system. If you prefer MacPorts, you can search the same packages (or 'ports') on the [https://ports.macports.org MacPorts port index].
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
</source>


If it complains about permission issues, then you have to fix it before you can continue. Since Mac OS X El Capitan 10.11, Apple introduced a new feature called System Integrity Protector (SIP), which prevents from writing to many system directories such as /usr, /System, /bin, regardless of whether or not you are root.
With Homebrew, installing st-flash and stm32flash can be performed through the following commands:
Also, if you have never opened Xcode before, it will ask you to agree to the license by opening Xcode.app or running:
 
<source lang="bash">
sudo xcodebuild -license
</source>
 
 
=== System dependencies installation ===
 
'''Install GNU tar'''
 
Running the Miosix toolchain compilation script may give you an error related to extracting a file. Therefore, using GNU tar instead of Apple tar is suggested.


<syntaxhighlight>
brew install stlink
brew install stm32flash
</syntaxhighlight>


Run this command in terminal to grab the most recent packages list from Homebrew:
QSTLink2 is not supported on macOS.


<source lang="bash">
==== Homebrew, macOS, and filesystem permissions ====
brew update
</source>


Homebrew specifically forbids being run with elevated privileges using <code>sudo</code> when installing packages. This is different than what all other package managers (on Linux and macOS) do.


Run this command to install GNU tar:
[https://docs.brew.sh/FAQ#why-does-homebrew-say-sudo-is-bad According to Homebrew's developers], this approach purportedly has the advantage of reducing the attack surface of a hypothetic malware that modifies Homebrew's executables for malicious purposes, but it makes it possible for malware to modify all of the files installed by Homebrew easily (as executable distributed by Homebrew are often not signed).


<source lang="bash">
Other package managers such as MacPorts (or all Linux-based package managers for the various distributions) run as root (or as a specialized user with reduced privileges) in order to make it more difficult for malware to tamper any file in the package manager's prefix, and to prevent un-authorized users from modifying the set of packages installed.
brew install gnu-tar
</source>


However tampering files installed by a package manager on macOS does not appear to be a popular attack vector for malware, thanks to the additional restrictions imposed on top of the standard Unix user permission system by the TCC subsystem in macOS ([https://eclecticlight.co/2023/02/11/permissions-sip-and-tcc-whos-controlling-access/ read this article] if you don't know what we are talking about). As a result the field importance of the security implications of Homebrew's choice about the ownership of all installed packages is not entirely clear.


'''Install GCC 9.2.0'''
However, being aware of the tradeoff being made is something to be aware of before you choose to install Homebrew or MacPorts, depending on your security-related preferences.


Running the Miosix toolchain compilation script using Apple GCC has proven unsuccessful. That's why we need to install GCC 9.2.0 from Homebrew. Perform the steps below:
=== Serial port setup ===


Serial port devices are available in <code>/dev</code> just like in Linux, however macOS sets the permissions of the device files such that read and write access are available for all groups and users. There is no need to add you user to the <code>dialup</code> group like on Linux.


Run this command in terminal to grab the most recent packages list from Homebrew:
macOS ships with <code>screen</code> built-in, there is no need to install it separately. If you find <code>screen</code> uncomfortable to use for accessing serial ports, we recommend you use [https://github.com/tio/tio tio], which can be installed via Homebrew with this command:


<source lang="bash">
<syntaxhighlight>
brew update
brew install tio
</source>
</syntaxhighlight>


== Install the Miosix Toolchain ==


Run this command to install GCC 9.2.0:
Download the latest version of the toolchain from the link provided in the [[Miosix Toolchain]] page. Make sure to install the macOS installable package, and not the Linux or Windows ones. Then you can install the toolchain by double-clicking the downloaded .pkg file.


<source lang="bash">
If the installer does not open and the following dialog box shows up:
brew install gcc@9
</source>


[[File:MacOS unidentified developer.png|The dialog box shown when Gatekeeper prevents opening an installer package.]]


'''Symlink GCC 9.2.0 executables'''
click with the right mouse button on the installer package (or click while pressing the ''control'' key on the keyboard) and select Open from the contextual menu. The dialog box will now let you open the package.


First, you need to create appropriate symlinks within /usr/local/bin from the versioned name of gcc executables to generic ones. Run these commands from terminal:
Follow the steps presented by the assistant to install the Miosix toolchain on your system. If you are using an Apple Silicon (ARM) Mac, the installer will automatically propose to install Rosetta for you in case it is not already installed.


<source lang="bash">
== Get, configure, and compile the Miosix kernel sources ==
ln -s /usr/local/bin/gcc-9 /usr/local/bin/gcc
ln -s /usr/local/bin/gcc-9 /usr/local/bin/cc
ln -s /usr/local/bin/g++-9 /usr/local/bin/g++
ln -s /usr/local/bin/cpp-9 /usr/local/bin/cpp
ln -s /usr/local/bin/c++-9 /usr/local/bin/c++
</source>


Please notice that gcc-9.2 has not been symlinked to ld has someone may expect, since it has proven prone to errors during the Miosix toolchain compilation. Instead, we are gonna use Apple own Clang ld as a linker.
At this point you can start following the steps outlined in [[Linux Quick Start#Configuring and compiling the kernel]] without modifications.
 
 
'''Edit $PATH variable'''
 
Now you need to make sure that /usr/local/bin gets inspected before /usr/bin when looking for gcc, so that Homebrew GCC 9.2.0 will be called instead of Apple GCC. In order to do so, we are gonna modify the $PATH terminal variable. Run from terminal:
 
<source lang="bash">
cd
</source>
 
To get into your home folder.
 
 
Run from terminal:
 
<source lang="bash">
edit .bash_profile
</source>
 
To edit the bash profile script.
 
 
You need to add the following lines as they are:
 
<source lang="bash">
#homebrew gcc
export PATH=/usr/local/bin:$PATH
#gnu-tar
export PATH=/usr/local/opt/gnu-tar/libexec/gnubin:$PATH
</source>
 
Save and close the file.
 
 
Then run from terminal:
 
<source lang="bash">
source .bash_profile
</source>
 
in order to reload the bash profile script.
 
 
'''Check the installed packages'''
 
If everything went as supposed, running from terminal:
 
<source lang="bash">
gcc -v
</source>
 
should return some text including:
 
<source lang="bash">
gcc version 9.2.0 (Homebrew GCC 9.2.0_2)
</source>
 
 
While running from terminal:
 
<source lang="bash">
ld -v
</source>
 
should return some text including:
 
<source lang="bash">
LTO support using: LLVM version 11.0.3
</source>
 
'''Install the following dependencies'''
 
<source lang="bash">
make, ncurses, byacc, flex, texinfo, patchutils, unzip, lzip, libelf, perl, expat, wget
</source>
Unfortunately they have to be installed one by one with brew.
 
GNU make will be installed as gmake, to use it as make, edit the PATH from the bashrc like:
<source lang="bash">
PATH="/usr/local/opt/make/libexec/gnubin:$PATH"
</source>
 
=== Toolchain compilation and installation ===
 
'''Toolchain sources download'''
 
In order to download the kernel and toolchains sources, you need git. If you don't have it already, you can install it using Homebrew:
 
<source lang="bash">
brew install git
</source>
 
 
From terminal, cd to a folder of your choice, making sure that the path from root to it doesn't contain spaces or special characters. Then run:
 
<source lang="bash">
git clone https://miosix.org/git-public/miosix-kernel.git
cd miosix-kernel
git fetch origin
</source>
To select the development version of the kernel
<source lang="bash">
git checkout -b testing origin/testing
</source>
 
Please note that currently, the ''master'' branch contains the stable 2.0 kernel, while the ''testing'' branch contains the current development version. Usually the latter contains the latest updates made, especially support packages for new boards, so its advised to use the code contained in this branch.
 
 
 
Make sure to be in a path without spaces, or compiling will fail.
 
Example:
<source lang="bash">
/home/foo/temp                          OK
/home/foo/directory with spaces/temp    NO!!
</source>
 
move to the compiler directory:
 
<source lang="bash">
cd miosix-kernel/miosix/_tools/compiler/gcc-9.2.0-mp3.1
</source>
If you prefer to have the toolchain in a different folder from the kernel tree, move this folder in another directory and then continue.
 
'''Toolchain dependencies download'''
 
Now you need to run the dependencies download script. From terminal, run:
 
<source lang="bash">
sh download.sh
</source>
 
from the folder where you performed the git clone command.
 
 
'''Toolchain compilation'''
 
System-wide installation of the toolchain is currently untested. It is then suggested to install it locally and then add its location the the $PATH.
First, edit the install script located at:
 
<source lang="bash">
miosix-kernel/miosix/_tools/compiler/gcc-9.2.0-mp3.1/install-script.sh
</source>
 
 
such that at the end the first few lines looks as follow:
 
<source lang="bash">
 
# Uncomment if installing globally on the system
 
#INSTALL_DIR=/opt/arm-miosix-eabi
 
#SUDO=sudo
 
# Uncomment if installing locally, sudo isn't necessary
 
INSTALL_DIR=`pwd`/gcc/arm-miosix-eabi
 
SUDO=
</source>
 
One can decide to install the toolchain globally, in that case uncomment the correct lines and substitute /opt with /usr/local/opt
 
We can now finally run the compilation script. From terminal, run:
 
<source lang="bash">
sh install-script.sh -j'nproc'
</source>
 
 
At the end, if everything worked correctly, you'll find the toolchain at:
 
<source lang="bash">
miosix-kernel/miosix/_tools/compiler/gcc-9.2.0-mp3.1/gcc/arm-miosix-eabi/bin
</source>
 
 
'''Toolchain compilation and installation'''
 
Now you need to add the toolchain to your path. Edit the bash profile script and add the following lines:
 
<source lang="bash">
#arm-miosix-eabi
export PATH={my-folder-of-choice-path}/miosix-kernel/miosix/_tools/compiler/gcc-9.2.0-mp3.1/gcc/arm-miosix-eabi/bin:$PATH
</source>
 
where you have to replace {my-folder-of-choice-path} with the path of the folder where you run the git clone command.
 
 
Then run from terminal:
 
<source lang="bash">
source .bash_profile
</source>
 
in order to reload the bash profile script.
 
 
'''Cleanup'''
 
You are now free to go back to Apple tar and GCC. In order to do so, edit the bash profile script and remove the following lines:
 
<source lang="bash">
#homebrew gcc
export PATH=/usr/local/bin:$PATH
#gnu-tar
export PATH=/usr/local/opt/gnu-tar/libexec/gnubin:$PATH
</source>
 
 
Then run from terminal:
 
<source lang="bash">
source .bash_profile
</source>
 
in order to reload the bash profile script.
 
In order to remove temporary and log files run from the terminal:
<source lang="bash">
sh cleanup.sh
</source>
 
This script will remove log files and temporary files created during the installation process, but will keep the downloaded files, so that it will be possible to run install-script.sh again without the need for redownloading anything.
 
=== Kernel compilation ===
 
In order to configure and compile the kernel, please follow the steps outlined in the [[Linux Quick Start|Linux Quick Start]].
 
 
=== Flash and debug an STM32F4DISCOVERY board ===
 
'''Tools installation'''
 
In order to be able to flash and debug an STM32F4DISCOVERY board, you need the stlink tools suite. You can grab it from Homebrew running:
 
<source lang="bash">
brew install stlink
</source>


Lastly, if you have a brand new board and QSTlink doesn't work you may take a look at [[ST-LINK utility update|this page]].
Remember that there is no need to install ''git'' as it has been already installed as part of the Command Line Tools (if you have been following this guide to the letter).

Latest revision as of 20:17, 11 June 2023

This page explains how to install the precompiled Miosix Toolchain, which since January 2023 is also available for macOS. The building instructions previously found on this page have been updated and moved to Building GCC from sources.

Both macOS and Linux are POSIX-conformant Unix-like systems, therefore the steps required to get started with Miosix are very similar. This guide only covers the differences between the steps outlined in Linux Quick Start and the steps needed for macOS. Therefore reading the Linux Quick Start page is recommended first.

Before you begin

Installing the Command Line Tools

macOS provides essentials tools for developing software (clang-based C and C++ compilers, git, and more) in a separate package called the Command Line Tools for Xcode. Despite the name, these tools do not require Xcode to be also installed, and since Xcode is a multi-gigabyte application which eats up quite the amount of disk space, you should not install Xcode, unless you are sure you need it for some other non-Miosix-related reason.

To install the Command Line Tools open Terminal.app and then run the following command: 

xcode-select --install

Then follow the instructions on screen to complete the installation.

Installing STM32-specific tools

STM32 microcontrollers are the most important target for Miosix, and programming them requires specialized tools which on Linux are often installed through a package manager.

In contrast to Linux but similarly to Windows, macOS does not provide a system package manager. However, thanks to community efforts, there are two third-party package managers for macOS that provide a similar experience to Linux for easily installing tools and programs on the command line: Homebrew and MacPorts. Both of them provide all packages you need to get started with development on STM32 MCUs.

In the following discussion we will assume you have Homebrew available and installed on your system. If you prefer MacPorts, you can search the same packages (or 'ports') on the MacPorts port index.

With Homebrew, installing st-flash and stm32flash can be performed through the following commands: 

brew install stlink
brew install stm32flash

QSTLink2 is not supported on macOS.

Homebrew, macOS, and filesystem permissions

Homebrew specifically forbids being run with elevated privileges using sudo when installing packages. This is different than what all other package managers (on Linux and macOS) do.

According to Homebrew's developers, this approach purportedly has the advantage of reducing the attack surface of a hypothetic malware that modifies Homebrew's executables for malicious purposes, but it makes it possible for malware to modify all of the files installed by Homebrew easily (as executable distributed by Homebrew are often not signed).

Other package managers such as MacPorts (or all Linux-based package managers for the various distributions) run as root (or as a specialized user with reduced privileges) in order to make it more difficult for malware to tamper any file in the package manager's prefix, and to prevent un-authorized users from modifying the set of packages installed.

However tampering files installed by a package manager on macOS does not appear to be a popular attack vector for malware, thanks to the additional restrictions imposed on top of the standard Unix user permission system by the TCC subsystem in macOS (read this article if you don't know what we are talking about). As a result the field importance of the security implications of Homebrew's choice about the ownership of all installed packages is not entirely clear.

However, being aware of the tradeoff being made is something to be aware of before you choose to install Homebrew or MacPorts, depending on your security-related preferences.

Serial port setup

Serial port devices are available in /dev just like in Linux, however macOS sets the permissions of the device files such that read and write access are available for all groups and users. There is no need to add you user to the dialup group like on Linux.

macOS ships with screen built-in, there is no need to install it separately. If you find screen uncomfortable to use for accessing serial ports, we recommend you use tio, which can be installed via Homebrew with this command: 

brew install tio

Install the Miosix Toolchain

Download the latest version of the toolchain from the link provided in the Miosix Toolchain page. Make sure to install the macOS installable package, and not the Linux or Windows ones. Then you can install the toolchain by double-clicking the downloaded .pkg file.

If the installer does not open and the following dialog box shows up:

The dialog box shown when Gatekeeper prevents opening an installer package.

click with the right mouse button on the installer package (or click while pressing the control key on the keyboard) and select Open from the contextual menu. The dialog box will now let you open the package.

Follow the steps presented by the assistant to install the Miosix toolchain on your system. If you are using an Apple Silicon (ARM) Mac, the installer will automatically propose to install Rosetta for you in case it is not already installed.

Get, configure, and compile the Miosix kernel sources

At this point you can start following the steps outlined in Linux Quick Start#Configuring and compiling the kernel without modifications.

Remember that there is no need to install git as it has been already installed as part of the Command Line Tools (if you have been following this guide to the letter).

Retrieved from "https://miosix.org/wiki/index.php?title=MacOS_Quick_Start&oldid=319"