# Installation

## Requirements

To install the library, you will need a unix-ish system with the following software:

- GNU `make` version 3.81 or better
- GNU `binutils` and `gcc` configured for `arm-elf` or `arm-eabi` targets. You can build the library with gcc versions 4.[0-4].x. It was not tested if you can use 3.x.x and 4.5.x versions of gcc.
- Basic unix utilities, such as `cc, sh, grep, install` and similar installed.
- If you want to generate the documentation, the one you're reading now, you will need `doxygen` 1.6 or newer.

All of the unix utilities are available on most BSD and Linux systems as well as on MacOS-X. On these systems installing the cross-binutils and cross-gcc is also fairly simple. If you do not know how to build a crosscompiler toolchain, you can read the Installation of the GNU tools page.

## Obtaining the library

Currently the library is only on our website and not mirrored anywhere else. If you go to http://www.bendor.com.au/armlib/index.html you will find the source there. We have a fairly slow uplink, so be patient. Library versions are tracked by their release date, the files are called

- `armlib.YYYY-MM-DD.tgz`

where YYYY, MM and DD are the year, month and day, respectively.

## Configuring, building and installing the library

Unpack the library and go into the source directory:

    tar xfz armlib-YYYY-MM-DD.tgz
    cd armlib-YYYY-MM-DD

There is no fancy `configure` script. There is a `Makefile.conf` file that you have to edit with your favourite text editor. All the configuration options are pretty well documented in that file, the options are not repeated here. The file is actually read by make, so the syntax rules are the same as for any makefile.
When you've finished with `Makefile.conf` you should just type

    make

As the make progresses, it will tell you what it does. If there is an error (there shouldn't be), the build process stops. The error messages will be stored in the file that has the stem of the file being processed, with the extension of ".err". That is, if for some reason the compilation of `libc/stdlib/qsort.c` fails, you will find the compiler's error messages in the file `qsort.err`.
If everything went fine, then you can type

    sudo make install

and the libraries, the header files, the tools and the documentation will be installed in the location you nominated in the configuration file (the default being `/usr/local/armlib/`).

### Keeping the configuration over library revisions

If you want to compile subsequent library versions with the same config file (so that you don't have to edit it again and again), you can pass an option to `make` when you build the library:

    make ARMLIB_CONFIG=~/my_config
    sudo make ARMLIB_CONFIG=~/my_config install

Alternatively, if you set the `ARMLIB_CONFIG` environment variable to point to the config file, `make` will pick it up. So, the location of the config file is determined by:

- If you pass it explicitely on the make command line, that location will be used.
- Otherwise, if the `ARMLIB_CONFIG` environment variable is set, then the file indicated by that is used.
- Finally, if neither the command line nor the environment specifies a file, the `Makefile.conf` in the source directory is used.

### Other make targets

Apart from no target and the `install` target, you can issue the following commands:

    make all

The same as starting `make` without an explicit target.

    make clean

Deletes all object files, dependency files and error files. It does not delete the HTML documentation.

    make veryclean

Deletes all object files, dependency files and error files as well as the HTML documentation. It furthermore deletes all files ending with the ~ (tilde) character, which customarily indicates that the file is an editor back-up file.

    make docs

Builds the HTML documentation. You need `doxygen` version 1.6 or better to be installed. If the build fails, the error messages will be in `docs.err`.

    make release

Creates a file, `/tmp/armlib.YYYY-MM-DD.tgz` with today's date. That file will contain the source code and the HTML documentation. The file is only created if the library as well as the documentation can be built successfully. If the source tree has a directory called `temp` and/or a directory called `junk`, then those directories will be omitted from the tarfile. The state of your current source tree, objects and so on is not modified; the entire build and packaging process is done in /tmp, on a copy of your current source tree.

## What gets installed

In the directory that you specified (default is `/usr/local/armlib`) the install process creates these subdirectories:

- `bin`
  Contains the binary utilities, native to the build system. These are simple tools that are not part of the library proper, but can be useful for development.

- `include`
  Contains all the include files declaring the library functions, data types and constants.

- `lib`
  Contains the library objects. Each library is built in eight different variants. The variant is represented as a suffix of the library name. The actual filename is
  libname-variant.a
  The variant is 3 letters. The first letter is 'a' or 't', indicating that the library was compiled for ARM or THUMB, respectively. The second letter is either 'i' or 'n', indicating that the library was compiled with interworking or with no interworking, respectively. The last letter is either 'f' or 's', indicating that the compiler was asked to generate fast (-O2) or small (-Os) code, respectively. Thus, `libm-aif.a` is the math library (customarily called 'm'), compiled for ARM, with interworking enabled and optimised for speed. All libraries contain debug symbols.

- `docs/html`
  Contains the HTML documentation, the same one that you are reading now. The main page is `index.html` in that directory.