diff options
Diffstat (limited to 'doc/FAQ/build45.texi')
| -rw-r--r-- | doc/FAQ/build45.texi | 602 |
1 files changed, 602 insertions, 0 deletions
diff --git a/doc/FAQ/build45.texi b/doc/FAQ/build45.texi new file mode 100644 index 0000000000..507b257803 --- /dev/null +++ b/doc/FAQ/build45.texi @@ -0,0 +1,602 @@ +@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 + |