[PATCH htdocs] docs: point to README in git

[PATCH htdocs] docs: point to README in git

[Mike Frysinger]

---
 README    | 595 ------------------------------------------------------
 docs.html |   3 +-
 2 files changed, 2 insertions(+), 596 deletions(-)
 delete mode 100644 README

diff --git a/README b/README
deleted file mode 100644
index f3273b2ee19d..000000000000
--- a/README
+++ /dev/null
@@ -1,595 +0,0 @@
-                        README for newlib-2.2.0 release
-           (mostly cribbed from the README in the gdb-4.13 release)
-
-This is `newlib', a simple ANSI C library, math library, and collection
-of board support packages.
-
-The newlib and libgloss subdirectories are a collection of software from
-several sources, each wi6h their own copyright and license.  See the file
-COPYING.NEWLIB for details.  The rest of the release tree is under either
-the GNU GPL or LGPL licenses.
-
-THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
-IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
-
-
-Unpacking and Installation -- quick overview
-==========================
-
-When you unpack the newlib-2.2.0.tar.gz file, you'll find a directory
-called `newlib-2.2.0', which contains:
-
-COPYING          config/          install-sh*      mpw-configure
-COPYING.LIB      config-ml.in     libgloss/        mpw-install
-COPYING.NEWLIB   config.guess*    mkinstalldirs*   newlib/
-CYGNUS           config.sub*      move-if-change*  symlink-tree*
-ChangeLog        configure*       mpw-README       texinfo/
-Makefile.in      configure.in     mpw-build.in
-README           etc/             mpw-config.in
-
-To build NEWLIB, you must follow the instructions in the section entitled
-"Compiling NEWLIB".
-
-This will configure and build all the libraries and crt0 (if one exists).
-If `configure' can't determine your host system type, specify one as its
-argument, e.g., sun4 or sun4sol2.  NEWLIB is most often used in cross
-environments.
-
-NOTE THAT YOU MUST HAVE ALREADY BUILT AND INSTALLED GCC and BINUTILS.
-
-
-More Documentation
-==================
-
-   Newlib documentation is available on the net via:
-   https://sourceware.org/newlib/docs.html
-
-   All the documentation for NEWLIB comes as part of the machine-readable
-distribution.  The documentation is written in Texinfo format, which is
-a documentation system that uses a single source file to produce both
-on-line information and a printed manual.  You can use one of the Info
-formatting commands to create the on-line version of the documentation
-and TeX (or `texi2roff') to typeset the printed version.
-
-   If you want to format these Info files yourself, you need one of the
-Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
-
-   If you want to typeset and print copies of this manual, you need TeX,
-a program to print its DVI output files, and `texinfo.tex', the Texinfo
-definitions file.
-
-   TeX is a typesetting program; it does not print files directly, but
-produces output files called DVI files.  To print a typeset document,
-you need a program to print DVI files.  If your system has TeX
-installed, chances are it has such a program.  The precise command to
-use depends on your system; `lpr -d' is common; another (for PostScript
-devices) is `dvips'.  The DVI print command may require a file name
-without any extension or a `.dvi' extension.
-
-   TeX also requires a macro definitions file called `texinfo.tex'. 
-This file tells TeX how to typeset a document written in Texinfo
-format.  On its own, TeX cannot read, much less typeset a Texinfo file.
-`texinfo.tex' is distributed with NEWLIB and is located in the
-`newlib-VERSION-NUMBER/texinfo' directory.
-
-
-
-Compiling NEWLIB
-================
-
-   To compile NEWLIB, you must build it in a directory separate from
-the source directory.  If you want to run NEWLIB versions for several host 
-or target machines, you need a different `newlib' compiled for each combination
-of host and target.  `configure' is designed to make this easy by allowing 
-you to generate each configuration in a separate subdirectory.
-If your `make' program handles the `VPATH' feature correctly (like GNU `make')
-running `make' in each of these directories builds the `newlib' libraries
-specified there.
-
-   To build `newlib' in a specific directory, run `configure' with the
-`--srcdir' option to specify where to find the source. (You also need
-to specify a path to find `configure' itself from your working
-directory.  If the path to `configure' would be the same as the
-argument to `--srcdir', you can leave out the `--srcdir' option; it
-will be assumed.)
-
-   For example, with version 2.2.0, you can build NEWLIB in a separate
-directory for a Sun 4 cross m68k-aout environment like this:
-
-     cd newlib-2.2.0
-     mkdir ../newlib-m68k-aout
-     cd ../newlib-m68k-aout
-     ../newlib-2.2.0/configure --host=sun4 --target=m68k-aout
-     make
-
-   When `configure' builds a configuration using a remote source
-directory, it creates a tree for the binaries with the same structure
-(and using the same names) as the tree under the source directory.  In
-the example, you'd find the Sun 4 library `libiberty.a' in the
-directory `newlib-m68k-aout/libiberty', and NEWLIB itself in
-`newlib-m68k-aout/newlib'.
-
-   When you run `make' to build a program or library, you must run it
-in a configured directory--whatever directory you were in when you
-called `configure' (or one of its subdirectories).
-
-   The `Makefile' that `configure' generates in each source directory
-also runs recursively.  If you type `make' in a source directory such
-as `newlib-2.2.0' (or in a separate configured directory configured with
-`--srcdir=PATH/newlib-2.2.0'), you will build all the required libraries.
-
-   When you have multiple hosts or targets configured in separate
-directories, you can run `make' on them in parallel (for example, if
-they are NFS-mounted on each of the hosts); they will not interfere
-with each other.
-
-
-Specifying names for hosts and targets
-======================================
-
-   The specifications used for hosts and targets in the `configure'
-script are based on a three-part naming scheme, but some short
-predefined aliases are also supported.  The full naming scheme encodes
-three pieces of information in the following pattern:
-
-     ARCHITECTURE-VENDOR-OS
-
-   For example, you can use the alias `sun4' as a HOST argument or in a
-`--target=TARGET' option.  The equivalent full name is
-`sparc-sun-sunos4'.
-
-   The `configure' script accompanying NEWLIB does not provide any query
-facility to list all supported host and target names or aliases. 
-`configure' calls the Bourne shell script `config.sub' to map
-abbreviations to full names; you can read the script, if you wish, or
-you can use it to test your guesses on abbreviations--for example:
-
-     % sh config.sub sun4
-     sparc-sun-sunos4.1.1
-     % sh config.sub sun3
-     m68k-sun-sunos4.1.1
-     % sh config.sub decstation
-     mips-dec-ultrix4.2
-     % sh config.sub hp300bsd
-     m68k-hp-bsd
-     % sh config.sub i386v
-     i386-pc-sysv
-     % sh config.sub i786v
-     Invalid configuration `i786v': machine `i786v' not recognized
-
-The Build, Host and Target Concepts in newlib
-=============================================
-
-The build, host and target concepts are defined for gcc as follows:
-
-build: the platform on which gcc is built.
-host: the platform on which gcc is run.
-target: the platform for which gcc generates code.
-
-Since newlib is a library, the target concept does not apply to it, and the
-build, host, and target options given to the top-level configure script must
-be changed for newlib's use.
-
-The options are shifted according to these correspondences:
-
-gcc's build platform has no equivalent in newlib.
-gcc's host platform is newlib's build platform.
-gcc's target platform is newlib's host platform.
-and as mentioned before, newlib has no concept of target.
-
-`configure' options
-===================
-
-   Here is a summary of the `configure' options and arguments that are
-most often useful for building NEWLIB.  `configure' also has several other
-options not listed here.
-
-     configure [--help]
-               [--prefix=DIR]
-               [--srcdir=PATH]
-               [--target=TARGET] HOST
-
-You may introduce options with a single `-' rather than `--' if you
-prefer; but you may abbreviate option names if you use `--'.
-
-`--help'
-     Display a quick summary of how to invoke `configure'.
-
-`--prefix=DIR'
-     Configure the source to install programs and files in directory
-     `DIR'.
-
-`--exec-prefix=DIR'
-     Configure the source to install host-dependent files in directory
-     `DIR'.
-
-`--srcdir=PATH'
-     *Warning: using this option requires GNU `make', or another `make'
-     that compatibly implements the `VPATH' feature.
-     Use this option to make configurations in directories separate
-     from the NEWLIB source directories.  Among other things, you can use
-     this to build (or maintain) several configurations simultaneously,
-     in separate directories.  `configure' writes configuration
-     specific files in the current directory, but arranges for them to
-     use the source in the directory PATH.  `configure' will create
-     directories under the working directory in parallel to the source
-     directories below PATH.
-
-`--norecursion'
-     Configure only the directory level where `configure' is executed;
-     do not propagate configuration to subdirectories.
-
-`--target=TARGET'
-     Configure NEWLIB for running on the specified TARGET.
-
-     There is no convenient way to generate a list of all available
-     targets.
-
-`HOST ...'
-     Configure NEWLIB to be built using a cross compiler running on
-     the specified HOST.
-
-     There is no convenient way to generate a list of all available
-     hosts.
-
-To fit diverse usage models, NEWLIB supports a group of configuration
-options so that library features can be turned on/off according to
-target system's requirements.
-
-One feature can be enabled by specifying `--enable-FEATURE=yes' or
-`--enable-FEATURE'.  Or it can be disable by `--enable-FEATURE=no' or
-`--disable-FEATURE'.
-
-`--enable-newlib-io-pos-args'
-     Enable printf-family positional arg support.
-     Disabled by default, but some hosts enable it in configure.host.
-
-`--enable-newlib-io-c99-formats'
-     Enable C99 support in IO functions like printf/scanf.
-     Disabled by default, but some hosts enable it in configure.host.
-
-`--enable-newlib-register-fini'
-     Enable finalization function registration using atexit.
-     Disabled by default.
-
-`--enable-newlib-io-long-long'
-     Enable long long type support in IO functions like printf/scanf.
-     Disabled by default, but many hosts enable it in configure.host.
-
-`--enable-newlib-io-long-double'
-     Enable long double type support in IO functions printf/scanf.
-     Disabled by default, but some hosts enable it in configure.host.
-
-`--enable-newlib-mb'
-     Enable multibyte support.
-     Disabled by default.
-
-`--enable-newlib-iconv-encodings'
-     Enable specific comma-separated list of bidirectional iconv
-     encodings to be built-in.
-     Disabled by default.
-
-`--enable-newlib-iconv-from-encodings'
-     Enable specific comma-separated list of \"from\" iconv encodings
-     to be built-in.
-     Disabled by default.
-
-`--enable-newlib-iconv-to-encodings'
-     Enable specific comma-separated list of \"to\" iconv encodings
-     to be built-in.
-     Disabled by default.
-
-`--enable-newlib-iconv-external-ccs'
-     Enable capabilities to load external CCS files for iconv.
-     Disabled by default.
-
-`--disable-newlib-atexit-dynamic-alloc'
-     Disable dynamic allocation of atexit entries.
-     Most hosts and targets have it enabled in configure.host.
-
-`--enable-newlib-global-atexit'
-     Enable atexit data structure as global variable.  By doing so it is
-     move out of _reent structure, and can be garbage collected if atexit
-     is not referenced.
-     Disabled by default.
-
-`--enable-newlib-reent-small'
-     Enable small reentrant struct support.
-     Disabled by default.
-
-`--disable-newlib-fvwrite-in-streamio'
-     NEWLIB implements the vector buffer mechanism to support stream IO
-     buffering required by C standard.  This feature is possibly
-     unnecessary for embedded systems which won't change file buffering
-     with functions like `setbuf' or `setvbuf'.  The buffering mechanism
-     still acts as default for STDIN/STDOUT/STDERR even if this option
-     is specified.
-     Enabled by default.
-
-`--disable-newlib-fseek-optimization'
-     Disable fseek optimization.  It can decrease code size of application
-     calling `fseek`.
-     Enabled by default.
-
-`--disable-newlib-wide-orient'
-     C99 states that each stream has an orientation, wide or byte.  This
-     feature is possibly unnecessary for embedded systems which only do
-     byte input/output operations on stream.  It can decrease code size
-     by disable the feature.
-     Enabled by default.
-
-`--enable-newlib-nano-malloc'
-     NEWLIB has two implementations of malloc family's functions, one in
-     `mallocr.c' and the other one in `nano-mallocr.c'.  This options
-     enables the nano-malloc implementation, which is for small systems
-     with very limited memory.  Note that this implementation does not
-     support `--enable-malloc-debugging' any more.
-     Disabled by default.
-
-`--disable-newlib-unbuf-stream-opt'
-     NEWLIB does optimization when `fprintf to write only unbuffered unix
-     file'.  It creates a temorary buffer to do the optimization that
-     increases stack consumption by about `BUFSIZ' bytes.  This option
-     disables the optimization and saves size of text and stack.
-     Enabled by default.
-
-`--enable-multilib'
-     Build many library versions.
-     Enabled by default.
-
-`--enable-target-optspace'
-     Optimize for space.
-     Disabled by default.
-
-`--enable-malloc-debugging'
-     Indicate malloc debugging requested.
-     Disabled by default.
-
-`--enable-newlib-multithread'
-     Enable support for multiple threads.
-     Enabled by default.
-
-`--enable-newlib-iconv'
-     Enable iconv library support.
-     Disabled by default.
-
-`--enable-newlib-elix-level'
-     Supply desired elix library level (1-4).  Please refer to HOWTO for
-     more information about this option.
-     Set to level 0 by default.
-
-`--disable-newlib-io-float'
-     Disable printf/scanf family float support.
-     Enabled by default.
-
-`--disable-newlib-supplied-syscalls'
-     Disable newlib from supplying syscalls.
-     Enabled by default.
-
-`--enable-lite-exit'
-     Enable lite exit, a size-reduced implementation of exit that doesn't
-     invoke clean-up functions such as _fini or global destructors.
-     Disabled by default.
-
-`--enable-newlib-nano-formatted-io'
-     This builds NEWLIB with a special implementation of formatted I/O
-     functions, designed to lower the size of application on small systems
-     with size constraint issues.  This option does not affect wide-char
-     formatted I/O functions.  Some notes about the feature:
-      1) The non-wide-char formatted I/O functions only support the C89
-	 standard.  The only exception is the configuration option provides
-	 limited support for long double.  Internally, the nano formatted I/O
-	 functions use double so accuracy is only guaranteed to double
-	 precision.
-      2) Floating-point support is split out of the formatted I/O code into
-	 weak functions which are not linked by default.  Programs that need
-	 floating-point I/O support must explicitly request linking of one or
-	 both of the floating-point functions: _printf_float or _scanf_float.
-	 This can be done at link time using the -u option which can be passed
-	 to either gcc or ld.  The -u option forces the link to resolve those
-	 function references.  Floating-point format specifiers are recognized
-	 by default, but if the floating-point functions are not explicitly
-	 linked in, this may result in undefined behavior for programs that
-	 need floating-point I/O support.
-      3) Integer-only versions of the formatted I/O functions (the iprintf/
-	 iscanf family) simply alias their regular counter-parts.
-	 The affected functions are:
-
-	  diprintf vdiprintf
-
-	  siprintf fiprintf iprintf sniprintf asiprintf asniprintf
-
-	  siscanf fiscanf iscanf
-
-	  viprintf vfiprintf vsiprintf vsniprintf vasiprintf vasniprintf
-
-	  viscanf vfiscanf vsiscanf
-
-	  _diprintf_r _vdiprintf_r
-
-	  _siprintf_r _fiprintf_r _iprintf_r _sniprintf_r _asiprintf_r
-	  _asniprintf_r
-
-	  _siscanf_r _fiscanf_r _iscanf_r
-
-	  _viprintf_r _vfiprintf_r _vsiprintf_r _asniprintf_r _vasiprintf_r
-	  _vasniprintf_r
-
-	  _viscanf_r _vfiscanf_r _vsiscanf_r
-
-      4) As mentioned, the option does not affect wide-char formatted I/O.
-	 The following configuration options are ignored for non-wide-char
-	 formatted I/O functions, and can be thought of as disabled.
-
-	  enable-newlib-io-pos-args
-	  enable-newlib-io-c99-formats
-	  enable-newlib-io-long-long
-	  enable-newlib-io-long-double
-	  enable-newlib-mb
-
-	 Additionally, "enable/disable-newlib-io-float" is supported in
-	 this specific implementation, one can use "disable-newlib-io-float"
-	 to further reduce code size.  In this case, the floating-point
-	 specifiers will not be recognized or handled, and the -u option
-	 will not work either.
-
-      5) As a rule, no features from outside of C89 standard will be
-	 considered in this implementation.
-
-     Disabled by default.
-
-Running the Testsuite
-=====================
-
-To run newlib's testsuite, you'll need a site.exp in your home
-directory which points dejagnu to the proper baseboards directory and
-the proper exp file for your target.
-
-Before running make check-target-newlib, set the DEJAGNU environment
-variable to point to ~/site.exp.
-
-Here is a sample site.exp:
-
-# Make sure we look in the right place for the board description files.
-if ![info exists boards_dir] {
-    set boards_dir {}
-}
-lappend boards_dir "your dejagnu/baseboards here"
-
-verbose "Global Config File: target_triplet is $target_triplet" 2
-
-global target_list
-case "$target_triplet" in {
-
-    { "mips-*elf*" } {
-	set target_list "mips-sim"
-    }
-
-    default {
-	set target_list { "unix" }
-    }
-}
-
-mips-sim refers to an exp file in the baseboards directory.  You'll
-need to add the other targets you're testing to the case statement.
-
-Now type make check-target-newlib in the top-level build directory to
-run the testsuite.
-
-Shared newlib
-=============
-
-newlib uses libtool when it is being compiled natively (with
---target=i[34567]86-pc-linux-gnu) on an i[34567]86-pc-linux-gnu
-host. This allows newlib to be compiled as a shared library.
-
-To configure newlib, do the following from your build directory:
-
-$(source_dir)/src/configure --with-newlib --prefix=$(install_dir)
-
-configure will recognize that host == target ==
-i[34567]86-pc-linux-gnu, so it will tell newlib to compile itself using
-libtool. By default, libtool will build shared and static versions of
-newlib.
-
-To compile a program against shared newlib, do the following (where
-target_install_dir = $(install_dir)/i[34567]86-pc-linux-gnu):
-
-gcc -nostdlib $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm -lgcc
-
-To run the program, make sure that $(target_install_dir)/lib is listed
-in the LD_LIBRARY_PATH environment variable.
-
-To create a static binary linked against newlib, do the following:
-
-gcc -nostdlib -static $(target_install_dir)/lib/crt0.o progname.c -I $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm
-
-libtool can be instructed to produce only static libraries. To build
-newlib as a static library only, do the following from your build
-directory:
-
-$(source_dir)/src/configure --with-newlib --prefix=$(install_dir) --disable-shared
-
-Regenerating Configuration Files
-================================
-
-At times you will need to make changes to configure.in and Makefile.am files.
-This will mean that configure and Makefile.in files will need to be
-regenerated.
-
-At the top level of newlib is the file: acinclude.m4.  This file contains
-the definition of the NEWLIB_CONFIGURE macro which is used by all configure.in
-files in newlib.  You will notice that each directory in newlib containing
-a configure.in file also contains an aclocal.m4 file.  This file is
-generated by issuing: aclocal -I${relative_path_to_toplevel_newlib_dir}
--I${relative_path_to_toplevel_src_dir}
-The first relative directory is to access acinclude.m4.  The second relative
-directory is to access libtool information in the top-level src directory.
-
-For example, to regenerate aclocal.m4 in newlib/libc/machine/arm:
-
-  aclocal -I ../../.. -I ../../../..
-
-Note that if the top level acinclude.m4 is altered, every aclocal.m4 file 
-in newlib should be regenerated.
-
-If the aclocal.m4 file is regenerated due to a change in acinclude.m4 or
-if a configure.in file is modified, the corresponding configure file in the 
-directory must be regenerated using autoconf.  No parameters are necessary.
-In the previous example, we would issue:
-
-  autoconf
-
-from the newlib/libc/machine/arm directory.
-
-If you have regenerated a configure file or if you have modified a Makefile.am
-file, you will need to regenerate the appropriate Makefile.in file(s).
-For newlib, automake is a bit trickier.  First of all, all Makefile.in
-files in newlib (and libgloss) are generated using the --cygnus option
-of automake.  
-
-Makefile.in files are generated from the nearest directory up the chain
-which contains a configure.in file.  In most cases, this is the same
-directory containing configure.in, but there are exceptions.
-For example, the newlib/libc directory has a number of
-subdirectories that do not contain their own configure.in files (e.g. stdio).
-For these directories, you must issue the automake command from newlib/libc
-which is the nearest parent directory that contains a configure.in.
-When you issue the automake command, you specify the subdirectory for
-the Makefile.in you are regenerating.  For example:
-
-   automake --cygnus stdio/Makefile stdlib/Makefile
-
-Note how multiple Makefile.in files can be created in the same step.  You
-would not specify machine/Makefile or sys/Makefile in the previous example
-because both of these subdirectories contain their own configure.in files.
-One would change to each of these subdirectories and in turn issue:
-
-   automake --cygnus Makefile
-
-Let's say you create a new machine directory XXXX off of newlib/libc/machine.
-After creating a new configure.in and Makefile.am file, you would issue:
-
-   aclocal -I ../../..
-   autoconf
-   automake --cygnus Makefile
-
-from newlib/libc/machine/XXXX
-
-It is strongly advised that you use an adequate version of autotools.
-For this latest release, the following were used: autoconf 2.69, aclocal 1.13.4, and 
-automake 1.13.4.
-
-Reporting Bugs
-==============
-
-The correct address for reporting bugs found in NEWLIB is
-"newlib@sourceware.org".  Please email all bug reports to that
-address.  Please include the NEWLIB version number (e.g., newlib-2.2.0),
-and how you configured it (e.g., "sun4 host and m68k-aout target").
-Since NEWLIB supports many different configurations, it is important
-that you be precise about this.
-
-Archives of the newlib mailing list are on-line, see
-	https://sourceware.org/ml/newlib/
diff --git a/docs.html b/docs.html
index 3389fa810deb..2c003edae3ae 100644
--- a/docs.html
+++ b/docs.html
@@ -16,7 +16,8 @@ The following web pages were generated from the texinfo documentation included i
 </p>
 
 <p>
