README

*******************************************************************************
*  Copyright (c) 2001, 2019 IBM Corp. and others
*
*  This program and the accompanying materials are made available under
*  the terms of the Eclipse Public License 2.0 which accompanies this
*  distribution and is available at https://www.eclipse.org/legal/epl-2.0/
*  or the Apache License, Version 2.0 which accompanies this distribution and
*  is available at https://www.apache.org/licenses/LICENSE-2.0.
*
*  This Source Code may also be made available under the following
*  Secondary Licenses when the conditions for such availability set
*  forth in the Eclipse Public License, v. 2.0 are satisfied: GNU
*  General Public License, version 2 with the GNU Classpath
*  Exception [1] and GNU General Public License, version 2 with the
*  OpenJDK Assembly Exception [2].
*
*  [1] https://www.gnu.org/software/classpath/license.html
*  [2] http://openjdk.java.net/legal/assembly-exception.html
*
*  SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 OR LicenseRef-GPL-2.0 WITH Assembly-exception
*******************************************************************************

This Readme is deprecated. Please run the jvmti test from the testKitGen framework.

Compiling Agent and Java (JAR) Code
--------------------

	1) Set INTREL_ROOT environment variable to point at J9 sources,
	   (for example, the jre/bin directory of an unzipped J9 SDK package on Windows
	    or jre/lib/i386/default - or different platform than i386 - on Linux).
	   The following components (under INTREL_ROOT) are required:
	    - include/       (JVM headers containing API details)
	    - buildtools/    (Needed to obtain the right version of uma.jar)
	    - buildpspecs/   (Needed by UMA to create makefiles)

	2) Change to tests/jvmti directory

	3) Run ./build.sh on *nix platforms, or do the same steps manually for other platforms.


Running All Tests while developing
----------------------------------

	java  -DJAR=bin -DEXE="path/to/jre/bin/java"  -jar <path_to_jar>/cmdlinetester.jar -config cmdlinetester/jvmtitests.xml



Running a Single Test
---------------------

	cd tests/jvmti
	path/to/jre/bin/java -agentlib:jvmtitest=test:fer001 -cp bin com.ibm.jvmti.tests.util.TestRunner

	Generally when unsure about the options, check the output of the cmdlinetester based run.
	(See "Running All Tests while developing"). The cmdlinetester harness will print the
	command line used to invoke a testcase.


Testcase Packages
-----------------

	Testing for each API function is composed by a separate package nested under tests/jvmti/src.

	For example	testing of ForceEarlyReturn is contained within a package called:
		com.ibm.jvmti.tests.forceEarlyReturn

	The package contains one or more tests named by abbreviating the API function name. For example
	the first test in com.ibm.jvmti.tests.forceEarlyReturn has its testcase class and agent c file
	called fer001.java and fer001.c. The next test of that API is called fer002 and so on.

	Usually all of the tests for each API function are contained within one test class (ex: fer001.java/.c)
	Sometimes it might be desirable to split such testing into multiple separate tests (for example
	when adding unit testing for a defect). This is when you'd want to use fer002.java/.c and so on.
	The idea is to split whenever there the test is "thematically" different.

	Each test class must contain at least one sub-testcase and a corresponding help method.

		public boolean testSomething() {  return true; }

			The testSomething() method should return true on success and false on failure.


		public String helpSomething() { return "testSomething does something"; }

			The helpSomething() method should return a description of what the test does. The
			"Something" part of the help method name must match the "Something" part of the
			test method name. The presence of that method is MANDATORY.


		public boolean setup(String args) { return true; }

			The setup() method is optional and may be added to perform some common preparation
			required by all of the subtests. It takes a String argument containing the command
			line argument string passed via the -agentlib:args="abc" option.

		public boolean teardown() { return true; }

			An optional teardown method run after all of the subtests have been executed.


Adding new testcases
--------------------

	1) Start eclipse, open the Java perspective

	2) The com.ibm.jvmti.tests project has a number of packages nested under tests/jvmti/src. Create a
	   new package that follows the naming convention, ex: com.ibm.jvmti.tests.getSomethingOrOther.
	   Use the default Source Folder of "com.ibm.jvmti.tests/tests/jvmti/src"
	   The package leaf directory (com/ibm/jvmti/tests/getSomethingOrOther) will be used to store
	   both the Java and C agent code for your testcase.

	3) The java class that serves as the "entry point" to your testcase should be called using an
	   abbreviated name with a numeric postfix. In the case of this example we have "getSomethingOrOther"
	   -> gsoo001.java  (and gsoo001.c for the agent part if required). See "Testcase Packages".

		Create a class under your package naming it gsoo001.

		You can have more then one test classes in your package. Name them using consecutive numbers.

	4) Add a testcase to the class. The method name MUST start with 'test' and return a boolean.
	   Do not add methods that start with that prefix and are not testcases.

	   For ex:
	      public boolean testSomething() {  return true; }

	   You can have multiple testcases in your test class.

	5) Add a help method that returns a String describing the testcase. Similarly to the testcase
	   method, the help method MUST start with a 'help' prefix.

	   For ex:
	      public String helpSomething() { return "testSomething does something"; }

	  NOTE that a help method is mandatory.

	6) Add your C agent code in the same directory. Take a look at ioh001.c for a simple example.

	7) If your java code needs to call your native, add an export definition of the native to
	   tests/jvmti/module.xml  in the <exports> section

	8) Run UMA (see one of the prior sections for instructions) to generate updated makefiles

	9) Add a test definition to the tests/jvmti/agent/tests.c file (jvmtiTestList[] array).
	   You need to add one such definition per each test class in your package.
	   The test initialization function should have a prototype added to include/jvmti_test.h

	10) Run make to compile the C code. (NB run 'make phase_jvmti_tests')

	11) Copy the compiled library (ie: jvmtitest.dll on Windows or libjvmtitest.so on Linux) to
		INTREL_ROOT in order to be able to run the new tests.