MacOS Quick Start: Difference between revisions
(Created page with "=== Before you begin === This procedure has been tested on OS X El Capitain 10.11. The Miosix toolchain has been successfully compiled using GCC 4.9.3, which can be installed...") |
m (MacOS is now called macOS.) |
||
| (21 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
{{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]]. | |||
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 ([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. | |||
To install the Command Line Tools open Terminal.app and then run the following command: | |||
<syntaxhighlight> | |||
xcode-select --install | |||
</syntaxhighlight> | |||
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: [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. | |||
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]. | |||
With Homebrew, installing st-flash and stm32flash can be performed through the following commands: | |||
<syntaxhighlight> | |||
brew install stlink | |||
brew install stm32flash | |||
</syntaxhighlight> | |||
QSTLink2 is not supported on macOS. | |||
==== Homebrew, macOS, and filesystem permissions ==== | |||
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. | |||
[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). | |||
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 ([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. | |||
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 <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. | |||
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: | |||
<syntaxhighlight> | |||
brew install tio | |||
</syntaxhighlight> | |||
== 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: | |||
[[File:MacOS unidentified developer.png|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). | |||
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 --installThen 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 stm32flashQSTLink2 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 tioInstall 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:
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).