[PATCH] README: Rewrite and reduce
Gedare Bloom
gedare at rtems.org
Mon Apr 22 17:31:40 UTC 2013
This patch eliminates the existing README and INSTALL files and points
users toward the doc/ subdirectory, RTEMS wiki, processed doxygen
output, and the two primary mailing lists.
The intent is to avoid bit-rot in places where users are most likely
to just download code and start hacking.
-Gedare
On Mon, Apr 22, 2013 at 1:29 PM, Gedare Bloom <gedare at rtems.org> wrote:
> Delete old bit-rotting README files and rewrite the README to point
> readers toward authoritative sources of documentation.
> ---
> INSTALL | 47 ------------
> README | 100 +++----------------------
> README.cdn-X | 73 ------------------
> README.configure | 222 ------------------------------------------------------
> 4 files changed, 11 insertions(+), 431 deletions(-)
> delete mode 100644 INSTALL
> delete mode 100644 README.cdn-X
> delete mode 100644 README.configure
>
> diff --git a/INSTALL b/INSTALL
> deleted file mode 100644
> index 5eee13e..0000000
> --- a/INSTALL
> +++ /dev/null
> @@ -1,47 +0,0 @@
> -Building RTEMS
> -==============
> -See the file README.configure.
> -
> -
> -UNCOMPRESSING .tgz FILES
> -===========================
> -Many of the files found in this directory and its subdirectories
> -are gzip'ed, tar archive files. These files have the ".tgz"
> -extension. They were compressed with gzip version 1.2.4.
> -
> -Use a command sequence similar to the following to uncompress each
> -file:
> -
> - gzcat FILE.tgz | tar xvof -
> -
> -where FILE.tgz is the file to be installed. This procedure will
> -extract the files in the archive into the current directory.
> -All of the .tgz files associated with this release RTEMS will
> -place their contents in a subdirectory rtems-<release> in the current
> -directory.
> -
> -If you are unsure of what is in an RTEMS archive file, then use
> -the following command sequence to get a listing of the contents:
> -
> - gzcat FILE.tgz | tar tvf -
> -
> -NOTES:
> -
> -(1) The "-o" option to tar is included on the tar command line
> - so that the user extracting the tar archive will own the extracted
> - files.
> -
> -(2) gzcat is sometimes installed as zcat. Be warned that on many
> - (most) UNIX machines, zcat is associated with compress (.Z files).
> -
> -(3) If you do not have gzip 1.2.4, it is available from numerous sites
> - including this one. Other sites include ftp.gnu.org and ftp.cdrom.com.
> -
> -(4) The GNU archive files included in this distribution are packaged
> - exactly like they are on official GNU ftp sites. When extracting
> - GNU archives, they will not extract under a rtems-<version>
> - directory. They will extract themselves under a directory which
> - is the name and version of the tool in question. For example,
> - gcc-2.5.8.tgz will extract its contents into the subdirectory
> - gcc-2.5.8.
> -
> diff --git a/README b/README
> index 37aeed9..2c7c661 100644
> --- a/README
> +++ b/README
> @@ -1,93 +1,15 @@
> -Building RTEMS
> -==============
> -See the file README.configure.
> +See the documentation manuals in doc/ with daily builds available online at
> +http://rtems.org/onlinedocs/doc-current/share/rtems/html/ and released builds
> +at http://www.rtems.org/onlinedocs/releases/
>
> -Directory Overview
> -==================
> +See the RTEMS Wiki at http://wiki.rtems.org/wiki/index.php/Main_Page
> +for community knowledge and tutorials.
>
> -This is the top level of the RTEMS directory structure. The following
> -is a description of the files and directories in this directory:
> +RTEMS Doxygen available at http://www.rtems.org/onlinedocs/doxygen/cpukit/html
>
> - INSTALL
> - Rudimentary installation instructions. For more detailed
> - information please see the Release Notes. The Postscript
> - version of this manual can be found in the file
> - c_or_ada/doc/relnotes.tgz.
> +Get help on the mailing lists:
> +* For general-purpose questions related to using RTEMS, use the
> + rtems-users ml: http://www.rtems.org/mailman/listinfo/rtems-users
> +* For questions and discussion related to development of RTEMS, use the
> + rtems-devel ml: http://www.rtems.org/mailman/listinfo/rtems-devel
>
> - LICENSE
> - Required legalese.
> -
> - README
> - This file.
> -
> - c
> - This directory contains the source code for the C
> - implementation of RTEMS as well as the test suites, sample
> - applications, Board Support Packages, Device Drivers, and
> - support libraries.
> -
> - doc
> - This directory contains the PDL for the RTEMS executive.
> -
> -Ada versus C
> -============
> -
> -There are two implementations of RTEMS in this source tree --
> -in Ada and in C. These two implementations are functionally
> -and structurally equivalent. The C implementation follows
> -the packaging conventions and hierarchical nature of the Ada
> -implementation. In addition, a style has been followed which
> -allows one to easily find the corresponding Ada and C
> -implementations.
> -
> -File names in C and code placement was carefully designed to insure
> -a close mapping to the Ada implementation. The following file name
> -extensions are used:
> -
> - .adb - Ada body
> - .ads - Ada specification
> - .adp - Ada body requiring preprocessing
> - .inc - include file for .adp files
> -
> - .c - C body (non-inlined routines)
> - .inl - C body (inlined routines)
> - .h - C specification
> -
> -In the executive source, XYZ.c and XYZ.inl correspond directly to a
> -single XYZ.adb or XYZ.adp file. A .h file corresponds directly to
> -the .ads file. There are only a handful of .inc files in the
> -Ada source and these are used to insure that the desired simple
> -inline textual expansion is performed. This avoids scoping and
> -calling convention side-effects in carefully constructed tests
> -which usually test context switch behavior.
> -
> -In addition, in Ada code and data name references are always fully
> -qualified as PACKAGE.NAME. In C, this convention is followed
> -by having the package name as part of the name itself and using a
> -capital letter to indicate the presence of a "." level. So we have
> -PACKAGE.NAME in Ada and _Package_Name in C. The leading "_" in C
> -is used to avoid naming conflicts between RTEMS and user variables.
> -By using these conventions, one can easily compare the C and Ada
> -implementations.
> -
> -The most noticeable difference between the C and Ada83 code is
> -the inability to easily obtain a "typed pointer" in Ada83.
> -Using the "&" operator in C yields a pointer with a specific type.
> -The 'Address attribute is the closest feature in Ada83. This
> -returns a System.Address and this must be coerced via Unchecked_Conversion
> -into an access type of the desired type. It is easy to view
> -System.Address as similar to a "void *" in C, but this is not the case.
> -A "void *" can be assigned to any other pointer type without an
> -explicit conversion.
> -
> -The solution adopted to this problem was to provide two routines for
> -each access type in the Ada implementation -- one to convert from
> -System.Address to the access type and another to go the opposite
> -direction. This results in code which accomplishes the same thing
> -as the corresponding C but it is easier to get lost in the clutter
> -of the apparent subprogram invocations than the "less bulky"
> -C equivalent.
> -
> -A related difference is the types which are only in Ada which are used
> -for pointers to arrays. These types do not exist and are not needed
> -in the C implementation.
> diff --git a/README.cdn-X b/README.cdn-X
> deleted file mode 100644
> index d259d5d..0000000
> --- a/README.cdn-X
> +++ /dev/null
> @@ -1,73 +0,0 @@
> -Building RTEMS Canadian Cross
> -=============================
> -
> -RTEMS now contains experimental and yet incomplete support for building
> -it Canadian Cross.
> -
> -1. Introduction
> ----------------
> -If you don't know what Canadian Cross Building means, you probably don't want
> -to apply it and should consider stop reading here.
> -
> -Interested readers might want to read Ian Lance Taylor's article at
> -http://www.airs.com/ian/configure for underlaying details and working
> -principles.
> -
> -
> -2. RTEMS
> ---------
> -Example: Building RTEMS for sparc-rtems under i386-pc-linux-gnu to be hosted
> -on a i386-cygwin platform.
> -
> -2.1 Required tools
> -------------------
> -* A i386-pc-linux-gnu cross sparc-rtems toolchain.
> -* A i386-pc-linux-gnu cross i386-cygwin toolchain.
> -* A i386-pc-linux-gnu native toolchain.
> -
> -We further on assume these to be installed to these locations:
> -/opt/rtems .. linux cross sparc-rtems toolchain
> -/opt/cygwin .. linux cross i386-cygwin cross-toolchain
> -/usr .. linux native toolchain and further tools.
> -
> -2.2 Building sparc-rtems
> -------------------------
> -The first step is to build RTEMS for sparc-rtems under linux.
> -
> -mkdir build
> -cd build
> -<path>/rtems/configure [options] \
> ---target=sparc-rtems \
> ---prefix=/opt/cygwin
> -make
> -make install
> -
> -This will build a standard sparc-rtems RTEMS and install it to the given
> -PREFIX.
> -
> -2.3 Building i386-cygwin host support
> --------------------------------------
> -The next step is to build RTEMS host support for i386-cygwin.
> -This basically means to cross-build the host tools contained in RTEMS.
> -
> -mkdir host
> -cd host
> -<path>/rtems/configure [options] \
> ---target=sparc-rtems \
> ---build=`<path>/rtems/config.guess` \
> ---host=i386-cygwin \
> ---prefix=/opt/cygwin
> -make
> -make install
> -
> -This will build RTEMS host-tools for i386-cygwin and install them to the given
> -PREFIX.
> -
> -
> -3. Known issues
> ----------------
> -
> -* At present time, building RTEMS Canadian Cross is known to be immature, and
> -to require additional work. Do not expect this to work.
> -
> -* The <toplevel>/make/ directory hierarchy is not treated correctly.
> diff --git a/README.configure b/README.configure
> deleted file mode 100644
> index 6ca355e..0000000
> --- a/README.configure
> +++ /dev/null
> @@ -1,222 +0,0 @@
> -1. Autoconf support
> -===================
> -
> -This version of RTEMS is configured with GNU autoconf. RTEMS can be
> -configured and built either standalone or together with the compiler
> -tools in the Cygnus one-tree structure. Using autoconf also means
> -that RTEMS now can be built in a separate build directory.
> -
> -To re-generate auto*tool generated files (configure, Makefile.in etc),
> -autoconf-2.68 and automake-1.11.1 are required.
> -
> -2. Installation
> -===============
> -
> -To configure RTEMS for a specific target, run configure in the build
> -directory. In addition to the standard configure options, the following
> -RTEMS-specific option are supported:
> -
> - --disable-rtems-inlines
> - --disable-posix
> - --disable-networking
> - --enable-cxx
> - --enable-multiprocessing
> - --enable-rtemsbsp="bsp1 bsp2 ..."
> - --enable-tests
> - --enable-rdbg (only valid for i386 and some PowerPC BSPs)
> - --enable-docs
> -
> -In addition, the following standard autoconf options are frequently
> -used when configuring RTEMS installations:
> -
> - --prefix=INSTALL_DIRECTORY
> -
> -By default, inline routines are used instead of macros where possible.
> -Macros can be selected using the --disable-inlines option. [NOTE:
> -Some APIs may not support macro versions of their inline routines.]
> -
> -By default, the RTEMS POSIX 1003.1b interface is built for targets that support
> -it. It can be disabled with the --disable-posix option.
> -
> -By default, the RTEMS networking support is built for targets which
> -support it. It can be specifically disabled for those targets
> -with the --disable-networking option.
> -
> -By default, the RTEMS remote debugger server support is not built.
> -It can be specifically enabled for the targets that support it.
> -with the --enable-rdbg option. NB : the RTEMS networking support
> -must be enabled to support the remote debugger server.
> -
> -By default, the RTEMS support of C++ is disabled. It can be enabled
> -with the --enable-cxx option. If the rtems++ C++ library is installed
> -it will also be build.
> -
> -By default, the RTEMS test suites are NOT configured -- only the
> -sample tests are built. --enable-tests will configure
> -the RTEMS test suite. The default speeds up the build
> -and configure process when the tests are not desired.
> -
> -By default, RTEMS is built using arguments and build rules which require a
> -gcc supporting the -specs option, ie. a gcc >= 2.8.
> -[The --disable-gcc28 option, which has been present in former releases, has
> -been removed.]
> -
> -By default, multiprocessing is is not built. It can be enabled
> -for those BSPs supporting it by the --enable-multiprocessing option.
> -
> -By default, all bsps for a target are built. The bare BSP is not built
> -unless directly specified. There are two ways of changing this:
> -
> -+ use the --enable-rtemsbsp option which will set the specified
> - bsps as the default bsps, or
> -+ set the RTEMS_BSP variable during make (see below).
> -
> -The --enable-rtemsbsp= option configures RTEMS for a specific board
> -within a target architecture. Remember that the target specifies the
> -CPU family while the BSP specifies the precise board you will be using.
> -The following targets are supported:
> -
> - arm-rtems4.10
> - avr-rtems4.10
> - bfin-rtems4.10
> - h8300-rtems4.10
> - i386-rtems4.10
> - lm32-rtems4.10
> - m32c-rtems4.10
> - m32r-rtems4.10
> - m68k-rtems4.10
> - mips-rtems4.10
> - no_cpu-rtems4.10
> - powerpc-rtems4.10
> - sh-rtems4.10
> - sparc-rtems4.10
> -
> -The cross-compiler is set to $(target)-gcc by default.
> -
> -To build, run make in the build directory. To specify which bsps to build,
> -add the RTEMS_BSP="bsp1 bsp2 .." to the make command. Specifying multiple
> -BSPs to build only works from the top level build directory.
> -
> -Installation is done under $(prefix)/rtems.
> -
> -As an example, to build and install the mvme136 and mvme162 bsps for m68k do:
> -
> - (path_to_rtems_src)/configure --target=m68k-rtems4.11
> -
> - make RTEMS_BSP="mvme136 mvme162"
> -
> - make install RTEMS_BSP="mvme136 mvme162"
> -
> -The sample tests are built by 'make all' when configured with
> ---enable-tests=samples. Use --enable-tests=all to build the full
> -test suite.
> -
> -Documentation is built separately from the source code.
> -
> -3. To use the installed RTEMS library
> -=====================================
> -
> -To use the installed RTEMS bsps to build applications, the application
> -makefile has to include a bsp-specific makefile that will define the
> -RTEMS variables necessary to find include files and libraries. The
> -bsp-specific makefile is installed at
> -
> - $(RTEMS_MAKEFILE_PATH)/Makefile.inc
> -
> -For the erc32 bsp installed at /usr/local/cross, the environment
> -variable RTEMS_MAKEFILE_PATH would be set as follows to the
> -following:
> -
> -/usr/local/cross/sparc-rtems/rtems/erc32/Makefile.inc
> -
> -4. Supported target bsps
> -========================
> -
> -The following bsps are supported:
> -
> -arm : csb336 csb337 edb7312 gba gp32 nds rtl22x rtl22xx_t
> - smdk2410
> -
> -avr: : avrtest
> -
> -bfin : eZKit533 bf537Stamp
> -
> -h8300 : h8sim
> -
> -i386 : i386ex pc386 pc386dx pc486 pc586 pc686 pck6 ts_386ex
> - NOTE: The "pc386" BSP can be compiled to support a
> - variety of PC configurations including PC-104
> - based solutions.
> -
> -lm32: : lm32_evr
> -
> -m32c : m32csim
> -
> -m32r : m32rsim
> -
> -m68k : av5282 csb360 gen68302 gen68360 gen68360_040
> - genmcf548x idp mcf5206elite mcf52235 mcf5235 mcf5239
> - m5484FireEngine mrm332 mvme136 mvme147s mvme162 mvme162lx
> - mvme167 ods68302 pgh360 sim68000 simcpu32 uC5282 COBRA5475
> -
> -no_cpu : no_bsp (porting example)
> -
> -mips : csb350 genmongoosev hurricane jmr3904 rbtx4925 rbtx4938
> - p4600 p4650
> -
> -powerpc : brs5l ep1a gen5200 gen83xx haleakala hsc_cm01 icecube
> - mbx821_001 mbx821_002 mbx821_002b mbx860_001b mbx860_002
> - mbx860_005b mcp750 mvme2100 mvme2307 mtx603e
> - mvme5500 mpc55xxevb mpc8260ads mpc8313erdb mpc8349eamds
> - pghplus pm520_cr825 pm520_ze30 psim score603e ss555
> - tqm8xx_stk8xx virtex
> -
> - NOTE: The "motorola_powerpc" BSP is a single BSP which
> - can be conditionally compiled to support most Motorola
> - VMEbus, CompactPCI, and MTX boards.)
> -
> - NOTE: The mbx8xx, gen5200, gen83xx, and tqm8xx BSPs are
> - designed to handle a variety of boards based on the same
> - family of system on chips CPUs
> -
> -sh : gensh1 gensh2 gensh4 simsh1 simsh2 simsh4
> -
> -sparc : erc32 sis leon2 leon3
> -
> -5. Makefile structure
> -=====================
> -
> -The makefiles have been re-organized. Most gnu-based bsps now use three
> -main makefiles:
> - + custom/default.cfg,
> - + custom/bsp.cfg and
> - + compilers/gcc-target-default.cfg.
> -
> -Default.cfg sets the default values of certain common build options.
> -
> -Bsp.cfg set bsp-specific build options and can also override the
> -default settings.
> -
> -Gcc-target-default.cfg contains the common gcc definitions.
> -
> -6. Adding a bsp
> -===============
> -
> -Please refer to the BSP and Device Driver Guide.
> -
> -
> -7. Tested configurations
> -========================
> -
> -All gnu-based bsps have been built on Linux.
> -
> -8. Prerequisites
> -================
> -
> -Gawk version 2 or higher.
> -GNU make version 3.72 or higher.
> -Bash.
> -gcc version > 2.8
> -
> -NOTE: These prerequisites are probably out of date but autoconf should detect
> - any problems.
> --
> 1.7.1
>
More information about the devel
mailing list