forked from Imagelibrary/rtems
Merged Ralf Corsepius' 4.5 Build Issues FAQ into this.
This commit is contained in:
Joel Sherrill
@@ -65,6 +65,7 @@ END-INFO-DIR-ENTRY
|
||||
@include basic.texi
|
||||
@include tools.texi
|
||||
@include concepts.texi
|
||||
@include build45.texi
|
||||
@include bsp.texi
|
||||
@include debug.texi
|
||||
@include freesw.texi
|
||||
@@ -88,6 +89,7 @@ Common questions have been divided into the following categories.
|
||||
* Basic Information::
|
||||
* General Development Tool Hints::
|
||||
* RTEMS Concepts::
|
||||
* Building RTEMS 4.5::
|
||||
* BSP Questions::
|
||||
* Debugging Hints::
|
||||
* Free Software that Works with RTEMS::
|
||||
|
||||
@@ -15,8 +15,8 @@ include $(top_srcdir)/project.am
|
||||
COMMON_FILES=$(top_srcdir)/common/cpright.texi $(top_builddir)/common/setup.texi
|
||||
|
||||
GENERATED_FILES= \
|
||||
basic.texi tools.texi concepts.texi bsp.texi debug.texi freesw.texi \
|
||||
embeddedinfo.texi hwdebugaids.texi projects.texi endoftime.texi
|
||||
basic.texi tools.texi concepts.texi build45.texi bsp.texi debug.texi \
|
||||
freesw.texi embeddedinfo.texi hwdebugaids.texi projects.texi endoftime.texi
|
||||
|
||||
FILES=
|
||||
|
||||
@@ -42,6 +42,11 @@ concepts.texi: concepts.t
|
||||
-u "Top" \
|
||||
-n "" $<
|
||||
|
||||
build45.texi: build45.t
|
||||
$(BMENU) -c -p "" \
|
||||
-u "Top" \
|
||||
-n "" $<
|
||||
|
||||
bsp.texi: bsp.t
|
||||
$(BMENU) -c -p "" \
|
||||
-u "Top" \
|
||||
|
||||
@@ -174,4 +174,19 @@ place restrictions on the application.
|
||||
|
||||
No.
|
||||
|
||||
@section RTEMS Mailing List
|
||||
|
||||
Yes.
|
||||
|
||||
@example
|
||||
rtems-users@@OARcorp.com
|
||||
@end example
|
||||
|
||||
This mailing list is dedicated to the discussion of issues related
|
||||
to RTEMS, including GNAT/RTEMS. If you have questions about RTEMS,
|
||||
wish to make suggestions, or just want to pick up hints, this is a
|
||||
good list to subscribe to. Subscribe by sending an empty mail
|
||||
message to rtems-users-subscribe@@OARcorp.com. Messages sent
|
||||
to rtems-users@@OARcorp.com are posted to the list.
|
||||
|
||||
|
||||
|
||||
345
doc/FAQ/build45.t
Normal file
345
doc/FAQ/build45.t
Normal file
@@ -0,0 +1,345 @@
|
||||
@c
|
||||
@c $Id$
|
||||
@c
|
||||
|
||||
@chapter Building RTEMS 4.5
|
||||
|
||||
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 4.5. Thanks to Ralf Corsepius for
|
||||
compiling this section from excerpts from various postings to the
|
||||
rtems-users mailing list.
|
||||
|
||||
@section 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
|
||||
|
||||
@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.ins or start to develop
|
||||
with RTEMS.
|
||||
|
||||
I.e. you won't need them to get started, but you will need them when getting
|
||||
serious.
|
||||
|
||||
@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.
|
||||
|
||||
@subsection Can I use a non-gcc cross-toolchain?
|
||||
|
||||
|
||||
Generally speaking, it should be possible.
|
||||
However, most RTEMS-4.5 development has taken place using gcc-2.9x, therefore
|
||||
getting it working may not be easy.
|
||||
|
||||
@subsection Do I need gcc-2.9x for cross compilation?
|
||||
|
||||
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?}).
|
||||
|
||||
@subsection Where to get autoconf automake ld gcc etc. ?
|
||||
|
||||
The sources of all gnutools are available at any
|
||||
@uref{GNU,ftp://ftp.gnu.org} 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{OAR Corporation,ftp://ftp.oarcorp.com}.
|
||||
|
||||
|
||||
@section 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-4.5.0},
|
||||
use something similar to this to configure RTEMS:
|
||||
|
||||
@example
|
||||
cd somewhere
|
||||
mkdir build
|
||||
cd build
|
||||
/usr/local/src/rtems-4.5.0/configure [options]
|
||||
@end example
|
||||
|
||||
@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.
|
||||
|
||||
@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?}).
|
||||
|
||||
|
||||
@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.
|
||||
|
||||
@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 etc.
|
||||
|
||||
If using OARCorp's rpms for the toolchain, simply prepend:
|
||||
@code{/opt/rtems/bin} to @code{$PATH}.
|
||||
|
||||
@subsection Can I build RTEMS Canadian Cross?
|
||||
|
||||
Unfortunately, not (yet).
|
||||
|
||||
@subsection Building RTEMS is slow
|
||||
|
||||
RTEMS has become fairly large :).
|
||||
|
||||
In comparison to building previous versions, building RTEMS-4.5 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.
|
||||
|
||||
@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?}.
|
||||
|
||||
@subsection make debug_install / make profile_install
|
||||
|
||||
These make targets are not supported anymore. Instead, use:
|
||||
|
||||
@example
|
||||
make VARIANT=DEBUG install
|
||||
make VARIANT=PROFILE install
|
||||
@end example
|
||||
|
||||
@subsection make debug / make profile
|
||||
|
||||
These make targets are not supported anymore.
|
||||
Instead, use:
|
||||
|
||||
@example
|
||||
make VARIANT=DEBUG all
|
||||
make VARIANT=PROFILE all
|
||||
@end example
|
||||
|
||||
@subsection Building RTEMS does not honor XXX_FOR_TARGET
|
||||
|
||||
RTEMS currently does not support passing flags from the environment.
|
||||
Instead add a @code{make/custom/mybsp.cfg} for your bsp and set
|
||||
appropriate flags there.
|
||||
|
||||
@subsection Editing Makefile.in Makefile configure
|
||||
|
||||
These files are generated by auto* tools, cf.
|
||||
@ref{Editing auto* generated files}).
|
||||
|
||||
@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.ins) auto* generated
|
||||
files are generated from directly.
|
||||
|
||||
If sending patches always send Makefile.ams and configure.ins.
|
||||
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{RTEMS Mailing List}.
|
||||
|
||||
@section 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.
|
||||
|
||||
@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?}).
|
||||
|
||||
@subsection Which Linux distribution is recommended?
|
||||
|
||||
None, any recent U*nix should work, i.e.
|
||||
any recent Linux distribution should work, too.
|
||||
|
||||
@section Development related questions
|
||||
|
||||
@subsection How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?
|
||||
|
||||
The simple answer is that between 4.0 and now, 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.in, 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.
|
||||
|
||||
@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.
|
||||
|
||||
@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 similiar
|
||||
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.
|
||||
|
||||
@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.
|
||||
|
||||
@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).
|
||||
|
||||
@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 (XXX ref sec-bootstrap).
|
||||
|
||||
@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 underlaying 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{--enable-maintainer-mode}).
|
||||
|
||||
@subsection --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-4.5.0/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 underlaying tools installed (Cf. @ref{Required Tools}).
|
||||
Reference in New Issue
Block a user