=================================================================
jacoco2lcov - Translate JaCoCo execution data to lcov format
=================================================================

:Manual section: 1
:Manual group: |ToolName| Tools

NAME
----

jacoco2lcov
  Translate JaCoCo execution data to lcov format


SYNOPSIS
--------

::

    jacoco2lcov [--output mydata.info] [options] execfile+

DESCRIPTION
-----------

``jacoco2lcov`` translates the execution data which JaCoCo collected while your
Java tests ran into LCOV ``.info`` format.

It does none of the translation itself: it is a wrapper which runs, in order,
the two commands you would otherwise run by hand -

- ``java -jar jacococli.jar report ... --xml tmp.xml``, to turn the ``.exec``
  execution data files into a JaCoCo XML report, and

- ``xml2lcov --format jacoco ... tmp.xml``, to translate that report into LCOV
  ``.info`` format -

and then reads the |ToolName| format ``.info`` file generated by ``xml2lcov``,
applies the common |ToolName|
options - filtering, exclusions, *etc.* - and writes the result to the
output file. The data is read and written by the same code every other tool in
the suite uses, so ``jacoco2lcov`` supports every common option - see **OPTIONS**.

The intermediate files are temporary and are removed when ``jacoco2lcov``
finishes; use ``--xml`` to keep the XML report.

Either of the two steps can be run independently if you want or need to -
say, because you need additional options or flags that are not supported
by the script.

**What JaCoCo needs to be told**

A JaCoCo ``.exec`` file holds execution data but not the names of
the classes it refers to or their source.
Thus, at least one class location
has to be named, with ``--classpath``: JaCoCo reads the coverage counts out of
the class files, and cannot write a report without them. At least one source
directory has to be named as well, with ``--source-directory``, because a JaCoCo
report names no search path of its own and ``xml2lcov`` has to find the sources
to translate them. ``--plugin-directory`` is a shorthand for both when your code
is laid out in the usual Eclipse or Maven way.

With none of ``--classpath``, ``--source-directory`` and ``--plugin-directory``
given, the current directory is searched as ``--plugin-directory .`` would search
it. That finds the source and class directories of a project laid out either of
those ways - ``src/main/java`` and ``target/classes`` for Maven, ``src`` and
``bin`` for Eclipse - and of a directory holding several such projects, in which
case each of them contributes the directories it has. ``jacoco2lcov`` says so
when it does this, and stops if it finds nothing: a layout it does not recognize,
or classes somewhere else your build put them, still has to be named. It is a
convenience for the usual case, not a search: nothing is looked for outside the
conventional places, and nothing is guessed from file extensions.

**Coverage types**

JaCoCo data always contains branch and function coverage - so ``jacoco2lcov``
enables both of them by default.  Use command line and/or config file options
to change this behaviour, if desired.

There is no MC/DC or condition coverage to write: JaCoCo does not collect it.

**Source versions**

A JaCoCo report does not say which version of the source it describes, so there
is no version in the data to carry through - unlike a ``lcov --capture``, which
records the version of each file it finds. ``--version-script`` therefore means
"compute the version", and ``jacoco2lcov`` turns ``compute_file_version`` on for
you when you name one: the callback is applied to each file as the translated
data is read back in, and the ``VER:`` records it returns are written to the
output. Say ``--rc compute_file_version=0`` if you want the callback used for
nothing but comparisons.

Without a version script there is no version to record, and a report generated
from the result has nothing to check the source it reads against - so
:manpage:`genhtml(1)` will stop with a ``version`` error if it is asked to
compute versions itself.

**Consistency**

JaCoCo counts instructions and branches rather than executions, so the execution
counts in the translated data are derived, and |ToolName| may consider the result
internally inconsistent - most often because JaCoCo reports a line as covered
whose branches it never saw evaluated. See the **JaCoCo conversion notes**
section of :manpage:`xml2lcov(1)` for why the derived data appears as it does.
If you need to work around the ``inconsistent`` error which is reported, either
exclude the offending code or add ``--ignore-errors inconsistent`` to your
command line.

