source: rtems/README.configure @ 3a7782b

1. Autoconf support
===================

This version of RTEMS is configured with GNU autoconf. RTEMS can be
configured and built either standalone or together with the compiler
tools in the Cygnus one-tree structure. Using autoconf also means
that RTEMS now can be built in a separate build directory.

2. Installation
===============

2.1 Standalone build

To configure RTEMS for a specific target, run configure in the build
directory. In addition to the standard configure options, the following
RTEMS-specific option are supported:

        --disable-rtems-inlines
        --disable-posix
        --disable-tests
        --disable-ka9q
        --enable-cpp
        --enable-gcc28               (also use enable-libcdir when disabled)
        --enable-gmake-print-directory
        --enable-libcdir=<DIRECTORY>      (do not use if gcc 2.8 is enabled)
        --enable-rtemsbsp="bsp1 bsp2 ..."

In addition, the following standard autoconf options are frequently
used when configuring RTEMS installations:

        --prefix=INSTALL_DIRECTORY
        --program-prefix=

By default, the RTEMS posix interface is built for targets that support
it. It can be disabled with the --disable-posix option.

By default, the RTEMS port of the KA9Q TCP/IP stack is build for targets
that support it.  It can be disabled with the --disable-ka9q option.

By default, the RTEMS support of C++ is disabled.  It can be enabled
with the --enable-cpp option. If the rtems++ C++ library is installed
it will also be build.

By default, the RTEMS test suites are configured.  The --disable-tests
will not configure the RTEMS test suite. This is used only to speed-up
configuration in case building the tests are not necessary.

By default, RTEMS is built using arguments and build rules which are 
compatible with gcc 2.7.2.2.  This requires that the user specify
the location of the Standard C Library with the --enable-libcdir
option.  If using a gcc which supports the -specs option, then
the --enable-gcc28 option may be used to enable this feature.
You should use the --enable-gcc28 option when using either the
egcs source tree, testgcc snapshots, or gcc 2.8.0 or newer.

By default, all bsps for a target are built. There are  two ways of
changing this:

  + use the --enable-rtemsbsp otion which will set the specified
    bsps as the default bsps, or 
  + set the RTEMS_BSP variable during make (see below).

The --enable-rtemsbsp= option configures RTEMS for a specific target
architecture.  The following targets are supported:

        (none)                  will build the host-based version on Linux,
                                Solaris and HPUX.

        a29k-rtems              only standalone, uses non-gnu compiler
        i386-rtems
        i386-go32-rtems         see notes
        i960-rtems
        hppa1_1-rtems
        m68k-rtems
        mips64orion-rtems
        no_cpu-rtems
        powerpc-rtems
        sparc-rtems
        
The cross-compiler is set to $(target)-gcc by default. This can be
overriden by:

  + using the --program-prefix option to configure to specify the
    string which will prepended to the tool names.  Be sure to include
    a trailing "-".  For example, to use a m68k-coff toolset, use the
    --program-prefix=m68k-coff- option.

To build, run make in the build directory. To specify which bsps to build,
add the RTEMS_BSP="bsp1 bsp2 .." to the make command.  Specifying multiple
BSPs to build only works from the top level build directory.

Installation is done under $(prefix)/$(target)/rtems.

As an example, to build and install the mvme136 and dmv152 bsps for m68k do:

        (path_to_rtems_src)/configure --target=m68k-rtems

        make RTEMS_BSP="mvme136 dmv152"
        
        make install RTEMS_BSP="mvme136 dmv152"

The sample tests are built by 'make all', do a 'make test' to build the full
test suite.

2.2 Build with Cygnus one-tree release

To build and install RTEMS with the one-tree structure, just copy the rtems
directory to the tree. The one-tree configure.in and Makefile.in has to be 
replaced with the RTEMS-aware versions. The build options are the same as 
for the standalone build.

2.3 Target Dependent Notes

