=========================================================================== Building a GNU HC12 Toolchain =========================================================================== :Author: Colin D. Bennett :Date: 23 May 2008 .. contents:: Introduction ============ This document describes the process of building a GNU toolchain for the Freescale 68HC12 microcontroller architecture. The toolchain includes an assembler, compiler, linker, and basic C standard library functions. We are going to install the toolchain under your home directory, ``$HOME``, in the ``$HOME/bin/m6812-elf`` directory. Then by adding ``$HOME/bin/m6812-elf/bin`` to your ``PATH`` environment variable, you can run the HC12 toolchain program easily from the shell prompt. Since we are installing under your home directory, you can install as a regular user and do not need to be root. You'll need to install Binutils, gcc, and Newlib in that order, since each needs the preceding package in order to build it. Prerequisites ============= You must have several build tools installed: * A native GNU toolchain (binutils, gcc) and GNU autotools, * lex and bison, and * texinfo (for the ``makeinfo`` program). Check whether lex and bison are installed:: $ lex --version lex 2.5.33 $ bison --version bison (GNU Bison) 2.3 If you get an error attempting to run lex or bison, you need to install them. On Ubuntu, run :: sudo apt-get install lex bison Build Process ============= Preparation ----------- Since we will be extracting several source archives into subdirectories and generation binaries in other subdirectories, it is best to do the building in a new directory that you can easy delete after the build is complete. In this guide, it will be assumed that you build in a directory called ``hc12build`` within your home directory, i.e., ``$HOME/hc12build``. To set this up, you can open a new shell (which you will want to keep open for the rest of the build) and execute these commands:: mkdir ~/hc12build cd ~/hc12build The next step is to download the source archives for the packages. You can save them anywhere on your system, but we'll assume you chose to save the source archives in the ``~/hc12build`` directory. You can download the archives from the `FreeHC12 downloads`_ page with your web browser, or you may prefer to download the source archives from the command line:: wget http://freehc12.gibibit.com/files/binutils-2.18.50.20080409.tar.bz2 wget http://freehc12.gibibit.com/files/gcc-4.2-svn134301.tar.bz2 wget http://freehc12.gibibit.com/files/newlib-1.16.0.tar.gz You are now ready to build and install the three packages. Installing Binutils ------------------- To install binutils, execute the following at a shell prompt:: tar -xjf binutils-2.18.50.20080409.tar.bz2 mkdir build-binutils && cd build-binutils ../binutils-2.18.50.20080409/configure \ --target=m6812-elf --prefix=$HOME/bin/m6812-elf make -j2 make install .. note:: If you receive an error message like :: checking for C compiler default output file name... configure: error: C compiler cannot create executables See `config.log' for more details. from the ``configure`` command, you probably need to install the native toolchain packages for your system. On Ubuntu Linux, install the "build-essential" package, which can be done most easily from the shell prompt with :: sudo apt-get install build-essential Once you have the toolchain installed, execute the ``configure`` step again. Now put the m6812-elf binutils in your PATH so that they can be used for the gcc build process, by executing the following command in your shell:: export PATH="$HOME/bin/m6812-elf/bin:$PATH" To test the Binutils installation, execute:: m6812-elf-objdump If you get a page or so of help on command line options, then your installation was successful and you can proceed to installing gcc. Installing gcc -------------- We'll do an out-of-source build of gcc:: cd ~/hc12build tar -xjf gcc-4.2-svn134301.tar.bz2 mkdir build-gcc && cd build-gcc ../gcc-4.2-svn134301/configure \ --target=m6812-elf --prefix=$HOME/bin/m6812-elf \ --disable-nls --disable-libssp --enable-languages=c,c++ make -j2 make install .. note:: If you receive an error message like :: gcc: gengtype-lex.c: No such file or directory gcc: no input files make[2]: *** [build/gengtype-lex.o] Error 1 then you need to install lex or bison. See Prerequisites_ for instructions. You will need to execute the ``configure`` step again after installing lex and bison. The m6812-elf gcc binaries are already in your path since you added ``$HOME/bin/m6812-elf/bin`` to your path after installing binutils. To test gcc, execute:: m6812-elf-gcc -v and ensure that gcc displays its version information. If you get a response indicating ``command not found``, then something is wrong and you should make sure that your PATH is set correctly, and that gcc was installed to the right directory. Installing Newlib ----------------- This is the C standard library for embedded systems. Even if you don't intend to use any C standard library functions, Newlib provides some helpful headers such as ``stdint.h``, which defines ``uint8_t`` and other specific integral types. Building Newlib:: cd ~/hc12build tar -xzf newlib-1.16.0.tar.gz mkdir build-newlib && cd build-newlib ../newlib-1.16.0/configure --prefix=$HOME/bin/m6812-elf \ --target=m6812-elf \ --disable-newlib-io-float --disable-newlib-multithread make make install .. note:: If ``make`` fails, you may see a message like :: WARNING: `makeinfo' is missing on your system. This means you need to install the texinfo package (Ubuntu: ``sudo apt-get install texinfo``). Final Setup ----------- The last thing to do is edit your ~/.profile or ~/.bash_profile to set up the required environment variables. At this point, putting ``$HOME/bin/m6812-elf/bin`` in your path is all that is needed, but when you install the FreeHC12 library, you will need to set up a couple more environment variables so that it can be located. To prepare for that step, we will create a file called ``.m6812-env`` in our home directory with the following contents:: PATH="$HOME/bin/m6812-elf/bin:$PATH" Then, add the following line to your ``~/.bash_profile`` or ``~/.profile`` (depending on which one your system is set up to use):: . ~/.m6812-env (Make sure there is a space between the ``.`` and the ``~/.m6812-env``.) Now if you log out and log back in to your account, you should still be able to execute ``m6812-elf-gcc`` from the shell prompt, since your ``.profile`` properly set up your ``PATH``. What To Do Next =============== Now that you have a working HC12 toolchain, read and follow the `FreeHC12 installation instructions`_ from the `FreeHC12 documentation`_ page. You may also delete the ``hc12build`` directory. The toolchain was installed to ``~/bin/m6812-elf`` and all necessary files have been installed there. Package Sources =============== The package source archives available on the `FreeHC12 downloads`_ page have been verified to build a working HC12 toolchain. The following section lists the locations where the source archives were obtained. .. note:: Some of the source archives for on the `FreeHC12 downloads`_ page have been repackaged from the original files to make the archive extract into a subdirectory with a more descriptive name (and one that matches the archive's file name without the extension). Binutils -------- :Version: 2.18.50 (2.18.50.20080409) :Source URL: ftp://sourceware.org/pub/binutils/snapshots/binutils-2.18.50.tar.bz2 gcc --- :Version: 4.2.4 20080411 (prerelease) (gcc-4_2-branch SVN rev 134197) :Source URL: svn://gcc.gnu.org/svn/gcc/branches/gcc-4_2-branch (rev 134197) I tried to build gcc 4.3 and gcc 4.4, and both failed to compile for the HC12 architecture. The 4.2 branch is the latest gcc version that I have been able to get working for the HC12. Newlib ------ :Version: 1.16.0 :Source URL: ftp://sources.redhat.com/pub/newlib/newlib-1.16.0.tar.gz .. _FreeHC12 downloads: http://freehc12.gibibit.com/Download .. _FreeHC12 documentation: http://freehc12.gibibit.com/Docs .. _FreeHC12 installation instructions: http://freehc12.gibibit.com/FreeHC12_install