OpenISA Tools

-------------------------------------------------------------------------------
-------------------------------------------------------------------------------

  Part I. Building the tools

-------------------------------------------------------------------------------
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
0. Introduction
-------------------------------------------------------------------------------

This document describes how to compile and install the OpenISA toolchain.

-------------------------------------------------------------------------------
1. Linker
-------------------------------------------------------------------------------

The OpenISA linker is based on GNU binutils. To have access to its source code,
you need to clone (you haven't done it already) the OpenISA master repository:

$ git clone https://github.com/rafaelauler/openisa.git --depth 1

1.1 Building the linker

In this step, we will build the first element of our OpenISA toolchain, a folder
where we will keep all toolchain utils. We will call this folder "oi-toolchain".

$ cd openisa/linker-oi
$ wget http://ftp.gnu.org/gnu/binutils/binutils-2.23.2.tar.bz2
$ tar xjvf binutils-2.23.2.tar.bz2
$ git reset --hard  #recover modifications caused by extracting binutils package
$ mkdir build
$ cd build
$ ../binutils-2.23.2/configure --prefix=$(pwd)/../../oi-toolchain \
  --disable-nls --enable-shared --disable-multilib \
  --target=mipsel-unknown-linux-gnu --disable-werror
$ make MAKEINFO=true -j20  # Adjust -j accordingly
$ make install MAKEINFO=true
$ cd ../..

-------------------------------------------------------------------------------
2. Compiler
-------------------------------------------------------------------------------

The OpenISA compiler is based on Clang and LLVM. The llvm-openisa.git repo
contains the source code in its entirety. Keep in mind that the LLVM project
is composed of multiple repositories. We fork llvm, clang and compiler-rt
repos. The latter two are added inside our llvm fork as git submodules, so
you may want to use the "--recursive" flag when cloning.

2.1 Setting up repos

$ git clone --recursive https://github.com/rafaelauler/llvm-openisa.git \
    -b openisa --depth 1

This may take a while because of the long history of commits of the LLVM
project. If you clone with "--depth 1", you can get a shallow copy much faster.

2.2 Setting up your build

Next step is to create a folder to build the compiler.

$ mkdir obj
$ cd obj

And configure it, keeping in mind we intend to install it in the *same* folder
you installed the linker, so adjust the command line to reflect so.

$ cmake ../llvm-openisa -DLLVM_TARGETS_TO_BUILD="Mips;X86;ARM" \
  -DCMAKE_INSTALL_PREFIX=$(pwd)/../oi-toolchain \
  -DLLVM_DEFAULT_TARGET_TRIPLE="mipsel-unknown-linux-gnu" \
  -DCLANG_VENDOR="OpenISA Tools" -GNinja

If you don't use ninja, please remember to remove "-GNinja". You may also want
to add the -DCMAKE_BUILD_TYPE="Release" flag to build an optimized binary.

Now build and install it:

$ ninja && ninja install
$ cd ..

-------------------------------------------------------------------------------
3. C standard library
-------------------------------------------------------------------------------

The OpenISA toolchain relies on newlib to provide its C library. Its source
code is available in the same repository of the linker (the master repository).

3.1 Setting up build

First you need to put whatever tools you have so far of the OpenISA toolchain in
your path:

$ cd oi-toolchain/bin
$ export PATH=$(pwd):$PATH
$ cd ../..

Now go to newlib's folder and prepare your build. Configure it to install in the
same oi-toolchain folder used before (adjust the command line below
accordingly).

$ cd newlib
$ mkdir build
$ cd build
$ CC_FOR_TARGET="clang"\
   CXX_FOR_TARGET="clang++"\
   AR_FOR_TARGET="mipsel-unknown-linux-gnu-ar"\
   AS_FOR_TARGET="mipsel-unknown-linux-gnu-as"\
   LD_FOR_TARGET="mipsel-unknown-linux-gnu-ld"\
   NM_FOR_TARGET="mipsel-unknown-linux-gnu-nm"\
   OBJDUMP_FOR_TARGET="mipsel-unknown-linux-gnu-objdump"\
   RANLIB_FOR_TARGET="mipsel-unknown-linux-gnu-ranlib"\
   READELF_FOR_TARGET="mipsel-unknown-linux-gnu-readelf"\
   STRIP_FOR_TARGET="mipsel-unknown-linux-gnu-strip"\
   ../newlib-2.1.0/configure --prefix=$(pwd)/../../oi-toolchain -target=oi-elf
$ make && make install

Now, manually copy the linker script used by the OpenISA linker:

$ cp ../newlib-2.1.0/libgloss/libnosys/ac_link.ld ../../oi-toolchain/oi-elf/lib

Finally, compile ac_start.o:

$ cd ../../oi-toolchain/oi-elf/lib
$ clang -c ../../../newlib/newlib-2.1.0/libgloss/libnosys/ac_start.S \
  -o ac_start.o

-------------------------------------------------------------------------------
-------------------------------------------------------------------------------

  Part II. Using the tools

-------------------------------------------------------------------------------
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
4. Using the compiler, assembler and disassembler
-------------------------------------------------------------------------------

Use the clang compiler driver (command line "clang" if you put oi-toolchain/bin
in your path) to access the OpenISA compiler, assembler or linker. The linker
itself is an external tool, but the clang driver knows where to find it, if you
installed everything following the instructions in this manual.

Example 1: compile to assembly

$ echo  'int main() { printf("Hello, world!\n"); return 0; }' | clang -x c \
  -S -o test.s - && cat test.s

Example 2: compile to object

$ echo  'int main() { printf("Hello, world!\n"); return 0; }' | clang -x c \
  -c -o test.o -

Example 3: using a disassembler to disassemble the obj created in the previous
  example

$ llvm-objdump -disassemble test.o

Example 4: compile to final executable

$ clang input.c -o input

                  *.---.* end of document *.---.*