The same ``inconsistent`` error is generated when
a function is marked "not executed" but contains a line which is covered - for example, ``function 'com.example.Widget.dead()V'
is not hit but line 8 is``. A JaCoCo ``method`` contains a 'begin' line but
no information about where it ends - so the range of lines contained within
the function is derived from the line data and source text.  This can
erroneously claim a line belonging to another method.
The message can be suppressed via ``--ignore-errors
inconsistent``. See the
**JaCoCo conversion notes** section of :manpage:`xml2lcov(1)`.

**Merging**

If you have execution data from more than one test run, hand all of the
``.exec`` files to a single ``jacoco2lcov`` command rather than translating each
of them and merging the results with ``lcov -a``: JaCoCo can combine per-branch
data exactly and the translated data cannot. See **Merging JaCoCo data** in
:manpage:`xml2lcov(1)`.

OPTIONS
-------

In addition to the common options supported by the other tools in the |ToolName|
suite (*e.g.*, ``--exclude``, ``--include``, ``--filter``, ``--substitute``,
``--omit-lines``, ``--erase-functions``, ``--ignore-errors``, ``--comment``,
``--version-script``, *etc.*), which are applied to the translated data, the
tool options are the ones below.

Each of them is marked optional or required, and the default of each is
given. Nothing but the ``.exec`` files is required unconditionally: the rest of
what ``jacoco2lcov`` has to know it can get from the environment or from the
layout of the directory it is run in.

*execfile*
   One or more JaCoCo ``.exec`` execution data files or directories which are
   searched for ``.exec`` files.
   Every argument which is not an option is taken to name execution data,
   whatever it is called: ``.exec`` is a convention and nothing here depends on
   it.
   Required.

``-o``, ``--output`` *file*
   Optional. Specify the output LCOV ``.info`` file.
   Default: ``jacoco2lcov.info`` in the current directory.

``-t``, ``--test-name``, ``--testname`` *name*
   Optional. Specify the test name for the ``TN:`` entry in the LCOV ``.info``
   file. Default: none - the ``TN:`` entry is empty.

``-d``, ``--root-directory`` *directory*
   Optional. The run directory and root of relative paths to source, class
   execution data files, and the output file.
   Default: the directory ``jacoco2lcov`` was run in.

``-c``, ``--classpath``, ``--classfiles`` *path*
   A directory or ``.jar`` file containing the class files whose coverage JaCoCo
   recorded. JaCoCo reads the coverage counts out of the class
   files, so it cannot write a report without them. Required, unless ``-p``
   names them or the default search below finds them.
   May be specified multiple times.
   Default: none.

``-s``, ``--source-directory``, ``--source-dir`` *directory*
   A root directory of your Java sources - that is, one of the directories you
   would pass to ``javac``, such that the name of a package, used as a directory
   path, names the directory holding that package's sources.
   Required, unless ``-p`` names them or the default search below finds them.
   May be specified multiple times.
   Default: none.

``-p``, ``--plugin-directory``, ``--plugin-dir`` *directory*
   Optional. The root of an Eclipse/Maven plugin, or the parent directory of
   several of them, to be searched for source and class directories in the usual
   places (``src``, ``src/java``, ``src/main/java``, ``src/test/java`` and
   ``bin``, ``classes``, ``target/classes``).
   This is a
   shorthand for the ``-s`` and ``-c`` options which such a directory implies.
   May be specified multiple times.
   Default: with none of ``-s``, ``-c`` and ``-p`` given, the current directory
   is searched as ``-p .`` would search it - see **What JaCoCo needs to be
   told** above.

