mirror of
https://github.com/autc04/Retro68.git
synced 2024-08-28 19:29:05 +00:00
118 lines
6.0 KiB
Plaintext
118 lines
6.0 KiB
Plaintext
|
This HOWTO file contains notes for maintainers and contributors to Newlib.
|
||
|
For information on using Newlib (building, installing), see README. (In
|
||
|
particular, the "Regenerating Configuration Files" section in README is of
|
||
|
interest to both users and contributors.)
|
||
|
|
||
|
(This file could probably use some other "sections" in addition to the
|
||
|
initially-provided sections. Please help by adding as appropriate.)
|
||
|
|
||
|
DOCUMENTATION
|
||
|
=============
|
||
|
|
||
|
All the documentation for Newlib comes as part of the machine-readable
|
||
|
distribution. Functions are documented in the source files, although not
|
||
|
every file contains documentation, as many functions share manual page
|
||
|
information. For example, lround(), lroundf(), llround(), and llroundf()
|
||
|
share a single man page, which is in the source for lround(). The documentation
|
||
|
is written partially in a custom format and partially in Texinfo format.
|
||
|
|
||
|
The custom part comprises makedoc.c and doc.str, both of which are in the
|
||
|
doc directory. doc.str is a macro file that can be used to define things to
|
||
|
be done by makedoc, using building blocks that are built into makedoc.c.
|
||
|
The basic function of makedoc is two-fold. First, it recognizes comments in
|
||
|
the proper format to pull out of source files. Second, it adds some Texinfo
|
||
|
commands as well as translating certain sequences into the appropriate
|
||
|
Texinfo commands. Refer to makedoc.c and doc.str for what these are.
|
||
|
(makedoc.c is not particularly-well commented.) Another way to see how they
|
||
|
work is to simply examine the source files with documentation comments.
|
||
|
|
||
|
(A couple of examples that use some of the fancier options:
|
||
|
libm/common/s_isnan.c ("o+" variable-"bullet" list),
|
||
|
libc/stdio/sprintf.c ("O+" bullet list; "." for example code).)
|
||
|
|
||
|
In addition to the makedoc.c stuff, Texinfo commands can be directly
|
||
|
used. Texinfo 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. While Newlib contains
|
||
|
a copy of the texinfo package (texinfo.tex), the manual for it is not
|
||
|
included. The latest one may be found at
|
||
|
|
||
|
http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html
|
||
|
|
||
|
(which could be for a newer version of texinfo.tex than is included in Newlib).
|
||
|
|
||
|
In addition to Texinfo commands, straight TeX commands can also be used,
|
||
|
but these, however, should be carefully limited and be given alternates for
|
||
|
when a non-printed manual is produced--such as when info pages are produced.
|
||
|
For an example of this kind of usage, see libm/common/s_logb.c.
|
||
|
|
||
|
Please note that most files with documentation contain both an
|
||
|
ANSI_SYNOPSIS and a TRAD_SYNOPSIS section. The TRAD_SYNOPSIS section gets
|
||
|
deleted (since at least 2000) by makedoc, so when working on files these
|
||
|
can safely be deleted and if you're making a new file, there is no need
|
||
|
to add the TRAD_SYNOPSIS section.
|
||
|
|
||
|
If writing a new function that requires documentation, the required
|
||
|
sections are FUNCTION, INDEX, ANSI_SYNOPSIS (or SYNOPSIS), DESCRIPTION, RETURNS,
|
||
|
and PORTABILITY. BUGS and SEEALSO should be added as appropriate.
|
||
|
|
||
|
Source files which contain documentation are processed into ".def"
|
||
|
files with the extracted information. These .def files are noted in the
|
||
|
makefiles as either CHEWOUT_FILES in the libc makefiles or chobj in the libm
|
||
|
makefiles. These .def files need to be included into an appropriate .tex
|
||
|
file for inclusion in the manuals (one each for libc and libm). Pay special
|
||
|
attention under libc, as the manual is arranged by header file name, but not
|
||
|
all header files are represented by directories (e.g. wcsftime.c is found
|
||
|
under libc/time, but goes under wchar.h in the manual.)
|
||
|
|
||
|
In summary, to add new documentation:
|
||
|
|
||
|
1. Add properly-formatted comments to source file (e.g. src.c);
|
||
|
2. add "chewout" file to list in Makefile.am (CHEWOUT_FILES in libc or chobj in
|
||
|
libm) (e.g. src.def), re-generate Makefile.in;
|
||
|
3. add file to something.tex;
|
||
|
4. make ChangeLog entry and generate patch.
|
||
|
|
||
|
EL/IX (ELIX_LEVEL_n, ELIX_n_SOURCES)
|
||
|
====================================
|
||
|
|
||
|
Some of the Makefiles contain definitions of ELIX_LEVEL_1 ... ELIX_LEVEL_4,
|
||
|
and corresponding definitions for ELIX_1_SOURCES ... ELIX_4_SOURCES.
|
||
|
These are referring to the EL/IX standards created by Red Hat for the
|
||
|
purpose of Linux-based open standards for embedded development. In brief,
|
||
|
the intent is to define multiple levels for API functions that allows the
|
||
|
user to size the library appropriately for their application--at least in
|
||
|
terms of the predefined lists. For full details, refer to the EL/IX home
|
||
|
page at http://sources.redhat.com/elix/. The likely best way to tell how to
|
||
|
classify any new functions in terms of needing an ELIX level qualification
|
||
|
is to ask Jeff Johnston. To see how it works and try classification on your
|
||
|
own, refer to the API specification on the web site,
|
||
|
|
||
|
http://sources.redhat.com/elix/api/current/api.pdf.
|
||
|
|
||
|
(Unfortunately, it is not complete with respect to either the C99 or POSIX
|
||
|
standards, so particular C and POSIX functions may or may not be found.)
|
||
|
|
||
|
The following definitions of the levels are from the (draft) standard.
|
||
|
|
||
|
Level 1
|
||
|
RTOS compatible layer. Functions available in both Linux and a
|
||
|
typical deeply embedded operating system (eCos, RTEMS, VxWorks, pSOS, VRTX32,
|
||
|
etc.). Some functions may have reduced or modified semantics.
|
||
|
|
||
|
Level 2
|
||
|
Linux single process only. Includes level 1 plus any functions from Linux
|
||
|
that are not easily implemented on an RTOS. Also full implementations of
|
||
|
reduced functions in Level 1.
|
||
|
|
||
|
Level 3
|
||
|
Linux multiprocess for embedded applications. This is basically POSIX.1
|
||
|
with some of the functions that are obviously not for embedded applications
|
||
|
(such as job control) removed.
|
||
|
|
||
|
Level 4
|
||
|
Full POSIX or Linux compliance. Essentially these are functions that are
|
||
|
present in a standard Linux kernel but are irrelevant to an embedded system.
|
||
|
These functions do not form part of the EL/IX API.
|