aboutsummaryrefslogtreecommitdiffstats
path: root/lib/tools/doc/src/cover.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/tools/doc/src/cover.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/tools/doc/src/cover.xml')
-rw-r--r--lib/tools/doc/src/cover.xml458
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>&nbsp;Module = atom()</v>
+ <v>&nbsp;File = string()</v>
+ <v>Options = [Option]</v>
+ <v>&nbsp;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>&nbsp;Module = atom()</v>
+ <v>&nbsp;BeamFile = string()</v>
+ <v>Result = {ok,Module} | {error,BeamFile} | {error,Reason}</v>
+ <v>&nbsp;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>&nbsp;Item = Line | Clause | Function</v>
+ <v>&nbsp;&nbsp;Line = {M,N}</v>
+ <v>&nbsp;&nbsp;Clause = {M,F,A,C}</v>
+ <v>&nbsp;&nbsp;Function = {M,F,A}</v>
+ <v>&nbsp;&nbsp;&nbsp;M = F = atom()</v>
+ <v>&nbsp;&nbsp;&nbsp;N = A = C = integer()</v>
+ <v>&nbsp;Value = {Cov,NotCov} | Calls</v>
+ <v>&nbsp;&nbsp;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>&nbsp;File = string()</v>
+ <v>&nbsp;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>
+