summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>2000-05-28 19:33:59 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>2000-05-28 19:33:59 +0000
commit2f957f19bd93c348a3eda7c1dff8547750034480 (patch)
tree8defd1ae47ca2b4e93cedac8a0304a86b529a40d /doc
parent31bfb92fe7deae44eb57616743d4f35cee0b6ec7 (diff)
downloadrtems-2f957f19bd93c348a3eda7c1dff8547750034480.tar.bz2
Merged Ralf Corsepius' 4.5 Build Issues FAQ into this.
Diffstat (limited to 'doc')
-rw-r--r--doc/FAQ/FAQ.texi2
-rw-r--r--doc/FAQ/Makefile.am9
-rw-r--r--doc/FAQ/basic.t15
-rw-r--r--doc/FAQ/build45.t345
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}).