How Do I Install the MiNTLib?
=============================

The installation process differs depending on the kind of distribution
you got.  Sections of this file that only refers to source or binary
distributions are marked.

Building the Library (source only)
----------------------------------

Read the file configvars and edit it to your needs.  All configuration
values are explained in a short comment.  If you edit the file, keep
in mind that it is both a Makefile and a shell script fragment.

IMPORTANT:  Please select a location from the file "zones" in the
toplevel directory and set the variables LOCALTIME and POSIXRULES
in "configvars" to that name.  The installation will succeed if you
don't do that, and the programs that use the time zone database 
provided here will you warn about it but it may be confusing.

By default four types of libraries are built: regular libraries with
32-bit integers (subdirectory lib), the same for shared-text executables 
for use with the -mbaserel gcc switch (subdirectory libb), 16-bit libraries
(subdirectory lib16) and shared-text libraries with 16-bit integers
(subdirectory libb16).

Former versions of the MiNTLib may have built more libraries by default.
To save space this has changed now.  If you need more libraries 
you have two basic ways of doing it:

	- Create new lib* subdirectories.  Copy the Makefile from another
	  lib subdirectory and edit it.  If you cd into your new 
	  lib directory and type "make" the library will be built.
	  Advantage: You always have a recent copy of all object files
	  you need and you can build all libraries with just one
	  make run (provided that you also added your directory to
	  the subdirectory list in the toplevel Makefile).
	
	- Edit configvars and add the options you need.  You will
	  then still build the same four libraries but with the 
	  additional options you specified.  If you still want
	  the original libraries you can copy the entire source
	  tree and edit configvars only in one tree.  To save space
	  you can savely link the subdirectories include and src
	  instead of copying them recursively.

Three important special cases:  Former MiNTLibs installed libraries
with a special identifier "g" in the name that contained debugging
information.  This is probably not a good idea.  First it is likely
that somebody may think that this library is needed for profiling
(because gcrt0.o is needed for profiling).  There is no real reason
to do so.  If you don't need debugging information you can always
strip the symbol table of the executable.  No need to keep distinct
libraries.  Just edit configvars, add "-g" and that's it.

Special versions for special processors.  Well, if you only need
the libraries for private use and never release software, simply
add the flag to configvar's CFLAGS.  Otherwise choose one of
the ways described above.

Soft floating-point support.  Either add -Dsfp004 to DEFS in configvars
or change the variable WITH_SOFT_FP to yes.  The latter will affect
the library naming scheme (for example "libc.a" => "libcsfp004.a").

Cross-building (source only)
----------------------------

It is very easy to cross-build the MiNTLib on another machine with
a different architecture.  Edit configvars and change the values
for CC, AR and RANLIB.  For the installation you should also
change prefix, includedir, libdir and mandir.  You also have to
define the variable CROSS to avoid some installations.

Running make (source only)
--------------------------

Change into the toplevel directory and type "make".  Depending 
on your system's performance this process may take up to
several hours.

NOTE: It may take a considerable amount of time for make to
figure out all dependencies.  This applies primarily (but not
only) to the "lib*" subdirectories, especially if you rebuild
the library from a former version (in this case a lot of 
dependency files have been created to force automatic recompilation
of obsoleted modules).  During this time (up to several minutes)
make will say nothing.  Don't desparate, just wait, once that
make has figured out everything, it will proceed at normal
speed.

Installing (source only)
------------------------

With a source distribution you just have to type "make install".
You probably need to be root for that.  You can also skip the
above step (Running make) and directly type "make install".  The
Makefiles won't install until everything is build correctly.

Installing (binary and source)
------------------------------

NOTE:  In the toplevel directory you will find a shell-script
called "libinstall".  It is still experimental but running it
should actually install everything accurately.  The script is
suitable both for binary and source distributions.  If it 
fails, please read on.

If for some reason "libinstall" resp. "make install" fails 
you will have to install by hand.  First install the header files.  
You will usually install them in "/usr/local/include" (make sure 
that this is in your compiler's include path and it comes before 
your system include directory).  You can also replace your system
header files and install in "/usr/include" instead.  But then 
when upgrading your system your new files may get overwritten.  
For the following we will assume that you install in 
"/usr/local/include".

You will probably need to be root to install!

Make sure that the directories "/usr/local/include",
"/usr/local/include/sys" and "/usr/local/include/mint" exist
and have appropriate permissions.

Copy all header files from the distribution's "include" subdirectory 
to "/usr/local/include":

	# cd include
	# cp *.h /usr/local/include
	# cp sys/*.h /usr/local/include/sys
	# cp mint/*.h /usr/local/include/mint
	# cp stab.def /usr/local/include
	# cp COPYMINT COPYRIGHT /usr/local/include

Don't forget the file "stab.def"! It's important.

