1COVERAGE FILES
2==============
3
4Every area of the POSIX spec that has tests written for it should be tracked by
5a corresponding COVERAGE.<area> file in the Documentation directory. The first
6example file is COVERAGE.timers, which I will keep up to date with the latest
7format.
8
9The idea with these files is to track the progress of test creation. Also, the
10files will be parsed nightly to generate the Project Status web page at
11http://posixtest.sf.net/status.html so they must conform to a certain format.
12
13To simplify the creation of a tool to parse these files, the following rules
14should be observed in creating the file.
15
16Completion of POSIX Function Conformance Tests
17----------------------------------------------
18There should be one line for each POSIX function included in this area of the
19POSIX spec. The tests for these functions are currently found in the
20conformance/behavior/<function-name> directory. (They may be moved to
21conformance/interfaces/<function-name> shortly.) The function test directory
22need not exist yet, but the list of functions in the COVERAGE file should be
23complete.
24
25Each line should have this format:
26<function-name>  <complete?>  <other-fields>
27
28That is, spaces or tabs as whitespace separating the function name and complete
29fields, and any other fields, if present. Other fields will be ignored by the
30parser currently.
31
32For example, from COVERAGE.timers:
33clock_gettime	NO*	MED
34
35Only the first letter of the complete? field will be read, and should be either
36N or Y. (So you are free to have asterisks as Julie has done.)
37
38She has a priority field after that HIGH/MED/LOW which is currently not used by
39the parser.
40
41Information Fields
42------------------
43Additional information should be provided with this format:
44Field-Name: Value-Data
45
46The field "Coverage-Area" MUST be provided with a description of this area of
47the POSIX spec such as "Clocks & Timers (TMR)".
48
49The field "Area-Code" MUST be provided, a unique code with no spaces to use
50internally within the web page to link to the stats about this coverage area,
51such as "tmr" or "sig".
52
53The field "Maintainer" SHOULD be provided with the name of the active
54maintainer of this area.
55
56The field "Contributor" MAY be provided (one or more times) with a name of
57someone who contributed to the tests in this area (other than the active
58maintainer).
59
60Comment Lines
61-------------
62Any line that is not of the type defined above must be denoted as a comment
63line. There are three types of comment lines that will be ignored:
64
65- Any blank line or line with whitespace only
66- Any line beginning with //
67- Any lines between an opening line of /* and a closing line of */ (inclusive)
68
69For example, only the clock_gettime line would be parsed below:
70
71// SAMPLE FILE: First Line
72
73// The line above is whitespace only, and the line below is blank
74
75/*
76This section is for longer
77comments.
78*/
79clock_gettime	NO*	MED
80
81// SAMPLE FILE: Last Line
82
83Other Tests: Definitions, Functional, Stress, etc.
84--------------------------------------------------
85These tests are not currently handled by the parser tool, and thus should be
86included in comment fields if the information is present.
87
88Future Extensions
89-----------------
90If other fields become required later, they will be moved to the front of the
91text lines, so that optional fields can still appear after them.
92
93Contributors:	geoffrey.r.gustafson REMOVE-THIS AT intel DOT com
94