INSTALL

BUILDING AND INSTALLATION HINTS FOR CEXP
$Id: INSTALL,v 1.15 2009/02/09 20:03:04 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:
----------
 - OPTIONAL: libbfd, libopcodes, libiberty (from binutils vers. 2.18)

 - 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 build system uses the well-known GNU 'configure' method.

a) Host Demo

  mkdir build-host
  cd    build-host
  ../configure
  make

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

Note that the symbol table is like any other object file
searched for using the PATH environment variable. E.g., if
'.' is not in your PATH you must specify the path to cexp.sym
explicitly (-s ./cexp.sym; just '-s cexp.sym' only works if
'.' is in your PATH).

b) Build Cexp target library and cross xsyms tool for a specific
   RTEMS BSP

     mkdir  build-mvme3100
     cd     build-mvme3100
     ../configure --with-rtems-top=/path/to/rtems --host=powerpc-rtems
     make

   NOTES:
    * point '--with-rtems-top' to RTEMS' 'PROJECT_ROOT', i.e., the
	  directory where RTEMS' '<cpu>-rtems' and 'make' directories
	  are found.
    * cross tools must be found in PATH
	* will build for all BSPs found under <with-rtems-top>/<host-cpu>-rtems/
	  but you can restrict the BSPs built using --enable-rtemsbsp='bsp1 bsp2'
    * if no '--host' option is given (but the build system 'knows'
      that the host system is RTEMS because of the --with-rtems-top option)
      then all BSPs for all architectures found under <with-rtems-top>
      are configured. It is possible to build for a subset of BSPs
      simply by listing them in --with-rtemsbsp -- the BSPs need not
      belong to the same host architecture (but if --host is given
      then they do).


   Build cross xsyms tool:

     mkdir build-xsyms
	 cd    build-xsyms
	 ../configure --disable-cexp --target=powerpc-rtems
	 make


c) Build CEXP multilibs. Note that this requires a multilibbed
   RTEMS cpukit.

     mkdir build-powerpc-rtems
	 cd    build-powerpc-rtems
	 ../configure --with-rtems-top=/path/to/rtems --host=powerpc-rtems --enable-multilib
	 make

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

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

	mkdir build-i386-linux

chdir to the new directory and issue

	../configure

This configures Cexp so that a native demo program is built
which can be executed on the host (e.g., linux) system.

When doing a 'cross-build' (e.g. for RTEMS), you need to
specify the host architecture on which Cexp shall be executed.
Also, you must point the configure script to your RTEMS 
installation, i.e., the directory where the target libraries
are located under "<cpu>-rtems/<bsp>/lib/". This is usually
/opt/rtems-<version>

	../configure --host=powerpc-rtems --with-rtems-top=/opt/rtems-4.9.0

This builds Cexp for all installed BSP's of the 'powerpc-rtems'
architecture. You may restrict the list of BSPs by using the
--enable-rtemsbsp='bsp1 bsp2 bsp3' option.

The configure script recognizes several other options:

	--help	list known options.

	--disable-nls
	        disable native language support.

	--disable-bfd
	        use pmbfd instead of libbfd (only relevant if you
	        have BFD sources installed).

	--disable-loader
	        disable the run-time loader. An ELF symbol file
	        can still be read. If you disable both, the loader AND
			pmbfd (--disable-loader --disable-pmbfd) then all support
			for reading files is removed. You must create, compile
			and link a 'built-in' symbol table in this case.

    --disable-opcodes
	        don't use the opcodes library. This removes the
	        disassembler. This option is only relevant if you
			have BFD sources installed.

	--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)

			If both, TECLA and readline are disabled then a minimal
			built-in editor is used.

	--enable-multilib
	        Build all variants the compiler knows about.
	        Contrary to the help text multilibs are NOT enabled by
			default. Also, since binutils is not multilib-capable
			multilib support is only available if BFD is not used.
			(pmbfd can be multilibbed).
			NOTE: multilibs can only be built if RTEMS' cpukit
			      was built with multilibs enabled.

	--prefix=<path>
	        Top directory under which everything gets installed
			(libraries, headers, documentation etc.).

	--exec-prefix-<path>
	        Prefix for libraries, executables and (by default) 
			headers. Default:

			   PREFIX/target/ssrlApps/${host_cpu}-rtems/${rtems_bsp}/

    --libdir
	        Where the libraries are to be installed. Defaults to

			   EPREFIX/lib

	--includedir
	        Where headers are to be installed. Defaults to

			   EPREFIX/include

	--bindir
	        Where executables are to be installed. Defaults to

			   EPREFIX/bin

    --enable-std-rtems-installdirs
            Install directly into the RTEMS installation directories;
			by default a location *outside* of the standard location
			is used. If you don't use this option you can also fine-tune
			the installation using the usual --prefix, --exec-prefix,
			--libdir, --includedir etc. options. If you use this
			option '--prefix' & friends are effectively overridden.

	--with-hostbindir=<path>
			Where tools, i.e., programs that execute on the development
			platform are to be installed. Defaults to

			   PREFIX/host/${build_alias}/bin

    --enable-text-segment= yes | no | 0 | <size>
	        Define how memory for PowerPC text segments is to be
			set aside (ignored on other platforms). Consult the
			README ('PowerPC Branch Relocation Information') for
			more information about this option.