``--jar`` *jacococli.jar*
   Optional if the environment names the jar, required if it does not. Path to
   the JaCoCo command line jar. Default: the jar named by the ``JACOCOCLI_JAR``
   environment variable, else the one found under the directory named by
   ``JACOCO_HOME``.

``--java`` *executable*
   Optional. The ``java`` executable used to run the JaCoCo command line jar.
   Default: ``$JAVA_HOME/bin/java`` if that is an executable, else ``java``,
   found on your PATH.

``--xml`` *file*
   Optional. Write the intermediate JaCoCo XML report to the named file and keep
   it. Default: a temporary file, removed when ``jacoco2lcov`` exits.

``--xml2lcov`` *path*
   Optional. The ``xml2lcov`` executable to use. Default: the one installed next
   to ``jacoco2lcov``.
   On Windows, a wrapper which Windows can run - an ``xml2lcov.bat``, say - is
   preferred to the extensionless script beside it.

``-v``, ``--verbose``
   Optional. Print each command before it is run. Default: off - only warnings,
   errors and notices are printed.

``-k``, ``--keep-going``
   Optional. Ignore errors and continue processing. Default: off - stop at the
   first error.

``-h``, ``--help``
   Print usage information and exit.

**Common options**

Every other option ``jacoco2lcov`` accepts is one the rest of the suite accepts,
and means here what it means there - it is applied to the translated data:

::

    $ jacoco2lcov -o mydata.info -s src -c bin --exclude='*/test/*' \
          --filter branch mytest.exec

See :manpage:`lcov(1)` and :manpage:`lcovrc(5)` for details of these options and
of the configuration settings which also reach them.


EXAMPLES
--------

::

      # run your tests with the JaCoCo agent attached, to collect coverage
    $ java -javaagent:jacocoagent.jar=destfile=test1.exec -cp bin MyTest1
    $ java -javaagent:jacocoagent.jar=destfile=test2.exec -cp bin MyTest2

      # translate all of the execution data in one step
    $ jacoco2lcov -o mydata.info -s src -c bin test1.exec test2.exec

      # the same, run from the root of a conventionally laid out project:  with
      # no directory named, the ones the layout implies are used
    $ jacoco2lcov -o mydata.info test1.exec test2.exec

      # the same, for a directory of Eclipse/Maven plugins, keeping the
      # intermediate XML report and dropping the test sources from the result
    $ jacoco2lcov -o mydata.info -p plugins --xml jacoco.xml \
        --exclude '*/src/test/java/*' test1.exec test2.exec

      # a build which wrote one .exec file per test below a results directory,
      # translated from the directory the rest of your coverage data is
      # relative to:  naming that directory is what makes the file names in the
      # result line up with it
    $ jacoco2lcov -d /work/myproject -o mydata.info -p plugins results

      # and generate an HTML coverage report.  JaCoCo reports lines as covered
      # whose branches it never saw evaluated, which genhtml considers
      # inconsistent - see 'Consistency' above
    $ genhtml -o html_report mydata.info --branch-coverage \
        --ignore-errors inconsistent

ENVIRONMENT
-----------

``JACOCOCLI_JAR``
   The JaCoCo command line jar to run, if ``--jar`` does not name one.

``JACOCO_HOME``
   The root of a JaCoCo installation, searched for ``lib/jacococli.jar`` and
   then ``jacococli.jar`` if neither ``--jar`` nor ``JACOCOCLI_JAR`` names a
   jar.

``JAVA_HOME``
   The root of the Java installation whose ``bin/java`` is used to run the
   JaCoCo command line jar, if ``--java`` does not name one.

AUTHOR
------

Henry Cox <henry.cox@mediatek.com>

SEE ALSO
--------

:manpage:`lcov(1)`, :manpage:`genhtml(1)`, :manpage:`xml2lcov(1)`

- JaCoCo documentation: https://www.jacoco.org/jacoco/trunk/doc
- JaCoCo command line interface: https://www.jacoco.org/jacoco/trunk/doc/cli.html