If you have the "install" command, instead of using "cp" you preferably
should use "install -m 644 -o root -g sys".

If you upgrade from a MiNTLib version before 0.50.1 you will probably
have to remove (or rename) some of your old include files.  Please
read the file include/00README and remove all header files mentioned
their from all (!) of your system include directories.

Next you have to install the libraries and the startup modules.  
They are usually installed in "/usr/local/lib" (or in "/usr/lib",
see the comments above).  The startup modules reside in the
distribution subdirectory "startup" and the individual libraries
can be found in "lib", "libb", "lib16", and "libb16".  Install
them all in the same directory:

	# cd startup
	# cp startup/*.o lib*/*.a /usr/local/lib

A safer alternative for installing the libraries would look like:

	# for dir in lib libb lib16 libb16; do
	# cp $dir/*.a /usr/local/lib
	# done

Now make sure that all installed files have the appropriate
permissions (use the chmod, chown and chgrp commands).

Troubleshooting
---------------

If something doesn't work and you don't find a solution here
you can also have a look at the file FAQ.

For all of the following hints please write a simple test program 
(for example hello.c) and compile it with the "-v" option for your 
compiler.  The compiler will then list all the paths it searches for 
include files and libraries and may also give other useful information.

- Include files not found.
  
  Check if the directory where you installed the included files is
  listed in the "gcc -v" output.  If you don't find it there you
  should change your gcc specs file.  It can usually be found
  in "/usr/local/lib/gcc-lib/m68k-mint/<VERSION>/specs".  Please
  make sure that you use an editor that can handle very long lines
  when editing "specs", notably qed and pico will probably mess
  up the file.
  
  You will find a line like
  
  *cpp:
  %{m...
  
  Put "-I/usr/local/include " (or wherever you installed) in front
  of everything else in the line (here in front of the % sign).
  
  Alternatively you can set the environment variable C_INCLUDE_PATH
  (or CPLUS_INCLUDE_PATH or OBJC_INCLUDE_PATH for C++/Objective C
  respectively) to "/usr/local/include".  These environment variables
  can actually contain colon separated lists of directories, much
  like the PATH variable.  You can therefore also specify multiple
  directories like "C_INCLUDE_PATH=/usr/local/include:/usr/special/include".

- Libraries or startup modules not found.

  This is more or less the same as for include files not found.
  Again write hello.c, compile it with the -v option and look
  what goes wrong.  Edit your specs (again, not with qed or pico!)
  and look for:
  
  *ld:
  %{...
  
  Put "-L/usr/local/lib" in front of the percent sign and everything
  should be fine.
  
- File not found for "c.olb" or "c.a"
  
  You have an old linker that uses a non-standard naming scheme.  Rename
  your libraries (or link them) to names that your linker expects, for
  example from "libc.a" to "c.olb" or "c.a".  If you have a source
  distribution you can avoid this problem by setting the configuration
  variables "lib_name_prefix" and "lib_name_extender" in the
  file configvars.

- Out of memory for some files

  If you run out of memory while building the libraries you have several
  options to reduce the memory consumption of the build process.
  
  You don't have to run the toplevel Makefile.  You can always cd into
  a specific subdirectory (probably the one where you ran out of memory)
  and do "make" there.
  
  If you only run out of memory for individual files you can also run
  make, wait until the command line that does the actual compilation
  ("gcc -...") shows up and interrupt make.  Then type in that command
  line by hand.  This way the make program gets bypassed for this
  module and will therefore not eat up your precious RAM.
  
  If it still doesn't work you can also bypass the compiler driver
  (gcc or cc).  Type the command line again but this time add the
  option -v.  You will then see how the compiler driver calls the other
  programs, the preprocessor cpp, the actual compiler cc1 and the
  assembler as.  The compiler driver will usually use temporary
  files for intermediate results, you have to replace them by
  non-temporary filenames but then you can run all required commands
  yourself.
  
  You can also try to compile problematic source files with 
  less optimization (remove -f... options or turn -O3 to -O2,
  -O or don't give any -O option).

- Generally not enough memory

  Buy some more.
  
  If you can't afford this kill all other unnecessary processes
  that are running simultaneously, for example daemons, accessories.
  If you run under an AES environment you can also reboot and 
  choose a command line login.
  
  Another possibility is to reduce the amount of optimization.  Edit
  the file configvars and change CFLAGS.  Optimization variables
  usually start with "-f".  The general degree of optimizaton
  is specified with "-O" (little optimization) "-O2" (normal
  optimization "-O3" (all most all except particulary expensive
  optimizations).  But if you have come so far you should really
  consider to grab a binary distribution from somewhere because
  a library that is not or only poorly optimized will suffer from
  considerable performance losses.

Hope this information is enough.

The MiNTLib maintainer

  