View source for CBI/p2repoAnalyzers/Repo Reports

=p2 Repository Analysis=

== Goals ==

The '''p2RepoAnalyzers''' ([https://github.com/eclipse-cbi/p2repo-analyzers source code on GitHub]) are a collection of automated quality (legal, version rules...) checks and reports to run against p2 repositories or directories of jars. They're meant to be used by Eclipse projects to guarantee conformance to typical Eclipse.org rules.

'''The main goal is that all projects can perform these tests themselves, early in development cycle, every time they build a p2 repository.'''

So far, the main user of these reports is SimRel Build: the reports for the simultaneous release repository are simply a final sanity check. They are ran against the latest successful [https://ci.eclipse.org/simrel/job/simrel.runaggregator.pipeline/ Simultaneous Release aggregator build on Jenkins], so can always be viewed there. There is a link on the SimRel CI instance [https://ci.eclipse.org/simrel/ main page] that links to the [https://ci.eclipse.org/simrel/job/simrel.runaggregator.pipeline/lastSuccessfulBuild/artifact/target/repository/final/buildInfo/reporeports/index.html latest report].  In that case, the report is also copied, along with the repository, so it ends up on staging area too, so it can be viewed under a URL such as for the [http://download.eclipse.org/staging/2018-12/buildInfo/reporeports/ staging repository].

While several projects have their own, similar tests (which have one way or another have provided the starting point for all these tests) it is worth some effort to collect some common tests in a common place to encourage reuse and improvements. So if you've set up some similar checks for your project, you should highly consider contributing them to this common place.

The reports can be ran locally from your workbench or adopted for your own production builds.

== Description of tests and reports ==

There are some tests, that look at jars specifically,
that require the jars to be on local file system and essentially use plain 'ol Java file IO and regex-type checks on
the contents.

Another class of tests, read the content.jar/xml meta-data and reports on the data or relationships in
that meta data. 

Yet another, small class of tests, verify that the jars are signed. 
These tests are not really "Java" or "workspace" related, but use Java's "exec" method
to invoke "jarsigner -verify" on multiple threads, on a directory of jars. (There is actually a faster heuristic in the code that simply looks for the presence of the Eclipse signature file, but that is a heuristic and might not always be accurate, so it not used by default).

The code and scripts, as of right now, are oriented towards simply '''producing reports'''. But if you browse the code, you'll see some commented-out code in places that can cause <span style="color:red">failed</span> flags to be set, which would be appropriate for most projects and, eventually, even the Simultaneous Release repository.. But more recently Dennis Huebner has contributed the framework to run as JUnit tests but that still needs to be documented. See also the -useNewApi flag which produces reports based on <span style="color:green">passed</span>, <span style="color:red">failed</span>, or <span style="color:orange">warning</span> (which is a variant of passed more than a variant of failed). Follow {{bug|487409}} for updating the documentation.

== Running reports for your project ==

The project is built and delivered as both an Eclipse "product" and as a feature installable from a p2 repository. The Jenkins builds and functional testing is done under https://ci.eclipse.org/cbi/view/p2RepoRelated/ and the p2 repository where the product and feature are currently published is http://download.eclipse.org/cbi/updates/analyzers/4.7/ .

The '''Eclipse Application is named <tt>org.eclipse.cbi.p2repo.analyzers.repoReport</tt>'''. It is parameterized by two mandatory System Properties; one to specify
where you want the output to go, and another to specify where the repository-to-analyze is on the file system. An optional third parameter names a repository to use as reference for the "version check" reports. For example:
<ul>
<li>-DreportOutputDir=/home/shared/eclipse/repoReport</li>
<li>-DreportRepoDir=/home/www/html/downloads/eclipse/updates/4.6-M-builds/M20161013-0730/</li>
<li>-DreferenceRepo=/home/www/html/downloads/eclipse/updates/4.6/R-4.6.1-201609071200/</li>
</ul>
There is another parameter, <tt>-DuseNewApi=true</tt> which is not yet documented ({{bug|487409}}) but runs the code in such a way that tests <span style="color:green">pass</span>, <span style="color:red">fail</span>, or give a <span style="color:orange">warning</span>, and produces [http://download.eclipse.org/eclipse/downloads/drops4/R-4.6.1-201609071200/buildlogs/errors-and-moderate_warnings.html compact, color coded table of results], to link to an experimental example.

=== In Eclipse IDE ===

Get source project  named 'org.eclipse.cbi.p2repo.analyzers' and is currently in Git in repository named 'cbi/org.eclipse.cbi.p2repo.analyzers.git'. See {{Git|CBI|org.eclipse.cbi.p2repo.analyzers.git}}. Once you load that project into your workspace, it will include one "launch configuration" that can be used as a starting example,
edited and used to launch the application from your workspace.

=== With Eclipse command-line ===

For one example of a bash script that takes advantage of a "product build" to run the report application, see the example in the Eclipse Platform Git repository named [http://git.eclipse.org/c/platform/eclipse.platform.releng.aggregator.git/plain/production/createReports.sh createReports.sh].

=== With Ant ===

Running the reports are, as of right now, oriented towards being a simple "Ant task".

For an example of installing as a feature from a p2 repository see the [http://git.eclipse.org/c/simrel/org.eclipse.simrel.tools.git/tree/build.xml#n110 'installTestsFromRepo' target] in the SimRel build.xml file. And then, see the actual running of the tests in the [http://git.eclipse.org/c/simrel/org.eclipse.simrel.tools.git/tree/runTests.xml#n97 'runReports' target] in the SimRel runTests.xml file. 

=== With Maven ===

There is a bug open to convert to Maven tasks (see {{bug|487468}}).

However, the application can already be used in a Tycho build, typically as a <tt>verify</tt> step when building an <tt>eclipse-repository</tt>. See example:
<source lang="xml">
<!-- ... -->
<build>
  <plugins>
    <plugin>
      <groupId>org.eclipse.tycho.extras</groupId>
      <artifactId>tycho-eclipserun-plugin</artifactId>
      <version>${tycho-version}</version>
      <executions>
        <execution>
  	  <phase>verify</phase>
  	  <goals>
  	    <goal>eclipse-run</goal>
  	  </goals>
  	  <configuration>
  	    <applicationsArgs>
  	      <arg>-application</arg>
  	      <arg>org.eclipse.cbi.p2repo.analyzers.repoReport</arg>
  	    </applicationsArgs>
  	    <jvmArgs>
  	      <arg>-DreportRepoDir=${project.build.directory}/repository</arg>
  	      <arg>-DreportOutputDir=${project.build.directory}/repository/buildInfo</arg>
	      <arg>-DreferenceRepo=/home/data/httpd/download.eclipse.org/staging/oxygen/</arg>
  	    </jvmArgs>
  	    <executionEnvironment>JavaSE-1.8</executionEnvironment>
  	    <dependencies>
	      <dependency>
		<artifactId>org.eclipse.cbi.p2repo.analyzers</artifactId>
		<type>eclipse-plugin</type>
	      </dependency>
	      <dependency>
	        <artifactId>org.eclipse.equinox.p2.core.feature</artifactId>
		<type>eclipse-feature</type>
	      </dependency>
	      <dependency>
	        <artifactId>org.eclipse.e4.rcp</artifactId>
		<type>eclipse-feature</type>
	      </dependency>
	    </dependencies>
  	    <repositories>
  	      <repository>
  	        <id>cbi-analyzers</id>
  		<url>http://download.eclipse.org/cbi/updates/analyzers/4.7/</url>
  		<layout>p2</layout>
  	      </repository>
  	      <repository>
  	        <id>eclipse-4.7.3</id>
  		<url>http://download.eclipse.org/eclipse/updates/4.7/R-4.7.3-201803010715/</url>
  		<layout>p2</layout>
  	      </repository>
  	    </repositories>
  	  </configuration>
  	</execution>
      </executions>
    </plugin>
  </plugins>
</build>
<!--... -->
</source>

== Notes ==

On a large repository, it take 5 or 10 minutes to complete, and then you just look at the
results (usually) with a web browser starting with the 'index.html' at the location you specified in 'reportOutputDir' property.

== Get support and Contribute ==

You can ask questions on [mailto:cbi-dev@eclipse.org cbi-dev] list if the tests do not work as expected. Or, even better, you can make improvements/fixes directly on this wiki, if the instructions can be better. Feel free to supply patches in the [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=CBI&component=p2%20Repository%20Analyzers p2 Repository Analyzers] component in Bugzilla.

For now, the tests and scripts are in Git repo. To load into workspace, an appropriate URL would be similar to <tt>ssh://<userid>@git.eclipse.org:29418/cbi/org.eclipse.cbi.p2repo.analyzers</tt>, or for casual browsing, see {{Git|cbi|org.eclipse.cbi.p2repo.analyzers.git}}.

If/when others have fixes, abstractions, or new tests, please open a bug in the [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=CBI&component=p2%20Repository%20Analyzers p2 Repository Analyzers] component in Bugzilla, so these tests and reports can be improved over time by community effort. 


[[Category:CBI| ]] [[Category:Luna| ]] [[Category:Mars| ]] [[Category:Neon| ]] [[Category:Oxygen| ]] [[Category:Photon| ]]