@c
@c  $Id$
@c


@node Building RTEMS, Required Tools, , Top

@chapter Building RTEMS
@ifinfo
@menu
* Required Tools::
* Issues when building RTEMS::
* Host Operating Systems and RTEMS::
* Development related questions::
@end menu
@end ifinfo

Building any package in a cross-compilation fashion can be difficult,
but configuring and building a real-time operating system that
supports many CPU families and target boards can be confusing.  The
RTEMS development team has made every effort to make this process as
straight forward as possible but there are going to be questions.

Moreover, between RTEMS 4.0 and 4.5, the configure and Makefile system in RTEMS
was changed to be more compatible with GNU standards.  This transition
has lead to a number of subtle differences.

This section of the FAQ tries to address the more frequently asked
questions about building RTEMS.  Thanks to Ralf Corsepius for
compiling this section from excerpts from various postings to the
rtems-users mailing list.


@node Required Tools, Which tools are required to build RTEMS?, Building RTEMS, Building RTEMS

@section Required Tools
@ifinfo
@menu
* Which tools are required to build RTEMS?::
* Do I need autoconf and automake to build RTEMS?::
* Do I need a native gcc on my host?::
* Can I use a non-gcc cross-toolchain?::
* Do I need gcc-2.9x for cross compilation?::
* Where to get autoconf automake ld gcc etc.?::
@end menu
@end ifinfo


@node Which tools are required to build RTEMS?, Do I need autoconf and automake to build RTEMS?, Required Tools, Required Tools

@subsection Which tools are required to build RTEMS?

@itemize @bullet

@item A native C-Toolchain, gcc prefered
@item GNU-Bash and shell utils
@item GNU-make.
@item A target (typically cross) C- and (optional) C++-Toolchain.
@item autoconf/automake (optional, recommended)
@item Perl (optional, recommended, needed by automake and some tools within RTEMS)
@item m4 (optional, recommended, needed by autoconf, GNU-m4 preferred)

@end itemize


@node Do I need autoconf and automake to build RTEMS?, Do I need a native gcc on my host?, Which tools are required to build RTEMS?, Required Tools

@subsection Do I need autoconf and automake to build RTEMS?

No, you don't.  Or to be more accurate, you won't need them until you
modify something in RTEMS's Makefile.ams/configure.acs or start to develop
with RTEMS.

I.e.  you won't need them to get started, but you will need them when getting
serious.


@node Do I need a native gcc on my host?, Can I use a non-gcc cross-toolchain?, Do I need autoconf and automake to build RTEMS?, Required Tools

@subsection Do I need a native gcc on my host?

No, you should be able to use any native, ansi-compliant C-compiler, but
using a native gcc is highly recommended.


@node Can I use a non-gcc cross-toolchain?, Do I need gcc-2.9x for cross compilation?, Do I need a native gcc on my host?, Required Tools

@subsection Can I use a non-gcc cross-toolchain?

Generally speaking, it should be possible.
However, most RTEMS development has taken place using gcc, therefore
getting it working may not be easy.


@node Do I need gcc-2.9x for cross compilation?, Where to get autoconf automake ld gcc etc.?, Can I use a non-gcc cross-toolchain?, Required Tools

@subsection Do I need gcc-2.9x for cross compilation?

[FIXME: Partially obsolete]

Not necessarily, but gcc-2.9x is highly recommended, because most development
has taken place using gcc-2.9x and previous versions of gcc are not actively
supported in RTEMS anymore (@ref{Can I use a non-gcc cross-toolchain?}).


@node Where to get autoconf automake ld gcc etc.?, Issues when building RTEMS, Do I need gcc-2.9x for cross compilation?, Required Tools

@subsection Where to get autoconf automake ld gcc etc.?

