Daniele.cattaneo: Create the page by mostly copy-pasting and adapting text from the macOS getting started guide.

2023-06-11T13:57:13Z

Create the page by mostly copy-pasting and adapting text from the macOS getting started guide.

New page

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

The Miosix repository contains a set of scripts which are used to build the
toolchain from sources. These scripts perform the entire building process
automatically, from downloading the dependencies, to compiling them, to
finally packaging them.

The steps required to use these scripts are similar for all three operating
systems supported by the toolchain (macOS, Windows, Linux), but some platform-specific
steps are also required.

== Before you begin ==

Building the Miosix toolchain can be time-consuming and stressful for system
resources. Make sure the system you intend to build the toolchain on has at
least the following system requirements:

* 4 GB of RAM
* 4 CPU cores
* 10 GB of free disk space

Any reasonably modern system will be able to meet these requirements. However
notice that the only truly necessary requirement is the free disk space for
the build products. Other requirements can be ignored if you are willing to
spend quite some time waiting out for the compilation to end.

== System dependencies installation ==

=== Linux ===

TODO

=== Windows ===

TODO

=== macOS ===

==== Install the Command Line Tools ====

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

<syntaxhighlight lang="bash">
xcode-select --install
</syntaxhighlight>

The command line tools provide <code>clang</code>, <code>clang++</code>,
<code>make</code>, <code>bison</code>, <code>flex</code> and headers for the C
standard library, the C++ STL, and more tools required for building the
toolchain.

It is not necessary to also install Xcode to build the Miosix toolchain, the
Command Line Tools suffice.

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

==== Check the installed packages ====

If everything went as supposed, running from terminal:

<syntaxhighlight lang="bash">
cc -v
</syntaxhighlight>

should return some text including:

<pre>
Apple clang version 14.0.3 (clang-1403.0.22.14.1)
Target: x86_64-apple-darwin22.5.0
</pre>

== Toolchain Sources Download ==

=== Download the Miosix git repository ===

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

<syntaxhighlight lang="bash">
git clone https://miosix.org/git-public/miosix-kernel.git
cd miosix-kernel
git fetch origin
</syntaxhighlight>
To select the development version of the kernel
<syntaxhighlight lang="bash">
git checkout -b testing origin/testing
</syntaxhighlight>

Please note that currently, the ''master'' branch contains the stable kernel,
the ''testing'' branch contains the current development version, and the
''unstable'' branch contains experimental commits that implement more radical
restructuring of the code.

Usually the ''testing'' branch contains the latest updates made, especially
support packages for new boards, so its advised to use the code contained in
this branch.

'''macOS only:''' If you are building for macOS, use the ''unstable'' branch
instead, because it is the one where the patches to the compilation scripts for
macOS support are currently located. Just replace <code>testing</code> with
<code>unstable</code> in the commands shown above.

Make sure the path to your current working directory does not contain spaces,
or compiling will fail! You can check the path to the current working directory
by running the command <code>pwd</code>. For example:
<syntaxhighlight lang="bash">
/home/foo/temp OK
/home/foo/directory with spaces/temp NO!!
</syntaxhighlight>

Now move to the compiler directory:

<syntaxhighlight lang="bash">
cd miosix-kernel/miosix/_tools/compiler/gcc-9.2.0-mp3.1
</syntaxhighlight>

=== Run the script for downloading the sources ===

At this point you need to run the dependencies download script. From terminal,
run <code>sh download.sh</code> from the folder where you performed the
<code>git clone</code> command.

If you want to build a redistributable package, you should also run the
command <code>sh installers/additional-download.sh</code>. Do '''not''' change
the working directory to <code>installers</code> before running this command!

== Toolchain install script configuration ==

The Miosix toolchain install script supports compiling the toolchain in three
different ways:
1. Non-redistributable, local install
2. Non-redistributable, global install
3. Redistributable (installable package), global install

The default configuration of the script compiles the toolchain as
'''non-redistributable, with local install'''. '''If this is OK for you, skip to the next section.'''

If you want a different configuration, edit the install script located at:

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

At the beginning of the script, the following lines of code (or similar ones)
should appear:

<syntaxhighlight lang="bash">
# Uncomment if installing globally on this system
PREFIX=/opt/arm-miosix-eabi
DESTDIR=
SUDO=sudo
# Uncomment if installing locally on this system, sudo isn't necessary
#PREFIX=`pwd`/gcc/arm-miosix-eabi
#DESTDIR=
#SUDO=
# Uncomment for producing a package for redistribution. The prefix is set to the
# final install directory, but when this script does "make install" files are
# copied with $DESTDIR as prefix. When doing a redistibutable build you also
# have to specify HOST or (on Mac OS), BUILD, see below.
#PREFIX=/opt/arm-miosix-eabi
#DESTDIR=`pwd`/dist
#SUDO=

