88 lines
4.8 KiB
Java
88 lines
4.8 KiB
Java
/*
|
|
* Copyright (c) 2021, 2022, Oracle and/or its affiliates. All rights reserved.
|
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
*
|
|
* This code is free software; you can redistribute it and/or modify it
|
|
* under the terms of the GNU General Public License version 2 only, as
|
|
* published by the Free Software Foundation.
|
|
*
|
|
* This code is distributed in the hope that it will be useful, but WITHOUT
|
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
* version 2 for more details (a copy is included in the LICENSE file that
|
|
* accompanied this code).
|
|
*
|
|
* You should have received a copy of the GNU General Public License version
|
|
* 2 along with this work; if not, write to the Free Software Foundation,
|
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
*
|
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
* or visit www.oracle.com if you need additional information or have any
|
|
* questions.
|
|
*/
|
|
|
|
package compiler.lib.ir_framework;
|
|
|
|
import java.lang.annotation.Retention;
|
|
import java.lang.annotation.RetentionPolicy;
|
|
|
|
/**
|
|
* Annotate all methods in your test class which the framework should test with {@code @Test}.
|
|
* <p>
|
|
* Let {@code m} be a test method specifying the {@code @Test} annotation. If {@code m} is neither part of a
|
|
* <b>checked test</b> (an additional method specifying {@link Check @Check} with {@code @Check(test = "m")}) nor part
|
|
* of a <b>custom run test</b> (an additional method specifying {@link Run @Run} with {@code @Run(test = "m")}),
|
|
* then {@code m} is a so-called <b>base test</b> and the framework invokes {@code m} in the following way:
|
|
* <ol>
|
|
* <li><p>The framework warms {@code m} up by invoking it for a predefined number of iterations (default: 2000)
|
|
* or any number specified by an additional {@link Warmup @Warmup} annotation at {@code m} or by using
|
|
* {@link TestFramework#setDefaultWarmup(int)} (could also be 0 which skips the warm-up completely which is similar
|
|
* to simulating {@code -Xcomp}). More information about the warm-up in general can be found at {@link Warmup}</li>
|
|
* <li><p>After the warm-up, the framework compiles {@code m} at the specified compilation level set by
|
|
* {@link #compLevel()} (default {@link CompLevel#ANY} will pick the highest available level which is usually
|
|
* {@link CompLevel#C2}).</li>
|
|
* <li><p>The framework invokes {@code m} one more time to run the compilation.</li>
|
|
* <li><p>The framework checks any specified {@link IR @IR} constraints at {@code m}. More information about IR matching
|
|
* can be found at {@link IR}.</li>
|
|
* </ol>
|
|
*
|
|
* <p>
|
|
* {@code m} has the following properties:
|
|
* <ul>
|
|
* <li><p>If {@code m} specifies no parameters, the framework can directly invoke {@code m}.</li>
|
|
* <li><p>If {@code m} specifies parameters, the framework needs to know how to invoke {@code m}. Use {@link Arguments}
|
|
* with {@link Argument} properties for each parameter to use well-defined parameters by the framework. If the method
|
|
* requires a more specific argument value, use a custom run test (see {@link Run}).</li>
|
|
* <li><p>{@code m} cannot specify {@link AbstractInfo} or any of its subclasses as parameter or return type.</li>
|
|
* <li><p>{@code m} is not inlined by the framework.</li>
|
|
* <li><p>Verification of the return value of {@code m} can only be done in a checked test (see {@link Check}) or
|
|
* custom run test (see {@link Run}).</li>
|
|
* </ul>
|
|
*
|
|
* <p>
|
|
* The following constraints must be met for the test method {@code m} specifying {@code @Test}:
|
|
* <ul>
|
|
* <li><p>{@code m} must be part of the test class. Using {@code @Test} in nested or helper classes is not allowed.</li>
|
|
* <li><p>{@code m} cannot have the same name as another {@code @Test} method in the same test class. Method
|
|
* overloading is only allowed (but not encouraged) with other non-{@code @Test} methods.</li>
|
|
* <li><p>{@code m} cannot specify any helper-method-specific compile command annotations
|
|
* ({@link ForceCompile @ForceCompile}, {@link DontCompile @DontCompile}, {@link ForceInline @ForceInline},
|
|
* {@link DontInline @DontInline}). </li>
|
|
* </ul>
|
|
*
|
|
* <p>
|
|
* Examples on how to write base tests can be found in {@link ir_framework.examples.BaseTestExample}
|
|
* and also as part of the internal testing in the package {@link ir_framework.tests}.
|
|
*
|
|
* @see Arguments
|
|
*/
|
|
@Retention(RetentionPolicy.RUNTIME)
|
|
public @interface Test {
|
|
/**
|
|
* Specify at which compilation level the framework should eventually compile the test method after an optional
|
|
* warm-up period. The default {@link CompLevel#ANY} will let the framework compile the method at the highest
|
|
* available level which is usually {@link CompLevel#C2}.
|
|
*/
|
|
CompLevel compLevel() default CompLevel.ANY;
|
|
}
|