The sources of all gnutools are available at any
@uref{ftp://ftp.gnu.org,GNU} mirror.
Native Linux binaries should come with any Linux distribution.
Native Cygwin binaries should be available at Cygnus.

GNU-Toolchain binaries (gcc, binutils etc.) for Linux and patches required
to build them from source are available from
@uref{@value{RTEMSFTPURL},the RTEMS ftp site}.



@node Issues when building RTEMS, When running ./configure weird thing start to happen, Where to get autoconf automake ld gcc etc.?, Building RTEMS

@section Issues when building RTEMS
@ifinfo
@menu
* When running ./configure weird thing start to happen::
* When running bootstrap weird thing start to happen::
* configure xxx cannot create executables::
* Why can I not build RTEMS inside of the source tree?::
* Which environment variables to set?::
* Compiler /Assembler /Linker report errors::
* How to set up $PATH?::
* Can I build RTEMS Canadian Cross?::
* Building RTEMS is slow::
* Building my pre-4.5.x BSPs does not work anymore::
* make debug_install / make profile_install::
* make debug / make profile::
* Building RTEMS does not honor XXX_FOR_TARGET::
* Editing Makefile.in Makefile configure::
* Editing auto* generated files::
@end menu
@end ifinfo


@node When running ./configure weird thing start to happen, When running bootstrap weird thing start to happen, Issues when building RTEMS, Issues when building RTEMS

@subsection When running ./configure weird thing start to happen

You are probably trying to build within the source-tree.
RTEMS requires a separate build directory.  I.e.  if the
sources are located at @code{/usr/local/src/rtems-@value{VERSION}},
use something similar to this to configure RTEMS:

@example
cd somewhere
mkdir build
cd build
/usr/local/src/rtems-@value{VERSION}/configure [options]
@end example


@node When running bootstrap weird thing start to happen, configure xxx cannot create executables, When running ./configure weird thing start to happen, Issues when building RTEMS

@subsection When running bootstrap weird thing start to happen

Many possibile causes: Most likely one of these:
@itemize @bullet
@item You are trying to build RTEMS with insufficient or incompatible
versions of autoconf and automake.
@item The autotools can't be found because your $PATH might not be set up
correctly (Cf. @ref{How to set up $PATH?})
@item You have used configure-script options which interfer with RTEMS
configuration (Cf. @ref{configure --program-[prefix|suffix|transform-name]})
@item You have tripped over a bug in RTEMS ;)
@end itemize


@node configure xxx cannot create executables, Why can I not build RTEMS inside of the source tree?, When running bootstrap weird thing start to happen, Issues when building RTEMS

@subsection configure xxx cannot create executables

While running a configure script, you see a message like this:
@example
checking for m68k-rtems-gcc... (cached) m68k-rtems-gcc
checking for C compiler default output... configure: error: C compiler cannot create executables
configure: error: /bin/sh '../../../../rtems-ss-@value{VERSION}/c/make/configure'
failed for c/make
@end example
This kind of error message typically indicates a broken toolchain, broken
toolchain installation or broken user environment.

Examinating the @code{config.log} corresponding to the the failing
configure script should provide further information of what
actually goes wrong (In the example above: @code{<target>/c/<BSP>/make/config.log})


@node Why can I not build RTEMS inside of the source tree?, Which environment variables to set?, configure xxx cannot create executables, Issues when building RTEMS

@subsection Why can I not build RTEMS inside of the source tree?

The build-directory hierarchy is setup dynamically at configuration time.

Configuring inside of the source tree would prevent being able to configure
for multiple targets simultaneously.

Using a separate build-tree simplifies Makefiles and configure scripts
significantly.

Adaptation to GNU/Cygnus conventions.


@node Which environment variables to set?, Compiler /Assembler /Linker report errors, Why can I not build RTEMS inside of the source tree?, Issues when building RTEMS

@subsection Which environment variables to set?

None.  Unlike for previous releases, it is not recommended anymore to set any
RTEMS related environment variable (Exception: $PATH, cf.
@ref{How to set up $PATH?}).



@node Compiler /Assembler /Linker report errors, How to set up $PATH?, Which environment variables to set?, Issues when building RTEMS

@subsection Compiler /Assembler /Linker report errors

If you see a bunch of the error messages related to invalid instructions
or similar, then probably your @code{$PATH} environment variable is not
set up correctly (cf.  @ref{How to set up $PATH?}).  Otherwise you might
have found a bug either in RTEMS or parts of the toolchain.


@node How to set up $PATH?, Can I build RTEMS Canadian Cross?, Compiler /Assembler /Linker report errors, Issues when building RTEMS

@subsection How to set up $PATH?

All target tools are supposed to be prefixed with a target-canonicalization
prefix, eg.  i386-rtems-gcc, m68k-rtems-ld are target tools.

