BUILDING AND INSTALLATION HINTS FOR CEXP
$Id: INSTALL,v 1.7 2004/05/01 01:17:01 till Exp $

For building Cexp you will need the
following programs and libraries:

Tools:
------
 - usual (cross) compiler toolchain
 - GNU bison (yacc is not enough).

NOTE: bison is only required if you
         change the grammar 'cexp.y'

Libraries:
----------
 - libbfd, libopcodes, libiberty (vers. 2.13.1, distributed with Cexp)
 - libelf (vers. 0.8.2; NOTE: 0.8.3 doesn't seem to work!)
   NOTE: libelf is only needed if cexp is configured for using libelf
         instead of BFD (discouraged; reduced functionality but a less
         restrictive license: LGPL vs. GPL) 
   libelf is downloadable at

     http://www.stud.uni-hannover.de/~michael/software/

 - Spencer's libregexp (distributed with Cexp). This is a modified,
   _reentrant_ version.

 - libtecla: clean & lean & reentrant line editor. I like it much
   better than GNU readline (messy, bloated & non-reentrant). Its
   license (X11) is less restrictive than readline's (GPL)
   NOTE: the version distributed with Cexp has been slightly
   patched to support RTEMS.

 - alternatively: GNU libreadline, which in turn requires
   libncurses or libtermcap. NOTE: libreadline is _not_ reentrant
   and hence should _NOT_ be used on RTEMS (unless you have
   one single thread using it) - I recommend using TECLA: it's smaller
   and nicer. Also, CEXP has command completion implemented for
   TECLA.

Building:
---------

Quick/Automated Method
----------------------
The top-level source directory now features a Makefile providing
some simple rules to automate the build process. The rules create
build subdirectories, 'configure' and 'make' the package.
Type 'make' in the Cexp top directory for instructions. The main
make targets are:

a) Host Demo

  make host

for building the host demo in a 'build.host' subdirectory. Both,
a 'cexp' demo executable and a 'xsyms' utility program (for
generating a symbol file in host format) are built there. To
play with the demo:

  cd build.host
  ./xsyms cexp cexp.sym
  ./cexp -s cexp.sym

b) Target library and cross xsyms tool

  make cross-TARCH

configures CEXP for running on target architecture 'TARCH' in a
'build-TARCH' subdirectory. The 'cross-xsyms' tool is configured
and built in a 'build-X-TARCH' subdirectory. E.g.,

  make cross-powerpc-rtems TGT_CONFIG_OPTS='--prefix=/opt/rtems --with-multi-subdir=m750'

Note that the rule only performes the 'configure' step once, i.e.,
at the same time the 'build-' directories are created. If a 'build-TARCH'
directory is already present, 'configure' is not re-run. You have to
remove it (either manually or by executing 'make clean' from the top-directory)
in order to re-configure.

The cross CEXP can be installed using the 'make install-TARCH' rule.
You might want to use a 'prefix=<destdir>' definition on the
command line (necessary if --prefix was not given at configuration time). 

The cross 'xsyms' tool needs to be installed manually

Examples:

    make install-powerpc-rtems prefix=/real/installpath
	install  build-X-powerpc-rtems/xsyms <cross_toolchain_bindir>/powerpc-rtems-xsyms

Manual Method in Detail
----------------------
Configuring Cexp:
- - - - - - - - -

NOTE: I'm not an autoconf/automake nightmare expert and I HATE
automake almost as much as I do windoze.

chdir to the source topdir and make a directory, e.g.

	mkdir build-i386-linux

chdir to the new directory and issue

	../configure --disable-nls

When doing a 'cross-build' (e.g. for RTEMS), you need to
set the CC environment variable an specify the host architecture
on which Cexp shall be executed:

	setenv CC powerpc-rtems-gcc
	../configure --host=powerpc-rtems --disable-nls

If you use a later gcc version with multilib support (such as
gcc-3.2 distributed by OAR/RTEMS) you most probably want to
select your CPU model (unless you are confident you will live
long enough to see the results and you can afford the disk space
it will take):

	../configure --host=powerpc-rtems --with-multisubdir=m750 --disable-nls

this example restricts the build to PowerPC mPC750...