i386-go32-rtems:

  1.  This is based on djgpp v1.xx.  It needs to be updated to v2.xx.
  2.  This cannot be built one-tree style since RTEMS requires some
      files which must be obtained from the binary distribution of the
      djgpp library.  DJGPP can be obtained from
      http://www.delorie.com/djgpp/dl/ofc.
  3.  You will need to manually install a number of files from the
      binary distribution of the DJGPP library doing something
      like the following:

      # unzip the djgpp distribution
      cd include
      cp dpmi.h INSTALL_POINT/lib/gcc-lib/i386-go32-rtems/2.7.2/include
      cp go32.h INSTALL_POINT/lib/gcc-lib/i386-go32-rtems/2.7.2/include
      cp dos.h INSTALL_POINT/lib/gcc-lib/i386-go32-rtems/2.7.2/include
      cp pc.h INSTALL_POINT/lib/gcc-lib/i386-go32-rtems/2.7.2/include

      cd ../lib
      cp crt* INSTALL_POINT/lib/gcc-lib/i386-go32-rtems/2.7.2
      cp libpc* INSTALL_POINT/lib/gcc-lib/i386-go32-rtems/2.7.2

      # Make sure about destination on the next lines.  It keeps the newlib
      # libc.a and the binary djgpp libc.a from conflicting.
      cp libc.a INSTALL_POINT/lib/gcc-lib/i386-go32-rtems/2.7.2/libcgo32.a
      cp libc_p.a INSTALL_POINT/lib/gcc-lib/i386-go32-rtems/2.7.2/libcgo32_p.a


3. To use the installed RTEMS library
=====================================

To use the installed RTEMS bsps to build applications, the application
makefile has to include a bsp-specific makefile that will define the
RTEMS variables necessary to find include files and libraries. The
bsp-specific makefile is installed at 

        $(RTEMS_MAKEFILE_PATH)/Makefile.inc

For the erc32 bsp installed at /usr/local/cross, the environment
variable RTEMS_MAKEFILE_PATH would be set as follows to the
following:

/usr/local/cross/sparc-rtems/rtems/erc32/Makefile.inc

4. Supported target bsps
========================

The following bsps are supported:

host-based      : posix (on linux, solaris and hpux)

a29k            : portsw
i386            : force386 i386ex
i386-go32       : go32 go32_p5
i960            : cvme961
hppa1_1         : simhppa
m68k            : dmv152 efi332 efi68k gen68302 gen68360 gen68360_040 idp
                  mvme136 mvme147 mvme147s mvme162 ods68302
no_cpu          : no_bsp
mips64orion     : p4600 p4650 (p4000 port with either R4600 or R4650)
powerpc         : papyrus
sparc           : erc32

5. Makefile structure
=====================

The makefiles have been re-organised. Most gnu-based bsps now use three
main makefiles:
    + custom/default.cfg,
    + custom/bsp.cfg and
    + ompilers/gcc-target-default.cfg.

Default.cfg sets the deafult values of certain common build options.

Bsp.cfg set bsp-specific build options and can also override the
default settings.

Gcc-target-default.cfg contains the common gcc definitions. Some targets
(a29k, no_cpu, and posix) still use the old structure.

6. Adding a bsp
===============

The top-level configure.in has to be modified if a new target is added
or if a new bsp is to be built by default. The additions required is
basically to add which makefiles are to be created by configure and
to add the target to the selection statement. To re-generate
configure, autoconf-2.12 is needed.

7. Tested configurations
========================

All gnu-based bsps have been built on Linux. 
The native (posix) ports have been built and run only on Linux.

The following configurations have NOT been tested:

    + Anything on Nextstep, HPUX and Irix.
    + The a29k port.

8. Pre-requisites
=================

Gawk version 2 or higher.
GNU make version 3.72 or higher.
Bash.
gcc version ???

TODO
====

The install-if-change script requires bash. On solaris systems, this should
be changed to ksh, since ksh is provided with solaris (bash not).

A fairly rescent version of gawk is needed to build RTEMS. This should be
changed so that a plain vanilla awk also works. [NOTE: This dependency
should disappear when the "gcc 2.8 -specs" is finished.]

'make install' should only install necessary files, not the full
PROJECT_RELEASE directory as now.

Posix port on solaris-2.5 fails due to undefined built-in functions
(gcc-2.7.2, might be my installation).

Improve support for 'make CFLAGS=xxx'.