# Uncomment if targeting a local install. This will use -march= -mtune= flags
# to optimize for your processor, but the code won't be portable to other
# architectures, so don't distribute it
BUILD=
HOST=
# Uncomment if targeting linux 64 bit (distributable)
#BUILD=
#HOST=x86_64-linux-gnu
# Uncomment if targeting windows 64 bit (distributable)
# you have to run this script from Linux anyway (see canadian cross compiling)
#BUILD=
#HOST=x86_64-w64-mingw32
# Uncomment if targeting macOS 64 bit Intel (distributable), compiling on Linux
# Must first install the osxcross toolchain
#BUILD=
#HOST=x86_64-apple-darwin18
# Uncomment if targeting macOS 64 bit Intel (distributable), compiling on macOS
# The script must be run under macOS and without canadian cross compiling
# because it confuses autotools's configuration scripts. Instead we set the
# compiler options for macOS minimum version and architecture in order to be
# able to deploy the binaries on older machines and OS versions. We also must
# force --build and --host to specify a x86_64 cpu to avoid
# architecture-dependent code.
#BUILD=x86_64-apple-darwin17 # No macs exist with a cpu older than a Core 2
#HOST=
#export CFLAGS='-mmacos-version-min=10.13 -O3'
#export CXXFLAGS='-mmacos-version-min=10.13 -O3'
</syntaxhighlight>

The comments in the source should be sufficiently self-explanatory. Just
un-comment the appropriate section depending on the kind of installation you
want to perform by removing the hash (<code>#</code>) characters at the
beginning of the appropriate lines of code.

Remember to also '''comment''' any line of code in this section that is
'''not''' related to the option you want to choose.

'''Warning about redistributable packages:''' The '''redistributable''' options
are used to build the installable packages that are available on the
[[Miosix Toolchain]] page. If you want to build the toolchain just for yourself,
do not build a redistributable package. Additionally, to build a redistributable
package you must have built and installed the toolchain '''at least once''' as a
non-redistributable global install.

'''Linux only:''' By default, in global install mode, the script installs the
toolchain in <code>/opt/arm-miosix-eabi</code>, but it also creates symlinks
to most tools of interest in <code>/usr/bin</code>. If you do not want to
pollute <code>/usr/bin</code> with stuff not installed by your package manager
(APT, pacman, ...) comment the following line in the script:
<syntaxhighlight lang="bash">
$SUDO ln -s $DESTDIR$PREFIX/bin/* /usr/bin
</syntaxhighlight>
After this modification you will also need to manually add
<code>/opt/arm-miosix-eabi/bin</code> to your <code>PATH</code> variable
to access the toolchain from your shell, for example by modifying your shell
profile setup script (<code>.profile</code> or <code>.bashrc</code> or another
file depending on your shell).

== Toolchain compilation and installation ==

We can now finally run the compilation script. From terminal, run:

<syntaxhighlight lang="bash">
sh install-script.sh -j`nproc`
</syntaxhighlight>

'''macOS only:''' macOS does not ship with the <code>nproc</code> tool by
default, used by the command above to automatically detect the number of CPUs
(or CPU cores) available on your system. In case you have not installed this
tool manually yourself via a third-party package manager (such as
[https://brew.sh Homebrew] or [https://www.macports.org MacPorts]) just replace
<code>`nproc`</code> in the command above with the number of CPUs you have
available.

The install script will print out progress information as it runs.
At the end, if everything worked correctly, and if you kept the default
configuration (non-redistributable, local install) you'll find the toolchain at:

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

If you selected a global install instead, by default the toolchain will be
installed here:

<syntaxhighlight>
/opt/arm-miosix-eabi/bin
</syntaxhighlight>

'''macOS only:''' Now you need to add the toolchain to your path. Edit the shell
profile script (<code>~/.profile</code>) and add the following lines:
<syntaxhighlight 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
</syntaxhighlight>
where you must replace {my-folder-of-choice-path} with the path of the folder
where you run the git clone command.
Then run from terminal:
<syntaxhighlight lang="bash">
source .bash_profile
</syntaxhighlight>
in order to reload the bash profile script.

== Cleanup ==

In order to remove temporary and log files run from the terminal:
<syntaxhighlight lang="bash">
sh cleanup.sh
</syntaxhighlight>

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.

Building GCC from sources - Revision history

Daniele.cattaneo: Create the page by mostly copy-pasting and adapting text from the macOS getting started guide.