source: rtems/README.configure @ c8f3e82

#
#  $Id$
#

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.

To re-generate auto*tool generated files (configure, Makefile.in etc),
autoconf-2.57 and automake-1.7.2 are required.

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-itron
        --disable-networking
        --enable-cxx
        --enable-bare-cpu-model=<MODEL>
        --enable-bare-cpu-cflags=<FLAGS>
        --enable-multiprocessing
        --enable-rtemsbsp="bsp1 bsp2 ..."
        --enable-tests
        --enable-rdbg            (only valid for i386 and some PowerPC BSPs)
        --enable-docs

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

        --prefix=INSTALL_DIRECTORY

By default, inline routines are used instead of macros where possible.
Macros can be selected using the --disable-inlines option.  [NOTE:
Some APIs may not support macro versions of their inline routines.]

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

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

By default, the RTEMS networking support is built for targets which
support it.  It can be specifically disabled for those targets
with the --disable-networking option.

By default, the RTEMS remote debugger server support is not built.
It can be specifically enabled for the targets that support it.
with the --enable-rdbg option. NB : the RTEMS networking support
must be enabled to support the remote debugger server.

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

By default, the RTEMS test suites are NOT configured -- only the 
sample tests are built.  --enable-tests will configure
the RTEMS test suite. The default speeds up the build
and configure process when the tests are not desired.

By default, RTEMS is built using arguments and build rules which require a
gcc supporting the -specs option, ie. a gcc >= 2.8.
[The --disable-gcc28 option, which has been present in former releases, has
been removed.]

By default, multiprocessing is is not built.  It can be enabled
for those BSPs supporting it by the --enable-multiprocessing option.

By default, all bsps for a target are built. The bare BSP is not built
unless directly specified. There are  two ways of changing this:

  + use the --enable-rtemsbsp option 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 board
within a target architecture.  Remember that the target specifies the
CPU family while the BSP specifies the precise board you will be using. 
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
        arm-rtems
        h8300-rtems
        i386-rtems
        i960-rtems
        hppa1.1-rtems
        m68k-rtems
        mips-rtems
        mips64orion-rtems
        no_cpu-rtems
        powerpc-rtems
        sh-rtems
        sparc-rtems
        bare                    see notes

The cross-compiler is set to $(target)-gcc by default. This can be
overridden 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)/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.

By default, --enable-docs is disabled and documentation is not built.

2.2 Build with Cygnus one-tree release

[NOTE: This section does not apply anymore.]

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

bare:

  1.  See the README in the bare bsp source directory. This should
      contain all info you need.
  2.  The bare bsp source contains a script to show how to build it.
  3.  The configure flags must be used to get the bare bsp to work.
      The --enable-bare-cpu-model and --enable-bare-cpu-cflags are the
      only pieces of information. The module is usually a gcc module
      such as m68302 or mcpu32. The flags are passed directly to gcc.
      Use "" if more than one option is specified.

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, FreeBSD, Cygwin, Solaris, and HPUX)

arm             : arm_bare_bsp armulator edb7312 vegaplus

c4x             : c4xsim

h8300           : h8sim

i386            : i386ex pc386 pc386dx pc486 pc586 pc686 pck6 ts_386ex
                  NOTE: The "pc386" BSP can be compiled to support a 
                        variety of PC configurations including PC-104
                        based solutions.

i960            : cvme961 i960sim rxgen960

m68k            : dmv152 efi332 efi68k gen68302 gen68340 gen68360 
                  gen68360_040 idp mcf5206elite mrm332 mvme136 mvme147
                  mvme147s mvme162 mvme162lx ods68302

no_cpu          : no_bsp  (porting example)

mips            : p4600 p4650 (p4000 port with either R4600 or R4650)
                  jmr3904 genmongoosev

or32:           : orp

powerpc         : dmv177 eth_comm gen405 helas403 mcp750 mbx8xx mtx603e
                  mvme230x ppcn_60x psim score603e

                  NOTE: The "motorola_powerpc" BSP is a single BSP which
                  can be conditionally compiled to support most Motorola
                  VMEbus, CompactPCI, and MTX boards.)

sh              : gensh1 gensh2 shsim simsh4 gensh4

sparc           : erc32 erc32nfp leon1 leon2

any             : bare

The following ports are considered deprecated and will be removed in
a future release:

a29k            : portsw

hppa1.1         : simhppa

mips64orion     : (deprecated)
                  p4600 p4650 (p4000 port with either R4600 or R4650)

                  NOTE: MIPS support is NOT being dropped.  This is a clean up
                        effort and the mips64orion BSPs and CPUs will be
                        supported by the mips port.

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

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

Default.cfg sets the default 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.

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

Please refer to the BSP and Device Driver Guide.


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
    + The C4x and OR32 ports (requires specially patched toolchain)

8. Prerequisites
================

Gawk version 2 or higher.
GNU make version 3.72 or higher.
Bash.
gcc version > 2.8

NOTE: These prerequisites are probably out of date but autoconf should detect
      any problems.