diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/FAQ/FAQ.texi | 2 | ||||
| -rw-r--r-- | doc/FAQ/Makefile.am | 9 | ||||
| -rw-r--r-- | doc/FAQ/basic.t | 15 | ||||
| -rw-r--r-- | doc/FAQ/build45.t | 345 |
4 files changed, 369 insertions, 2 deletions
diff --git a/doc/FAQ/FAQ.texi b/doc/FAQ/FAQ.texi index 45b68b1004..dc1a176ad5 100644 --- a/doc/FAQ/FAQ.texi +++ b/doc/FAQ/FAQ.texi @@ -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:: diff --git a/doc/FAQ/Makefile.am b/doc/FAQ/Makefile.am index 5aefbf236a..876b034048 100644 --- a/doc/FAQ/Makefile.am +++ b/doc/FAQ/Makefile.am @@ -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" \ diff --git a/doc/FAQ/basic.t b/doc/FAQ/basic.t index 4f653650f9..50564843ef 100644 --- a/doc/FAQ/basic.t +++ b/doc/FAQ/basic.t @@ -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. + diff --git a/doc/FAQ/build45.t b/doc/FAQ/build45.t new file mode 100644 index 0000000000..01bf0e920f --- /dev/null +++ b/doc/FAQ/build45.t @@ -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}). |