113 lines
5.6 KiB
Plaintext
113 lines
5.6 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
|
|
|
|
https://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.
|
|
|
|
If writing a new function that requires documentation, the required
|
|
sections are FUNCTION, INDEX, SYNOPSIS, DESCRIPTION, RETURNS,
|
|
and PORTABILITY. BUGS, NOTES, SEEALSO and WARNINGS 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 CHEWOUT_FILES. 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 CHEWOUT_FILES list in Makefile.am (e.g. src.def),
|
|
re-generate Makefile.in;
|
|
3. @include that .def file in the appropriate .tex file, add texinfo menu
|
|
entries that reference the @node(s) in that .def file;
|
|
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 https://sourceware.org/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,
|
|
|
|
https://sourceware.org/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.
|