OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [newlib-1.18.0/] [newlib/] [HOWTO] - Blame information for rev 207

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 207 jeremybenn
This HOWTO file contains notes for maintainers and contributors to Newlib.
2
For information on using Newlib (building, installing), see README.  (In
3
particular, the "Regenerating Configuration Files" section in README is of
4
interest to both users and contributors.)
5
 
6
(This file could probably use some other "sections" in addition to the
7
initially-provided sections.  Please help by adding as appropriate.)
8
 
9
DOCUMENTATION
10
=============
11
 
12
     All the documentation for Newlib comes as part of the machine-readable
13
distribution.  Functions are documented in the source files, although not
14
every file contains documentation, as many functions share manual page
15
information.  For example, lround(), lroundf(), llround(), and llroundf()
16
share a single man page, which is in the source for lround().  The documentation
17
is written partially in a custom format and partially in Texinfo format.
18
 
19
     The custom part comprises makedoc.c and doc.str, both of which are in the
20
doc directory.  doc.str is a macro file that can be used to define things to
21
be done by makedoc, using building blocks that are built into makedoc.c.
22
The basic function of makedoc is two-fold.  First, it recognizes comments in
23
the proper format to pull out of source files.  Second, it adds some Texinfo
24
commands as well as translating certain sequences into the appropriate
25
Texinfo commands.  Refer to makedoc.c and doc.str for what these are.
26
(makedoc.c is not particularly-well commented.)  Another way to see how they
27
work is to simply examine the source files with documentation comments.
28
 
29
(A couple of examples that use some of the fancier options:
30
        libm/common/s_isnan.c ("o+" variable-"bullet" list),
31
        libc/stdio/sprintf.c ("O+" bullet list; "." for example code).)
32
 
33
     In addition to the makedoc.c stuff, Texinfo commands can be directly
34
used.  Texinfo is a documentation system that uses a single source file to
35
produce both on-line information and a printed manual.  You can use one of the
36
Info formatting commands to create the on-line version of the documentation
37
and TeX (or `texi2roff') to typeset the printed version.  While Newlib contains
38
a copy of the texinfo package (texinfo.tex), the manual for it is not
39
included.  The latest one may be found at
40
 
41
http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html
42
 
43
(which could be for a newer version of texinfo.tex than is included in Newlib).
44
 
45
     In addition to Texinfo commands, straight TeX commands can also be used,
46
but these, however, should be carefully limited and be given alternates for
47
when a non-printed manual is produced--such as when info pages are produced.
48
For an example of this kind of usage, see libm/common/s_logb.c.
49
 
50
     Please note that most files with documentation contain both an
51
ANSI_SYNOPSIS and a TRAD_SYNOPSIS section.  The TRAD_SYNOPSIS section gets
52
deleted (since at least 2000) by makedoc, so when working on files these
53
can safely be deleted and if you're making a new file, there is no need
54
to add the TRAD_SYNOPSIS section.
55
 
56
     If writing a new function that requires documentation, the required
57
sections are FUNCTION, INDEX, ANSI_SYNOPSIS (or SYNOPSIS), DESCRIPTION, RETURNS,
58
and PORTABILITY.  BUGS and SEEALSO should be added as appropriate.
59
 
60
     Source files which contain documentation are processed into ".def"
61
files with the extracted information.  These .def files are noted in the
62
makefiles as either CHEWOUT_FILES in the libc makefiles or chobj in the libm
63
makefiles.  These .def files need to be included into an appropriate .tex
64
file for inclusion in the manuals (one each for libc and libm).  Pay special
65
attention under libc, as the manual is arranged by header file name, but not
66
all header files are represented by directories (e.g.  wcsftime.c is found
67
under libc/time, but goes under wchar.h in the manual.)
68
 
69
In summary, to add new documentation:
70
 
71
1.  Add properly-formatted comments to source file (e.g. src.c);
72
2.  add "chewout" file to list in Makefile.am (CHEWOUT_FILES in libc or chobj in
73
    libm) (e.g. src.def), re-generate Makefile.in;
74
3.  add file to something.tex;
75
4.  make ChangeLog entry and generate patch.
76
 
77
EL/IX (ELIX_LEVEL_n, ELIX_n_SOURCES)
78
====================================
79
 
80
     Some of the Makefiles contain definitions of ELIX_LEVEL_1 ... ELIX_LEVEL_4,
81
and corresponding definitions for ELIX_1_SOURCES ... ELIX_4_SOURCES.
82
These are referring to the EL/IX standards created by Red Hat for the
83
purpose of Linux-based open standards for embedded development.  In brief,
84
the intent is to define multiple levels for API functions that allows the
85
user to size the library appropriately for their application--at least in
86
terms of the predefined lists.  For full details, refer to the EL/IX home
87
page at http://sources.redhat.com/elix/.  The likely best way to tell how to
88
classify any new functions in terms of needing an ELIX level qualification
89
is to ask Jeff Johnston.  To see how it works and try classification on your
90
own, refer to the API specification on the web site,
91
 
92
http://sources.redhat.com/elix/api/current/api.pdf.
93
 
94
(Unfortunately, it is not complete with respect to either the C99 or POSIX
95
standards, so particular C and POSIX functions may or may not be found.)
96
 
97
     The following definitions of the levels are from the (draft) standard.
98
 
99
Level 1
100
     RTOS compatible layer.  Functions available in both Linux and a
101
typical deeply embedded operating system (eCos, RTEMS, VxWorks, pSOS, VRTX32,
102
etc.).  Some functions may have reduced or modified semantics.
103
 
104
Level 2
105
     Linux single process only. Includes level 1 plus any functions from Linux
106
that are not easily implemented on an RTOS.  Also full implementations of
107
reduced functions in Level 1.
108
 
109
Level 3
110
     Linux multiprocess for embedded applications.  This is basically POSIX.1
111
with some of the functions that are obviously not for embedded applications
112
(such as job control) removed.
113
 
114
Level 4
115
     Full POSIX or Linux compliance.  Essentially these are functions that are
116
present in a standard Linux kernel but are irrelevant to an embedded system.
117
These functions do not form part of the EL/IX API.

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.