maven/infrastructure/parent-pom/src/site/apt/usage.apt

	------
	Using the Object Teams Parent POM
	------
	Olaf Otto & Stephan Herrmann
	------
	2019-12-08
	------

Using the Object Teams Parent POM

 Declaring this module as the parent of your project will add basic capabilities
 for using OT/J in your sources.
 
* Weaving schemes OTRE vs. OTDRE
 
 This pom supports the traditional {{{http://help.eclipse.org/topic/org.eclipse.objectteams.otdt.doc/guide/weavingscheme.html}weaving scheme OTRE}}.
 For OTDRE please use {{{../objectteams-otdre-parent-pom}org.eclipse.objectteams:objectteams-otdre-parent-pom}} instead.
 
 <<Note:>> Due to limitations of the used version of BCEL (see below) the OTRE weaver is unable to process class files that have been compiled for Java 8.

* Include the parent pom

 For simple cases two declarations in your pom will suffice:

 [[1]] declare the maven repository for fetching Object Teams related modules

+-----
	<repositories>
		<repository>
			<id>ObjectTeamsRepository</id>
			<name>Object Teams Repository</name>
			<url>http://download.eclipse.org/objectteams/maven/3/repository</url>
		</repository>
	</repositories>
+----- 

 [[1]] declare the parent pom

+-----
	<parent>
		<groupId>org.eclipse.objectteams</groupId>
		<artifactId>objectteams-parent-pom</artifactId>
		<version>2.7.6</version>
	</parent>
+-----

 Starting with version 2.1.1 the parent pom also supports using OT/J in tycho builds (projects using OSGi).

* Example

  See the {{{../objectteams-compile-test}objectteams-compile-test}} project for an example of how to use this parent pom.
  
* Under the hood
 
** Standard OT/J dependencies documented

  All OT/J projects using the <<<objectteams-parent-pom>>> implicitly depend on the following artifacts which are developed 
  independent of maven and simply repackaged using the {{{../objectteams-artifact-deployer}org.eclipse.objectteams:objectteams-artifact-deployer}} module:
  
  [org.eclipse.objectteams:objectteams-runtime] the Object Teams runtime (minimal OT/J API) repackaged from the <<<org.eclipse.objectteams.runtime>>> OSGi bundle.
  
  [org.eclipse.objectteams:objectteams-otre] the Object Teams Runtime Environment (the bytecode weaver) repackaged from the <<<org.eclipse.objectteams.otre>>> OSGi bundle.
  
  [org.eclipse.objectteams:objectteams-otre-agent] the Java agent that hooks the Object Teams runtime into the JVM (repackaged from file <<<otre_agent.jar>>>
  from the <<<org.eclipse.objectteams.otdt>>> project).
  
  [org.eclipse.objectteams:objectteams-otj-compiler] a compatible replacement for <<<org.eclipse.tycho:org.eclipse.jdt.core>>> that enables the 
  <<<org.eclipse.tycho:tycho-compiler-jdt>>> plugin to compile OT/J sources.

  []
  
  The following module is indirectly used:

  [org.apache.bcel:bcel] the original {{{http://jakarta.apache.org/bcel}apache bcel}} Byte Code Engineering Library. Object Teams still uses the version 5.2 which is <<incompatible>> with the byte code of <<Java 8>>. Due to the lack of support for rewriting stack map tables, however, a migration to the current version 6 of BCEL would not make the weaver Java 8 compatible, as a Java 8 VM no longer tolerates class files without this attribute.