diff options
Diffstat (limited to 'lib/tools/doc/src/cover.xml')
| -rw-r--r-- | lib/tools/doc/src/cover.xml | 458 |
1 files changed, 458 insertions, 0 deletions
diff --git a/lib/tools/doc/src/cover.xml b/lib/tools/doc/src/cover.xml new file mode 100644 index 0000000000..323bd0dda8 --- /dev/null +++ b/lib/tools/doc/src/cover.xml @@ -0,0 +1,458 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2001</year> + <year>2007</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>cover</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <module>cover</module> + <modulesummary>A Coverage Analysis Tool for Erlang</modulesummary> + <description> + <p>The module <c>cover</c> provides a set of functions for coverage + analysis of Erlang programs, counting how many times each + <em>executable line</em> of code is executed when a program is run. <br></br> + + An executable line contains an Erlang expression such as a matching + or a function call. A blank line or a line containing a comment, + function head or pattern in a <c>case</c>- or <c>receive</c> statement + is not executable.</p> + <p>Coverage analysis can be used to verify test cases, making sure all + relevant code is covered, and may also be helpful when looking for + bottlenecks in the code.</p> + <p>Before any analysis can take place, the involved modules must be + <em>Cover compiled</em>. 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 + <c>.beam</c> file is created.</p> + <p>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 <c>Answer</c> is determined by two + parameters, <c>Level</c> and <c>Analysis</c>.</p> + <list type="bulleted"> + <item> + <p><c>Level = module</c></p> + <p><c>Answer = {Module,Value}</c>, where <c>Module</c> is the module + name.</p> + </item> + <item> + <p><c>Level = function</c></p> + <p><c>Answer = [{Function,Value}]</c>, one tuple for each function in + the module. A function is specified by its module name <c>M</c>, + function name <c>F</c> and arity <c>A</c> as a tuple + <c>{M,F,A}</c>.</p> + </item> + <item> + <p><c>Level = clause</c></p> + <p><c>Answer = [{Clause,Value}]</c>, one tuple for each clause in + the module. A clause is specified by its module name <c>M</c>, + function name <c>F</c>, arity <c>A</c> and position in the function + definition <c>C</c> as a tuple <c>{M,F,A,C}</c>.</p> + </item> + <item> + <p><c>Level = line</c></p> + <p><c>Answer = [{Line,Value}]</c>, one tuple for each executable + line in the module. A line is specified by its module name <c>M</c> + and line number in the source file <c>N</c> as a tuple + <c>{M,N}</c>.</p> + </item> + <item> + <p><c>Analysis = coverage</c></p> + <p><c>Value = {Cov,NotCov}</c> where <c>Cov</c> is the number of + executable lines in the module, function, clause or line that have + been executed at least once and <c>NotCov</c> is the number of + executable lines that have not been executed.</p> + </item> + <item> + <p><c>Analysis = calls</c></p> + <p><c>Value = Calls</c> which is the number of times the module, + function, or clause has been called. In the case of line level + analysis, <c>Calls</c> is the number of times the line has been + executed.</p> + </item> + </list> + <p><em>Distribution</em></p> + <p>Cover can be used in a distributed Erlang system. One of the + nodes in the system must then be selected as the <em>main node</em>, and all Cover commands must be executed from this + node. The error reason <c>not_main_node</c> is returned if an + interface function is called on one of the remote nodes.</p> + <p>Use <c>cover:start/1</c> and <c>cover:stop/1</c> 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.</p> + </description> + <funcs> + <func> + <name>start() -> {ok,Pid} | {error,Reason}</name> + <fsummary>Start Cover.</fsummary> + <type> + <v>Pid = pid()</v> + <v>Reason = {already_started,Pid}</v> + </type> + <desc> + <p>Starts the Cover server which owns the Cover internal database. + This function is called automatically by the other functions in + the module.</p> + </desc> + </func> + <func> + <name>start(Nodes) -> {ok,StartedNodes} | {error,not_main_node}</name> + <fsummary>Start Cover on remote nodes.</fsummary> + <type> + <v>Nodes = StartedNodes = [atom()]</v> + </type> + <desc> + <p>Starts a Cover server on the each of given nodes, and loads + all cover compiled modules.</p> + </desc> + </func> + <func> + <name>compile(ModFile) -> Result</name> + <name>compile(ModFile, Options) -> Result</name> + <name>compile_module(ModFile) -> Result</name> + <name>compile_module(ModFile, Options) -> Result</name> + <fsummary>Compile a module for Cover analysis.</fsummary> + <type> + <v>ModFile = Module | File</v> + <v> Module = atom()</v> + <v> File = string()</v> + <v>Options = [Option]</v> + <v> Option = {i,Dir} | {d,Macro} | {d,Macro,Value}</v> + <d>See <c>compile:file/2.</c></d> + <v>Result = {ok,Module} | {error,File} | {error,not_main_node}</v> + </type> + <desc> + <p>Compiles a module for Cover analysis. The module is given by its + module name <c>Module</c> or by its file name <c>File</c>. + The <c>.erl</c> extension may be omitted. If the module is + located in another directory, the path has to be specified.</p> + <p><c>Options</c> is a list of compiler options which defaults to + <c>[]</c>. Only options defining include file directories and + macros are passed to <c>compile:file/2</c>, everything else is + ignored.</p> + <p>If the module is successfully Cover compiled, the function + returns <c>{ok,Module}</c>. Otherwise the function returns + <c>{error,File}</c>. Errors and warnings are printed as they + occur.</p> + <p>Note that the internal database is (re-)initiated during + the compilation, meaning any previously collected coverage data + for the module will be lost.</p> + </desc> + </func> + <func> + <name>compile_directory() -> [Result] | {error,Reason}</name> + <name>compile_directory(Dir) -> [Result] | {error,Reason}</name> + <name>compile_directory(Dir, Options) -> [Result] | {error,Reason}</name> + <fsummary>Compile all modules in a directory for Cover analysis.</fsummary> + <type> + <v>Dir = string()</v> + <v>Options = [Option]</v> + <d>See <c>compile_module/1,2</c></d> + <v>Result = {ok,Module} | {error,File} | {error,not_main_node}</v> + <d>See <c>compile_module/1,2</c></d> + <v>Reason = eacces | enoent</v> + </type> + <desc> + <p>Compiles all modules (<c>.erl</c> files) in a directory + <c>Dir</c> for Cover analysis the same way as + <c>compile_module/1,2</c> and returns a list with the return + values.</p> + <p><c>Dir</c> defaults to the current working directory.</p> + <p>The function returns <c>{error,eacces}</c> if the directory is not + readable or <c>{error,enoent}</c> if the directory does not exist.</p> + </desc> + </func> + <func> + <name>compile_beam(ModFile) -> Result</name> + <fsummary>Compile a module for Cover analysis, using an existing beam.</fsummary> + <type> + <v>ModFile = Module | BeamFile</v> + <v> Module = atom()</v> + <v> BeamFile = string()</v> + <v>Result = {ok,Module} | {error,BeamFile} | {error,Reason}</v> + <v> Reason = non_existing | {no_abstract_code,BeamFile} | {encrypted_abstract_code,BeamFile} | {already_cover_compiled,no_beam_found,Module} | not_main_node</v> + </type> + <desc> + <p>Does the same as <c>compile/1,2</c>, but uses an existing + <c>.beam</c> file as base, i.e. the module is not compiled + from source. Thus <c>compile_beam/1</c> is faster than + <c>compile/1,2</c>.</p> + <p>Note that the existing <c>.beam</c> file must contain + <em>abstract code</em>, i.e. it must have been compiled with + the <c>debug_info</c> option. If not, the error reason + <c>{no_abstract_code,BeamFile}</c> is returned. + If the abstract code is encrypted, and no key is available + for decrypting it, the error reason + <c><![CDATA[{encrypted_abstract_code,BeamFile} is returned. <p>If only the module name (i.e. not the full name of the <c>.beam]]></c> file) is given to this function, the + <c>.beam</c> file is found by calling + <c>code:which(Module)</c>. If no <c>.beam</c> file is found, + the error reason <c>non_existing</c> is returned. If the + module is already cover compiled with <c>compile_beam/1</c>, + the <c>.beam</c> file will be picked from the same location + as the first time it was compiled. If the module is already + cover compiled with <c>compile/1,2</c>, there is no way to + find the correct <c>.beam</c> file, so the error reason + <c>{already_cover_compiled,no_beam_found,Module}</c> is + returned.</p> + <p><c>{error,BeamFile}</c> is returned if the compiled code + can not be loaded on the node.</p> + </desc> + </func> + <func> + <name>compile_beam_directory() -> [Result] | {error,Reason}</name> + <name>compile_beam_directory(Dir) -> [Result] | {error,Reason}</name> + <fsummary>Compile all .beam files in a directory for Cover analysis.</fsummary> + <type> + <v>Dir = string()</v> + <v>Result = See compile_beam/1</v> + <v>Reason = eacces | enoent</v> + </type> + <desc> + <p>Compiles all modules (<c>.beam</c> files) in a directory + <c>Dir</c> for Cover analysis the same way as + <c>compile_beam/1</c> and returns a list with the return + values.</p> + <p><c>Dir</c> defaults to the current working directory.</p> + <p>The function returns <c>{error,eacces}</c> if the directory is not + readable or <c>{error,enoent}</c> if the directory does not exist.</p> + </desc> + </func> + <func> + <name>analyse(Module) -> {ok,Answer} | {error,Error}</name> + <name>analyse(Module, Analysis) -> {ok,Answer} | {error,Error}</name> + <name>analyse(Module, Level) -> {ok,Answer} | {error,Error}</name> + <name>analyse(Module, Analysis, Level) -> {ok,Answer} | {error,Error}</name> + <fsummary>Analyse a Cover compiled module.</fsummary> + <type> + <v>Module = atom()</v> + <v>Analysis = coverage | calls</v> + <v>Level = line | clause | function | module</v> + <v>Answer = {Module,Value} | [{Item,Value}]</v> + <v> Item = Line | Clause | Function</v> + <v> Line = {M,N}</v> + <v> Clause = {M,F,A,C}</v> + <v> Function = {M,F,A}</v> + <v> M = F = atom()</v> + <v> N = A = C = integer()</v> + <v> Value = {Cov,NotCov} | Calls</v> + <v> Cov = NotCov = Calls = integer()</v> + <v>Error = {not_cover_compiled,Module} | not_main_node</v> + </type> + <desc> + <p>Performs analysis of a Cover compiled module <c>Module</c>, as + specified by <c>Analysis</c> and <c>Level</c> (see above), by + examining the contents of the internal database.</p> + <p><c>Analysis</c> defaults to <c>coverage</c> and <c>Level</c> + defaults to <c>function</c>.</p> + <p>If <c>Module</c> is not Cover compiled, the function returns + <c>{error,{not_cover_compiled,Module}}</c>.</p> + </desc> + </func> + <func> + <name>analyse_to_file(Module) -> </name> + <name>analyse_to_file(Module,Options) -> </name> + <name>analyse_to_file(Module, OutFile) -> </name> + <name>analyse_to_file(Module, OutFile, Options) -> {ok,OutFile} | {error,Error}</name> + <fsummary>Detailed coverage analysis of a Cover compiled module.</fsummary> + <type> + <v>Module = atom()</v> + <v>OutFile = string()</v> + <v>Options = [Option]</v> + <v>Option = html</v> + <v>Error = {not_cover_compiled,Module} | {file,File,Reason} | no_source_code_found | not_main_node</v> + <v> File = string()</v> + <v> Reason = term()</v> + </type> + <desc> + <p>Makes a copy <c>OutFile</c> of the source file for a module + <c>Module</c>, where it for each executable line is specified + how many times it has been executed.</p> + <p>The output file <c>OutFile</c> defaults to + <c>Module.COVER.out</c>, or <c>Module.COVER.html</c> if the + option <c>html</c> was used.</p> + <p>If <c>Module</c> is not Cover compiled, the function returns + <c>{error,{not_cover_compiled,Module}}</c>.</p> + <p>If the source file and/or the output file cannot be opened using + <c>file:open/2</c>, the function returns + <c>{error,{file,File,Reason}}</c> where <c>File</c> is the file + name and <c>Reason</c> is the error reason.</p> + <p>If the module was cover compiled from the <c>.beam</c> + file, i.e. using <c>compile_beam/1</c> or + <c>compile_beam_directory/0,1</c>, it is assumed that the + source code can be found in the same directory as the + <c>.beam</c> file, or in <c>../src</c> relative to that + directory. If no source code is found, + <c>,{error,no_source_code_found}</c> is returned.</p> + </desc> + </func> + <func> + <name>modules() -> [Module] | {error,not_main_node}</name> + <fsummary>Return all Cover compiled modules.</fsummary> + <type> + <v>Module = atom()</v> + </type> + <desc> + <p>Returns a list with all modules that are currently Cover + compiled.</p> + </desc> + </func> + <func> + <name>imported_modules() -> [Module] | {error,not_main_node}</name> + <fsummary>Return all modules for which there are imported data.</fsummary> + <type> + <v>Module = atom()</v> + </type> + <desc> + <p>Returns a list with all modules for which there are + imported data.</p> + </desc> + </func> + <func> + <name>imported() -> [File] | {error,not_main_node}</name> + <fsummary>Return all imported files.</fsummary> + <type> + <v>File = string()</v> + </type> + <desc> + <p>Returns a list with all imported files.</p> + </desc> + </func> + <func> + <name>which_nodes() -> [Node] | {error,not_main_node}</name> + <fsummary>Return all nodes that are part of the coverage analysis.</fsummary> + <type> + <v>Node = atom()</v> + </type> + <desc> + <p>Returns a list with all nodes that are part of the coverage + analysis. Note that the current node is not returned. This + node is always part of the analysis.</p> + </desc> + </func> + <func> + <name>is_compiled(Module) -> {file,File} | false | {error,not_main_node}</name> + <fsummary>Check if a module is Cover compiled.</fsummary> + <type> + <v>Module = atom()</v> + <v>Beam = string()</v> + </type> + <desc> + <p>Returns <c>{file,File}</c> if the module <c>Module</c> is + Cover compiled, or <c>false</c> otherwise. <c>File</c> is + the <c>.erl</c> file used by <c>cover:compile_module/1,2</c> + or the <c>.beam</c> file used by <c>compile_beam/1</c>.</p> + </desc> + </func> + <func> + <name>reset(Module) -></name> + <name>reset() -> ok | {error,not_main_node}</name> + <fsummary>Reset coverage data for Cover compiled modules.</fsummary> + <type> + <v>Module = atom()</v> + </type> + <desc> + <p>Resets all coverage data for a Cover compiled module + <c>Module</c> in the Cover database on all nodes. If the + argument is omitted, the coverage data will be reset for all + modules known by Cover.</p> + <p>If <c>Module</c> is not Cover compiled, the function returns + <c>{error,{not_cover_compiled,Module}}</c>.</p> + </desc> + </func> + <func> + <name>export(ExportFile)</name> + <name>export(ExportFile,Module) -> ok | {error,Reason}</name> + <fsummary>Reset coverage data for Cover compiled modules.</fsummary> + <type> + <v>ExportFile = string()</v> + <v>Module = atom()</v> + <v>Reason = {not_cover_compiled,Module} | {cant_open_file,ExportFile,Reason} | not_main_node</v> + </type> + <desc> + <p>Exports the current coverage data for <c>Module</c> to the + file <c>ExportFile</c>. It is recommended to name the + <c>ExportFile</c> with the extension <c>.coverdata</c>, since + other filenames can not be read by the web based interface to + cover.</p> + <p>If <c>Module</c> is not given, data for all Cover compiled + or earlier imported modules is exported.</p> + <p>This function is useful if coverage data from different + systems is to be merged.</p> + <p>See also <c>cover:import/1</c></p> + </desc> + </func> + <func> + <name>import(ExportFile) -> ok | {error,Reason}</name> + <fsummary>Reset coverage data for Cover compiled modules.</fsummary> + <type> + <v>ExportFile = string()</v> + <v>Reason = {cant_open_file,ExportFile,Reason} | not_main_node</v> + </type> + <desc> + <p>Imports coverage data from the file <c>ExportFile</c> + created with <c>cover:export/1,2</c>. Any analysis performed + after this will include the imported data.</p> + <p>Note that when compiling a module <em>all existing coverage data is removed</em>, including imported data. If a module is + already compiled when data is imported, the imported data is + <em>added</em> to the existing coverage data.</p> + <p>Coverage data from several export files can be imported + into one system. The coverage data is then added up when + analysing.</p> + <p>Coverage data for a module can not be imported from the + same file twice unless the module is first reset or + compiled. The check is based on the filename, so you can + easily fool the system by renaming your export file.</p> + <p>See also <c>cover:export/1,2</c></p> + </desc> + </func> + <func> + <name>stop() -> ok | {error,not_main_node}</name> + <fsummary>Stop Cover.</fsummary> + <desc> + <p>Stops the Cover server and unloads all Cover compiled code.</p> + </desc> + </func> + <func> + <name>stop(Nodes) -> ok | {error,not_main_node}</name> + <fsummary>Stop Cover on remote nodes.</fsummary> + <type> + <v>Nodes = [atom()]</v> + </type> + <desc> + <p>Stops the Cover server and unloads all Cover compiled code + on the given nodes. Data stored in the Cover database on the + remote nodes is fetched and stored on the main node.</p> + </desc> + </func> + </funcs> + + <section> + <title>SEE ALSO</title> + <p>code(3), compile(3)</p> + </section> +</erlref> + |