Host tools are supposed not to be prefixed.
e.g.: cc, ld, gcc, autoconf, automake, aclocal etc.

If using the pre-built tool binaries provided by the RTEMS project,
simply prepend @code{@value{RTEMSPREFIX}} to @code{$PATH}.


@node Can I build RTEMS Canadian Cross?, Building RTEMS is slow, How to set up $PATH?, Issues when building RTEMS

@subsection Can I build RTEMS Canadian Cross?

RTEMS >= 4.6.0 configuration is prepared for building RTEMS Canadian Cross,
however building RTEMS Canadian Cross is known to be in its infancy, so
your mileage may vary (See @code{README.cdn-X} in the toplevel directory of
RTEMS's source tree for details.)


@node Building RTEMS is slow, Building my pre-4.5.x BSPs does not work anymore, Can I build RTEMS Canadian Cross?, Issues when building RTEMS

@subsection Building RTEMS is slow

RTEMS has become fairly large :).

In comparison to building previous versions, building RTEMS is slow,
 but that's the tradeoff to pay for simplier and safer configuration.

If using Cygwin, remember that Cygwin is emulating one OS ontop of another
 -- this necessarily must be significantly slower than using U*nix on the
 same hardware.


@node Building my pre-4.5.x BSPs does not work anymore, make debug_install / make profile_install, Building RTEMS is slow, Issues when building RTEMS

@subsection Building my pre-4.5.x BSPs does not work anymore

See @ref{How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?}.


@node make debug_install / make profile_install, make debug / make profile, Building my pre-4.5.x BSPs does not work anymore, Issues when building RTEMS

@subsection make debug_install / make profile_install

[FIXME:Partially obsolete]

These make targets are not supported anymore.  Instead, use:

@example
make VARIANT=DEBUG install
make VARIANT=PROFILE install
@end example


@node make debug / make profile, Building RTEMS does not honor XXX_FOR_TARGET, make debug_install / make profile_install, Issues when building RTEMS

@subsection make debug / make profile

[FIXME:Partially obsolete]

These make targets are not supported anymore.
Instead, use:

@example
make VARIANT=DEBUG all
make VARIANT=PROFILE all
@end example



@node Building RTEMS does not honor XXX_FOR_TARGET, Editing Makefile.in Makefile configure, make debug / make profile, Issues when building RTEMS

@subsection Building RTEMS does not honor XXX_FOR_TARGET

RTEMS < 4.6.0 did not support passing flags from the environment.
If using RTEMS < 4.6.0, editing your BSP's @code{make/custom/mybsp.cfg} and
setting appropriate flags there is required.

RTEMS >= 4.6.0 honors several XXX_FOR_TARGET environment variables.
Run @code{<path-to-rtems>/configure --help} for a full list of supported variables.


@node Editing Makefile.in Makefile configure, Editing auto* generated files, Building RTEMS does not honor XXX_FOR_TARGET, Issues when building RTEMS

@subsection Editing Makefile.in Makefile configure

These files are generated by auto* tools, cf.
@ref{Editing auto* generated files}).


@node Editing auto* generated files, Host Operating Systems and RTEMS, Editing Makefile.in Makefile configure, Issues when building RTEMS

@subsection Editing auto* generated files

RTEMS uses automake, therefore @b{never}, @b{ever}, @b{ever}
edit Makefile.ins, Makefiles, configure or other auto* generated files.
Changes to them will be swapped away soon and will get lost.

Instead edit the sources (eg.: Makefile.ams, configure.acs) auto* generated
files are generated from directly.

If sending patches always send Makefile.ams and configure.acs.
Sending Makefile.ins, Makefiles and configure scripts is pretty much useless.
If sending larger patches, consider removing all auto* generated files
by running @code{bootstrap -c} (cf. See @ref{./bootstrap})
before running diff to cut a patch.

