-
Notifications
You must be signed in to change notification settings - Fork 3k
/
cover.erl
3111 lines (2705 loc) · 101 KB
/
cover.erl
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
%%
%% %CopyrightBegin%
%%
%% Copyright Ericsson AB 2001-2024. All Rights Reserved.
%%
%% Licensed under the Apache License, Version 2.0 (the "License");
%% you may not use this file except in compliance with the License.
%% You may obtain a copy of the License at
%%
%% http://www.apache.org/licenses/LICENSE-2.0
%%
%% Unless required by applicable law or agreed to in writing, software
%% distributed under the License is distributed on an "AS IS" BASIS,
%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
%% See the License for the specific language governing permissions and
%% limitations under the License.
%%
%% %CopyrightEnd%
%%
-module(cover).
-moduledoc """
A Coverage Analysis Tool for Erlang
The module `cover` provides a set of functions for coverage analysis
of Erlang programs, counting how many times each _executable line_ of
code is executed when a program is run. Executable lines are
lines in the body of a clause in a function, `case`,
`receive`, or `try`. Lines in clause heads, blank lines, and lines
containing only comments are not executable.
Coverage analysis can be used to verify that test cases covers all
relevant line in the code being test. It can also be helpful when
looking for bottlenecks in the code.
Before any analysis can take place, the involved modules has to be
_cover-compiled_. This means that some extra information is added to
the module before it is compiled into a binary which then is
loaded. The source file of the module is not affected and no `.beam`
file is created. If the runtime system supports coverage natively,
Cover will automatically use that functionality to lower the execution
overhead for cover-compiled code.
> #### Change {: .info }
>
> Native coverage support was added in Erlang/OTP 27.
Each time a function in a cover-compiled module is called, information about the
call is added to an internal database of Cover. The coverage analysis is
performed by examining the contents of the Cover database. The output `Answer`
is determined by two parameters: `Level` and `Analysis`.
- `Level = module`
`Answer = {Module,Value}`, where `Module` is the module name.
- `Level = function`
`Answer = [{Function,Value}]`, one tuple for each function in the module. A
function is specified by its module name `M`, function name `F` and arity `A`
as a tuple `{M,F,A}`.
- `Level = clause`
`Answer = [{Clause,Value}]`, one tuple for each clause in the module. A clause
is specified by its module name `M`, function name `F`, arity `A` and position
in the function definition `C` as a tuple `{M,F,A,C}`.
- `Level = line`
`Answer = [{Line,Value}]`, one tuple for each executable line in the module. A
line is specified by its module name `M` and line number in the source file
`N` as a tuple `{M,N}`.
- `Analysis = coverage`
`Value = {Cov,NotCov}` where `Cov` is the number of executable lines in the
module, function, clause or line that have been executed at least once and
`NotCov` is the number of executable lines that have not been executed.
- `Analysis = calls`
`Value = Calls` which is the number of times the module, function, or clause
has been called. In the case of line level analysis, `Calls` is the number of
times the line has been executed.
### Distribution
Cover can be used in a distributed Erlang system. One of the nodes in the system
has to be selected as the _main node_, and all Cover commands must be
executed from that node. The error reason `not_main_node` is returned if an
interface function is called on one of the remote nodes.
Use `cover:start/1` and `cover:stop/1` to add or remove nodes. The
same cover-compiled code will be loaded on each node, and analysis
will collect and sum up coverage data results from all nodes.
To only collect data from remote nodes without stopping `cover` on those nodes,
use `cover:flush/1`
If the connection to a remote node goes down, the main node will mark it as
lost. If the node comes back it will be added again. If the remote node was
alive during the disconnected period, cover data from before and during this
period will be included in the analysis.
""".
%%
%% This module implements the Erlang coverage tool.
%%
%% ARCHITECTURE
%%
%% The coverage tool consists of one process on each node involved in
%% coverage analysis. The process is registered as 'cover_server'
%% (?SERVER). The cover_server on the 'main' node is in charge, and
%% it monitors the cover_servers on all remote nodes. When it gets a
%% 'DOWN' message for another cover_server, it marks the node as
%% 'lost'. If a nodeup is received for a lost node the main node
%% ensures that the cover compiled modules are loaded again. If the
%% remote node was alive during the disconnected period, cover data
%% for this period will also be included in the analysis.
%%
%% The cover_server process on the main node is implemented by the
%% functions init_main/1 and main_process_loop/1. The cover_server on
%% the remote nodes are implemented by the functions init_remote/2 and
%% remote_process_loop/1.
%%
%% COUNTERS
%%
%% The 'counters' modules is used for counting how many time each line
%% executed. Each cover-compiled module will have its own array of
%% counters.
%%
%% The counter reference for module Module is stored in a persistent
%% term with the key {cover,Module}.
%%
%% When the cover:local_only/0 function has been called, the reference
%% for the counter array will be compiled into each cover-compiled
%% module directly (instead of retrieving it from a persistent term).
%% That will be faster, but the resulting code can be only be used on
%% the main node.
%%
%% TABLES
%%
%% Each node has one table: ?COVER_MAPPING_TABLE.
%%
%% ?COVER_MAPPING_TABLE maps from a #bump{} record to an index in the
%% counter array for the module. It is used both during instrumentation
%% of cover-compiled modules and when collecting the counter values.
%%
%% The main node owns the table ?COLLECTION_TABLE. The counter data
%% is consolidated into this table from the counters on both the main
%% node and from remote nodes. This consolidation is done when a
%% remote node is stopped with cover:stop/1 or just before starting an
%% analysis.
%%
%% The main node also has a table named ?BINARY_TABLE. This table
%% contains the abstract code code for each cover-compiled
%% module. This is necessary so that the code can be loaded on remote
%% nodes that are started after the compilation.
%%
%% PARALLELISM
%%
%% To take advantage of SMP when doing the cover analysis both the data
%% collection and analysis has been parallelized. One process is spawned for
%% each node when collecting data, and on the remote node when collecting data
%% one process is spawned per module.
%%
%% When analyzing data it is possible to issue multiple
%% analyse(_to_file)/X calls at once. They are, however, all calls
%% (for backwards compatibility reasons), so the user of cover will
%% have to spawn several processes to to the calls (or use
%% async_analyse_to_file/X).
%%
%% External exports
-export([start/0, start/1,
compile/1, compile/2, compile_module/1, compile_module/2,
compile_directory/0, compile_directory/1, compile_directory/2,
compile_beam/1, compile_beam_directory/0, compile_beam_directory/1,
analyse/0, analyse/1, analyse/2, analyse/3,
analyze/0, analyze/1, analyze/2, analyze/3,
analyse_to_file/0,
analyse_to_file/1, analyse_to_file/2, analyse_to_file/3,
analyze_to_file/0,
analyze_to_file/1, analyze_to_file/2, analyze_to_file/3,
async_analyse_to_file/1,async_analyse_to_file/2,
async_analyse_to_file/3, async_analyze_to_file/1,
async_analyze_to_file/2, async_analyze_to_file/3,
export/1, export/2, import/1,
modules/0, imported/0, imported_modules/0, which_nodes/0, is_compiled/1,
reset/1, reset/0,
flush/1,
stop/0, stop/1,
local_only/0]).
-export([remote_start/1,get_main_node/0]).
%% Used internally to ensure we upgrade the code to the latest version.
-export([main_process_loop/1,remote_process_loop/1]).
-record(main_state, {compiled=[], % [{Module,File}]
imported=[], % [{Module,File,ImportFile}]
stopper, % undefined | pid()
local_only=false, % true | false
nodes=[], % [Node]
lost_nodes=[]}). % [Node]
-record(remote_data, {module,
file,
code,
mapping,
clauses}).
-record(remote_state, {compiled=[], % [{Module,File}]
main_node}). % atom()
-record(bump, {module = '_', % atom()
function = '_', % atom()
arity = '_', % integer()
clause = '_', % integer()
line = '_' % integer()
}).
-define(BUMP_REC_NAME,bump).
-define(CHUNK_SIZE, 20000).
-define(COVER_MAPPING_TABLE, 'cover_internal_mapping_table').
-define(BINARY_TABLE, 'cover_binary_code_table').
-define(COLLECTION_TABLE, 'cover_collected_remote_data_table').
-define(TAG, cover_compiled).
-define(SERVER, cover_server).
-define(SPAWN_DBG(Tag,Value),put(Tag,Value)).
-define(STYLESHEET, "styles.css").
-define(TOOLS_APP, tools).
-include_lib("stdlib/include/ms_transform.hrl").
%%%----------------------------------------------------------------------
%%% External exports
%%%----------------------------------------------------------------------
-doc """
Starts the Cover server which owns the Cover internal database. This function is
called automatically by the other functions in the module.
""".
-spec start() -> {'ok', pid()} | {'error', Reason} when
Reason :: {'already_started', pid()}
| term().
start() ->
case whereis(?SERVER) of
undefined ->
Starter = self(),
Pid = spawn(fun() ->
?SPAWN_DBG(start,[]),
init_main(Starter)
end),
Ref = erlang:monitor(process,Pid),
Return =
receive
{?SERVER,started} ->
{ok,Pid};
{?SERVER,{error,Error}} ->
{error,Error};
{'DOWN', Ref, _Type, _Object, Info} ->
{error,Info}
end,
erlang:demonitor(Ref),
Return;
Pid ->
{error,{already_started,Pid}}
end.
-doc """
Starts a Cover server on the each of given nodes, and loads all cover compiled
modules.
This call will fail if `cover:local_only/0` has been called.
""".
-spec start(Nodes) -> {'ok', StartedNodes}
| {'error', 'not_main_node'}
| {'error', 'local_only'} when
Nodes :: node() | [node()],
StartedNodes :: [node()].
start(Node) when is_atom(Node) ->
start([Node]);
start(Nodes) ->
call({start_nodes,remove_myself(Nodes,[])}).
-doc """
Only support running Cover on the local node.
This function has to be called before any modules have been compiled or
any nodes added. When running in this mode, modules will be
cover-compiled in a more efficient way, but the resulting code will
only work on the same node they were compiled on.
""".
-doc(#{since => <<"OTP 22.0">>}).
-spec local_only() -> 'ok' | {'error', 'too_late'}.
local_only() ->
call(local_only).
-type compile_result() :: {'ok', Module :: module()}
| {'error', file:filename()}
| {'error', 'not_main_node'}.
-type mod_file() :: (Module :: module()) | (File :: file:filename()).
-type mod_files() :: mod_file() | [mod_file()].
-type option() :: {'i', Dir :: file:filename()}
| {'d', Macro :: atom()}
| {'d', Macro :: atom(), Value :: term()}
| 'export_all'.
-doc #{equiv => compile_module(ModFiles, [])}.
-spec compile(ModFiles) -> Result | [Result] when
ModFiles :: mod_files(),
Result :: compile_result().
compile(ModFile) ->
compile_module(ModFile, []).
-doc #{equiv => compile_module(ModFile, Options)}.
-spec compile(ModFiles, Options) -> Result | [Result] when
ModFiles :: mod_files(),
Options :: [option()],
Result :: compile_result().
compile(ModFile, Options) ->
compile_module(ModFile, Options).
-doc(#{equiv => compile_module(ModFile, [])}).
-spec compile_module(ModFiles) -> Result | [Result] when
ModFiles :: mod_files(),
Result :: compile_result().
compile_module(ModFile) when is_atom(ModFile);
is_list(ModFile) ->
compile_module(ModFile, []).
-doc """
Cover-compiles one or more modules.
The module is given by its module name `Module` or by its file name
`File`.
The `.erl` extension can be omitted. If the module is not located in
the current directory, the full path to it must be specified.
`Options` is a list of compiler options. Only options defining include
file directories and macros are passed to `compile:file/2`;
everything else is ignored.
If the module is successfully cover-compiled, the function returns
`{ok, Module}`. Otherwise the function returns `{error, File}`. Errors and
warnings are printed as they occur.
If a list of `ModFiles` is given as input, a list of [`Result`](`t:compile_result/0`)
will be returned. The order of the returned results in the list is undefined.
Note that the internal database is initialized during the compilation,
which means that any previously collected coverage data for the module
is lost.
""".
-spec compile_module(ModFiles, Options) -> Result | [Result] when
ModFiles :: mod_files(),
Options :: [option()],
Result :: compile_result().
compile_module(ModFile, Options) when is_atom(ModFile);
is_list(ModFile), is_integer(hd(ModFile)) ->
[R] = compile_module([ModFile], Options),
R;
compile_module(ModFiles, Options) when is_list(Options) ->
AbsFiles =
[begin
File =
case ModFile of
_ when is_atom(ModFile) -> atom_to_list(ModFile);
_ when is_list(ModFile) -> ModFile
end,
WithExt = case filename:extension(File) of
".erl" ->
File;
_ ->
File++".erl"
end,
filename:absname(WithExt)
end || ModFile <- ModFiles],
compile_modules(AbsFiles, Options).
-type file_error() :: 'eacces' | 'enoent'.
-doc #{equiv => compile_directory(".", [])}.
-spec compile_directory() -> [Result] | {'error', Reason} when
Reason :: file_error(),
Result :: compile_result().
compile_directory() ->
case file:get_cwd() of
{ok, Dir} ->
compile_directory(Dir, []);
Error ->
Error
end.
-doc #{equiv => compile_directory(Dir, [])}.
-spec compile_directory(Dir) -> [Result] | {'error', Reason} when
Dir :: file:filename(),
Reason :: file_error(),
Result :: compile_result().
compile_directory(Dir) when is_list(Dir) ->
compile_directory(Dir, []).
-doc """
Compiles all modules (`.erl` files) in a directory `Dir` for Cover analysis the
same way as [`compile_module/1,2`](`compile_module/1`) and returns a list of
[`Result`](`t:compile_result/0`).
This function returns `{error, eacces}` if the directory is not readable or
`{error, enoent}` if the directory does not exist.
""".
-spec compile_directory(Dir, Options) -> [Result] | {'error', Reason} when
Dir :: file:filename(),
Options :: [option()],
Reason :: file_error(),
Result :: compile_result().
compile_directory(Dir, Options) when is_list(Dir), is_list(Options) ->
case file:list_dir(Dir) of
{ok, Files} ->
ErlFiles = [filename:join(Dir, File) ||
File <- Files,
filename:extension(File) =:= ".erl"],
compile_modules(ErlFiles, Options);
Error ->
Error
end.
compile_modules(Files,Options) ->
Options2 = filter_options(Options),
call({compile, Files, Options2}).
filter_options(Options) ->
lists:filter(fun(Option) ->
case Option of
{i, Dir} when is_list(Dir) -> true;
{d, _Macro} -> true;
{d, _Macro, _Value} -> true;
export_all -> true;
tuple_calls -> true;
{feature,_,enable} -> true; %FIXME: To be removed.
{feature,_,disable} -> true; %FIXME: To be removed.
_ -> false
end
end,
Options).
-type beam_mod_file() :: (Module :: module()) | (BeamFile :: file:filename()).
-type beam_mod_files() :: beam_mod_file() | [beam_mod_file()].
-type compile_beam_rsn() ::
'non_existing'
| {'no_abstract_code', BeamFile :: file:filename()}
| {'encrypted_abstract_code', BeamFile :: file:filename()}
| {'already_cover_compiled', 'no_beam_found', module()}
| {{'missing_backend', module()}, BeamFile :: file:filename()}
| {'no_file_attribute', BeamFile :: file:filename()}
| 'not_main_node'.
-type compile_beam_result() :: {'ok', module()}
| {'error', BeamFile :: file:filename()}
| {'error', Reason :: compile_beam_rsn()}.
-doc """
Cover-compiles one or more modules based `.beam` files containing
abstract code (option `debug_info`).
Cover-compiling from `.beam` files is faster than compiling from
source and less hassle, because there is no need to supply options for
include paths or macros. However, the existing `.beam` files must have
been compiled with option
[`debug_info`](`e:compiler:compile.md#debug_info`) so that they contain
[*abstract code*](`e:erts:absform`).
If abstract code is missing, the error reason `{no_abstract_code,
BeamFile}` is returned. If the abstract code is encrypted, and no key
is available for decrypting it, the error reason
`{encrypted_abstract_code, BeamFile}` is returned.
If only the module name (that is, not the full name of the `.beam`
file) is given to this function, the `.beam` file is found by calling
[`code:which(Module)`](`code:which/1`). If no `.beam` file is found,
the error reason `non_existing` is returned. If the module is already
cover compiled with [`compile_beam/1`](`compile_beam/1`), the `.beam`
file will be picked from the same location as the first time it was
compiled. If the module is already cover-compiled with
`compile_module/2`, there is no way to find the correct `.beam` file,
so the error reason `{already_cover_compiled, no_beam_found, Module}`
is returned.
`{error, BeamFile}` is returned if the compiled code cannot be loaded on the
node.
If a list of `ModFiles` is given as input, a list of `Result` will be returned.
The order of the returned list is undefined.
""".
-spec compile_beam(ModFiles) -> Result | [Result] when
ModFiles :: beam_mod_files(),
Result :: compile_beam_result().
compile_beam(ModFile0) when is_atom(ModFile0);
is_list(ModFile0), is_integer(hd(ModFile0)) ->
case compile_beams([ModFile0]) of
[{error,{non_existing,_}}] ->
%% Backwards compatibility
{error,non_existing};
[Result] ->
Result
end;
compile_beam(ModFiles) when is_list(ModFiles) ->
compile_beams(ModFiles).
-doc(#{equiv => compile_beam_directory(".")}).
-spec compile_beam_directory() -> [Result] | {'error', Reason} when
Reason :: file_error(),
Result :: compile_beam_result().
compile_beam_directory() ->
case file:get_cwd() of
{ok, Dir} ->
compile_beam_directory(Dir);
Error ->
Error
end.
-doc """
Cover-compiles all `.beam` files in directory `Dir` in the same way
as `compile_beam/1`.
This function returns a list of [`compile_beam_result()`](`t:compile_beam_result/0`)
if successful. Otherwise, it returns `{error, eacces}` if the directory is not
readable, and `{error, enoent}` if the directory does not exist.
""".
-spec compile_beam_directory(Dir) ->
[Result] | {'error', Reason} when
Dir :: file:filename(),
Reason :: file_error(),
Result :: compile_beam_result().
compile_beam_directory(Dir) when is_list(Dir) ->
case file:list_dir(Dir) of
{ok, Files} ->
BeamFiles = [filename:join(Dir, File) ||
File <- Files,
filename:extension(File) =:= ".beam"],
compile_beams(BeamFiles);
Error ->
Error
end.
compile_beams(ModFiles0) ->
ModFiles = get_mods_and_beams(ModFiles0,[]),
call({compile_beams,ModFiles}).
get_mods_and_beams([Module|ModFiles],Acc) when is_atom(Module) ->
case code:which(Module) of
non_existing ->
get_mods_and_beams(ModFiles,[{error,{non_existing,Module}}|Acc]);
File ->
get_mods_and_beams([{Module,File}|ModFiles],Acc)
end;
get_mods_and_beams([File|ModFiles],Acc) when is_list(File) ->
{WithExt,WithoutExt}
= case filename:rootname(File,".beam") of
File ->
{File++".beam",File};
Rootname ->
{File,Rootname}
end,
AbsFile = filename:absname(WithExt),
Module = list_to_atom(filename:basename(WithoutExt)),
get_mods_and_beams([{Module,AbsFile}|ModFiles],Acc);
get_mods_and_beams([{Module,File}|ModFiles],Acc) ->
%% Check for duplicates
case lists:keyfind(Module,2,Acc) of
{ok,Module,File} ->
%% Duplicate, but same file so ignore
get_mods_and_beams(ModFiles,Acc);
{ok,Module,_OtherFile} ->
%% Duplicate and different file - error
get_mods_and_beams(ModFiles,[{error,{duplicate,Module}}|Acc]);
_ ->
get_mods_and_beams(ModFiles,[{ok,Module,File}|Acc])
end;
get_mods_and_beams([],Acc) ->
lists:reverse(Acc).
-type analyse_item() ::
(Line :: {M :: module(), N :: non_neg_integer()})
| (Clause :: {M :: module(), F :: atom(), A :: arity(),
C :: non_neg_integer()})
| (Function :: {M :: module(), F :: atom(), A :: arity()}). % mfa()
-type analyse_value() :: {Cov :: non_neg_integer(), NotCov :: non_neg_integer()}
| Calls :: non_neg_integer().
-type analyse_ok() :: [{Module :: module(), Value :: analyse_value()}]
| [{Item :: analyse_item(), Value :: analyse_value()}].
-type analyse_fail() :: [{'not_cover_compiled', module()}].
-type analysis() :: 'coverage' | 'calls'.
-type level() :: 'line' | 'clause' | 'function' | 'module'.
-type modules() :: module() | [module()].
-type one_result() ::
{'ok', {Module :: module(), Value :: analyse_value()}}
| {'ok', [{Item :: analyse_item(), Value :: analyse_value()}]}
| {'error', {'not_cover_compiled', module()}}.
-define(is_analysis(__A__),
(__A__=:=coverage orelse __A__=:=calls)).
-define(is_level(__L__),
(__L__=:=line orelse __L__=:=clause orelse
__L__=:=function orelse __L__=:=module)).
-doc #{equiv => analyse('_', coverage, function),
since => <<"OTP 18.0">>}.
-spec analyse() -> {'result', analyse_ok(), analyse_fail()} |
{'error', 'not_main_node'}.
analyse() ->
analyse('_').
-dialyzer({no_contracts, analyse/1}).
-doc """
analyse(Arg)
Analyzes one or more modules as specified by `Arg`.
If `Arg` is one of the values in [`analysis()`](`t:analysis/0`), this
call is equivalent to [`analyse('_', Arg, function)`](`analyse/3`).
If `Arg` is one of the values in [`level()`](`t:level/0`), this
call is equivalent to [`analyse('_', coverage, Arg)`](`analyse/3`).
Otherwise `Arg` is assumed to be a module name, and this call is equivalent
to [`analyse(Arg, coverage, function)`](`analyse/3`).
> #### Note {: .info }
>
> To analyze a module whose name overlaps with one the values in
> [`analysis()`](`t:analysis/0`) or [`level()`](`t:level/0`), the module
> name has to be in a list. For example, to analyze a module named `calls`:
>
> ```
> cover:analyse([calls]).
> ```
""".
-spec analyse(Analysis) -> {'result', analyse_ok(), analyse_fail()} |
{'error', 'not_main_node'} when
Analysis :: analysis();
(Level) -> {'result', analyse_ok(), analyse_fail()} |
{'error', 'not_main_node'} when
Level :: level();
(Modules) -> OneResult |
{'result', analyse_ok(), analyse_fail()} |
{'error', 'not_main_node'} when
Modules :: modules(),
OneResult :: one_result().
analyse(Analysis) when ?is_analysis(Analysis) ->
analyse('_', Analysis);
analyse(Level) when ?is_level(Level) ->
analyse('_', Level);
analyse(Module) ->
analyse(Module, coverage).
-dialyzer({no_contracts,analyse/2}).
-doc """
analyse(Arg1, Arg2)
Analyzes one or more modules as specified by `Arg1` and `Arg2`.
If `Arg1` is one of the values in [`analysis()`](`t:analysis/0`) and
`Arg2` is one of the values in [`level()`](`t:level/0`), this
call is equivalent to [`analyse('_', Arg1, Arg2)`](`analyse/3`).
If `Arg2` is one of the values in [`analysis()`](`t:analysis/0`),
`Arg1` is assumed to be a module and this call is equivalent to
[`analyse(Arg1, Arg2, function)`](`analyse/3`).
If `Arg2` is one of the values in [`level()`](`t:level/0`), `Arg1` is
assumed to be a module and this call is equivalent to [`analyse(Arg1,
coverage, Arg2)`](`analyse/3`).
> #### Note {: .info }
>
> To analyze a module whose name overlaps with one of the values in
> [`analysis()`](`t:analysis/0`), the module name needs to be in a
> list. For example, to analyze a module named `calls`:
>
> ```
> cover:analyse([calls], function).
> ```
""".
-spec analyse(Analysis, Level) -> {'result', analyse_ok(), analyse_fail()} |
{'error', 'not_main_node'} when
Analysis :: analysis(),
Level :: level();
(Modules, Analysis) -> OneResult |
{'result', analyse_ok(), analyse_fail()} |
{'error', 'not_main_node'} when
Analysis :: analysis(),
Modules :: modules(),
OneResult :: one_result();
(Modules, Level) -> OneResult |
{'result', analyse_ok(), analyse_fail()} |
{'error', 'not_main_node'} when
Level :: level(),
Modules :: modules(),
OneResult :: one_result().
analyse(Analysis, Level) when ?is_analysis(Analysis), ?is_level(Level) ->
analyse('_', Analysis, Level);
analyse(Module, Analysis) when ?is_analysis(Analysis) ->
analyse(Module, Analysis, function);
analyse(Module, Level) when ?is_level(Level) ->
analyse(Module, coverage, Level).
-doc """
Perform analysis of one or more cover-compiled modules, as specified by
`Analysis` and `Level`, by examining the contents of the internal
database.
If `Modules` is an atom (a single module), the return is `OneResult`,
otherwise the return is `{result, Ok, Fail}`.
If `Modules` is atom `'_'`, all modules that have data in the cover data table
are analysed. Note that this includes both cover-compiled modules and imported
modules.
If a given module is not cover-compiled, this is indicated by the error reason
`{not_cover_compiled, Module}`.
""".
-spec analyse(Modules, Analysis, Level) ->
OneResult |
{'result', analyse_ok(), analyse_fail()} |
{'error', 'not_main_node'} when
Analysis :: analysis(),
Level :: level(),
Modules :: modules(),
OneResult :: one_result().
analyse(Module, Analysis, Level) when ?is_analysis(Analysis),
?is_level(Level) ->
call({{analyse, Analysis, Level}, Module}).
-doc false.
analyze() -> analyse( ).
-doc false.
analyze(Module) -> analyse(Module).
-doc false.
analyze(Module, Analysis) -> analyse(Module, Analysis).
-doc false.
analyze(Module, Analysis, Level) -> analyse(Module, Analysis, Level).
%% Kept for backwards compatibility:
%% analyse_to_file(Modules, OutFile) ->
%% analyse_to_file(Modules, OutFile, Options) -> {ok,OutFile} | {error,Error}
-doc(#{equiv => analyse_to_file('_', []),
since => <<"OTP 18.0">>}).
-spec analyse_to_file() -> {'result', analyse_file_ok(), analyse_file_fail()} |
{'error', 'not_main_node'}.
analyse_to_file() ->
analyse_to_file('_').
-type analyse_option() :: 'html'
| {'outfile', OutFile :: file:filename()}
| {'outdir', OutDir :: file:filename()}.
-type analyse_answer() :: {'ok', OutFile :: file:filename()} |
{'error', analyse_rsn()}.
-type analyse_file_ok() :: [OutFile :: file:filename()].
-type analyse_file_fail() :: [analyse_rsn()].
-type analyse_rsn() :: {'not_cover_compiled', Module :: module()} |
{'file', File :: file:filename(), Reason :: term()} |
{'no_source_code_found', Module :: module()}.
-dialyzer({no_contracts, analyse_to_file/1}).
%% The option list [html] overlaps with module list [html].
-doc """
If `Arg` is a list of [`analyse_option()`](`t:analyse_option/0`)
options, this call is equivalent to [`analyse_to_file('_',
Arg)`](`analyse_to_file/2`).
Otherwise `Arg` is assumed to be a module, and this call is equivalent to
[`analyse_to_file(Arg, [])`](`analyse_to_file/2`).
> #### Note {: .info }
>
> To analyze a module of the name `html` (which overlaps with an option
> in [`analyse_option()`](`t:analyse_option/0`)), it is necessary to
> use `cover:analyse_to_file/2`:
>
> ```
> cover:analyse_to_file([html], []).
> ```
""".
-spec analyse_to_file(Modules) -> Answer |
{'result',
analyse_file_ok(), analyse_file_fail()} |
{'error', 'not_main_node'} when
Modules :: modules(),
Answer :: analyse_answer();
(Options) -> {'result',
analyse_file_ok(), analyse_file_fail()} |
{'error', 'not_main_node'} when
Options :: [analyse_option()].
analyse_to_file(Arg) ->
case is_options(Arg) of
true ->
analyse_to_file('_', Arg);
false ->
analyse_to_file(Arg, [])
end.
-doc """
Outputs copies of the source code for the given modules annotated with
execution counts for each executable line.
The output file `OutFile` defaults to `Module.COVER.out`, and to `Module.COVER.html`
if option `html` is used.
If `Modules` is an atom (one module), the return will be `Answer`, otherwise the
return will be a list, `{result, Ok, Fail}`.
If `Modules` is '_', all modules that have data in the Cover data table
are analysed. Note that this includes both cover-compiled modules and imported
modules.
If a module is not cover-compiled, this is indicated by the error reason
`{not_cover_compiled, Module}`.
If the source file and/or the output file cannot be opened using `file:open/2`,
the function returns `{error, {file, File, Reason}}`, where `File` is the file
name and `Reason` is the error reason.
If a module was cover compiled from the `.beam` file, that is, using
`compile_beam/1` or
[`compile_beam_directory/0,1` ](`compile_beam_directory/0`), it is assumed that
the source code can be found in one of the following locations:
- the same directory as the `.beam` file
- `../src` relative to the directory with `.beam` file
- the source path in `Module:module_info(compile)`, in which case two paths
are examined:
* first the one constructed by joining `../src` and the tail of the compiled path
below a trailing `src` component
* the compiled path itself
If no source code is found, this is indicated by the error reason
`{no_source_code_found, Module}`.
""".
-spec analyse_to_file(Modules, Options) ->
Answer |
{'result',
analyse_file_ok(), analyse_file_fail()} |
{'error', 'not_main_node'} when
Modules :: modules(),
Options :: [analyse_option()],
Answer :: analyse_answer().
analyse_to_file(Module, OutFile) when is_list(OutFile), is_integer(hd(OutFile)) ->
%% Kept for backwards compatibility
analyse_to_file(Module, [{outfile,OutFile}]);
analyse_to_file(Module, Options) when is_list(Options) ->
call({{analyse_to_file, Options}, Module}).
-doc false.
analyse_to_file(Module, OutFile, Options) when is_list(OutFile) ->
%% Kept for backwards compatibility
analyse_to_file(Module,[{outfile,OutFile}|Options]).
-doc false.
analyze_to_file() -> analyse_to_file().
-doc false.
analyze_to_file(Module) -> analyse_to_file(Module).
-doc false.
analyze_to_file(Module, OptOrOut) -> analyse_to_file(Module, OptOrOut).
-doc false.
analyze_to_file(Module, OutFile, Options) ->
analyse_to_file(Module, OutFile, Options).
-doc(#{equiv => async_analyse_to_file/3}).
-doc(#{since => <<"OTP R14B02">>}).
-spec async_analyse_to_file(Module) -> pid() when
Module :: module().
async_analyse_to_file(Module) ->
do_spawn(?MODULE, analyse_to_file, [Module]).
-dialyzer({no_contracts, async_analyse_to_file/2}).
%% The types file:filename() (string()) and ['html'] has something in
%% common, namely [].
-doc(#{equiv => async_analyse_to_file/3}).
-doc(#{since => <<"OTP R14B02">>}).
-spec async_analyse_to_file(Module, OutFile) -> pid() when
Module :: module(),
OutFile :: file:filename();
(Module, Options) -> pid() when
Module :: module(),
Options :: [Option],
Option :: 'html'.
async_analyse_to_file(Module, OutFileOrOpts) ->
do_spawn(?MODULE, analyse_to_file, [Module, OutFileOrOpts]).
-doc """
This function works the same way as
[`analyse_to_file/2`](`analyse_to_file/2`) except that it is asynchronous instead
of synchronous.
The spawned process will link with the caller when created. If an
error of type [`analyse_rsn()`](`t:analyse_rsn/0`) occurs while doing
the cover analysis the process will crash with the same error reason
as [`analyse_to_file`](`analyse_to_file/1`) would return.
""".
-doc(#{since => <<"OTP R14B02">>}).
-spec async_analyse_to_file(Module, OutFile, Options) -> pid() when
Module :: module(),
OutFile :: file:filename(),
Options :: [Option],
Option :: 'html'.
async_analyse_to_file(Module, OutFile, Options) ->
do_spawn(?MODULE, analyse_to_file, [Module, OutFile, Options]).
is_options([html]) ->
true; % this is not 100% safe - could be a module named html...
is_options([html|Opts]) ->
is_options(Opts);
is_options([{Opt,_}|_]) when Opt==outfile; Opt==outdir ->
true;
is_options(_) ->
false.
do_spawn(M,F,A) ->
spawn_link(fun() ->
case apply(M,F,A) of
{ok, _} ->
ok;
{error, Reason} ->
exit(Reason)
end
end).
-doc false.
async_analyze_to_file(Module) ->
async_analyse_to_file(Module).
-doc false.
async_analyze_to_file(Module, OutFileOrOpts) ->
async_analyse_to_file(Module, OutFileOrOpts).
-doc false.
async_analyze_to_file(Module, OutFile, Options) ->
async_analyse_to_file(Module, OutFile, Options).
outfilename(undefined, Module, HTML) ->
outfilename(Module, HTML);
outfilename(OutDir, Module, HTML) ->
filename:join(OutDir, outfilename(Module, HTML)).
outfilename(Module, true) ->
atom_to_list(Module)++".COVER.html";
outfilename(Module, false) ->
atom_to_list(Module)++".COVER.out".
-type export_reason() :: {'not_cover_compiled', Module :: module()} |
{'cant_open_file',
ExportFile :: file:filename(), FileReason :: term()} |
'not_main_node'.
-doc #{equiv => export(File, '_')}.
-spec export(File) -> 'ok' | {'error', Reason} when
File :: file:filename(),
Reason :: export_reason().
export(File) ->
export(File, '_').
-doc """
Exports the current coverage data for `Module` to the file `ExportFile`.
It is recommended to name the `ExportFile` with the extension `.coverdata`.
If `Module` is '_', data for all cover-compiled or earlier imported
modules is exported.
This function is useful if coverage data from different systems is to be merged.