From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.gentoo.org (dev.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) by sourceware.org (Postfix) with ESMTP id 1B46F3858D20 for ; Sun, 15 Oct 2023 07:55:31 +0000 (GMT) ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 1B46F3858D20 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=2001:470:ea4a:1:5054:ff:fec7:86e4 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1697356534; cv=none; b=PWsfl4nFyWR5e/FCLg1N3kJ/ltVpi3m/qPvSYAX+RPbeydSoH8al9Nu1JFXbPN0dfcOBXnlQEfoLrq+OvShBdrAXzNmAn/RZpGqdKwnq/GvNnMrGM2/myK0oqw1v7J6hFECUKWDtK5Gm1Lwo5k4RRSJPEVUNJvRPDGoeTJbgYLo= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1697356534; c=relaxed/simple; bh=BcdhW939eCTqFZX8VjcZowC5HZ/lRUBFjNC5O+igLCE=; h=From:To:Subject:Date:Message-ID:MIME-Version; b=t8CqMs8das8kIa7pL/tyayhxtOIrvbdzlXGgtKjdKwQ5Vc4T/BYrcogjyO1xTXNrtMx8qcof6h4Y1xglTyZhjCKNoYXRDUgrwujeE+rzDrb0j328YL7GnZ73vmicW4YZUE87q+m5uqeBClG3SDiU3ITPT63dyCVfHU/FY9aGx6A= ARC-Authentication-Results: i=1; server2.sourceware.org DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 1B46F3858D20 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=gentoo.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gentoo.org Received: by smtp.gentoo.org (Postfix, from userid 559) id 9836A335CDF; Sun, 15 Oct 2023 07:55:30 +0000 (UTC) From: Mike Frysinger To: newlib@sourceware.org Subject: [PATCH htdocs] docs: point to README in git Date: Sun, 15 Oct 2023 13:40:26 +0545 Message-ID: <20231015075526.17911-1-vapier@gentoo.org> X-Mailer: git-send-email 2.42.0 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-10.7 required=5.0 tests=BAYES_00,GIT_PATCH_0,JMQ_SPF_NEUTRAL,KAM_ASCII_DIVIDERS,KAM_DMARC_STATUS,SPF_HELO_PASS,SPF_PASS,TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: --- 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

-The Red Hat newlib README file contains useful information on how to configure, build and install newlib, how to run the testsuite, and how to report bugs. +The Red Hat newlib README file +contains useful information on how to configure, build and install newlib, how to run the testsuite, and how to report bugs.

-- 2.42.0