[htdocs] docs: point to README in git
Commit Message
---
README | 595 ------------------------------------------------------
docs.html | 3 +-
2 files changed, 2 insertions(+), 596 deletions(-)
delete mode 100644 README
Comments
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
>
>
deleted file mode 100644
@@ -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/
@@ -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>