MacOS Quick Start: Difference between revisions

From Miosix Wiki
Jump to navigation Jump to search
No edit summary
m (Artem.glukhov moved page OSX Quick Start to MacOS Quick Start: renamed the operating system since 2016)
(7 intermediate revisions by 3 users not shown)
Line 3: Line 3:
=== Before you begin ===
=== 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 using the Homebrew package manager.
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.




'''Install Xcode'''
'''Install Xcode'''


Install Xcode by downloading it from the Mac App Store [https://itunes.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.  
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.  




Line 19: Line 19:
</source>
</source>


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.11 from a previous release.
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.




Line 27: Line 27:


<source lang="bash">
<source lang="bash">
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
</source>
</source>


If it complains about permission issues, then you have to fix it before you can continue. In 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. Apple is leaving /usr/local open for developers to use, so Homebrew can still be used as expected; however, performing a few steps may be required depending on you system, as outlined in the official Homebrew documentation [https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/El_Capitan_and_Homebrew.md here].
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.
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>




Line 38: Line 43:


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.
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.
Run this command in terminal to add the repository containing GNU tar to Homebrew:
<source lang="bash">
brew tap homebrew/dupes
</source>




Line 61: Line 59:




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


 
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:
Run this command in terminal to add the repository containing GCC 4.9.3 to Homebrew:
 
<source lang="bash">
brew tap homebrew/versions
</source>




Line 80: Line 71:




Run this command to install GCC 4.9.3:
Run this command to install GCC 9.2.0:


<source lang="bash">
<source lang="bash">
brew install gcc49
brew install gcc@9
</source>
</source>




'''Symlink GCC 4.9.3 executables'''
'''Symlink GCC 9.2.0 executables'''


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:
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:


<source lang="bash">
<source lang="bash">
ln -s /usr/local/bin/gcc-4.9 /usr/local/bin/gcc
ln -s /usr/local/bin/gcc-9 /usr/local/bin/gcc
ln -s /usr/local/bin/gcc-4.9 /usr/local/bin/cc
ln -s /usr/local/bin/gcc-9 /usr/local/bin/cc
ln -s /usr/local/bin/g++-4.9 /usr/local/bin/g++
ln -s /usr/local/bin/g++-9 /usr/local/bin/g++
ln -s /usr/local/bin/cpp-4.9 /usr/local/bin/cpp
ln -s /usr/local/bin/cpp-9 /usr/local/bin/cpp
ln -s /usr/local/bin/c++-4.9 /usr/local/bin/c++
ln -s /usr/local/bin/c++-9 /usr/local/bin/c++
</source>
</source>


Please notice that gcc-4.9 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.
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.




'''Edit $PATH variable'''
'''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 4.9.3 will be called instead of Apple GCC. In order to do so, we are gonna modify the $PATH terminal variable. Run from terminal:
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">
<source lang="bash">
Line 154: Line 145:


<source lang="bash">
<source lang="bash">
gcc version 4.9.3 (Homebrew gcc49 4.9.3)
gcc version 9.2.0 (Homebrew GCC 9.2.0_2)  
</source>
</source>


Line 167: Line 158:


<source lang="bash">
<source lang="bash">
LTO support using: Apple LLVM 7.0.0
LTO support using: LLVM version 11.0.3
</source>
</source>


 
'''Install the following dependencies'''
And finally running from terminal:


<source lang="bash">
<source lang="bash">
tar --version
make, ncurses, byacc, flex, texinfo, patchutils, unzip, lzip, libelf, perl, expat, wget
</source>
</source>
Unfortunately they have to be installed one by one with brew.


should return some text including:
GNU make will be installed as gmake, to use it as make, edit the PATH from the bashrc like:
 
<source lang="bash">
<source lang="bash">
tar (GNU tar)
PATH="/usr/local/opt/make/libexec/gnubin:$PATH"
</source>
</source>


=== Toolchain compilation and installation ===
=== Toolchain compilation and installation ===
Line 195: Line 184:




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:
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">
<source lang="bash">
Line 201: Line 190:
cd miosix-kernel
cd miosix-kernel
git fetch origin
git fetch origin
</source>
To select the development version of the kernel
<source lang="bash">
git checkout -b testing origin/testing
</source>
</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.


'''Toolchain dependencies download'''


You need to fix a link in the Miosix toolchain dependencies download script, located at:


<source lang="bash">
Make sure to be in a path without spaces, or compiling will fail.
miosix-kernel/miosix/_tools/compiler/download.sh
</source>
 
 
Replace the following line:


Example:
<source lang="bash">
<source lang="bash">
wget http://www.mpfr.org/mpfr-current/mpfr-3.1.2.tar.xz
/home/foo/temp                          OK
/home/foo/directory with spaces/temp    NO!!
</source>
</source>


with:
move to the compiler directory:


<source lang="bash">
<source lang="bash">
wget http://www.mpfr.org/mpfr-3.1.2/mpfr-3.1.2.tar.xz
cd miosix-kernel/miosix/_tools/compiler/gcc-9.2.0-mp3.1
</source>
</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:
Now you need to run the dependencies download script. From terminal, run:


<source lang="bash">
<source lang="bash">
sh miosix-kernel/miosix/_tools/compiler/download.sh
sh download.sh
</source>
</source>


Line 241: Line 232:


<source lang="bash">
<source lang="bash">
miosix-kernel/miosix/_tools/compiler/install-script.sh
miosix-kernel/miosix/_tools/compiler/gcc-9.2.0-mp3.1/install-script.sh
</source>
</source>


Line 248: Line 239:


<source lang="bash">
<source lang="bash">
# Uncomment if installing globally on the system
# Uncomment if installing globally on the system
#INSTALL_DIR=/opt
 
#INSTALL_DIR=/opt/arm-miosix-eabi
 
#SUDO=sudo
#SUDO=sudo
# Uncomment if installing locally, sudo isn't necessary
# Uncomment if installing locally, sudo isn't necessary
INSTALL_DIR=`pwd`/gcc
 
INSTALL_DIR=`pwd`/gcc/arm-miosix-eabi
 
SUDO=
SUDO=
</source>
</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:  
We can now finally run the compilation script. From terminal, run:  


<source lang="bash">
<source lang="bash">
sh miosix-kernel/miosix/_tools/compiler/install-script.sh
sh install-script.sh -j'nproc'
</source>
</source>


Line 267: Line 265:


<source lang="bash">
<source lang="bash">
miosix-kernel/miosix/_tools/compiler/gcc/arm-miosix-eabi/bin
miosix-kernel/miosix/_tools/compiler/gcc-9.2.0-mp3.1/gcc/arm-miosix-eabi/bin
</source>
</source>


Line 277: Line 275:
<source lang="bash">
<source lang="bash">
#arm-miosix-eabi
#arm-miosix-eabi
export PATH={my-folder-of-choice-path}/miosix-kernel/miosix/_tools/compiler/gcc/arm-miosix-eabi/bin:$PATH
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>
</source>


Line 312: Line 310:
in order to reload the bash profile script.
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 ===
=== Kernel compilation ===
Line 327: Line 331:
brew install stlink
brew install stlink
</source>
</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]].

Revision as of 10:37, 11 July 2020

ATTENTION: This page is still a WIP. Usual disclaimers about not taking responsibility for your system disruption applies.

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.


Install Xcode

Install Xcode by downloading it from the Mac App Store here. This is needed for installing the XCode command line tools which in turn is needed by Homebrew.


Install Xcode Command Line Tools

Install the Command Line Tools by running the following command in terminal:

xcode-select --install

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.


Install Homebrew

Grab a copy of Homebrew and run the install script in one step using this command in terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

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. Also, if you have never opened Xcode before, it will ask you to agree to the license by opening Xcode.app or running:

	sudo xcodebuild -license


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.


Run this command in terminal to grab the most recent packages list from Homebrew:

brew update


Run this command to install GNU tar:

brew install gnu-tar


Install GCC 9.2.0

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:


Run this command in terminal to grab the most recent packages list from Homebrew:

brew update


Run this command to install GCC 9.2.0:

brew install gcc@9


Symlink GCC 9.2.0 executables

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:

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++

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.


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:

cd

To get into your home folder.


Run from terminal:

edit .bash_profile

To edit the bash profile script.


You need to add the following lines as they are:

#homebrew gcc
export PATH=/usr/local/bin:$PATH
#gnu-tar
export PATH=/usr/local/opt/gnu-tar/libexec/gnubin:$PATH

Save and close the file.


Then run from terminal:

source .bash_profile

in order to reload the bash profile script.


Check the installed packages

If everything went as supposed, running from terminal:

gcc -v

should return some text including:

gcc version 9.2.0 (Homebrew GCC 9.2.0_2)


While running from terminal:

ld -v

should return some text including:

LTO support using: LLVM version 11.0.3

Install the following dependencies

make, ncurses, byacc, flex, texinfo, patchutils, unzip, lzip, libelf, perl, expat, wget

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:

PATH="/usr/local/opt/make/libexec/gnubin:$PATH"

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:

brew install git


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:

git clone https://miosix.org/git-public/miosix-kernel.git
cd miosix-kernel
git fetch origin

To select the development version of the kernel

git checkout -b testing origin/testing

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:

/home/foo/temp                          OK
/home/foo/directory with spaces/temp    NO!!

move to the compiler directory:

cd miosix-kernel/miosix/_tools/compiler/gcc-9.2.0-mp3.1

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:

sh download.sh

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:

miosix-kernel/miosix/_tools/compiler/gcc-9.2.0-mp3.1/install-script.sh


such that at the end the first few lines looks as follow:

# 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=

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:

sh install-script.sh -j'nproc'


At the end, if everything worked correctly, you'll find the toolchain at:

miosix-kernel/miosix/_tools/compiler/gcc-9.2.0-mp3.1/gcc/arm-miosix-eabi/bin


Toolchain compilation and installation

Now you need to add the toolchain to your path. Edit the bash profile script and add the following lines:

#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

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 .bash_profile

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:

#homebrew gcc
export PATH=/usr/local/bin:$PATH
#gnu-tar
export PATH=/usr/local/opt/gnu-tar/libexec/gnubin:$PATH


Then run from terminal:

source .bash_profile

in order to reload the bash profile script.

In order to remove temporary and log files run from the terminal:

sh cleanup.sh

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.


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:

brew install stlink

Lastly, if you have a brand new board and QSTlink doesn't work you may take a look at this page.