Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "JaCoCo/Proposal"

 
(9 intermediate revisions by the same user not shown)
Line 12: Line 12:
 
There are several open source coverage technologies for Java available. While implementing the Eclipse plug-in EclEmma (http://www.eclemma.org/) the observation was that none of them are really designed for integration. Most of them are specifically fit to a particular tool (Ant tasks, command line, IDE plug-in) and do not offer a documented API that allows embedding in different contexts. One of the best and widely used available open source tools is EMMA (http://emma.sourceforge.net/). While EclEmma is based on it the EMMA library is not actively maintained any more by the original author. Due to the lack of regression tests maintenance and feature additions will become very difficult.
 
There are several open source coverage technologies for Java available. While implementing the Eclipse plug-in EclEmma (http://www.eclemma.org/) the observation was that none of them are really designed for integration. Most of them are specifically fit to a particular tool (Ant tasks, command line, IDE plug-in) and do not offer a documented API that allows embedding in different contexts. One of the best and widely used available open source tools is EMMA (http://emma.sourceforge.net/). While EclEmma is based on it the EMMA library is not actively maintained any more by the original author. Due to the lack of regression tests maintenance and feature additions will become very difficult.
  
JaCoCo should become the standard backend technology for code coverage analysis in Java VM based environments. The focus is providing a lightweight, flexible and well documented library for integration with various build and development tools. Ant tasks are provided as reference usage scenarios. Other tools like a ready to use Eclipse plug-in (future version of EclEmma) or a Maven plug-in might follow.  
+
JaCoCo should become the standard backend technology for code coverage analysis in Java VM based environments. The focus is providing a lightweight, flexible and well documented library for integration with various build and development tools. Ant tasks and a Maven plug-in are provided as reference usage scenarios. Other tools like a ready to use Eclipse plug-in (future version of EclEmma) might follow.  
  
 
== Architecture and Extensibility ==
 
== Architecture and Extensibility ==
Line 55: Line 55:
  
 
In addition an "all-in-one" JAR is provided that includes all required dependencies and can be easily used in standalone Ant environments.
 
In addition an "all-in-one" JAR is provided that includes all required dependencies and can be easily used in standalone Ant environments.
 +
 +
=== jacoco-maven-plugin ===
 +
 +
The JaCoCo Maven plug-in provides the JaCoCo runtime agent to your tests and allows basic report creation.
  
 
== Project Scope ==
 
== Project Scope ==
  
The primary scope of the JaCoCo project is to build a code coverage library that can be used by other tools to provide coverage reports.  To ensure that the library is usable we also maintain a small number of exemplary tools that use the library.  Currently this includes standalone example programs and Ant tasks.
+
The primary scope of the JaCoCo project is to build a code coverage library that can be used by other tools to provide coverage reports.  To ensure that the library is usable we also maintain a small number of exemplary tools that use the library.  Currently this includes standalone example programs, Ant tasks and Maven plug-in.
  
Providing integration with other tools such as Hundson/Jenkins, Sonar and Maven are currently out of scope
+
Providing integration with other tools such as Hundson/Jenkins and Sonar are currently out of scope.
  
 
== Future Roadmap ==
 
== Future Roadmap ==
Line 82: Line 86:
 
We will continue to use this archive for distributing the framework portion of JaCoCo but will provide a P2 repository containing the agent, core and report bundles to support the EclEmma 2.0 plugin.
 
We will continue to use this archive for distributing the framework portion of JaCoCo but will provide a P2 repository containing the agent, core and report bundles to support the EclEmma 2.0 plugin.
  
All bundles will also be uploaded to a Maven2 repository to make the creation of a Maven2 plugin easier
+
All bundles will also be uploaded to a Maven2 repository (https://sourceforge.net/apps/trac/eclemma/wiki/MavenBuild).
  
 
== Organization ==
 
== Organization ==
Line 91: Line 95:
  
 
'''Initial committers'''
 
'''Initial committers'''
* Marc R. Hoffmann
+
* Marc R. Hoffmann (Project Lead)
 
* Brock Janiczak, Individual
 
* Brock Janiczak, Individual
* Evgeny Mandrikov, SonarSource (http://www.sonarsource.com/)
+
* Evgeny Mandrikov, [http://www.sonarsource.com/ SonarSource]
  
 
'''Interested parties'''
 
'''Interested parties'''
 
* Chris Aniszczyk
 
* Chris Aniszczyk
 
* Dave Carver
 
* Dave Carver
 +
* Christopher Marsh-Bourdon, Individual
 +
* Anthony Dahanne, [http://www.compuware.com/ Compuware]
 +
* David Matějček, Individual
  
 
[[Category:Eclipse Project]] [[Category:JaCoCo]]
 
[[Category:Eclipse Project]] [[Category:JaCoCo]]

Latest revision as of 03:57, 19 July 2011

Draft proposal

This is a draft proposal, feel free to contribute to it!

Introduction

JaCoCo (http://www.eclemma.org/jacoco) is a free code coverage library for Java, which is currently developed by the EclEmma team based on the lessons learned from using and integration existing libraries over the last three years.

JaCoCo is proposed as an open source project under the Eclipse Technology Project (http://www.eclipse.org/technology/). This proposal is still in the Project Proposal Phase, and is being made in order to call for more community participation. You are invited to comment on and/or join the project. Please send all feedback to the http://www.eclipse.org/newsportal/thread.php?group=eclipse.technology.jacoco newsgroup.

Background and Goal

There are several open source coverage technologies for Java available. While implementing the Eclipse plug-in EclEmma (http://www.eclemma.org/) the observation was that none of them are really designed for integration. Most of them are specifically fit to a particular tool (Ant tasks, command line, IDE plug-in) and do not offer a documented API that allows embedding in different contexts. One of the best and widely used available open source tools is EMMA (http://emma.sourceforge.net/). While EclEmma is based on it the EMMA library is not actively maintained any more by the original author. Due to the lack of regression tests maintenance and feature additions will become very difficult.

JaCoCo should become the standard backend technology for code coverage analysis in Java VM based environments. The focus is providing a lightweight, flexible and well documented library for integration with various build and development tools. Ant tasks and a Maven plug-in are provided as reference usage scenarios. Other tools like a ready to use Eclipse plug-in (future version of EclEmma) might follow.

Architecture and Extensibility

JaCoCo is pure Java library designed for integration with different tools. The code coverage analysis is based on byte code instrumentation.

JaCoCo is modularized in a set of OSGi bundles but does not have a dependency on OSGi, therefore can be used in any Java 1.5 environment. The only external dependency is ASM and optionally Ant when using the JaCoCo Ant tasks. Here is an overview of the current JaCoCo bundles:

Jacoco proposal dependencies.png

Bundle org.jacoco.core

The core provides the actual backend to perform code coverage analysis. It implements the bytecode instrumentation required to add the coverage recording ability to classes. It defines data structures and a binary format to record execution data. Finally the core implements the actual coverage analysis, which means comparing the recorded execution data with the class files to cover.

Bundle org.jacoco.agent

JaCoCo offers a convenient way to collect execution data from any Java process using a so call java agent (http://download.oracle.com/javase/1.5.0/docs/api/java/lang/instrument/package-summary.html). This bundle provides the JaCoCo Java agent JAR as a resource so integrators can extract the agent and provide it to the target application.

Bundle org.jacoco.agent.rt

This is the actual implementation of the Java agent. As it runs in the target VM it does not provide any Java API. The agent is controlled via command line parameters or remotely via TCP/IP connections. The agent is responsible for setting up an agent controller (either local or remote) and determining which classes should be instrumented. Classes that are to be instrumented will be passed to the core library for instrumentation.

The Agent also contains the code that is responsible for inserting the coverage runtime into the current Java execution environment. Several strategies are available to work around restrictions in some constrained environments, such as J2EE containers. These runtimes are supplies by the core library, but created/installed by the agent

Current strategies include:

  • (default) Modified System Class - Instruments a standard java class (UUID)
  • Java Util Logging - Adds a special 'logger'
  • URL Stream handler - Registers a custom URL handler
  • System properties - Inserts an object into the sysem properties

Bundle org.jacoco.report

Currently the following report types are supported:

  • HTML - Designed for end users
  • XML - designed for further processing by external tools such as Sonar or Hudson
  • CSV - Basic report type suitable for creating simple graphs

The reporting bundle is not externally extensible but does provide an internal API for writing new report types.

Bundle org.jacoco.ant

The JaCoCo Ant integration include tasks to launch an application with the coverage agent, request remote dumps, merge execution data and reports in different formats.

In addition an "all-in-one" JAR is provided that includes all required dependencies and can be easily used in standalone Ant environments.

jacoco-maven-plugin

The JaCoCo Maven plug-in provides the JaCoCo runtime agent to your tests and allows basic report creation.

Project Scope

The primary scope of the JaCoCo project is to build a code coverage library that can be used by other tools to provide coverage reports. To ensure that the library is usable we also maintain a small number of exemplary tools that use the library. Currently this includes standalone example programs, Ant tasks and Maven plug-in.

Providing integration with other tools such as Hundson/Jenkins and Sonar are currently out of scope.

Future Roadmap

  • API cleanup
  • Eclipse Plugin (EclEmma 2.0)
  • Support filtering of untestable/synthetic code

Concerns

The development of JaCoCo (as well as EclEmma) is backed by a few part time developers only. Currently a lightweight development process and development infrastructure (based on SourceForge) is used to let the team focus on coding, testing and documentation. We need to clarify the amount of ongoing administrative effort that is required to host a project at Elicpse.org properly.

Packaging and Deployment

JaCoCo currently ships in the form of a .zip download that contains the following:

  • JaCoCo Java agent jar continaing all dependencies
  • Ant jar containing all dependencies
  • runtime agent, ant task, core and reporting bundles (not required if using the all in one jars)
  • Documentation including usage examples

We will continue to use this archive for distributing the framework portion of JaCoCo but will provide a P2 repository containing the agent, core and report bundles to support the EclEmma 2.0 plugin.

All bundles will also be uploaded to a Maven2 repository (https://sourceforge.net/apps/trac/eclemma/wiki/MavenBuild).

Organization

Mentors

  • Chris Aniszczyk
  • TODO

Initial committers

  • Marc R. Hoffmann (Project Lead)
  • Brock Janiczak, Individual
  • Evgeny Mandrikov, SonarSource

Interested parties

  • Chris Aniszczyk
  • Dave Carver
  • Christopher Marsh-Bourdon, Individual
  • Anthony Dahanne, Compuware
  • David Matějček, Individual

Copyright © Eclipse Foundation, Inc. All Rights Reserved.