-The <a href="README">Red Hat newlib README file</a> contains useful information on how to configure, build and install newlib, how to run the testsuite, and how to report bugs.
+The <a href="https://sourceware.org/git/?p=newlib-cygwin.git;a=blob_plain;f=newlib/README;hb=HEAD">Red Hat newlib README file</a>
+contains useful information on how to configure, build and install newlib, how to run the testsuite, and how to report bugs.
 </p>
 
 </body>
-- 
2.42.0

Re: [PATCH htdocs] docs: point to README in git

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 15 bytes --]

ping ...
-mike

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH htdocs] docs: point to README in git

[Jeff Johnston]

[-- Attachment #1: Type: text/plain, Size: 26814 bytes --]

Patch merged.  Thanks.

-- Jeff J.


On Sun, Oct 15, 2023 at 3:55 AM Mike Frysinger <vapier@gentoo.org> wrote:

> ---
>  README    | 595 ------------------------------------------------------
>  docs.html |   3 +-
>  2 files changed, 2 insertions(+), 596 deletions(-)
>  delete mode 100644 README
>
> diff --git a/README b/README
> deleted file mode 100644
> index f3273b2ee19d..000000000000
> --- a/README
> +++ /dev/null
> @@ -1,595 +0,0 @@
> -                        README for newlib-2.2.0 release
> -           (mostly cribbed from the README in the gdb-4.13 release)
> -
> -This is `newlib', a simple ANSI C library, math library, and collection
> -of board support packages.
> -
> -The newlib and libgloss subdirectories are a collection of software from
> -several sources, each wi6h their own copyright and license.  See the file
> -COPYING.NEWLIB for details.  The rest of the release tree is under either
> -the GNU GPL or LGPL licenses.
> -
> -THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
> -IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
> -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
> -
> -
> -Unpacking and Installation -- quick overview
> -==========================
> -
> -When you unpack the newlib-2.2.0.tar.gz file, you'll find a directory
> -called `newlib-2.2.0', which contains:
> -
> -COPYING          config/          install-sh*      mpw-configure
> -COPYING.LIB      config-ml.in     libgloss/        mpw-install
> -COPYING.NEWLIB   config.guess*    mkinstalldirs*   newlib/
> -CYGNUS           config.sub*      move-if-change*  symlink-tree*
> -ChangeLog        configure*       mpw-README       texinfo/
> -Makefile.in      configure.in     mpw-build.in
> -README           etc/             mpw-config.in
> -
> -To build NEWLIB, you must follow the instructions in the section entitled
> -"Compiling NEWLIB".
> -
> -This will configure and build all the libraries and crt0 (if one exists).
> -If `configure' can't determine your host system type, specify one as its
> -argument, e.g., sun4 or sun4sol2.  NEWLIB is most often used in cross
> -environments.
> -
> -NOTE THAT YOU MUST HAVE ALREADY BUILT AND INSTALLED GCC and BINUTILS.
> -
> -
> -More Documentation
> -==================
> -
> -   Newlib documentation is available on the net via:
> -   https://sourceware.org/newlib/docs.html
> -
> -   All the documentation for NEWLIB comes as part of the machine-readable
> -distribution.  The documentation is written in Texinfo format, which is
> -a documentation system that uses a single source file to produce both
> -on-line information and a printed manual.  You can use one of the Info
> -formatting commands to create the on-line version of the documentation
> -and TeX (or `texi2roff') to typeset the printed version.
> -
> -   If you want to format these Info files yourself, you need one of the
> -Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
> -
> -   If you want to typeset and print copies of this manual, you need TeX,
> -a program to print its DVI output files, and `texinfo.tex', the Texinfo
> -definitions file.
> -
> -   TeX is a typesetting program; it does not print files directly, but
> -produces output files called DVI files.  To print a typeset document,
> -you need a program to print DVI files.  If your system has TeX
> -installed, chances are it has such a program.  The precise command to
> -use depends on your system; `lpr -d' is common; another (for PostScript
> -devices) is `dvips'.  The DVI print command may require a file name
> -without any extension or a `.dvi' extension.
> -
> -   TeX also requires a macro definitions file called `texinfo.tex'.
> -This file tells TeX how to typeset a document written in Texinfo
> -format.  On its own, TeX cannot read, much less typeset a Texinfo file.
> -`texinfo.tex' is distributed with NEWLIB and is located in the
> -`newlib-VERSION-NUMBER/texinfo' directory.
> -
> -
> -
> -Compiling NEWLIB
> -================
> -
> -   To compile NEWLIB, you must build it in a directory separate from
> -the source directory.  If you want to run NEWLIB versions for several
> host
> -or target machines, you need a different `newlib' compiled for each
> combination
> -of host and target.  `configure' is designed to make this easy by
> allowing
> -you to generate each configuration in a separate subdirectory.
> -If your `make' program handles the `VPATH' feature correctly (like GNU
> `make')
> -running `make' in each of these directories builds the `newlib' libraries
> -specified there.
> -
> -   To build `newlib' in a specific directory, run `configure' with the
> -`--srcdir' option to specify where to find the source. (You also need
> -to specify a path to find `configure' itself from your working
> -directory.  If the path to `configure' would be the same as the
> -argument to `--srcdir', you can leave out the `--srcdir' option; it
> -will be assumed.)
> -
> -   For example, with version 2.2.0, you can build NEWLIB in a separate
> -directory for a Sun 4 cross m68k-aout environment like this:
> -
> -     cd newlib-2.2.0
> -     mkdir ../newlib-m68k-aout
> -     cd ../newlib-m68k-aout
> -     ../newlib-2.2.0/configure --host=sun4 --target=m68k-aout
> -     make
> -
> -   When `configure' builds a configuration using a remote source
> -directory, it creates a tree for the binaries with the same structure
> -(and using the same names) as the tree under the source directory.  In
> -the example, you'd find the Sun 4 library `libiberty.a' in the
> -directory `newlib-m68k-aout/libiberty', and NEWLIB itself in
> -`newlib-m68k-aout/newlib'.
> -
> -   When you run `make' to build a program or library, you must run it
> -in a configured directory--whatever directory you were in when you
> -called `configure' (or one of its subdirectories).
> -
> -   The `Makefile' that `configure' generates in each source directory
> -also runs recursively.  If you type `make' in a source directory such
> -as `newlib-2.2.0' (or in a separate configured directory configured with
> -`--srcdir=PATH/newlib-2.2.0'), you will build all the required libraries.
> -
> -   When you have multiple hosts or targets configured in separate
> -directories, you can run `make' on them in parallel (for example, if
> -they are NFS-mounted on each of the hosts); they will not interfere
> -with each other.
> -
> -
> -Specifying names for hosts and targets
> -======================================
> -
> -   The specifications used for hosts and targets in the `configure'
> -script are based on a three-part naming scheme, but some short
> -predefined aliases are also supported.  The full naming scheme encodes
> -three pieces of information in the following pattern:
> -
> -     ARCHITECTURE-VENDOR-OS
> -
> -   For example, you can use the alias `sun4' as a HOST argument or in a
> -`--target=TARGET' option.  The equivalent full name is
> -`sparc-sun-sunos4'.
> -
> -   The `configure' script accompanying NEWLIB does not provide any query
> -facility to list all supported host and target names or aliases.
> -`configure' calls the Bourne shell script `config.sub' to map
> -abbreviations to full names; you can read the script, if you wish, or
> -you can use it to test your guesses on abbreviations--for example:
> -
> -     % sh config.sub sun4
> -     sparc-sun-sunos4.1.1
> -     % sh config.sub sun3
> -     m68k-sun-sunos4.1.1
> -     % sh config.sub decstation
> -     mips-dec-ultrix4.2
> -     % sh config.sub hp300bsd
> -     m68k-hp-bsd
> -     % sh config.sub i386v
> -     i386-pc-sysv
> -     % sh config.sub i786v
> -     Invalid configuration `i786v': machine `i786v' not recognized
> -
> -The Build, Host and Target Concepts in newlib
> -=============================================
> -
> -The build, host and target concepts are defined for gcc as follows:
> -
> -build: the platform on which gcc is built.
> -host: the platform on which gcc is run.
> -target: the platform for which gcc generates code.
> -
> -Since newlib is a library, the target concept does not apply to it, and
> the
> -build, host, and target options given to the top-level configure script
> must
> -be changed for newlib's use.
> -
> -The options are shifted according to these correspondences:
> -
> -gcc's build platform has no equivalent in newlib.
> -gcc's host platform is newlib's build platform.
> -gcc's target platform is newlib's host platform.
> -and as mentioned before, newlib has no concept of target.
> -
> -`configure' options
> -===================
> -
> -   Here is a summary of the `configure' options and arguments that are
> -most often useful for building NEWLIB.  `configure' also has several other
> -options not listed here.
> -
> -     configure [--help]
> -               [--prefix=DIR]
> -               [--srcdir=PATH]
> -               [--target=TARGET] HOST
> -
> -You may introduce options with a single `-' rather than `--' if you
> -prefer; but you may abbreviate option names if you use `--'.
> -
> -`--help'
> -     Display a quick summary of how to invoke `configure'.
> -
> -`--prefix=DIR'
> -     Configure the source to install programs and files in directory
> -     `DIR'.
> -
> -`--exec-prefix=DIR'
> -     Configure the source to install host-dependent files in directory
> -     `DIR'.
> -
> -`--srcdir=PATH'
> -     *Warning: using this option requires GNU `make', or another `make'
> -     that compatibly implements the `VPATH' feature.
> -     Use this option to make configurations in directories separate
> -     from the NEWLIB source directories.  Among other things, you can use
> -     this to build (or maintain) several configurations simultaneously,
> -     in separate directories.  `configure' writes configuration
> -     specific files in the current directory, but arranges for them to
> -     use the source in the directory PATH.  `configure' will create
> -     directories under the working directory in parallel to the source
> -     directories below PATH.
> -
> -`--norecursion'
> -     Configure only the directory level where `configure' is executed;
> -     do not propagate configuration to subdirectories.
> -
> -`--target=TARGET'
> -     Configure NEWLIB for running on the specified TARGET.
> -
> -     There is no convenient way to generate a list of all available
> -     targets.
> -
> -`HOST ...'
> -     Configure NEWLIB to be built using a cross compiler running on
> -     the specified HOST.
> -
> -     There is no convenient way to generate a list of all available
> -     hosts.
> -
> -To fit diverse usage models, NEWLIB supports a group of configuration
> -options so that library features can be turned on/off according to
> -target system's requirements.
> -
> -One feature can be enabled by specifying `--enable-FEATURE=yes' or
> -`--enable-FEATURE'.  Or it can be disable by `--enable-FEATURE=no' or
> -`--disable-FEATURE'.
> -
> -`--enable-newlib-io-pos-args'
> -     Enable printf-family positional arg support.
> -     Disabled by default, but some hosts enable it in configure.host.
> -
> -`--enable-newlib-io-c99-formats'
> -     Enable C99 support in IO functions like printf/scanf.
> -     Disabled by default, but some hosts enable it in configure.host.
> -
> -`--enable-newlib-register-fini'
> -     Enable finalization function registration using atexit.
> -     Disabled by default.
> -
> -`--enable-newlib-io-long-long'
> -     Enable long long type support in IO functions like printf/scanf.
> -     Disabled by default, but many hosts enable it in configure.host.
> -
> -`--enable-newlib-io-long-double'
> -     Enable long double type support in IO functions printf/scanf.
> -     Disabled by default, but some hosts enable it in configure.host.
> -
> -`--enable-newlib-mb'
> -     Enable multibyte support.
> -     Disabled by default.
> -
> -`--enable-newlib-iconv-encodings'
> -     Enable specific comma-separated list of bidirectional iconv
> -     encodings to be built-in.
> -     Disabled by default.
> -
> -`--enable-newlib-iconv-from-encodings'
> -     Enable specific comma-separated list of \"from\" iconv encodings
> -     to be built-in.
> -     Disabled by default.
> -
> -`--enable-newlib-iconv-to-encodings'
> -     Enable specific comma-separated list of \"to\" iconv encodings
> -     to be built-in.
> -     Disabled by default.
> -
> -`--enable-newlib-iconv-external-ccs'
> -     Enable capabilities to load external CCS files for iconv.
> -     Disabled by default.
> -
> -`--disable-newlib-atexit-dynamic-alloc'
> -     Disable dynamic allocation of atexit entries.
> -     Most hosts and targets have it enabled in configure.host.
> -
> -`--enable-newlib-global-atexit'
> -     Enable atexit data structure as global variable.  By doing so it is
> -     move out of _reent structure, and can be garbage collected if atexit
> -     is not referenced.
> -     Disabled by default.
> -
> -`--enable-newlib-reent-small'
> -     Enable small reentrant struct support.
> -     Disabled by default.
> -
> -`--disable-newlib-fvwrite-in-streamio'
> -     NEWLIB implements the vector buffer mechanism to support stream IO
> -     buffering required by C standard.  This feature is possibly
> -     unnecessary for embedded systems which won't change file buffering
> -     with functions like `setbuf' or `setvbuf'.  The buffering mechanism
> -     still acts as default for STDIN/STDOUT/STDERR even if this option
> -     is specified.
> -     Enabled by default.
> -
> -`--disable-newlib-fseek-optimization'
> -     Disable fseek optimization.  It can decrease code size of application
> -     calling `fseek`.
> -     Enabled by default.
> -
> -`--disable-newlib-wide-orient'
> -     C99 states that each stream has an orientation, wide or byte.  This
> -     feature is possibly unnecessary for embedded systems which only do
> -     byte input/output operations on stream.  It can decrease code size
> -     by disable the feature.
> -     Enabled by default.
> -
> -`--enable-newlib-nano-malloc'
> -     NEWLIB has two implementations of malloc family's functions, one in
> -     `mallocr.c' and the other one in `nano-mallocr.c'.  This options
> -     enables the nano-malloc implementation, which is for small systems
> -     with very limited memory.  Note that this implementation does not
> -     support `--enable-malloc-debugging' any more.
> -     Disabled by default.
> -
> -`--disable-newlib-unbuf-stream-opt'
> -     NEWLIB does optimization when `fprintf to write only unbuffered unix
> -     file'.  It creates a temorary buffer to do the optimization that
> -     increases stack consumption by about `BUFSIZ' bytes.  This option
> -     disables the optimization and saves size of text and stack.
> -     Enabled by default.
> -
> -`--enable-multilib'
> -     Build many library versions.
> -     Enabled by default.
> -
> -`--enable-target-optspace'
> -     Optimize for space.
> -     Disabled by default.
> -
> -`--enable-malloc-debugging'
> -     Indicate malloc debugging requested.
> -     Disabled by default.
> -
> -`--enable-newlib-multithread'
> -     Enable support for multiple threads.
> -     Enabled by default.
> -
> -`--enable-newlib-iconv'
> -     Enable iconv library support.
> -     Disabled by default.
> -
> -`--enable-newlib-elix-level'
> -     Supply desired elix library level (1-4).  Please refer to HOWTO for
> -     more information about this option.
> -     Set to level 0 by default.
> -
> -`--disable-newlib-io-float'
> -     Disable printf/scanf family float support.
> -     Enabled by default.
> -
> -`--disable-newlib-supplied-syscalls'
> -     Disable newlib from supplying syscalls.
> -     Enabled by default.
> -
> -`--enable-lite-exit'
> -     Enable lite exit, a size-reduced implementation of exit that doesn't
> -     invoke clean-up functions such as _fini or global destructors.
> -     Disabled by default.
> -
> -`--enable-newlib-nano-formatted-io'
> -     This builds NEWLIB with a special implementation of formatted I/O
> -     functions, designed to lower the size of application on small systems
> -     with size constraint issues.  This option does not affect wide-char
> -     formatted I/O functions.  Some notes about the feature:
> -      1) The non-wide-char formatted I/O functions only support the C89
> -        standard.  The only exception is the configuration option provides
> -        limited support for long double.  Internally, the nano formatted
> I/O
> -        functions use double so accuracy is only guaranteed to double
> -        precision.
> -      2) Floating-point support is split out of the formatted I/O code
> into
> -        weak functions which are not linked by default.  Programs that
> need
> -        floating-point I/O support must explicitly request linking of one
> or
> -        both of the floating-point functions: _printf_float or
> _scanf_float.
> -        This can be done at link time using the -u option which can be
> passed
> -        to either gcc or ld.  The -u option forces the link to resolve
> those
> -        function references.  Floating-point format specifiers are
> recognized
> -        by default, but if the floating-point functions are not explicitly
> -        linked in, this may result in undefined behavior for programs that
> -        need floating-point I/O support.
> -      3) Integer-only versions of the formatted I/O functions (the
> iprintf/
> -        iscanf family) simply alias their regular counter-parts.
> -        The affected functions are:
> -
> -         diprintf vdiprintf
> -
> -         siprintf fiprintf iprintf sniprintf asiprintf asniprintf
> -
> -         siscanf fiscanf iscanf
> -
> -         viprintf vfiprintf vsiprintf vsniprintf vasiprintf vasniprintf
> -
> -         viscanf vfiscanf vsiscanf
> -
> -         _diprintf_r _vdiprintf_r
> -
> -         _siprintf_r _fiprintf_r _iprintf_r _sniprintf_r _asiprintf_r
> -         _asniprintf_r
> -
> -         _siscanf_r _fiscanf_r _iscanf_r
> -
> -         _viprintf_r _vfiprintf_r _vsiprintf_r _asniprintf_r _vasiprintf_r
> -         _vasniprintf_r
> -
> -         _viscanf_r _vfiscanf_r _vsiscanf_r
> -
> -      4) As mentioned, the option does not affect wide-char formatted I/O.
> -        The following configuration options are ignored for non-wide-char
> -        formatted I/O functions, and can be thought of as disabled.
> -
> -         enable-newlib-io-pos-args
> -         enable-newlib-io-c99-formats
> -         enable-newlib-io-long-long
> -         enable-newlib-io-long-double
> -         enable-newlib-mb
> -
> -        Additionally, "enable/disable-newlib-io-float" is supported in
> -        this specific implementation, one can use
> "disable-newlib-io-float"
> -        to further reduce code size.  In this case, the floating-point
> -        specifiers will not be recognized or handled, and the -u option
> -        will not work either.
> -
> -      5) As a rule, no features from outside of C89 standard will be
> -        considered in this implementation.
> -
> -     Disabled by default.
> -
> -Running the Testsuite
> -=====================
> -
> -To run newlib's testsuite, you'll need a site.exp in your home
> -directory which points dejagnu to the proper baseboards directory and
> -the proper exp file for your target.
> -
> -Before running make check-target-newlib, set the DEJAGNU environment
> -variable to point to ~/site.exp.
> -
> -Here is a sample site.exp:
> -
> -# Make sure we look in the right place for the board description files.
> -if ![info exists boards_dir] {
> -    set boards_dir {}
> -}
> -lappend boards_dir "your dejagnu/baseboards here"
> -
> -verbose "Global Config File: target_triplet is $target_triplet" 2
> -
> -global target_list
> -case "$target_triplet" in {
> -
> -    { "mips-*elf*" } {
> -       set target_list "mips-sim"
> -    }
> -
> -    default {
> -       set target_list { "unix" }
> -    }
> -}
> -
> -mips-sim refers to an exp file in the baseboards directory.  You'll
> -need to add the other targets you're testing to the case statement.
> -
> -Now type make check-target-newlib in the top-level build directory to
> -run the testsuite.
> -
> -Shared newlib
> -=============
> -
> -newlib uses libtool when it is being compiled natively (with
> ---target=i[34567]86-pc-linux-gnu) on an i[34567]86-pc-linux-gnu
> -host. This allows newlib to be compiled as a shared library.
> -
> -To configure newlib, do the following from your build directory:
> -
> -$(source_dir)/src/configure --with-newlib --prefix=$(install_dir)
> -
> -configure will recognize that host == target ==
> -i[34567]86-pc-linux-gnu, so it will tell newlib to compile itself using
> -libtool. By default, libtool will build shared and static versions of
> -newlib.
> -
> -To compile a program against shared newlib, do the following (where
> -target_install_dir = $(install_dir)/i[34567]86-pc-linux-gnu):
> -
> -gcc -nostdlib $(target_install_dir)/lib/crt0.o progname.c -I
> $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm -lgcc
> -
> -To run the program, make sure that $(target_install_dir)/lib is listed
> -in the LD_LIBRARY_PATH environment variable.
> -
> -To create a static binary linked against newlib, do the following:
> -
> -gcc -nostdlib -static $(target_install_dir)/lib/crt0.o progname.c -I
> $(target_install_dir)/include -L $(target_install_dir)/lib -lc -lm
> -
> -libtool can be instructed to produce only static libraries. To build
> -newlib as a static library only, do the following from your build
> -directory:
> -
> -$(source_dir)/src/configure --with-newlib --prefix=$(install_dir)
> --disable-shared
> -
> -Regenerating Configuration Files
> -================================
> -
> -At times you will need to make changes to configure.in and Makefile.am
> files.
> -This will mean that configure and Makefile.in files will need to be
> -regenerated.
> -
> -At the top level of newlib is the file: acinclude.m4.  This file contains
> -the definition of the NEWLIB_CONFIGURE macro which is used by all
> configure.in
> -files in newlib.  You will notice that each directory in newlib containing
> -a configure.in file also contains an aclocal.m4 file.  This file is
> -generated by issuing: aclocal -I${relative_path_to_toplevel_newlib_dir}
> --I${relative_path_to_toplevel_src_dir}
> -The first relative directory is to access acinclude.m4.  The second
> relative
> -directory is to access libtool information in the top-level src directory.
> -
> -For example, to regenerate aclocal.m4 in newlib/libc/machine/arm:
> -
> -  aclocal -I ../../.. -I ../../../..
> -
> -Note that if the top level acinclude.m4 is altered, every aclocal.m4 file
> -in newlib should be regenerated.
> -
> -If the aclocal.m4 file is regenerated due to a change in acinclude.m4 or
> -if a configure.in file is modified, the corresponding configure file in
> the
> -directory must be regenerated using autoconf.  No parameters are
> necessary.
> -In the previous example, we would issue:
> -
> -  autoconf
> -
> -from the newlib/libc/machine/arm directory.
> -
> -If you have regenerated a configure file or if you have modified a
> Makefile.am
> -file, you will need to regenerate the appropriate Makefile.in file(s).
> -For newlib, automake is a bit trickier.  First of all, all Makefile.in
> -files in newlib (and libgloss) are generated using the --cygnus option
> -of automake.
> -
> -Makefile.in files are generated from the nearest directory up the chain
> -which contains a configure.in file.  In most cases, this is the same
> -directory containing configure.in, but there are exceptions.
> -For example, the newlib/libc directory has a number of
> -subdirectories that do not contain their own configure.in files (e.g.
> stdio).
> -For these directories, you must issue the automake command from
> newlib/libc
> -which is the nearest parent directory that contains a configure.in.
> -When you issue the automake command, you specify the subdirectory for
> -the Makefile.in you are regenerating.  For example:
> -
> -   automake --cygnus stdio/Makefile stdlib/Makefile
> -
> -Note how multiple Makefile.in files can be created in the same step.  You
> -would not specify machine/Makefile or sys/Makefile in the previous example
> -because both of these subdirectories contain their own configure.in
> files.
> -One would change to each of these subdirectories and in turn issue:
> -
> -   automake --cygnus Makefile
> -
> -Let's say you create a new machine directory XXXX off of
> newlib/libc/machine.
> -After creating a new configure.in and Makefile.am file, you would issue:
> -
> -   aclocal -I ../../..
> -   autoconf
> -   automake --cygnus Makefile
> -
> -from newlib/libc/machine/XXXX
> -
> -It is strongly advised that you use an adequate version of autotools.
> -For this latest release, the following were used: autoconf 2.69, aclocal
> 1.13.4, and
> -automake 1.13.4.
> -
> -Reporting Bugs
> -==============
> -
> -The correct address for reporting bugs found in NEWLIB is
> -"newlib@sourceware.org".  Please email all bug reports to that
> -address.  Please include the NEWLIB version number (e.g., newlib-2.2.0),
> -and how you configured it (e.g., "sun4 host and m68k-aout target").
> -Since NEWLIB supports many different configurations, it is important
> -that you be precise about this.
> -
> -Archives of the newlib mailing list are on-line, see
> -       https://sourceware.org/ml/newlib/
> diff --git a/docs.html b/docs.html
> index 3389fa810deb..2c003edae3ae 100644
> --- a/docs.html
> +++ b/docs.html
> @@ -16,7 +16,8 @@ The following web pages were generated from the texinfo
> documentation included i
>  </p>
>
>  <p>
> -The <a href="README">Red Hat newlib README file</a> contains useful
> information on how to configure, build and install newlib, how to run the
> testsuite, and how to report bugs.
> +The <a href="
> https://sourceware.org/git/?p=newlib-cygwin.git;a=blob_plain;f=newlib/README;hb=HEAD">Red
> Hat newlib README file</a>
> +contains useful information on how to configure, build and install
> newlib, how to run the testsuite, and how to report bugs.
>  </p>
>
>  </body>
> --
> 2.42.0
>
>