If you don't understand what this is all about, try start getting familiar
with auto* tools by reading autoconf.info and automake.info, or feel free
to ask for assistance on the RTEMS Mailing List
(See @ref{Are there any mailing lists?}.


@node Host Operating Systems and RTEMS, Can I use Windows or DOS?, Editing auto* generated files, Building RTEMS

@section Host Operating Systems and RTEMS
@ifinfo
@menu
* Can I use Windows or DOS?::
* Do I need Linux?::
* Which Linux distribution is recommended?::
@end menu
@end ifinfo


@node Can I use Windows or DOS?, Do I need Linux?, Host Operating Systems and RTEMS, Host Operating Systems and RTEMS

@subsection Can I use Windows or DOS?


No, plain DOS and plain Win will not work, but Cygwin should.
Other U*nix emulations, such as Mingw and DJGPP are not supported and very
likely will not work.
Cywin / WinNT is known to work, but at the time of writing this, there
seem to persist non-RTEMS related issues with Cygwin under Win9x which
seem to prevent success on those systems.


@node Do I need Linux?, Which Linux distribution is recommended?, Can I use Windows or DOS?, Host Operating Systems and RTEMS

@subsection Do I need Linux?


No, you should be able to build RTEMS on any U*ix OS and under Cygwin/NT
(cf. @ref{Can I use Windows or DOS?}).


@node Which Linux distribution is recommended?, Development related questions, Do I need Linux?, Host Operating Systems and RTEMS

@subsection Which Linux distribution is recommended?

None, any recent U*nix should work, i.e.
any recent Linux distribution should work, too.


@node Development related questions, How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?, Which Linux distribution is recommended?, Building RTEMS

@section Development related questions
@ifinfo
@menu
* How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?::
* What is no_bsp / no_cpu?::
* What is the bare-BSP?::
* What is the cpukit?::
* Multilib vs.  RTEMS CPU-variants::
* Keeping auto* generated files in CVS::
* Importing RTEMS into CVS/RCS::
* ./bootstrap::
* configure --enable-maintainer-mode::
* configure --program-[prefix|suffix|transform-name]::
* configure.ac vs. configure.in::
* Reporting bugs::
@end menu
@end ifinfo


@node How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?, What is no_bsp / no_cpu?, Development related questions, Development related questions

@subsection How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?

[FIXME:Partially obsolete]

The simple answer is that between 4.0 and 4.5.0, RTEMS has moved to automake
and greater compliance with GNU conventions.
In 4.0, there was a single configure script at the top of the tree.
Now RTEMS is configured more like other GNU tools -- as a collection of
configurable entities.

Each BSP now has its own configure script.
I highly recommend you look at the Makefile.am's, configure.ac, of a similar
BSP.  You might even want to consider running "bootstrap -c" from the top of
the tree and looking at what is left.  bootstrap (cf. @ref{./bootstrap})
generates/removes all automatically generated files.


@node What is no_bsp / no_cpu?, What is the bare-BSP?, How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?, Development related questions

@subsection What is no_bsp / no_cpu?

@code{no_bsp} is a fictional BSP for a fictional CPU of type
@code{no_cpu}.  @code{no_cpu/no_bsp} support files in RTEMS can be used as
templates when implementing BSPs or porting RTEMS to new CPUs.


@node What is the bare-BSP?, What is the cpukit?, What is no_bsp / no_cpu?, Development related questions

@subsection What is the bare-BSP?

At the time being RTEMS is build per BSP, with all support files being build
separately for each BSP.  This can become unhandy when using several similar
but not identical boards (e.g.  a PC with different peripherial cards plugged
in), because this in general requires to implement a BSP for each setup.
The bare BSP is a general, setup independent BSP which can be used when
keeping all BSP specific parts external from RTEMS.

At present time the bare BSP is in its infancy.
It is known that it can be build for most CPUs RTEMS supports.
It is also known to work in individual cases, but your mileage may vary.


@node What is the cpukit?, Multilib vs.  RTEMS CPU-variants, What is the bare-BSP?, Development related questions

@subsection What is the cpukit?

[FIXME:To be extended]

One major change having been introduced to RTEMS-4.6.0 is the cpukit,
located below the directory @code{cpukit/} in RTEMS's toplevel directory.


@node Multilib vs.  RTEMS CPU-variants, Keeping auto* generated files in CVS, What is the cpukit?, Development related questions

@subsection Multilib vs.  RTEMS CPU-variants

The GNU toolchain applies a specific classification of similar CPUs into
CPU variants (eg.  SH1, SH2 etc.) to provide better support for each CPU variant.

RTEMS uses a different classification because it internally requires more
details about a specific CPU than the GNU toolchain's multilib classification
provides.


@node Keeping auto* generated files in CVS, Importing RTEMS into CVS/RCS, Multilib vs.  RTEMS CPU-variants, Development related questions

@subsection Keeping auto* generated files in CVS

When using CVS to archive source code, problems arise from keeping generated
files in CVS.  In general, two possible solutions exist:

@itemize @bullet

@item Find a way to get correct timestamps after checking out the sources
from CVS.  Some people try to achieve this by

@itemize @bullet
@item carefully checking in files into CVS in appropriate order
@item applying scripts to fix timestamps accordingling (eg.  by applying
@code{touch} and @code{find}).
@end itemize

@item Not keeping generated files in CVS, but regenerate them after
having checked them out from CVS.

@end itemize

RTEMS favors the the latter variant, because it appears to be less error-prone
and easier to handle (cf. @ref{./bootstrap} for details).


@node Importing RTEMS into CVS/RCS, ./bootstrap, Keeping auto* generated files in CVS, Development related questions

@subsection Importing RTEMS into CVS/RCS

When importing RTEMS into CVS/RCS or similar, we recommend not to import
auto* generated files (cf. @ref{Keeping auto* generated files in CVS}).

To remove them before importing, run

@example
./bootstrap -c
@end example

from the toplevel directory of the source tree (cf. @ref{./bootstrap}).


@node ./bootstrap, configure --enable-maintainer-mode, Importing RTEMS into CVS/RCS, Development related questions

@subsection ./bootstrap


@code{bootstrap} is a simple shell script which automatically generates all
auto* generated files within RTEMS's source tree (Other packages use the name
@code{autogen.sh} for similar scripts).  You will need to have autoconf,
automake and further underlying packages installed to apply it.