Configuring Cexp using the GNU BFD library
- - - - - - - - - - - - - - - - - - - - - -

By default, Cexp now uses the 'poor man's bfd and elf'
libraries as a replacement for the GNU BFD library
but you can still use the GNU BFD library. The main
reason for using BFD would be the desire to use Cexp
on a target that is unsupported by pmbfd (however,
for any ELF target you are encouraged to implement
relocations and contribute the code to Cexp).

Also, if you want to use the disassembler then you need
to install the BFD/opcodes libraries (note that you may
use opcodes with pmbfd yielding a smaller executable).

In order to use BFD, opcodes or both you need to
perform the following steps:

  a) download binutils-2.18 source
  b) untar and install the source into the 'cexp' source directory
  c) create a symlink binutils -> binutils-2.18
  d) *patch* the binutils-2.18 sources running

       patch -b -p0 < binutils-2.18.diff

	 from the cexp source directory (it is always a good idea
	 to try '--dry-run' first).

  e) configure and make cexp in the usual way. Note that
     by default both the BFD and opcodes libraries are
	 configured and used if 'configure' finds binutils
	 sources in the cexp source dir.
     The following 'configure' options are relevant if
	 you have binutils sources available:

	   --disable-bfd
	        do NOT use BFD but use pmbfd. By default
			BFD is used if binutils sources are found.

	   --disable-opcodes
	        Disable disassembler support.

     E.g., if you want to configure Cexp to use pmbfd
	 and and opcodes (for disassembler support) then say

	   --disable-bfd

Building Cexp :
- - - - - - - -
Recommendation: 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
or libpmbfd/libpmelf), 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 --with-rtems-top=<path> --host=<cpu>-rtems'

   will generate 'libcexp' for running 'cexp' on the target.
   E.g., 
     mkdir build-powerpc-rtems
     cd    build-powerpc-rtems
     ../configure --with-rtems-top=/opt/rtems --prefix=/opt/rtems --host=powerpc-rtems
     make
     make install

 - a cross-tool-configuration

     '../configure --target=<cpu>-rtems --disable-cexp'
	 
   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 --build=i386-linux26 --target=powerpc-rtems --disable-cexp --prefix=/opt/rtems
     make
     make install

   Note: 'xsyms' is installed in the 'hostbindir' (see --with-hostbindir
         above) in this example the executable will be installed as

		   /opt/rtems/host/i386-linux26/bin/powerpc-rtems-xsyms

[
 - a native configuration ('configure') 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').
]

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.

Linking an Application (Library Dependencies)
---------------------------------------------
Consult the README for important information about how to produce
auxiliary files that force linkage of essential std library code.

Here we only document the library dependencies: In order to use
Cexp, your application needs to link

      -lcexp -lspencer_regexp

  if NOT configured with --disable-tecla then add

      -ltecla_r 

  if binutils sources are available and Cexp was NOT configured
  with --disable-opcodes then add

      -lopcodes

  if NOT configured with --disable-loader then add

    EITHER (binutils sources not installed or --disable-bfd given)

      -lpmbfd -lpmelf  

    OR (binutils sources available and --disable-bfd NOT given)   
	  
	    -lbfd 

  else (i.e., --disable-loader *was* given)
  if --disable-elfsyms was NOT given then add

      -lpmelf

  Finally, if you end up using either -lbfd or -lopcodes (or both)
  then you also need to add

      -liberty

Tested Configurations:
----------------------
 - linux-x86
 - linux-ppc
 - solaris-sparc
 - RTEMS-mvme23xx (PowerPC 604)
 - RTEMS-svgm     (PowerPC 750 and 7400)
 - RTEMS-mvme5500
 - RTEMS-beatnik (mvme5500, mvme6100)
 - RTEMS-mvme2100
 - RTEMS-mvme3100
 - ML405 (virtex)
 - RTEMS-pc586
 - RTEMS-mvme167
 - RTEMS-uC5282

Installing Cexp:
- - - - - - - - -
'make install' should do the job. Choose the prefixes or
--enable-std-rtems-installdirs to meet your needs.