fcadc50ff673dabbe94d58abfb6eae21cb824608
[ghc.git] / testsuite / utils / check-api-annotations / README
1 This programme is intended to be used by any GHC developers working on Parser.y
2 or RdrHsSyn.hs, and who want to check that their changes do not break the API
3 Annotations.
4
5 It does a basic test that all annotations do make it to the final AST, and dumps
6 a list of the annotations generated for a given file, so that they can be
7 checked against the source being parsed for sanity.
8
9 This utility is also intended to be used in tests, so that when new features are
10 added the expected annotations are also captured.
11
12 Usage
13
14 In a test Makefile
15
16   $(CHECK_API_ANNOTATIONS) "`'$(TEST_HC)' $(TEST_HC_OPTS) --print-libdir | tr -d '\r'`" FileToParse.hs
17
18 See examples in (REPO_HOME)/testsuite/tests/ghc-api/annotations/Makefile
19
20
21 Description of operation
22 ------------------------
23
24 The programme is called with the name of a haskell source file.
25
26 It uses the GHC API to load and parse this, and extracts the API annotations.
27
28 These are of the form
29
30     Map.Map ApiAnnKey [SrcSpan]
31
32 where
33
34     type ApiAnnKey = (SrcSpan,AnnKeywordId)
35
36 So an annotation is a key comprising the parent SrcSpan in the ParsedSource
37 together with an AnnKeywordId, and this maps to a list of locations where the
38 specific keyword item occurs in the original source.
39
40 The utility extracts all SrcSpans in the ParsedSource, and makes sure that for
41 every ApiAnnKey the SrcSpan is actually present in the final ParsedSource. This
42 is to ensure that when a given parser production is postprocessed anywhere along
43 the line the relevant SrcSpan is not discarded, thus detaching the annotation
44 from the final output.
45
46 It also provides a list of each ApiAnnKey and the corresponding source
47 locations, so these can be checked against the original source for correctness.
48
49 Example
50 -------
51
52 Test10255.hs in the ghc-api/annotations tests has the following source
53
54 ------------------------------
55 1:{-# LANGUAGE ScopedTypeVariables #-}
56 2:module Test10255 where
57 3:
58 4:import Data.Maybe
59 5:
60 6:fob (f :: (Maybe t -> Int)) =
61 7:  undefined
62 ------------------------------
63
64 The output of this utility is
65
66 ------------------------------------------------------------------------
67 ---Problems (should be empty list)---
68 []
69 ---Annotations-----------------------
70 -- SrcSpan the annotation is attached to, AnnKeywordId,
71 --    list of locations the keyword item appears in
72 [
73 ((Test10255.hs:1:1,AnnModule), [Test10255.hs:2:1-6]),
74 ((Test10255.hs:1:1,AnnWhere), [Test10255.hs:2:18-22]),
75 ((Test10255.hs:4:1-17,AnnImport), [Test10255.hs:4:1-6]),
76 ((Test10255.hs:4:1-17,AnnSemi), [Test10255.hs:6:1]),
77 ((Test10255.hs:(6,1)-(7,11),AnnEqual), [Test10255.hs:6:29]),
78 ((Test10255.hs:(6,1)-(7,11),AnnFunId), [Test10255.hs:6:1-3]),
79 ((Test10255.hs:(6,1)-(7,11),AnnSemi), [Test10255.hs:8:1]),
80 ((Test10255.hs:6:5-27,AnnCloseP), [Test10255.hs:6:27]),
81 ((Test10255.hs:6:5-27,AnnOpenP), [Test10255.hs:6:5]),
82 ((Test10255.hs:6:6-26,AnnDcolon), [Test10255.hs:6:8-9]),
83 ((Test10255.hs:6:11-26,AnnCloseP), [Test10255.hs:6:26]),
84 ((Test10255.hs:6:11-26,AnnOpenP), [Test10255.hs:6:11]),
85 ((Test10255.hs:6:12-18,AnnRarrow), [Test10255.hs:6:20-21]),
86 ((Test10255.hs:6:12-25,AnnRarrow), [Test10255.hs:6:20-21]),
87 ((<no location info>,AnnEofPos), [Test10255.hs:8:1])
88 ]
89 ------------------------------------------------------------------------
90
91 To interpret this, firstly the problems list is empty, so there are not
92 annotations that do not appear in the final AST.
93
94 Secondly, the list of annotations and locations can be checked against the test
95 source code to ensure that every AnnKeywordId does in fact appear.
96
97 It will return a zero exit code if the list of problems is empty, non-zero
98 otherwise.
99
100 Note: In some cases, such as T10269 in the ghc-api/annotations tests the list is
101 non-empty, due to postprocessing of the parsed result. In general this should
102 only happen for an `AnnVal` and if it does the actual annotations provided need
103 to be inspected to check that an equivalent annotation is provided.