The configure script recognizes several options:

	--help		list known options
	--disable-nls	disable native language support.
			You probably _must_ specify this as several
			directories have been deleted from the distributed
			libbfd...
	--disable-bfd	use libelf instead of libbfd. Note that this comes
			at the expense of losing the runtime loader and
			the disassembler functionality.

			NOTE: you must download libelf (0.8.2 recommended; 0.8.3
                  didn't work for me) and install it into the CEXP
                  source directory. Tweaking of the configure/makefiles
                  required for versions other than 0.8.2.
	--disable-tecla	don't use the TECLA library (discouraged)
	--disable-readline don't use GNU readline either (this option is only
			effective if --disable-tecla is also specified)

	--prefix=<path> where the libraries, headers and GNU documentation
			should be installed

Building Cexp :
- - - - - - - -
Recomendation: start with a native build (e.g. on linux or solaris) and
play around with the demo.

In the directory where you configured 'cexp', issue

	make

this builds the object file interface librarie(s) (libbfd, libopcode, libiberty
of libelf), the tecla library, the regexp library, the cexp library and (on a
host only) the 'cexp' demo program and the 'xsyms' utility.


Building xsyms:
- - - - - - - -
'xsyms' is a 'cross-tool', i.e. it runs on a host working on target object
files. Hence, if you want 'libcexp' for a target and the 'xsyms' tool for
generating symbol tables you must build the package twice:
 - a cross-configuration ('../configure CC=<cross>-gcc --host=<cross>') will
   generate 'libcexp' for running 'cexp' on the target.
   E.g., 
     mkdir build-powerpc-rtems
     cd    build-powerpc-rtems
     ../configure --prefix=/opt/rtems CC=powerpc-rtems-gcc --host=powerpc-rtems --with-multisubdir=m750 --disable-nls
     make
     make install

 - a cross-tool-configuration ('../configure CC=gcc --target=<cross>') will
   generate 'xsyms' which can be used for extracting symbol tables on
   target-objects. E.g.,
     mkdir build-X-powerpc-rtems
     cd    build-X-powerpc-rtems
     ../configure --target=powerpc-rtems
     make
     cp xsyms  <cross_toolchain_bin>/powerpc-rtems-xsyms
 
   Note that I manually installed the 'cross-xsyms' for sake of simplicity.  

[
 - a native configuration ('configure CC=gcc') builds 'libcexp' as well
   as the 'cexp' demo and 'xsyms'. The demo can be run on the host and
   'xsyms' can extract its symbol table ('xsyms cexp cexp.sym').
]

NOTE: If target and host are both ELF systems, it makes sense to
      configure 'xsyms' to use 'libelf'. One single version is then
      capable of extracting symbol tables of any ELF object:

		configure --disable-bfd --disable-cexp

RTEMS_NOTE:
Cexp (and the patched tecla library) contain some hacks to avoid
having to build for a specific BSP. Hence, one instance of the libraries
per CPU architecture should be enough (at least for PowerPC - other RTEMS
targets are untested). This also eliminates the need for
the RTEMS makefile system. The package can be built ignoring the BSP - just
specify the correct cross compiler when configuring (setenv CC).

Running the Cexp Demo on a Host
- - - - - - - - - - - - - - - -
Invoke the executable telling it to read symbols from the executable
file:

    ./cexp -s cexp

You now can type expressions etc. See 'README' for details about using
CEXP.

On some systems you may get errors 'libtecla-1.4.1.so not found' or 
similar. In this case, libtecla was built as a shared library but not
installed into one of the directories searched by the (system's)
runtime linker. Use the LD_LIBRARY_PATH environment variable and set
it to point to the directory where libtecla was built.

Tested Configurations:
----------------------
 - linux-x86
 - linux-ppc
 - solaris-sparc
 - RTEMS-mvme23xx (PowerPC 604)
 - RTEMS-svgm     (PowerPC 750 and 7400)


Installing Cexp:
- - - - - - - - -
Theoretically, 'make install' should do the job (provided that you specified
the correct '--prefix' options during configuration - this is just one
more example why GNU configure SUCKS - changing the install location after
configuration [and spending LOTS of time] is difficult if not impossible).

However, as this is prone to missing the correct location and installing
unwanted docs etc.  I prefer a manual install (I have 3 to 4 cross-gccs -
each one with its own 'info' 'man'):

Install the relevant libraries (paths relative to the build directory)
	libcexp.a
	binutils-xxx/bfd/.libs/libbfd.a
	binutils-xxx/libiberty/libiberty.a
	binutils-xxx/opcodes/.libs/libopcodes.a
	libtecla-xxx/libtecla_r.a
	regexp/libregexp.a
and headers
	../cexp.h
        ../cexpHelp.h
	other library headers as needed
