Changeset d84995d2 in rtems for doc


Ignore:
Timestamp:
03/11/15 14:29:13 (9 years ago)
Author:
Gedare Bloom <gedare@…>
Branches:
4.11, 5, master
Children:
bdf23b6c
Parents:
cf404563
git-author:
Gedare Bloom <gedare@…> (03/11/15 14:29:13)
git-committer:
Gedare Bloom <gedare@…> (03/11/15 17:39:29)
Message:

doc/started: simplify and fix

  • fix and remove some macros in rtems.texi.in.
  • refer to devel mailing list.
  • remove reference to Debian packaging in requirements section.
  • remove section on prebuilt tools.
  • replace toolset build instructions with link to RSB docs.
  • Add a note in building RTEMS section about using RSB.
  • Fix URLs

Closes #2291.

Location:
doc
Files:
1 deleted
7 edited

Legend:

Unmodified
Added
Removed
  • doc/common/rtems.texi.in

    rcf404563 rd84995d2  
    1 @set RTEMSHTTPSITE              www.rtems.org
    2 @set RTEMSUSERS                 rtems-users@@rtems.com
    3 @set RTEMSUSERSSUBSCRIBE        rtems-users-subscribe@@rtems.com
    4 @set RTEMSBUGS                  http://www.rtems.org/bugzilla
    5 @set RTEMSFTPURL                ftp://www.rtems.org
     1@set RTEMSUSERS                 users@@rtems.org
     2@set RTEMSDEVEL                 devel@@rtems.org
    63@set RTEMSHTTPURL               http://www.rtems.org
    74@set RTEMSPREFIX                @RTEMSPREFIX@
  • doc/started/Makefile.am

    rcf404563 rd84995d2  
    99include $(top_srcdir)/main.am
    1010
    11 GENERATED_FILES = binaries.texi buildc.texi buildrt.texi intro.texi nt.texi \
     11GENERATED_FILES = buildc.texi buildrt.texi intro.texi nt.texi \
    1212    require.texi nextstep.texi sample.texi
    1313
     
    2525
    2626require.texi: require.t
    27         $(BMENU2) -c -p "GCC Mailing Lists" \
     27        $(BMENU2) -c -p "RTEMS Mailing Lists" \
    2828            -u "Top" \
    29             -n "Prebuilt Toolset Executables" < $< > $@
    30 
    31 binaries.texi: binaries.t
    32         $(BMENU2) -c \
    33             -p "GNU/Linux Distributions using Debian Packaging Format" \
    34             -u "Top" \
    35             -n "Building the GNU Cross Compiler Toolset" < $< > $@
     29            -n "Building the GNU Cross Compiler Toolset with RSB" < $< > $@
    3630
    3731buildc.texi: buildc.t
    38         $(BMENU2) -c -p "Removing Zipped Tar Files" \
     32        $(BMENU2) -c \
     33            -p "Distribution Independent Potential GNU/Linux Issues" \
    3934            -u "Top" \
    4035            -n "Building RTEMS" < $< > $@
    4136
    4237buildrt.texi: buildrt.t
    43         $(BMENU2) -c -p "Error Messages Indicating Configuration Problems" \
     38        $(BMENU2) -c \
     39            -p "Building the GNU Cross Compiler Toolset with RSB" \
    4440            -u "Top" \
    4541            -n "Building the Sample Applications" < $< > $@
     
    6056            -n "" < $< > $@
    6157
    62 EXTRA_DIST = binaries.t buildc.t buildrt.t intro.t nextstep.t nt.t require.t \
     58EXTRA_DIST = buildc.t buildrt.t intro.t nextstep.t nt.t require.t \
    6359    sample.t
    6460
  • doc/started/buildc.t

    rcf404563 rd84995d2  
    44@c  All rights reserved.
    55
    6 @chapter Building the GNU Cross Compiler Toolset
     6@chapter Building the GNU Cross Compiler Toolset with RSB
    77
    8 @b{NOTE}:  This chapter describes the steps required to build cross-compilation
    9 toolset on Linux (and possibly Windows using Cygwin) systems.  This chapter
    10 does @b{NOT} apply if you installed prebuilt toolset executables for BINUTILS,
    11 GCC, NEWLIB, and GDB.  If you installed prebuilt executables for all of those,
    12 proceed to @ref{Building RTEMS}.  If you require a GDB with a special
    13 configuration to connect to your target board, then proceed to
    14 @ref{Installing GDB Without RPM} for some advice.
     8The RTEMS Projects recommends using the RTEMS Source Builder (RSB)
     9for building the toolset from source. RSB has evolved over time from
     10various instructions and scripts for building the toolset, and it removes
     11much of the frustration associated with building the toolset from source.
     12Although prebuilt binaries are much easier to install, they are harder
     13for the RTEMS Project to support.
    1514
    16 This chapter describes the steps required to acquire the source code for
    17 a GNU cross compiler toolset, apply any required RTEMS specific patches,
    18 compile that toolset and install it.
     15Documentation for RSB is available from @uref{https://docs.rtems.org/rsb/,https://docs.rtems.org/rsb/}.
    1916
    20 It is recommended that when toolset binaries are available for your
    21 particular host, that they be used.  Prebuilt binaries are much easier
    22 to install.  They are also much easier for the RTEMS Project to support.
    23 
    24 @c
    25 @c  Preparation
    26 @c
    27 @section Preparation
    28 
    29 Before you can build an RTEMS toolset from source, there are some
    30 preparatory steps which must be performed.  You will need to determine
    31 the various tool versions and patches required and download them  You
    32 will also have to unarchive the source and apply any patches.
    33 
    34 @c
    35 @c  Determining Tool Version and Patch Revision
    36 @c
    37 @subsection Determining Tool Version and Patch Revision
    38 
    39 The tool versions and patch revisions change on a fairly frequent basis.
    40 In addition, these may vary based upon the target architecture.  In some
    41 cases, the RTEMS Project may have to stick with a particular version
    42 of a tool to provide a working version for a specific architecture.
    43 Because of this, it is impossible to provide this information in a
    44 complete and accurate manner in this manual.  You will need to refer
    45 to the configuration files used by the RTEMS RPM specification files to
    46 determine the current versions and, if a patch is required, what version.
    47 This section describes how to locate the appropriate tool versions and
    48 patches for a particular target architecture.
    49 
    50 All patches and RPM specification files are kept under source code
    51 control.  They are not included in release tarballs.  You will have to
    52 access the CVS branch for RTEMS @value{RTEMSAPI}.  For details on this,
    53 visit @uref{http://wiki.rtems.org/wiki/index.php/RTEMS_GIT_Repository,
    54 http://wiki.rtems.org/wiki/index.php/RTEMS_GIT_Repository} and look for
    55 instructions on accessing the RTEMS Source Code Repository in read-only
    56 mode.
    57 
    58 In the checked out source code, you will need to look in the subdirectory
    59 @code{contrib/crossrpms/autotools} to determine the versions of AUTOCONF
    60 and AUTOMAKE as well as any patches required.  In this directory are
    61 a few files you will need to look at.  The first is @code{Makefile.am}
    62 which defines the versions of AUTOCONF and AUTOMAKE required for this
    63 RTEMS Release Series.  Make a note of the version numbers required for
    64 AUTOCONF and AUTOMAKE (AUTOCONF_VERS and AUTOMAKE_VERS respectively).  Then
    65 examine the following files to determine the master location for the source
    66 tarballs and to determine if a patch is required for each tool version cited in
    67 the @code{Makefile.am}.
    68 
    69 @example
    70 autoconf-sources.add
    71 automake-sources.add
    72 @end example
    73 
    74 If any patches are required, they will be in the
    75 @code{contrib/crossrpms/patches} subdirectory of your checked out RTEMS
    76 source tree.
    77 
    78 If no patches are required, you can use a package manager provided by your
    79 Linux distribution to install AUTOMAKE and AUTOCONF to avoid building them from
    80 source.
    81 
    82 In the checked out source code, you will need to look in the subdirectory
    83 @code{contrib/crossrpms/rtems@value{RTEMSAPI}} to determine the target
    84 specific tool versions and patches required. In this directory, you
    85 will find a number of subdirectories with many named after target
    86 architectures supported by RTEMS.  Descend into the directory for the
    87 architecture you plan to build tools for.  Again, the @code{Makefile.am}
    88 defines the tool versions for this architecture and RTEMS Release Series.
    89 Make a note of the version numbers required for BINUTILS, GCC, NEWLIB,
    90 and GDB.  Then examine the following files to determine the master
    91 location for the source tarballs and to determine if a patch is required
    92 for each tool version cited in the @code{Makefile.am}.
    93 
    94 @itemize
    95 @item binutils-sources.add
    96 @item gcc-sources.add
    97 @item gdb-sources.add
    98 @end itemize
    99 
    100 If any patches are required, they will be in the
    101 @code{contrib/crossrpms/patches} subdirectory of your checked out RTEMS
    102 source tree.
    103 
    104 This is the entire set of source tarballs and patches required for a
    105 toolset targeting the selected architecture.  In many cases, this will be
    106 the same versions required by other targets on this RTEMS Release Series.
    107 
    108 @c
    109 @c  Obtain Source and Patches
    110 @c
    111 @subsection Obtain Source and Patches
    112 
    113 You will need to download the sources for the various packages from
    114 their master locations as identified in the previous section.
    115 
    116 Any patches needed should be in the @code{contrib/crossrpms/patches}
    117 directory of your RTEMS source.
    118 
    119 @c
    120 @c  Installing the Tools Without RPM
    121 @c
    122 @section Installing the Tools Without RPM
    123 
    124 This section describes the procedure for building and installing an RTEMS
    125 cross toolset from source code without using the RPM build infrastructure.
    126 
    127 Direct invocation of @code{configure} and @code{make} provides more control
    128 and easier recovery from problems when building.
    129 
    130 @c
    131 @c Archive and Build Directory Format
    132 @c
    133 @subsection Archive and Build Directory Format
    134 
    135 When no packaging format requirements are present, the root directory for
    136 the storage of source archives and patches as well as for building the
    137 tools is up to the user.  The only concern is that there be enough
    138 disk space to complete the build.  In this document, the following
    139 organization will be used.
    140 
    141 Make an @code{archive} directory to contain the downloaded source code
    142 and pataches.  Additionally, a @code{tools} directory to be used as a
    143 build directory.  The command sequence to do this is shown below:
    144 
    145 @example
    146 mkdir archive
    147 mkdir tools
    148 @end example
    149 
    150 This will result in an initial directory structure similar to the
    151 one shown in the following figure:
    152 
    153 @example
    154 @group
    155 /whatever/prefix/you/choose/
    156         archive/
    157         tools/
    158 
    159 @end group
    160 @end example
    161 
    162 The RTEMS Project tries to submit all of our patches upstream to the
    163 parent projects.  In the event there are patches, the master copy of them
    164 is located in the appropriate branch of the RTEMS source module in CVS.
    165 Patches are in the @code{contrib/crossrpms/patches}.
    166 
    167 @c
    168 @c  Unarchiving the Tools
    169 @c
    170 @subsection Unarchiving the Tools
    171 
    172 @b{NOTE}:  This step is required if building any of the tools without using RPM.
    173 It is @b{NOT} required if using the procedure described in @ref{Using RPM
    174 to Build Tools}.  This section describes the process of unarchiving the
    175 tools that comprise an RTEMS toolset.
    176 
    177 GNU source distributions are archived using @code{tar} and
    178 compressed using either @code{gzip} or @code{bzip}.
    179 If compressed with @code{gzip}, the extension @code{.gz} is used.
    180 If compressed with @code{bzip}, the extension @code{.bz2} is used.
    181 
    182 While in the @code{tools} directory, unpack the compressed tar files
    183 using the appropriate command based upon the compression program used.
    184 
    185 @example
    186 cd tools
    187 tar xzf ../archive/TOOLNAME.tar.gz  # for gzip'ed tools
    188 tar xjf ../archive/TOOLNAME.tar.bz2 # for bzip'ed tools
    189 @end example
    190 
    191 Assuming you are building a complete toolset, after all of the the
    192 compressed tar files have been unpacked using the appropriate commands,
    193 the following directories will have been created under @code{tools}.
    194 
    195 @itemize @bullet
    196 @item autoconf-<VERSION>
    197 @item automake-<VERSION>
    198 @item binutils-<VERSION>
    199 @item gcc-<VERSION>
    200 @item newlib-<VERSION>
    201 @item gdb-<VERSION>
    202 @end itemize
    203 
    204 The tree should look something like the following figure:
    205 
    206 @example
    207 @group
    208 /whatever/prefix/you/choose/
    209         archive/
    210           variable tarballs
    211           variable patches
    212         tools/
    213           various tool source trees
    214 @end group
    215 @end example
    216 
    217 @c
    218 @c Applying RTEMS Project Tool Patches
    219 @c
    220 
    221 @subsection Applying RTEMS Project Tool Patches
    222 
    223 @b{NOTE}:  This step is required if building any of the tools IF they have a
    224 patch currently required and you are building the tools without using RPM.
    225 is @b{NOT} required if using the procedure described in @ref{Using RPM
    226 to Build Tools}.  This section describes the process of applying the
    227 RTEMS patches to any of the tools.
    228 
    229 If a patch is required for a particular tool source tree, it is placed in the
    230 @code{contrib/crossrpms/patches} directory in the CVS tree.  Make sure the
    231 patch version is the same as of the tool you are building.  You will perform a
    232 command similar to the following to apply the patch.  In this example, <TOOL>
    233 should be replaced by the appropriate tool directory and <TOOL_PATCH> with the
    234 appropriate patch file.
    235 
    236 @example
    237 cd tools/<TOOL>
    238 cat ../../archive/<TOOL_PATCH> | patch -p1
    239 @end example
    240 
    241 @b{NOTE}: If you add the @code{--dry-run} option to the @code{patch} command
    242 in the above commands, it will attempt to apply the patch and report
    243 any issues without actually modifying any files.
    244 
    245 If the patch was compressed with the @code{gzip} program, it will
    246 have a suffix of @code{.gz} and you should use @code{zcat} instead
    247 of @code{cat} as shown above.  If the patch was compressed with
    248 the @code{gzip} program, it will have a suffix of @code{.bz2} and
    249 you should use @code{bzcat} instead of @code{cat} as shown above.
    250 
    251 Check to see if any of these patches have been rejected using the following
    252 sequence:
    253 
    254 @example
    255 cd tools/<TOOL>
    256 find . -name "*.rej" -print
    257 @end example
    258 
    259 If any files are found with the .rej extension, a patch has been rejected.
    260 This should not happen with a good patch file which is properly applied.
    261 
    262 @c
    263 @c  Installing AUTOCONF From Source
    264 @c
    265 
    266 @subsection Installing AUTOCONF From Source
    267 
    268 The following example illustrates the invocation of @code{configure}
    269 and @code{make} to build and install autoconf-<version>.  This tool is
    270 installed as a native utility and is independent of any RTEMS target.
    271 
    272 @b{NOTE}: If no patch is required for Autoconf and Automake, you can use the
    273 standard package manager provided by your Linux distribution to install them.
    274 Of course, the versions provided by your package manager should be the same
    275 that specified in Makefile.am or better.
    276 
    277 @example
    278 mkdir b-autoconf
    279 cd b-autoconf
    280 ../autoconf-<VERSION>/configure --prefix=@value{RTEMSPREFIX}
    281 make
    282 make install
    283 @end example
    284 
    285 After autoconf-<VERSION> is built and installed the build directory
    286 @code{b-autoconf} may be removed.
    287 
    288 For more information on the invocation of @code{configure}, please
    289 refer to the documentation for autoconf-<VERSION> or invoke the
    290 autoconf-VERSION> @code{configure} command with the @code{--help} option.
    291 
    292 @c
    293 @c  Installing AUTOMAKE From Source
    294 @c
    295 
    296 @subsection Installing AUTOMAKE From Source
    297 
    298 The following example illustrates the invocation of @code{configure}
    299 and @code{make} to build and install automake-<version>.  This tool is
    300 installed as a native utility and is independent of any RTEMS target.
    301 
    302 @example
    303 mkdir b-automake
    304 cd b-automake
    305 ../automake-<VERSION>/configure --prefix=@value{RTEMSPREFIX}
    306 make all
    307 make info
    308 make install
    309 @end example
    310 
    311 After automake-<VERSION> is built and installed the build directory
    312 @code{b-automake} may be removed.
    313 
    314 For more information on the invocation of @code{configure}, please
    315 refer to the documentation for automake-<VERSION> or invoke the
    316 automake-VERSION> @code{configure} command with the @code{--help} option.
    317 
    318 @c
    319 @c  Installing BINUTILS From Source
    320 @c
    321 @subsection Installing BINUTILS From Source
    322 
    323 The following example illustrates the invocation of @code{configure}
    324 and @code{make} to build and install binutils-<version>
    325 sparc-rtems@value{RTEMSAPI} target:
    326 
    327 @example
    328 mkdir b-binutils
    329 cd b-binutils
    330 ../binutils-<VERSION>/configure --target=sparc-rtems@value{RTEMSAPI} \
    331   --prefix=@value{RTEMSPREFIX}
    332 make all
    333 make info
    334 make install
    335 @end example
    336 
    337 After binutils-<VERSION> is built and installed the build directory
    338 @code{b-binutils} may be removed.
    339 
    340 For more information on the invocation of @code{configure}, please
    341 refer to the documentation for binutils-<VERSION> or invoke the
    342 binutils-VERSION> @code{configure} command with the @code{--help} option.
    343 
    344 NOTE: The shell PATH variable needs to be updated to include the path
    345 the binutils user executables have  been installed in.  The directory
    346 containing the executables is the prefix used above with
    347 @file{bin} post-fixed.
    348 
    349 @example
    350 export PATH=@value{RTEMSPREFIX}/bin:$@{PATH@}
    351 @end example
    352 
    353 As you will need to frequently run various commands in the
    354 @value{RTEMSPREFIX}/bin, you can update your @code{~/.bashrc} to include this
    355 line. After doing that, don't forget to run
    356 @example
    357 source ~/.bashrc
    358 @end example
    359 for the changes to take place.
    360 
    361 Failure to have the binutils in the path will cause the GCC and NEWLIB
    362 build to fail with an error message similar to:
    363 
    364 @example
    365 sparc-rtems@value{RTEMSAPI}-ar: command not found
    366 @end example
    367 
    368 @c
    369 @c  Installing GCC and NEWLIB Without RPM
    370 @c
    371 @subsection Installing GCC and NEWLIB Without RPM
    372 
    373 Before building gcc-<VERSION> and newlib-<VERSION>,
    374 binutils-<VERSION> must be installed and the directory
    375 containing those executables must be in your PATH.
    376 
    377 The C Library is built as a subordinate component of
    378 gcc-<VERSION>.  Because of this, the newlib-<VERSION>
    379 directory source must be available inside the gcc-<VERSION>
    380 source tree.  This is normally accomplished using a symbolic
    381 link as shown in this example:
    382 
    383 @example
    384 cd gcc-<VERSION>
    385 ln -s ../newlib-<VERSION>/newlib .
    386 @end example
    387 
    388 The following example illustrates the invocation of
    389 @code{configure} and @code{make}
    390 to build and install gcc-<VERSION> with only
    391 C and C++ support for the sparc-rtems@value{RTEMSAPI} target:
    392 
    393 @example
    394 mkdir b-gcc
    395 cd b-gcc
    396 ../gcc-<VERSION>/configure --target=sparc-rtems@value{RTEMSAPI} \
    397    --with-gnu-as --with-gnu-ld --with-newlib --verbose \
    398    --enable-threads --enable-languages="c,c++" \
    399    --prefix=@value{RTEMSPREFIX}
    400 make all
    401 make info
    402 make install
    403 @end example
    404 
    405 After gcc-<VERSION> is built and installed the
    406 build directory @code{b-gcc} may be removed.
    407 
    408 For more information on the invocation of @code{configure}, please
    409 refer to the documentation for gcc-<VERSION> or
    410 invoke the gcc-<VERSION> @code{configure} command with the
    411 @code{--help} option.
    412 
    413 @c
    414 @c Building GCC with Ada Support
    415 @c
    416 @subsection Building GCC with Ada Support
    417 
    418 If you want a GCC toolset that includes support for Ada
    419 (e.g. GNAT), there are some additional requirements on
    420 the host environment and additional build steps to perform.
    421 It is critical that you use the same version of GCC/GNAT as
    422 the native compiler.  GNAT must be compiled with an Ada compiler
    423 and when building a GNAT cross-compiler, it should be
    424 the same version of GNAT itself.
    425 
    426 It is also important to verify whether there is an RTEMS specific
    427 Ada patch required for GCC.  These can be found in
    428 @uref{http://www.rtems.org/ftp/pub/rtems/people/joel/ada,
    429 http://www.rtems.org/ftp/pub/rtems/people/joel/ada}.  The patch is
    430 often a minor version or two behind GCC but will usually apply cleanly.
    431 This patch must be applied.
    432 
    433 After this, it is critical to perform these steps in the correct order.
    434 GNAT requires that the C Library and RTEMS itself be installed before
    435 the language run-time can be built.
    436 
    437 @itemize @bullet
    438 @item install native GCC with GNAT
    439 @item place new native GNAT at head of PATH
    440 @item install BINUTILS
    441 @item place RTEMS prefix at head of PATH
    442 @item install C toolset (C++ is optional)
    443 @item install RTEMS built multilib
    444 @item install RTEMS built for your BSP
    445 @end itemize
    446 
    447 The build procedure is the same until the Ada configure step.  A GCC
    448 toolset with GNAT enabled requires that @code{ada} be included in the set
    449 of enabled languages.  The following example illustrates the invocation of
    450 @code{configure} and @code{make} to build and install gcc-<VERSION> with
    451 only C, C++, and Ada support for the sparc-rtems@value{RTEMSAPI} target:
    452 
    453 @example
    454 mkdir b-gcc
    455 cd b-gcc
    456 ../gcc-<VERSION>/configure --target=sparc-rtems@value{RTEMSAPI} \
    457    --with-gnu-as --with-gnu-ld --with-newlib --verbose \
    458    --enable-threads --enable-languages="c,c++,ada" \
    459    --prefix=@value{RTEMSPREFIX}
    460 make all
    461 make info
    462 make install
    463 @end example
    464 
    465 After gcc-<VERSION> is built and installed the build directory
    466 @code{b-gcc} may be removed.
    467 
    468 @c
    469 @c Installing GDB Without RPM
    470 @c
    471 @subsection Installing GDB Without RPM
    472 
    473 @b{NOTE}:  This step is NOT required if prebuilt executables for the
    474 GDB were installed and they meet your target interface
    475 requirements.
    476 
    477 GDB supports many configurations but requires some means of communicating
    478 between the host computer and target board.  This communication can be via
    479 a serial port, Ethernet, BDM, or ROM emulator.  The communication protocol
    480 can be the GDB remote protocol or GDB can talk directly to a ROM monitor.
    481 This setup is target board specific.  Some of the configurations that have
    482 been successfully used with RTEMS applications are:
    483 
    484 @itemize @bullet
    485 @item BDM with ColdFire, 683xx, MPC860 CPUs
    486 @item Motorola Mxxxbug found on M68xxx VME boards
    487 @item Motorola PPCbug found on PowerPC VME, CompactPCI, and MTX boards
    488 @item ARM based Cogent EDB7312
    489 @item PC's using various Intel and AMD CPUs including i386,
    490 i486, Pentium and above, and Athlon
    491 @item PowerPC Instruction Simulator in GDB (PSIM)
    492 @item MIPS Instruction Simulator in GDB (JMR3904)
    493 @item Sparc Instruction Simulator in GDB (SIS)
    494 @item Sparc Instruction Simulator (TSIM)
    495 @end itemize
    496 
    497 GDB is currently RTEMS thread/task aware only if you are using the
    498 remote debugging support via Ethernet.  These are configured
    499 using gdb targets of the form CPU-RTEMS.  Note the capital RTEMS.
    500 
    501 It is recommended that when toolset binaries are available for
    502 your particular host, that they be used.  Prebuilt binaries
    503 are much easier to install but in the case of gdb may or may
    504 not include support for your particular target board.
    505 
    506 The following example illustrates the invocation of @code{configure}
    507 and @code{make} to build and install gdb-<VERSION> for the
    508 m68k-rtems@value{RTEMSAPI} target:
    509 
    510 @example
    511 mkdir b-gdb
    512 cd b-gdb
    513 ../gdb-<VERSION>/configure --target=m68k-rtems@value{RTEMSAPI} \
    514   --prefix=@value{RTEMSPREFIX}
    515 make all
    516 make info
    517 make install
    518 @end example
    519 
    520 For some configurations, it is necessary to specify extra options
    521 to @code{configure} to enable and configure option components
    522 such as a processor simulator.  The following is a list of
    523 configurations for which there are extra options:
    524 
    525 @table @b
    526 @item powerpc-rtems@value{RTEMSAPI}
    527 @code{--enable-sim --enable-sim-powerpc --enable-sim-timebase --enable-sim-hardware}
    528 
    529 @item sparc-rtems@value{RTEMSAPI}
    530 @code{--enable-sim}
    531 
    532 @end table
    533 
    534 After gdb-<VERSION> is built and installed the
    535 build directory @code{b-gdb} may be removed.
    536 
    537 For more information on the invocation of @code{configure}, please
    538 refer to the documentation for gdb-<VERSION> or
    539 invoke the gdb-<VERSION> @code{configure} command with the
    540 @code{--help} option.
    541 
    542 
    543 @c
    544 @c  Using RPM to Build Tools
    545 @c
    546 
    547 @section Using RPM to Build Tools
    548 
    549 RPM is a packaging format which can be used to distribute binary files as
    550 well as to capture the procedure and source code used to produce those
    551 binary files.  For RPM, it is assumed that the following subdirectories
    552 are under a root directory such as @code{/usr/src/redhat} or
    553 @code{/usr/local/src/redhat}) on your machine.
    554 
    555 @example
    556 BUILD
    557 RPMS
    558 SOURCES
    559 SPECS
    560 SRPMS
    561 @end example
    562 
    563 For the purposes of this document, the RPM @code{SOURCES} directory is the
    564 directory into which all tool source and patches are assumed to reside.
    565 The @code{BUILD} directory is where the actual build is performed when
    566 building binaries from a source RPM.
    567 
    568 RPM automatically unarchives the source and applies any needed patches
    569 so you do @b{NOT} have to manually perform the procedures described
    570 @ref{Unarchiving the Tools} and @ref{Applying RTEMS Project Tool Patches}.
    571 But you are responsible for placing all source tarballs
    572 and patches in the @code{SOURCES} directory per the instructions in
    573 @ref{Obtain Source and Patches}
    574 
    575 This procedure starts by installing the source (e.g. @code{.src.rpm}
    576 extension) RPMs.  The RTEMS tool source RPMS are called "nosrc" to
    577 indicate that one or more source files required to produce the RPMs
    578 are not present.  The RTEMS source RPMs typically include all required
    579 patches, but do not include the large @code{.tar.gz} or @code{.tgz} files
    580 for each component such as BINUTILS, GCC, or NEWLIB.  These are shared
    581 by all RTEMS RPMs regardless of target CPU and there was no reason to
    582 duplicate them.  You will have to get the required source archive files
    583 by hand and place them in the @code{SOURCES} directory before attempting
    584 to build.  If you forget to do this, RPM is smart -- it will tell you
    585 what is missing. You can fetch any missing files and try again.
    586 
    587 @c
    588 @c  Building AUTOCONF using RPM
    589 @c
    590 @subsection Building AUTOCONF using RPM
    591 
    592 This section illustrates the invocation of RPM to build a new, locally
    593 compiled, AUTOCONF binary RPM that matches the installed source RPM.
    594 This example assumes that all of the required source is installed.
    595 
    596 @example
    597 rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-autoconf-<VERSION>-<RPM_RELEASE>.src.rpm
    598 @end example
    599 
    600 @example
    601 cd <RPM_ROOT_DIRECTORY>/SPECS
    602 rpm -bb i386-rtems@value{RTEMSAPI}-autoconf-<VERSION>.spec
    603 @end example
    604 
    605 If the build completes successfully, RPMS like the following will be
    606 generated in a build-host architecture specific subdirectory of the RPMs
    607 directory under the RPM root directory.
    608 
    609 @example
    610 @value{RTEMSRPMPREFIX}rtems@value{RTEMSAPI}-autoconf-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
    611 @end example
    612 
    613 @b{NOTE}:  It may be necessary to remove the build tree in the @code{BUILD}
    614 directory under the RPM root directory.
    615 
    616 @c
    617 @c  Building AUTOMAKE using RPM
    618 @c
    619 @subsection Building AUTOMAKE using RPM
    620 
    621 This section illustrates the invocation of RPM to build a new, locally
    622 compiled, AUTOMAKE binary RPM that matches the installed source RPM.
    623 This example assumes that all of the required source is installed.
    624 
    625 @example
    626 rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-automake-<VERSION>-<RPM_RELEASE>.src.rpm
    627 @end example
    628 
    629 @example
    630 cd <RPM_ROOT_DIRECTORY>/SPECS
    631 rpm -bb i386-rtems@value{RTEMSAPI}-automake-<VERSION>.spec
    632 @end example
    633 
    634 If the build completes successfully, RPMS like the following will be
    635 generated in a build-host architecture specific subdirectory of the RPMs
    636 directory under the RPM root directory.
    637 
    638 @example
    639 @value{RTEMSRPMPREFIX}rtems@value{RTEMSAPI}-automake-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
    640 @end example
    641 
    642 @b{NOTE}:  It may be necessary to remove the build tree in the @code{BUILD}
    643 directory under the RPM root directory.
    644 
    645 
    646 @c
    647 @c  Building BINUTILS using RPM
    648 @c
    649 @subsection Building BINUTILS using RPM
    650 
    651 This section illustrates the invocation of RPM to build a new, locally
    652 compiled, binutils binary RPM that matches the installed source RPM.
    653 This example assumes that all of the required source is installed.
    654 
    655 @example
    656 rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-binutils-<VERSION>-<RPM_RELEASE>.src.rpm
    657 @end example
    658 
    659 @example
    660 cd <RPM_ROOT_DIRECTORY>/SPECS
    661 rpm -bb i386-rtems@value{RTEMSAPI}-binutils-<VERSION>.spec
    662 @end example
    663 
    664 If the build completes successfully, RPMS like the following will be
    665 generated in a build-host architecture specific subdirectory of the RPMS
    666 directory under the RPM root directory.
    667 
    668 @example
    669 @value{RTEMSRPMPREFIX}binutils-common-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
    670 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-binutils-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
    671 @end example
    672 
    673 NOTE: It may be necessary to remove the build tree in the @code{BUILD}
    674 directory under the RPM root directory.
    675 
    676 @c
    677 @c  Building GCC and NEWLIB using RPM
    678 @c
    679 @subsection Building GCC and NEWLIB using RPM
    680 
    681 This section illustrates the invocation of RPM to build a new,
    682 locally compiled, set of GCC and NEWLIB binary RPMs that match the
    683 installed source RPM.  It is also necessary to install the BINUTILS
    684 RPMs and place them in your PATH.  This example assumes that all of
    685 the required source is installed.
    686 
    687 @example
    688 cd <RPM_ROOT_DIRECTORY>/SPECS
    689 rpm -bb i386-rtems@value{RTEMSAPI}-gcc-<VERSION>.spec
    690 @end example
    691 
    692 If the build completes successfully, a set of RPMS like the following will
    693 be generated in a build-host architecture specific subdirectory
    694 of the RPMS directory under the RPM root directory.
    695 
    696 @example
    697 @value{RTEMSRPMPREFIX}gcc-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
    698 @value{RTEMSRPMPREFIX}newlib-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
    699 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gcc-<VERSION>-<RPM>.<ARCH>.rpm \
    700 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-newlib-<VERSION>-<RPM>.<ARCH>.rpm \
    701 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-libgcc-<VERSION>-<RPM>.<ARCH>.rpm \
    702 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gcc-c++-<VERSION>-<RPM>.<ARCH>.rpm \
    703 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-libstd++-<VERSION>-<RPM>.<ARCH>.rpm
    704 @end example
    705 
    706 @b{NOTE}: Some targets do not support building all languages.
    707 
    708 @b{NOTE}: It may be necessary to remove the build tree in the
    709 @code{BUILD} directory under the RPM root directory.
    710 
    711 @c
    712 @c Building the GDB using RPM
    713 @c
    714 @subsection Building the GDB using RPM
    715 
    716 The following example illustrates the invocation of RPM to build a new,
    717 locally compiled, binutils binary RPM that matches the installed source
    718 RPM.  This example assumes that all of the required source is installed.
    719 
    720 
    721 @example
    722 rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gdb-<VERSION>-<RPM_RELEASE>.src.rpm
    723 @end example
    724 
    725 @example
    726 cd <RPM_ROOT_DIRECTORY>/SPECS
    727 rpm -bb i386-rtems@value{RTEMSAPI}-gdb-<VERSION>.spec
    728 @end example
    729 
    730 If the build completes successfully, RPMS like the following will
    731 be generated in a build-host architecture specific subdirectory
    732 of the RPMS directory under the RPM root directory.
    733 
    734 @example
    735 @value{RTEMSRPMPREFIX}gdb-common-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
    736 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gdb-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
    737 @end example
    738 
    739 @b{NOTE}: It may be necessary to remove the build tree in the
    740 @code{BUILD} directory under the RPM root directory.
    741 
    742 @c
    743 @c Common Problems
    744 @c
    745 
    746 @section Common Problems
    747 
    748 @subsection Error Message Indicates Invalid Option to Assembler
    749 
    750 If a message like this is printed then the new cross compiler
    751 is most likely using the native assembler instead of the cross
    752 assembler or vice-versa (native compiler using new cross assembler).
    753 This can occur for one of the following reasons:
    754 
    755 @itemize @bullet
    756 
    757 @item Binutils Patch Improperly Applied
    758 @item Binutils Not Built
    759 @item Current Directory is in Your PATH
    760 
    761 @end itemize
    762 
    763 If you are using binutils 2.9.1 or newer with certain older versions of
    764 gcc, they do not agree on what the name of the newly
    765 generated cross assembler is.  Older binutils called it @code{as.new}
    766 which became @code{as.new.exe} under Windows.  This is not a valid
    767 file name, so @code{as.new} is now called @code{as-new}.  By using the latest
    768 released tool versions and RTEMS patches, this problem will be avoided.
    769 
    770 If binutils did not successfully build the cross assembler, then
    771 the new cross gcc (@code{xgcc}) used to build the libraries can not
    772 find it.  Make sure the build of the binutils succeeded.
    773 
    774 If you include the current directory in your PATH, then there
    775 is a chance that the native compiler will accidentally use
    776 the new cross assembler instead of the native one.  This usually
    777 indicates that "." is before the standard system directories
    778 in your PATH.  As a general rule, including "." in your PATH
    779 is a security risk and should be avoided.  Remove "." from
    780 your PATH.
    781 
    782 @b{NOTE}:  In some environments, it may be difficult to remove "."
    783 completely from your PATH.  In this case, make sure that "."
    784 is after the system directories containing "as" and "ld".
    785 
    786 @subsection Error Messages Indicating Configuration Problems
    787 
    788 If you see error messages like the following,
    789 
    790 @itemize @bullet
    791 
    792 @item cannot configure libiberty
    793 @item coff-emulation not found
    794 @item etc.
    795 
    796 @end itemize
    797 
    798 Then it is likely that one or more of your gnu tools is
    799 already configured locally in its source tree.  You can check
    800 for this by searching for the @code{config.status} file
    801 in the various tool source trees.  The following command
    802 does this for the binutils source:
    803 
    804 @example
    805 find binutils-<VERSION> -name config.status -print
    806 @end example
    807 
    808 The solution for this is to execute the command
    809 @code{make distclean} in each of the GNU tools
    810 root source directory.  This should remove all
    811 generated files including Makefiles.
    812 
    813 This situation usually occurs when you have previously
    814 built the tool source for some non-RTEMS target.  The
    815 generated configuration specific files are still in
    816 the source tree and the include path specified during
    817 the RTEMS build accidentally picks up the previous
    818 configuration.  The include path used is something like
    819 this:
    820 
    821 @example
    822 -I../../binutils-<VERSION>/gcc -I/binutils-<VERSION>/gcc/include -I.
    823 @end example
    824 
    825 Note that the tool source directory is searched before the
    826 build directory.
    827 
    828 This situation can be avoided entirely by never using
    829 the source tree as the build directory.
  • doc/started/buildrt.t

    rcf404563 rd84995d2  
    55
    66@chapter Building RTEMS
     7
     8@b{NOTE}: If you built your toolset with RSB, by default the RSB also
     9builds RTEMS while building the compiler toolset. You may already have
     10a built and installed RTEMS in this case, and if not you should check
     11the RSB documentation at @uref{https://docs.rtems.org/rsb/,https://docs.rtems.org/rsb/}.
    712
    813@section Obtain the RTEMS Source Code
     
    1520
    1621@itemize @bullet
    17 @item @uref{http://www.rtems.org/ftp/pub/rtems,http://www.rtems.org/ftp/pub/rtems}
    18 @item @uref{ftp://www.rtems.org/pub/rtems,ftp://www.rtems.org/pub/rtems}
     22@item @uref{http://ftp.rtems.org/pub/rtems,http://ftp.rtems.org/pub/rtems}
     23@item @uref{ftp://ftp.rtems.org/pub/rtems,ftp://ftp.rtems.org/pub/rtems}
    1924@end itemize
    2025
     
    4853accessing the RTEMS source repository consult:
    4954
    50 @uref{http://wiki.rtems.org/wiki/index.php/RTEMS_GIT_Repository, http://wiki.rtems.org/wiki/index.php/RTEMS_GIT_Repository}.
     55@uref{https://devel.rtems.org/wiki/Developer/Git,https://devel.rtems.org/wiki/Developer/Git}.
    5156
    5257@section Add <INSTALL_POINT>/bin to Executable PATH
     
    5762tools.  The following command prepends the directory where
    5863the tools were installed in a previous step.  If you are using
    59 binaries provided by the RTEMS Project, the <INSTALL_POINT> will be
    60 @code{/opt/rtems-@value{RTEMSAPI}}
     64binaries installed to @code{/opt/rtems-@value{RTEMSAPI}}, then the
     65<INSTALL_POINT> will be @code{/opt/rtems-@value{RTEMSAPI}}
    6166
    6267@example
     
    107112
    108113If this produces messages that indicate the assembly code is not valid,
    109 then it is likely that you have fallen victim to one of the problems
    110 described in @ref{Error Message Indicates Invalid Option to Assembler}
    111 Please do not feel bad about this and do not give up, one of the most
    112 common installation errors is for the cross-compiler not to be able
    113 to find the cross assembler and default to using the native @code{as}.
     114then it is likely that you have fallen victim to one of the most
     115common installation errors and the cross-compiler is not able
     116to find the cross assembler and defaults to using the native @code{as}.
    114117This can result in very confusing error messages.
    115118
     
    163166mkdir build-rtems
    164167cd build-rtems
    165 ../rtems-@value{RTEMSAPI}.VERSION/configure --target=<TARGET_CONFIGURATION> \
    166     --disable-posix --disable-networking --disable-cxx \
     168../rtems-@value{RTEMSAPI}.VERSION/configure \
     169    --target=<TARGET_CONFIGURATION> \
     170    --disable-networking \
    167171    --enable-rtemsbsp=<BSP>\
    168172    --prefix=<INSTALL_POINT>
  • doc/started/intro.t

    rcf404563 rd84995d2  
    137137NEWLIB, and GDB with the pre-built versions of those tools.
    138138
    139 Much of the documentation is available at other sites on the Internet.
    140 The following is a list of URLs where one can find HTML versions of
    141 the GNU manuals:
     139Much of the documentation is available at other sites on the Internet,
     140for example the GNU manuals are hosted by the Free Software Foundation
     141at @uref{http://www.gnu.org/manual/manual.html, http://www.gnu.org/manual/manual.html}.
    142142
    143 @table @b
    144 
    145 @item Free Software Foundation
    146 @uref{http://www.gnu.org/manual/manual.html,
    147 http://www.gnu.org/manual/manual.html}
    148 
    149 @item Delorie Software
    150 @uref{http://www.delorie.com/gnu/docs, http://www.delorie.com/gnu/docs}
    151 
    152 @end table
    153 
    154 
    155 @subsection RTEMS Mailing List
     143@subsection RTEMS Mailing Lists
    156144
    157145@uref{mailto:@value{RTEMSUSERS},@value{RTEMSUSERS}}
    158146
    159 This is the primary  mailing list for the discussion of issues
    160 related to RTEMS, including GNAT/RTEMS.  If you have questions
    161 about RTEMS, wish to make suggestions, track development efforts,
    162 or just want to pick up hints, this is a good list to monitor.
     147The users mailing list is for any and all questions about RTEMS, especially
     148those focusing on how to use RTEMS.
    163149If you would like to browse the thousands of messages in the fifteen
    164150year archive of the mailing list or subscribe to it, please visit
    165 @uref{http://www.rtems.org/mailman,http://www.rtems.org/mailman} for
     151@uref{https://lists.rtems.org/mailman/listinfo/users,https://lists.rtems.org/mailman/listinfo/users} for
    166152more information,
    167153
    168 @subsection GCC Mailing Lists
     154@uref{mailto:@value{RTEMSDEVEL},@value{RTEMSDEVEL}}
    169155
    170 The GCC Project is hosted at @uref{http://gcc.gnu.org,http://gcc.gnu.org}.
    171 They maintain multiple mailing lists that are described at the web site
    172 along with subscription information.
     156The devel mailing list is the place to track ongoing RTEMS development
     157and to discuss changes to RTEMS. This list is also where patches are
     158submitted.
     159
  • doc/started/require.t

    rcf404563 rd84995d2  
    153153@end itemize
    154154
    155 @subsection GNU/Linux Distributions using Debian Packaging Format
    156 
    157 The RTEMS Project does not currently provide prebuilt toolsets in the Debian packaging format used by the Debian and Ubuntu distributions.  If you are using a distribution using this packaging format, then you have two options for installing the RTEMS toolset.
    158 
    159 The first option is to build the toolset from source following the instructions in the @ref{Building the GNU Cross Compiler Toolset}.  This is an approach taken by many users.
    160 
    161 Alternatively, it is often possible to extract the contents of the RPM files which contain the portions of the toolset you require.  In this case, you will follow the instructions in @ref{Locating the RPMs for your GNU/Linux Distribution} but assume your distribution is the RedHat Enterprise Linux version which is closest to yours from a shared library perspective.  As of December 2010, this is usually RedHat Enterprise Linux version 5.  As time passes, it is expected that version 6 will be appropriate in more cases.  You will extract the contents of these RPM files using either @code{rpm2cpio} and install them or you may be able to use the @code{alien} tool to convert them to Debian packaging.
  • doc/started/started.texi

    rcf404563 rd84995d2  
    6565* Introduction::
    6666* Requirements::
    67 * Prebuilt Toolset Executables::
    68 * Building the GNU Cross Compiler Toolset::
     67* Building the GNU Cross Compiler Toolset with RSB::
    6968* Building RTEMS::
    7069* Building the Sample Applications::
     
    7877@include intro.texi
    7978@include require.texi
    80 @include binaries.texi
    8179@include buildc.texi
    8280@include buildrt.texi
Note: See TracChangeset for help on using the changeset viewer.