It typically should be applied when having:

@itemize @bullet

@item checked out RTEMS sources from a CVS repository which does
not contain generated files.

@item added new automake / autoconf files to the source tree (eg.
having added a new BSP), and when not being sure about what needs to be
updated.

@end itemize

Once all autoconf/automake generated files are present, you will rarely
need to run @code{bootstrap}, because automake automatically updates
generated files when it detects some files need to be updated (Cf.
@ref{configure --enable-maintainer-mode}).


@node configure --enable-maintainer-mode, configure --program-[prefix|suffix|transform-name], ./bootstrap, Development related questions

@subsection configure --enable-maintainer-mode

When working within the source-tree, consider to append
@code{--enable-maintainer-mode} to the options passed to configure RTEMS.

@example
<path>/rtems-@value{VERSION}/configure <options> --enable-maintainer-mode
@end example

This will enable the maintainer-mode in automake generated Makefiles, which
will let automake take care about dependencies between auto* generated
files.  I.e.  auto* generated files will get automatically updated.

Configuring RTEMS in maintainer-mode will require to have autoconf, automake
and underlying tools installed (Cf. @ref{Required Tools}).


@node configure --program-[prefix|suffix|transform-name], configure.ac vs. configure.in, configure --enable-maintainer-mode, Development related questions

@subsection configure --program-[prefix|suffix|transform-name]

These are generic configure script options automatically added by autoconf.
RTEMS configuration does not support these, worse, they interfer with
RTEMS's configuration -- i.e. @b{do not use them}.


@node configure.ac vs. configure.in, Reporting bugs, configure --program-[prefix|suffix|transform-name], Development related questions

@subsection configure.ac vs. configure.in

autoconf < 2.50 used the name @code{configure.in} for it's input files.
autoconf >= 2.50 recommends using the name @code{configure.ac}, instead.

RTEMS > 4.5.0 applies autoconf >= 2.50, therefore all former RTEMS's
@code{configure.in}'s have been renamed into @code{configure.ac} and
have been adapted to autoconf >= 2.50 demands.


@node Reporting bugs, , configure.ac vs. configure.in, Development related questions

@subsection Reporting bugs

Several possibilities (In decreasing preference):
@itemize @bullet
@item File a bug report at @uref{@value{RTEMSGNATS},RTEMS's GNATS}
@item Send an email to @uref{mailto:@value{RTEMSBUGS},@value{RTEMSBUGS}}
@item Report your problem to one of the RTEMS mailing lists
(Cf. @ref{Are there any mailing lists?}).
@end itemize