src/build-manual/How-to-build-toolchain.texi - stadia-controller/gcc-arm-none-eabi - Git at Google

 \input texinfo @c -*-texinfo-*-
 @c %**start of header
 @c makeinfo and texinfo.tex ignore all text before @setfilename.
 @c
 @c Ordinarily, the setfilename argument ends with .info.  But
 @c texinfo.info-13 is too long for 14-character filesystems.
 @setfilename how-to-build-toolchain.info
 @include version.texi
 @settitle How To Build Toolchain
 @paragraphindent asis
 @c %**end of header

 @copying
 Copyright @copyright{} 2012-@value{CURRENT_YEAR} ARM Ltd.
 @end copying

 @finalout
 @smallbook

 @titlepage
 @title The Build Process
 @subtitle of @value{VERSION_PACKAGE}
 @subtitle @value{CURRENT_YEAR}-@value{CURRENT_MONTH}

 @c The following two commands start the copyright page
 @page
 @vskip 0pt plus 1filll
 @insertcopying
 @end titlepage

 @c Output the table of contents at the beginning.
 @contents

 @ifnottex
 @node Top
 @top How To Build Toolchain

 @insertcopying
 @end ifnottex

 @node Preface
 @unnumbered Preface
 This manual provides a step-by-step guide to help you build
 @samp{GNU Tools for Arm Embedded Processors} on a newly installed
 Ubuntu 14.04 LTS 64-bit operating system.

 @noindent
 Note that the steps below may most likely also work on an Ubuntu which is
 not newly installed or version other than 14.04 LTS, but it is not guaranteed.
 In this case please go through @ref{Known Issues} before you go, and
 you need to solve any other problems you may encounter by yourself.  We
 highly appreciate if you could share the problems and solutions with us.

 @node Ubuntu
 @chapter Build GNU Tools for Linux and Windows Platforms

 @node Install Ubuntu
 @section Install Ubuntu
 @c Use '@/' to allow break inside a URL
 Ubuntu 14.04.5 ISO image is available from
 @uref{http://releases.ubuntu.com@//14.04@//ubuntu-14.04.5-desktop-amd64.iso}.
 You can install it as a native system or a virtual machine.

 @page
 @node Install Dependencies
 @section Install Dependencies

 @node Install dependencies available in Ubuntu's repositories
 @subsection Install dependencies available in Ubuntu's repositories

 Execute the commands in this section to install the tools needed to build the
 toolchain.  Lines starting with '$' denote commands that need to be input as is
 while lines starting with '#' are comments and as such do not need to be typed
 in.

 @noindent
 Please note that the "Ignoring Provides line" and "unknown Multi-Arch type"
 warnings when executing @code{apt-get update} are harmless and can thus safely
 be ignored.  Similarly, the warning about @code{update-alternatives} skipping
 the creation of symbolic links when executing @code{apt-get install} is also
 harmless and can therefore safely be ignored.@*

 @smallformat
 @codequoteundirected on
 @group
 @verbatim
 # Start root session
 $ sudo su
 @end verbatim
 @end group

 @group
 @verbatim
 # Add extra repositories to be used by APT
 $ apt-get install software-properties-common
 $ add-apt-repository universe
 $ cat >/etc/apt/sources.list.d/xenial.list <<EOF
 deb http://archive.ubuntu.com/ubuntu xenial main universe
 deb-src http://archive.ubuntu.com/ubuntu xenial main universe
 deb http://security.ubuntu.com/ubuntu xenial-security main
 EOF
 @end verbatim
 @end group

 @group
 @verbatim
 # Ensure package for Ubuntu Trusty are chosen by default
 $ echo 'APT::Default-Release "trusty";' > /etc/apt/apt.conf.d/00default
 @end verbatim
 @end group

 @group
 @verbatim
 # Enable use of 32bit packages
 $ dpkg --add-architecture i386
 $ apt-get update
 @end verbatim
 @end group

 @group
 @verbatim
 # Install packages
 $ apt-get install -y -t xenial \
     gcc-mingw-w64-i686 g++-mingw-w64-i686 binutils-mingw-w64-i686
 $ apt-get -f install -y \
     build-essential \
     autoconf \
     autogen \
     bison \
     dejagnu \
     flex \
     flip \
     gawk \
     git \
     gperf \
     gzip \
     nsis \
     openssh-client \
     p7zip-full \
     perl \
     python-dev \
     libisl-dev \
     scons \
     tcl \
     texinfo \
     tofrodos \
     wget \
     zip \
     texlive \
     texlive-extra-utils
 @end verbatim
 @end group

 @group
 @verbatim
 # End root session
 $exit
 @end verbatim
 @end group
 @codequoteundirected off
 @end smallformat

 @page
 @node Build GNU Tools for Arm Embedded Processors
 @section Build GNU Tools for Arm Embedded Processors

 @noindent
 You are now ready to build the toolchain. Just follow the below instructions,
 substituting @code{~/toolchain} by the directory in which you wish to build
 the toolchain. Note that if you are not interested in the Windows toolchain,
 you can speed up the build by passing the option @code{--skip_steps=mingw32}
 to @strong{all} of install-sources.sh, build-prerequisites.sh and
 build-toolchain.sh.

 @smallexample
 @group
 @set txicodequoteundirected
 # Create a directory in which to build the toolchain and copy the source
 # release package into it.
 $ mkdir ~/toolchain
 $ cp @value{PKG_NAME}-src.tar.bz2 ~/toolchain

 # Untar the source tarball.
 $ cd ~/toolchain
 $ tar -xjf @value{PKG_NAME}-src.tar.bz2
 $ cd ./@value{PKG_NAME}
 $ ./install-sources.sh

 # Build the toolchain(s).
 $ cd ../
 $ ./build-prerequisites.sh
 $ ./build-toolchain.sh

 @clear txicodequoteundirected
 @end group
 @end smallexample

 @noindent
 Once the build completes you can find the binary and source tarballs in
  @* @samp{~/toolchain/@value{PKG_NAME}/pkg}
 along with the md5 checksum.

 @node Mac
 @chapter Build GNU Tools on Mac OS X
 In addition to the build on Ubuntu, the build scripts in same source
 package can also be used on Mac OS X to natively build a tool chain
 whose host is Mac OS X and target is arm-none-eabi.  In this step we
 will describe how to install required software components and how to
 execute the build scripts.  After this step you should be able to
 generate a same tool chain with the one released.  Due to resource
 limit, this build process is only tested against Mac OS X 10.7.3 along
 with components listed below.

 @node Prepare a Mac OS X environment
 @section Prepare a Mac OS X environment
 The hardware should be an x86-based Mac machine like iMac. The installed
 OS should be Mac OS X which is updated to 10.7.3.  The way to find out
 the Mac OS X version information is to click the @strong{Apple} menu and
 choose @strong{About This Mac}.

 @sp 1
 @center @image{click-apple-menu,,,,.png}

 @page
 @noindent
 For the environment we are using, it looks as below:

 @sp 1
 @center @image{about-this-mac,,,,.png}

 @node Install the Command Line Tools for Xcode
 @section Install the Command Line Tools for Xcode
 This component is originally part of Apple Xcode but can be installed
 separately without Xcode.  It can be freely obtained from Apple's official
 website @uref{https://developer.apple.com@//downloads/index.action}.
 A valid Apple ID is required to login and download.  The one we are using
 is in the item named @samp{Command Line Tools (OS X Lion) for Xcode - April 2013}.
 After the download finishes, just double click the @samp{.dmg} file and
 follow the instructions to install it.

 @node Build a native version of gcc
 @section  Build a native version of gcc
 Download and install MacPorts for Mac OS X Lion following the steps on MacPorts
 website @uref{https://www.macports.org/install.php#installing}.
 Then use MacPorts to install gcc5 with the following commands:

 Install gcc 5.
 @smallexample

 $ sudo port install gcc5
 @end smallexample

 Make sure the newly installed gcc is the one reachable by PATH.
 @smallexample

 $ sudo ln -s /opt/local/bin/@{x86_64-apple-darwin11-gcc-5.*,gcc@}
 $ sudo ln -s /opt/local/bin/@{g++-mp-5,g++@}
 $ export PATH=/opt/local/bin:$PATH

 @end smallexample

 On the Mac, in general, C++ programs need to be built with the system's
 exception unwinder which libgcc currently overrides. To make sure we use the
 system unwinder, libgcc needs to be overridden. This needs a patched
 gcc. Instructions to build such a patched gcc are given below.

 Fetch gcc 7 sources.
 @smallexample
 $ mkdir gcc-7-patched
 $ cd gcc-7-patched
 $ wget https://ftp.gnu.org/gnu/gcc/gcc-7.2.0/gcc-7.2.0.tar.xz

 @end smallexample

 Fetch the unwinder patch.
 @smallexample
 $ wget https://gcc.gnu.org/ml/gcc-patches/2017-09/txtd196Be63lt.txt -O /tmp/p.txt

 @end smallexample

 Untar and patch gcc 7.
 @smallexample
 $ tar xf gcc-7.2.0.tar.xz
 $ cd gcc-7.2.0
 $ patch -p1 < /tmp/p.txt

 @end smallexample

 Build gcc 7.
 @smallexample
 $ mkdir -p ../gcc-7-build/install ../gcc-7-build/obj  && cd ../gcc-7-build/obj
 $ ../../gcc7.2.0/configure --prefix=$PWD/../install --disable-nls \
   --enable-languages=c,c++ --enable-checking=release \
   --with-gmp=/opt/local --with-mpfr=/opt/local --with-mpc=/opt-local \
   --with-isl=/opt/local/ --with-libiconv-prefix=/opt/local/
 $ make && make install

 @end smallexample

 Once the build finishes, put the patched gcc 7 in the path.

 @smallexample

 $ export PATH=/path/to/gcc-7-build/install/bin:$PATH
 @end smallexample

 @node Install MacTeX to build PDF format documents
 @section Install MacTeX to build PDF format documents
 This is an optional step and can be skipped if PDF format documents aren't
 needed.  The build process will use TeX engineer provided by MacTeX-2012 to
 generate PDF format documents.  This component can be freely obtained from
 its official FTP server
 @uref{ftp://ftp.tug.org/historic/systems/mactex/2012/MacTeX.pkg}.
 Its original size is approximately 2.1G.  Once downloaded, just double click
 on the @samp{MacTeX.pkg} file and follow the instructions to install it.  By
 default the related TeX executable files won't be installed into the default
 path like @samp{/usr/bin}, so the Terminal need to be restarted before running
 the build scripts.

 @node Build the tool chain under Mac OS X
 @section Build the tool chain under Mac OS X
 With all the dependent packages installed, we can start to natively
 build the tool chain on Mac OS.  Following are the commands and steps we are
 using:

 @smallexample
 @set txicodequoteundirected

 # Copy the src release package into ~/mac-build/ directory
 $ cp @value{PKG_NAME}-src.tar.bz2 ~/mac-build

 # Prepare source codes
 $ cd ~/mac-build
 $ tar xjf @value{PKG_NAME}-src.tar.bz2
 $ cd ./@value{PKG_NAME}
 $ ./install-sources.sh

 # Start building the toolchain.
 $ ./build-prerequisites.sh
 $ ./build-toolchain.sh

 @clear txicodequoteundirected
 @end smallexample

 @node Known Issues
 @appendix Known Issues

 @itemize @bullet
 @item
 If you are using different build environment and tools, you might run
 into a problem where binutils can not be successfully built.  This is
 probably caused by binutils bug 13036.
 For more information, please refer to
 @uref{http://sourceware.org/bugzilla/show_bug.cgi?id=13036}.

 @item
 Some shell scripts in gcc and other packages are incompatible with
 the dash shell, which is the default /bin/sh for Ubuntu 14.04 LTS.
 You must make /bin/sh a symbolic link to one of the supported shells:
 saying bash.  Here on Ubuntu 14.04 LTS system, this can be done by
 running following command:
 @smallexample
 $ sudo dpkg-reconfigure -plow dash
 @end smallexample

 Then choose @samp{No} in the @samp{Configuring dash} popup dialog and
 press enter.  You can run following command and check that /bin/sh
 points to @samp{bash}:
 @smallexample
 $ ls -l /bin/sh
 ...... /bin/sh -> bash
 @end smallexample
 @bye
	\input texinfo @c --texinfo--
	@c %**start of header
	@c makeinfo and texinfo.tex ignore all text before @setfilename.
	@c
	@c Ordinarily, the setfilename argument ends with .info. But
	@c texinfo.info-13 is too long for 14-character filesystems.
	@setfilename how-to-build-toolchain.info
	@include version.texi
	@settitle How To Build Toolchain
	@paragraphindent asis
	@c %**end of header

	@copying
	Copyright @copyright{} 2012-@value{CURRENT_YEAR} ARM Ltd.
	@end copying

	@finalout
	@smallbook

	@titlepage
	@title The Build Process
	@subtitle of @value{VERSION_PACKAGE}
	@subtitle @value{CURRENT_YEAR}-@value{CURRENT_MONTH}

	@c The following two commands start the copyright page
	@page
	@vskip 0pt plus 1filll
	@insertcopying
	@end titlepage

	@c Output the table of contents at the beginning.
	@contents

	@ifnottex
	@node Top
	@top How To Build Toolchain

	@insertcopying
	@end ifnottex

	@node Preface
	@unnumbered Preface
	This manual provides a step-by-step guide to help you build
	@samp{GNU Tools for Arm Embedded Processors} on a newly installed
	Ubuntu 14.04 LTS 64-bit operating system.

	@noindent
	Note that the steps below may most likely also work on an Ubuntu which is
	not newly installed or version other than 14.04 LTS, but it is not guaranteed.
	In this case please go through @ref{Known Issues} before you go, and
	you need to solve any other problems you may encounter by yourself. We
	highly appreciate if you could share the problems and solutions with us.

	@node Ubuntu
	@chapter Build GNU Tools for Linux and Windows Platforms

	@node Install Ubuntu
	@section Install Ubuntu
	@c Use '@/' to allow break inside a URL
	Ubuntu 14.04.5 ISO image is available from
	@uref{http://releases.ubuntu.com@//14.04@//ubuntu-14.04.5-desktop-amd64.iso}.
	You can install it as a native system or a virtual machine.

	@page
	@node Install Dependencies
	@section Install Dependencies

	@node Install dependencies available in Ubuntu's repositories
	@subsection Install dependencies available in Ubuntu's repositories

	Execute the commands in this section to install the tools needed to build the
	toolchain. Lines starting with '$' denote commands that need to be input as is
	while lines starting with '#' are comments and as such do not need to be typed
	in.

	@noindent
	Please note that the "Ignoring Provides line" and "unknown Multi-Arch type"
	warnings when executing @code{apt-get update} are harmless and can thus safely
	be ignored. Similarly, the warning about @code{update-alternatives} skipping
	the creation of symbolic links when executing @code{apt-get install} is also
	harmless and can therefore safely be ignored.@*

	@smallformat
	@codequoteundirected on
	@group
	@verbatim
	# Start root session
	$ sudo su
	@end verbatim
	@end group

	@group
	@verbatim
	# Add extra repositories to be used by APT
	$ apt-get install software-properties-common
	$ add-apt-repository universe
	$ cat >/etc/apt/sources.list.d/xenial.list <<EOF
	deb http://archive.ubuntu.com/ubuntu xenial main universe
	deb-src http://archive.ubuntu.com/ubuntu xenial main universe
	deb http://security.ubuntu.com/ubuntu xenial-security main
	EOF
	@end verbatim
	@end group

	@group
	@verbatim
	# Ensure package for Ubuntu Trusty are chosen by default
	$ echo 'APT::Default-Release "trusty";' > /etc/apt/apt.conf.d/00default
	@end verbatim
	@end group

	@group
	@verbatim
	# Enable use of 32bit packages
	$ dpkg --add-architecture i386
	$ apt-get update
	@end verbatim
	@end group

	@group
	@verbatim
	# Install packages
	$ apt-get install -y -t xenial \
	gcc-mingw-w64-i686 g++-mingw-w64-i686 binutils-mingw-w64-i686
	$ apt-get -f install -y \
	build-essential \
	autoconf \
	autogen \
	bison \
	dejagnu \
	flex \
	flip \
	gawk \
	git \
	gperf \
	gzip \
	nsis \
	openssh-client \
	p7zip-full \
	perl \
	python-dev \
	libisl-dev \
	scons \
	tcl \
	texinfo \
	tofrodos \
	wget \
	zip \
	texlive \
	texlive-extra-utils
	@end verbatim
	@end group

	@group
	@verbatim
	# End root session
	$exit
	@end verbatim
	@end group
	@codequoteundirected off
	@end smallformat

	@page
	@node Build GNU Tools for Arm Embedded Processors
	@section Build GNU Tools for Arm Embedded Processors

	@noindent
	You are now ready to build the toolchain. Just follow the below instructions,
	substituting @code{~/toolchain} by the directory in which you wish to build
	the toolchain. Note that if you are not interested in the Windows toolchain,
	you can speed up the build by passing the option @code{--skip_steps=mingw32}
	to @strong{all} of install-sources.sh, build-prerequisites.sh and
	build-toolchain.sh.

	@smallexample
	@group
	@set txicodequoteundirected
	# Create a directory in which to build the toolchain and copy the source
	# release package into it.
	$ mkdir ~/toolchain
	$ cp @value{PKG_NAME}-src.tar.bz2 ~/toolchain

	# Untar the source tarball.
	$ cd ~/toolchain
	$ tar -xjf @value{PKG_NAME}-src.tar.bz2
	$ cd ./@value{PKG_NAME}
	$ ./install-sources.sh

	# Build the toolchain(s).
	$ cd ../
	$ ./build-prerequisites.sh
	$ ./build-toolchain.sh

	@clear txicodequoteundirected
	@end group
	@end smallexample

	@noindent
	Once the build completes you can find the binary and source tarballs in
	@* @samp{~/toolchain/@value{PKG_NAME}/pkg}
	along with the md5 checksum.

	@node Mac
	@chapter Build GNU Tools on Mac OS X
	In addition to the build on Ubuntu, the build scripts in same source
	package can also be used on Mac OS X to natively build a tool chain
	whose host is Mac OS X and target is arm-none-eabi. In this step we
	will describe how to install required software components and how to
	execute the build scripts. After this step you should be able to
	generate a same tool chain with the one released. Due to resource
	limit, this build process is only tested against Mac OS X 10.7.3 along
	with components listed below.

	@node Prepare a Mac OS X environment
	@section Prepare a Mac OS X environment
	The hardware should be an x86-based Mac machine like iMac. The installed
	OS should be Mac OS X which is updated to 10.7.3. The way to find out
	the Mac OS X version information is to click the @strong{Apple} menu and
	choose @strong{About This Mac}.

	@sp 1
	@center @image{click-apple-menu,,,,.png}

	@page
	@noindent
	For the environment we are using, it looks as below:

	@sp 1
	@center @image{about-this-mac,,,,.png}

	@node Install the Command Line Tools for Xcode
	@section Install the Command Line Tools for Xcode
	This component is originally part of Apple Xcode but can be installed
	separately without Xcode. It can be freely obtained from Apple's official
	website @uref{https://developer.apple.com@//downloads/index.action}.
	A valid Apple ID is required to login and download. The one we are using
	is in the item named @samp{Command Line Tools (OS X Lion) for Xcode - April 2013}.
	After the download finishes, just double click the @samp{.dmg} file and
	follow the instructions to install it.

	@node Build a native version of gcc
	@section Build a native version of gcc
	Download and install MacPorts for Mac OS X Lion following the steps on MacPorts
	website @uref{https://www.macports.org/install.php#installing}.
	Then use MacPorts to install gcc5 with the following commands:

	Install gcc 5.
	@smallexample

	$ sudo port install gcc5
	@end smallexample

	Make sure the newly installed gcc is the one reachable by PATH.
	@smallexample

	$ sudo ln -s /opt/local/bin/@{x86_64-apple-darwin11-gcc-5.*,gcc@}
	$ sudo ln -s /opt/local/bin/@{g++-mp-5,g++@}
	$ export PATH=/opt/local/bin:$PATH

	@end smallexample

	On the Mac, in general, C++ programs need to be built with the system's
	exception unwinder which libgcc currently overrides. To make sure we use the
	system unwinder, libgcc needs to be overridden. This needs a patched
	gcc. Instructions to build such a patched gcc are given below.

	Fetch gcc 7 sources.
	@smallexample
	$ mkdir gcc-7-patched
	$ cd gcc-7-patched
	$ wget https://ftp.gnu.org/gnu/gcc/gcc-7.2.0/gcc-7.2.0.tar.xz

	@end smallexample

	Fetch the unwinder patch.
	@smallexample
	$ wget https://gcc.gnu.org/ml/gcc-patches/2017-09/txtd196Be63lt.txt -O /tmp/p.txt

	@end smallexample

	Untar and patch gcc 7.
	@smallexample
	$ tar xf gcc-7.2.0.tar.xz
	$ cd gcc-7.2.0
	$ patch -p1 < /tmp/p.txt

	@end smallexample

	Build gcc 7.
	@smallexample
	$ mkdir -p ../gcc-7-build/install ../gcc-7-build/obj && cd ../gcc-7-build/obj
	$ ../../gcc7.2.0/configure --prefix=$PWD/../install --disable-nls \
	--enable-languages=c,c++ --enable-checking=release \
	--with-gmp=/opt/local --with-mpfr=/opt/local --with-mpc=/opt-local \
	--with-isl=/opt/local/ --with-libiconv-prefix=/opt/local/
	$ make && make install

	@end smallexample

	Once the build finishes, put the patched gcc 7 in the path.

	@smallexample

	$ export PATH=/path/to/gcc-7-build/install/bin:$PATH
	@end smallexample

	@node Install MacTeX to build PDF format documents
	@section Install MacTeX to build PDF format documents
	This is an optional step and can be skipped if PDF format documents aren't
	needed. The build process will use TeX engineer provided by MacTeX-2012 to
	generate PDF format documents. This component can be freely obtained from
	its official FTP server
	@uref{ftp://ftp.tug.org/historic/systems/mactex/2012/MacTeX.pkg}.
	Its original size is approximately 2.1G. Once downloaded, just double click
	on the @samp{MacTeX.pkg} file and follow the instructions to install it. By
	default the related TeX executable files won't be installed into the default
	path like @samp{/usr/bin}, so the Terminal need to be restarted before running
	the build scripts.

	@node Build the tool chain under Mac OS X
	@section Build the tool chain under Mac OS X
	With all the dependent packages installed, we can start to natively
	build the tool chain on Mac OS. Following are the commands and steps we are
	using:

	@smallexample
	@set txicodequoteundirected

	# Copy the src release package into ~/mac-build/ directory
	$ cp @value{PKG_NAME}-src.tar.bz2 ~/mac-build

	# Prepare source codes
	$ cd ~/mac-build
	$ tar xjf @value{PKG_NAME}-src.tar.bz2
	$ cd ./@value{PKG_NAME}
	$ ./install-sources.sh

	# Start building the toolchain.
	$ ./build-prerequisites.sh
	$ ./build-toolchain.sh

	@clear txicodequoteundirected
	@end smallexample

	@node Known Issues
	@appendix Known Issues

	@itemize @bullet
	@item
	If you are using different build environment and tools, you might run
	into a problem where binutils can not be successfully built. This is
	probably caused by binutils bug 13036.
	For more information, please refer to
	@uref{http://sourceware.org/bugzilla/show_bug.cgi?id=13036}.

	@item
	Some shell scripts in gcc and other packages are incompatible with
	the dash shell, which is the default /bin/sh for Ubuntu 14.04 LTS.
	You must make /bin/sh a symbolic link to one of the supported shells:
	saying bash. Here on Ubuntu 14.04 LTS system, this can be done by
	running following command:
	@smallexample
	$ sudo dpkg-reconfigure -plow dash
	@end smallexample

	Then choose @samp{No} in the @samp{Configuring dash} popup dialog and
	press enter. You can run following command and check that /bin/sh
	points to @samp{bash}:
	@smallexample
	$ ls -l /bin/sh
	...... /bin/sh -> bash
	@end smallexample
	@bye