Add CLI tools for offline instrumentation and report generation

[johnkeeping]

These tools help people who are using a build system other than Ant/Maven, as discussed in issue #50.

To that end, I also include a commit adding some OSGi metadata to the runtime agent JAR. This allows that JAR to be stored in a bundle repository and downloaded from there during the build.

[judovana]

This tool is missing merge functionality. It will be critically missed:(
Anyway, thanx for moving this issue forward!

[awyork]

I hope this includes in place instrumentation of JAR files :)

[judovana]

In place instrumentation was abandoned long ago IIRC.

[awyork]

Is the Merge coming soon? I keep looking for a cli package in the snapshots and don't see it. Maybe I'm not looking correctly. Thanks. Much appreciated. This can really help what I'm working on.

[judovana]

I'm not sure:( Although I like my original code bit more (O:) I'm looking forward to this..
You can download and compile it from: http://icedtea.classpath.org/hg/icedtea-web/file/e99591814f02/tests/jacoco-operator
You can see that it is nothing more then api to already finished and excelent api. Also no SCM export provided (but it is two lines fix)

[somechris]

Since this PR is still waiting for a merge, and I needed a CLI tool for the report
generation part, I threw something similar together at

https://github.com/quelltextlich/jacoco-toolbox

. The jar (available from central, so no compilation necessary) allows
to access JaCoCo's functionality to

• merge inputs, and
• generate CSV, XML, and HTML reports

directly from the command line.

Maybe it's useful for other people that find this PR in the future.

[mathjeff]

This would be helpful for me too. Android would like to be able to have code coverage metrics via jacoco, but the classes later get processed further and executed in a vm that isn't a jvm (hence wanting the offline instrumentation), and the build system is a custom (though the portion that would interact with Jacoco is essentially Make) build system (hence wanting a command-line tool that both starts a couple seconds faster than Ant or Maven, and that is slightly simpler than including Ant or Maven in the build process).

@marchof you indicated in #520 that some of the main blockers for getting this merged were tests and documentation. Could you elaborate on what kinds of documentation and tests are expected? For documentation, are you thinking we'd just add some html under the file path /org.jacoco.doc/docroot in the same commit (as opposed to also separately updating some external wiki)? For tests, are you thinking full integration tests that build the .jar, execute it with command-line arguments, and check the resultant output files, or do you think it would be fine to just test the parser itself in memory?

I'd be happy to write some tests and/or documentation if that would get this to be merged

Thanks

[marchof]

@mathjeff Thanks for following this up here! Regarding missing parts:

Documentation

All official documentation goes to module org.jacoco.doc. External wiki is only for development purpose (e.g. design documents for new features) and not considered documentation. For the command line tool I envision that the documentation is generated from the annotated source code, like we do for Maven. Actually I started a new implementation some time ago to do exactly this. The idea was to work "ducumentation first" to identify the minimal required feature set before starting the actual implementation.

Test

Testing the built cli.jar as a separate process would probably the integration test. I think we already do the same for our Maven goals.

[mathjeff]

@marchof Thanks so much; that looks like it should give me a good understanding of what you're looking for.

I'm starting some updates at https://github.com/mathjeff/jacoco/commits/updating-cli-of-johnkeeping but I haven't yet implemented the test and documentation changes that you're talking about; once I do that then I'll turn it into a proper pull request.

Thanks so much!

[marchof]

@mathjeff I also started working on the documentation and test part. I hope I can push something by next week so we can see what is left for your use cases.

[marchof]

We follow-up the command line interface implementation in a new pull request: #525