/****************************************************************************/
/*	Copyright (c) 2009, Bendor Research Pty. Ltd. All rights reserved.		*/
/*	This software is released under the GNU General Public License, version	*/
/*	3, with the exemptions that 1) the header files installed by this 	 	*/
/*	package can be included in closed-source code and 2) the libraries		*/
/*	built by this package can be statically linked into a closed-source 	*/
/*	binary. See the file LICENSE for the details.							*/
/*	This software is provided "AS IS", without any warranty or guarantee.	*/
/*	By using this software you acknowledge that neither Bendor Research nor	*/
/*	any of its personnel or affiliates can be held liable for any damages,	*/
/*	including, but not limited to, loss of business, loss of money, loss of */
/*	life, loss or reputation, arising out of this software being faulty or	*/
/*	not performing as advertised, even if Bendor Research was aware of such	*/
/*	faults in the software. You use this software at your own risk, any and */
/*	all liabilities that arise out of your using this software are strictly	*/
/*	yours.																	*/
/****************************************************************************/

/**

@page install Installation

@section Requirements Requirements

To install the library, you will need a unix-ish system with the following
software:
-	GNU <tt>make</tt> version 3.81 or better
-	GNU <tt>binutils</tt> and <tt>gcc</tt> configured for
	<tt>arm-elf</tt> or <tt>arm-eabi</tt> 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 <tt>cc, sh, grep, install</tt> and
	similar installed.
-	If you want to generate the documentation, the one you're reading now,
	you will need <tt>doxygen</tt> 1.6 or newer.<br>

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 \ref gnu_install page.<br>

@section howtoget 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

- <tt>armlib.YYYY-MM-DD.tgz</tt>

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

@section Configuration Configuring, building and installing the library

Unpack the library and go into the source directory:
@verbatim
tar xfz armlib-YYYY-MM-DD.tgz
cd armlib-YYYY-MM-DD
@endverbatim
There is no fancy <tt>configure</tt> script. There is a <tt>Makefile.conf</tt>
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.
<br><br>
When you've finished with <tt>Makefile.conf</tt> you should just type
@verbatim
make
@endverbatim
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
<tt>libc/stdlib/qsort.c</tt> fails, you will find the compiler's error
messages in the file <tt>qsort.err</tt>.
<br><br>
If everything went fine, then you can type
@verbatim
sudo make install
@endverbatim
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 <tt>/usr/local/armlib/</tt>).

@subsection keep 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 <tt>make</tt> when you build the library:
@verbatim
make ARMLIB_CONFIG=~/my_config
sudo make ARMLIB_CONFIG=~/my_config install
@endverbatim
Alternatively, if you set the <tt>ARMLIB_CONFIG</tt> environment variable
to point to the config file, <tt>make</tt> 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 <tt>ARMLIB_CONFIG</tt> 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 <tt>Makefile.conf</tt> in the source directory is used.

@subsection other Other make targets

Apart from no target and the <tt>install</tt> target, you can issue the
following commands:
@verbatim
make all
@endverbatim
The same as starting <tt>make</tt> without an explicit target.
<br><br>
@verbatim
make clean
@endverbatim
Deletes all object files, dependency files and error files. It does not
delete the HTML documentation.
<br><br>
@verbatim
make veryclean
@endverbatim
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.
<br><br>
@verbatim
make docs
@endverbatim
Builds the HTML documentation. You need <tt>doxygen</tt> version 1.6 or better
to be installed. If the build fails, the error messages will be in
<tt>docs.err</tt>.
<br><br>
@verbatim
make release
@endverbatim
Creates a file, <tt>/tmp/armlib.YYYY-MM-DD.tgz</tt> 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 <tt>temp</tt>,
then that directory 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.

@section locations What gets installed

In the directory that you specified (default is <tt>/usr/local/armlib</tt>) the
install process creates these subdirectories:
- <tt>bin</tt><br>
	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.

- <tt>include</tt><br>
	Contains all the include files declaring the library functions, data
	types and constants.

- <tt>lib</tt><br>
	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
	<br><br>
	<b>lib</b><i>name</i><b>-</b><i>variant</i><b>.a</b><br><br>
	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, <tt>libm-aif.a</tt> is the
	math library (customarily called 'm'), compiled for ARM, with interworking
	enabled and optimised for speed. All libraries contain debug symbols.

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

