Require "-Xuse-experimental=kotlin.Experimental" on usages of Experimental

Since we're not yet sure of the design of Experimental/UseExperimental,
we're making them "experimental" themselves in some sense, in that the
user is required to provide the magic argument
"-Xuse-experimental=kotlin.Experimental" to be allowed to use either
Experimental or UseExperimental. This is more convenient than the
previous approach of "-language-version 1.3
-Xskip-metadata-version-check" because it's simpler and does not cause
pre-release binaries to be produced
This commit is contained in:
Alexander Udalov
2018-04-27 14:11:57 +02:00
parent 2a61d42fc1
commit c57864e46c
41 changed files with 121 additions and 85 deletions
@@ -240,6 +240,7 @@ public interface Errors {
DiagnosticFactory2<PsiElement, FqName, DeclarationDescriptor> EXPERIMENTAL_OVERRIDE = DiagnosticFactory2.create(WARNING);
DiagnosticFactory2<PsiElement, FqName, DeclarationDescriptor> EXPERIMENTAL_OVERRIDE_ERROR = DiagnosticFactory2.create(ERROR);
DiagnosticFactory0<PsiElement> EXPERIMENTAL_IS_NOT_ENABLED = DiagnosticFactory0.create(ERROR);
DiagnosticFactory0<KtAnnotationEntry> USE_EXPERIMENTAL_WITHOUT_ARGUMENTS = DiagnosticFactory0.create(WARNING);
DiagnosticFactory1<KtAnnotationEntry, FqName> USE_EXPERIMENTAL_ARGUMENT_IS_NOT_MARKER = DiagnosticFactory1.create(WARNING);
DiagnosticFactory1<KtAnnotationEntry, String> EXPERIMENTAL_ANNOTATION_WITH_WRONG_TARGET = DiagnosticFactory1.create(ERROR);
@@ -146,6 +146,7 @@ public class DefaultErrorMessages {
MAP.put(EXPERIMENTAL_OVERRIDE, "This declaration overrides experimental member of supertype ''{1}'' and should be annotated with ''@{0}''", TO_STRING, NAME);
MAP.put(EXPERIMENTAL_OVERRIDE_ERROR, "This declaration overrides experimental member of supertype ''{1}'' and must be annotated with ''@{0}''", TO_STRING, NAME);
MAP.put(EXPERIMENTAL_IS_NOT_ENABLED, "This class can only be used with the compiler argument '-Xuse-experimental=kotlin.Experimental'");
MAP.put(USE_EXPERIMENTAL_WITHOUT_ARGUMENTS, "@UseExperimental without any arguments has no effect");
MAP.put(USE_EXPERIMENTAL_ARGUMENT_IS_NOT_MARKER, "Annotation ''{0}'' is not an experimental API marker, therefore its usage in @UseExperimental is ignored", TO_STRING);
MAP.put(EXPERIMENTAL_ANNOTATION_WITH_WRONG_TARGET, "Experimental annotation cannot be used on the following code elements: {0}. Please remove these targets", STRING);
@@ -37,6 +37,7 @@ import org.jetbrains.kotlin.resolve.constants.EnumValue
import org.jetbrains.kotlin.resolve.constants.KClassValue
import org.jetbrains.kotlin.resolve.descriptorUtil.annotationClass
import org.jetbrains.kotlin.resolve.descriptorUtil.fqNameSafe
import org.jetbrains.kotlin.resolve.descriptorUtil.fqNameUnsafe
import org.jetbrains.kotlin.resolve.descriptorUtil.module
import org.jetbrains.kotlin.storage.LockBasedStorageManager
import org.jetbrains.kotlin.utils.SmartSet
@@ -67,6 +68,9 @@ class ExperimentalUsageChecker(project: Project) : CallChecker {
private val WARNING_LEVEL = Name.identifier("WARNING")
private val ERROR_LEVEL = Name.identifier("ERROR")
private val EXPERIMENTAL_SHORT_NAME = EXPERIMENTAL_FQ_NAME.shortName()
private val USE_EXPERIMENTAL_SHORT_NAME = USE_EXPERIMENTAL_FQ_NAME.shortName()
private fun reportNotAcceptedExperimentalities(
experimentalities: Collection<Experimentality>, element: PsiElement, context: CheckerContext
) {
@@ -196,7 +200,9 @@ class ExperimentalUsageChecker(project: Project) : CallChecker {
}
val validExperimental = languageVersionSettings.getFlag(AnalysisFlag.experimental).filter(::checkAnnotation)
val validUseExperimental = languageVersionSettings.getFlag(AnalysisFlag.useExperimental).filter(::checkAnnotation)
val validUseExperimental = languageVersionSettings.getFlag(AnalysisFlag.useExperimental).filter { fqName ->
fqName == EXPERIMENTAL_FQ_NAME.asString() || checkAnnotation(fqName)
}
for (fqName in validExperimental.intersect(validUseExperimental)) {
reportError("'-Xuse-experimental=$fqName' has no effect because '-Xexperimental=$fqName' is used")
@@ -208,9 +214,24 @@ class ExperimentalUsageChecker(project: Project) : CallChecker {
private val moduleAnnotationsResolver = ModuleAnnotationsResolver.getInstance(project)
override fun check(targetDescriptor: ClassifierDescriptor, element: PsiElement, context: ClassifierUsageCheckerContext) {
val name = targetDescriptor.name
if (name == EXPERIMENTAL_SHORT_NAME || name == USE_EXPERIMENTAL_SHORT_NAME) {
val fqName = targetDescriptor.fqNameUnsafe
if (fqName == EXPERIMENTAL_FQ_NAME.toUnsafe() || fqName == USE_EXPERIMENTAL_FQ_NAME.toUnsafe()) {
checkUsageOfKotlinExperimentalOrUseExperimental(element, context)
return
}
}
val experimentalities = targetDescriptor.loadExperimentalities(moduleAnnotationsResolver)
reportNotAcceptedExperimentalities(experimentalities, element, context)
}
private fun checkUsageOfKotlinExperimentalOrUseExperimental(element: PsiElement, context: CheckerContext) {
if (EXPERIMENTAL_FQ_NAME.asString() !in context.languageVersionSettings.getFlag(AnalysisFlag.useExperimental)) {
context.trace.report(Errors.EXPERIMENTAL_IS_NOT_ENABLED.on(element))
}
}
}
class Overrides(project: Project) : DeclarationChecker {
@@ -1,8 +1,6 @@
$TESTDATA_DIR$/experimentalAndUseExperimentalWithSameAnnotation.kt
-d
$TEMP_DIR$
-Xskip-runtime-version-check
-language-version
1.3
-Xuse-experimental=kotlin.Experimental
-Xexperimental=org.test.ExperimentalAPI
-Xuse-experimental=org.test.ExperimentalAPI
@@ -1,3 +1,2 @@
warning: language version 1.3 is experimental, there are no backwards compatibility guarantees for new language and library features
error: '-Xuse-experimental=org.test.ExperimentalAPI' has no effect because '-Xexperimental=org.test.ExperimentalAPI' is used
COMPILATION_ERROR
+1 -3
View File
@@ -1,9 +1,7 @@
$TESTDATA_DIR$/experimentalDeprecated.kt
-d
$TEMP_DIR$
-Xskip-runtime-version-check
-language-version
1.3
-Xuse-experimental=kotlin.Experimental
-Xexperimental=org.test.Error1
-Xexperimental=org.test.Hidden1
-Xuse-experimental=org.test.Error2
-1
View File
@@ -1,4 +1,3 @@
warning: language version 1.3 is experimental, there are no backwards compatibility guarantees for new language and library features
error: experimental API marker org.test.Error1 is deprecated. Error1
error: experimental API marker org.test.Hidden1 is deprecated. Hidden1
error: experimental API marker org.test.Error2 is deprecated. Error2
@@ -1,8 +1,6 @@
$TESTDATA_DIR$/experimentalDeprecatedWarning.kt
-d
$TEMP_DIR$
-Xskip-runtime-version-check
-language-version
1.3
-Xuse-experimental=kotlin.Experimental
-Xuse-experimental=org.test.Warning1
-Xexperimental=org.test.Warning2
@@ -1,4 +1,3 @@
warning: language version 1.3 is experimental, there are no backwards compatibility guarantees for new language and library features
warning: experimental API marker org.test.Warning2 is deprecated. Warning2
warning: experimental API marker org.test.Warning1 is deprecated. Warning1
OK
+1 -3
View File
@@ -1,7 +1,5 @@
$TESTDATA_DIR$/experimentalNested.kt
-d
$TEMP_DIR$
-Xskip-runtime-version-check
-language-version
1.3
-Xuse-experimental=kotlin.Experimental
-Xexperimental=org.test.Outer.Nested
-1
View File
@@ -1,2 +1 @@
warning: language version 1.3 is experimental, there are no backwards compatibility guarantees for new language and library features
OK
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// !DIAGNOSTICS: -UNUSED_PARAMETER
// FILE: api.kt
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// FILE: api.kt
package api
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// FILE: api.kt
package api
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// FILE: api.kt
package api
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// FILE: api.kt
package api
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// FILE: api.kt
package api
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// FILE: api.kt
package api
@@ -0,0 +1,23 @@
// FILE: api.kt
@<!EXPERIMENTAL_IS_NOT_ENABLED!>Experimental<!>
annotation class Marker
@Marker
fun f() {}
// FILE: usage.kt
fun use1() {
<!EXPERIMENTAL_API_USAGE_ERROR!>f<!>()
}
@Marker
fun use2() {
f()
}
@<!EXPERIMENTAL_IS_NOT_ENABLED!>UseExperimental<!>(Marker::class)
fun use3() {
f()
}
@@ -0,0 +1,13 @@
package
@Marker public fun f(): kotlin.Unit
public fun use1(): kotlin.Unit
@Marker public fun use2(): kotlin.Unit
@kotlin.UseExperimental(markerClass = {Marker::class}) public fun use3(): kotlin.Unit
@kotlin.Experimental public final annotation class Marker : kotlin.Annotation {
public constructor Marker()
public open override /*1*/ /*fake_override*/ fun equals(/*0*/ other: kotlin.Any?): kotlin.Boolean
public open override /*1*/ /*fake_override*/ fun hashCode(): kotlin.Int
public open override /*1*/ /*fake_override*/ fun toString(): kotlin.String
}
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// !EXPERIMENTAL: api.ExperimentalAPI
// MODULE: api
// FILE: api.kt
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// FILE: api.kt
package api
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
<!USE_EXPERIMENTAL_WITHOUT_ARGUMENTS!>@UseExperimental<!>
fun f1() {}
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// FILE: api.kt
package api
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
@Experimental(Experimental.Level.WARNING)
annotation class E1
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// !DIAGNOSTICS: -UNUSED_VARIABLE
// FILE: api.kt
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// !DIAGNOSTICS: -UNUSED_VARIABLE
// FILE: api.kt
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// FILE: api.kt
package api
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// FILE: api.kt
package api
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// FILE: api.kt
package api
@@ -1,5 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: api.ExperimentalAPI
// !USE_EXPERIMENTAL: kotlin.Experimental api.ExperimentalAPI
// MODULE: api
// FILE: api.kt
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// !DIAGNOSTICS: -UNUSED_PARAMETER
// FILE: api.kt
@@ -1,4 +1,4 @@
// !API_VERSION: 1.3
// !USE_EXPERIMENTAL: kotlin.Experimental
// FILE: api.kt
package api
@@ -2112,6 +2112,11 @@ public class DiagnosticsTestWithStdLibGenerated extends AbstractDiagnosticsTestW
runTest("compiler/testData/diagnostics/testsWithStdLib/experimental/errors.kt");
}
@TestMetadata("experimentalIsNotEnabled.kt")
public void testExperimentalIsNotEnabled() throws Exception {
runTest("compiler/testData/diagnostics/testsWithStdLib/experimental/experimentalIsNotEnabled.kt");
}
@TestMetadata("experimentalOnWholeModule.kt")
public void testExperimentalOnWholeModule() throws Exception {
runTest("compiler/testData/diagnostics/testsWithStdLib/experimental/experimentalOnWholeModule.kt");
@@ -2112,6 +2112,11 @@ public class DiagnosticsTestWithStdLibUsingJavacGenerated extends AbstractDiagno
runTest("compiler/testData/diagnostics/testsWithStdLib/experimental/errors.kt");
}
@TestMetadata("experimentalIsNotEnabled.kt")
public void testExperimentalIsNotEnabled() throws Exception {
runTest("compiler/testData/diagnostics/testsWithStdLib/experimental/experimentalIsNotEnabled.kt");
}
@TestMetadata("experimentalOnWholeModule.kt")
public void testExperimentalOnWholeModule() throws Exception {
runTest("compiler/testData/diagnostics/testsWithStdLib/experimental/experimentalOnWholeModule.kt");
@@ -97,9 +97,7 @@ class JvmModuleProtoBufTest : KtUsefulTestCase() {
fun testExperimental() {
doTest(
"/moduleProtoBuf/experimental", extraOptions = listOf(
"-Xskip-runtime-version-check",
"-language-version",
"1.3",
"-Xuse-experimental=kotlin.Experimental",
"-Xexperimental=org.foo.A",
"-Xexperimental=org.foo.B.C",
"-Xuse-experimental=org.foo.D"
@@ -15,29 +15,22 @@ class ExperimentalIntegrationTest : AbstractKotlinCompilerIntegrationTest() {
fun testJvmExperimentalModule() {
val lib = compileLibrary(
"lib", additionalOptions = listOf(
"-Xskip-runtime-version-check",
"-language-version",
"1.3",
"-Xuse-experimental=kotlin.Experimental",
"-Xexperimental=lib.ExperimentalAPI"
),
checkKotlinOutput = { output -> assertTrue(output, output.trimEnd().endsWith("OK")) }
)
compileKotlin("usage.kt", tmpdir, listOf(lib), additionalOptions = listOf("-Xskip-metadata-version-check"))
compileKotlin("usage.kt", tmpdir, listOf(lib))
}
fun testJsExperimentalModule() {
val lib = compileJsLibrary(
"lib", additionalOptions = listOf(
"-Xskip-runtime-version-check",
"-language-version",
"1.3",
"-Xuse-experimental=kotlin.Experimental",
"-Xexperimental=lib.ExperimentalAPI"
),
checkKotlinOutput = { output -> assertTrue(output, output.trimEnd().endsWith("OK")) }
)
compileKotlin(
"usage.kt", File(tmpdir, "usage.js"), listOf(lib), K2JSCompiler(),
additionalOptions = listOf("-Xskip-metadata-version-check")
)
compileKotlin("usage.kt", File(tmpdir, "usage.js"), listOf(lib), K2JSCompiler())
}
}
@@ -33,7 +33,6 @@ import org.jetbrains.kotlin.cli.common.arguments.K2JVMCompilerArguments
import org.jetbrains.kotlin.config.LanguageVersion
import org.jetbrains.kotlin.idea.caches.project.ModuleSourceInfo
import org.jetbrains.kotlin.idea.caches.project.SdkInfo
import org.jetbrains.kotlin.idea.compiler.configuration.KotlinCommonCompilerArgumentsHolder
import org.jetbrains.kotlin.idea.completion.test.withServiceRegistered
import org.jetbrains.kotlin.idea.facet.KotlinFacetConfiguration
import org.jetbrains.kotlin.idea.facet.KotlinFacetType
@@ -218,42 +217,24 @@ open class MultiModuleHighlightingTest : AbstractMultiModuleHighlightingTest() {
val lib = MockLibraryUtil.compileJvmLibraryToJar(
testDataPath + "${getTestName(true)}/lib", "lib",
extraOptions = listOf(
"-Xskip-runtime-version-check",
"-language-version",
"1.3",
"-Xuse-experimental=kotlin.Experimental",
"-Xexperimental=lib.ExperimentalAPI"
)
)
withSkipMetadataVersionCheck {
module("usage").addLibrary(lib)
checkHighlightingInAllFiles()
}
module("usage").addLibrary(lib)
checkHighlightingInAllFiles()
}
fun testJsExperimentalLibrary() {
val lib = MockLibraryUtil.compileJsLibraryToJar(
testDataPath + "${getTestName(true)}/lib", "lib", false,
extraOptions = listOf(
"-Xskip-runtime-version-check",
"-language-version",
"1.3",
"-Xuse-experimental=kotlin.Experimental",
"-Xexperimental=lib.ExperimentalAPI"
)
)
withSkipMetadataVersionCheck {
module("usage").addLibrary(lib, kind = JSLibraryKind)
checkHighlightingInAllFiles()
}
}
private fun withSkipMetadataVersionCheck(block: () -> Unit) {
val holder = KotlinCommonCompilerArgumentsHolder.getInstance(project)
try {
holder.update { skipMetadataVersionCheck = true }
block()
} finally {
holder.update { skipMetadataVersionCheck = false }
}
module("usage").addLibrary(lib, kind = JSLibraryKind)
checkHighlightingInAllFiles()
}
private fun Module.setupKotlinFacet(configure: KotlinFacetConfiguration.() -> Unit) = apply {
+5 -5
View File
@@ -176,8 +176,8 @@ task compileJs(type: JavaExec) {
doFirst {
args = [jsOutputFile, rootDir, "$jsSrcDir/wrapper.js"] + inputFiles.collect { it.path }.sort() +
(compileBuiltinsKotlin2Js.outputs.files.collect { it.path }.sort() +
compileKotlin2Js.outputs.files.collect { it.path }.sort() +
compileExperimentalKotlin2Js.outputs.files.collect { it.path }.sort()).findAll {
compileKotlin2Js.outputs.files.collect { it.path }.sort() /* +
compileExperimentalKotlin2Js.outputs.files.collect { it.path }.sort() */).findAll {
it.endsWith(".js") && !it.endsWith(".meta.js")
}
}
@@ -223,9 +223,9 @@ task compileJs(type: JavaExec) {
sourceMapFile.text = groovy.json.JsonOutput.toJson(sourceMap)
file(jsOutputMetaFile).text = file(compileKotlin2Js.outputFile.path.replaceAll('\\.js$', '.meta.js')).text +
file(jsOutputMetaFile).text = file(compileKotlin2Js.outputFile.path.replaceAll('\\.js$', '.meta.js')).text /* +
file(compileExperimentalKotlin2Js.outputFile.path.replaceAll('\\.js$', '.meta.js')).text
.replaceFirst(experimentalJsModuleName, 'kotlin')
.replaceFirst(experimentalJsModuleName, 'kotlin') */
}
}
@@ -357,4 +357,4 @@ task runMocha(type: NodeTask, dependsOn: [testClasses, installMocha, ':kotlin-te
}
}
test.dependsOn runMocha
test.dependsOn runMocha
@@ -8,16 +8,21 @@ package kotlin
import kotlin.annotation.AnnotationRetention.BINARY
import kotlin.annotation.AnnotationRetention.SOURCE
import kotlin.annotation.AnnotationTarget.*
import kotlin.internal.RequireKotlin
import kotlin.internal.RequireKotlinVersionKind
import kotlin.reflect.KClass
/**
* Signals that the annotated annotation class is a marker of an experimental API. Any declaration annotated with that marker is thus
* considered an experimental declaration and its call sites should accept the experimental aspect of it either by using [UseExperimental],
* or by being annotated with that marker themselves, effectively causing further propagation of that experimental aspect.
*
* This class is experimental itself and can only be used with the compiler argument `-Xuse-experimental=kotlin.Experimental`.
*/
@Target(ANNOTATION_CLASS)
@Retention(BINARY)
@SinceKotlin("1.3")
@SinceKotlin("1.2")
@RequireKotlin("1.2.50", versionKind = RequireKotlinVersionKind.COMPILER_VERSION)
@Suppress("ANNOTATION_CLASS_MEMBER")
annotation class Experimental(val level: Level = Level.ERROR) {
/**
@@ -35,10 +40,13 @@ annotation class Experimental(val level: Level = Level.ERROR) {
/**
* Allows to use experimental API denoted by the given markers in the annotated file, declaration, or expression.
* If a declaration is annotated with [UseExperimental], its usages are **not** required to opt-in to that experimental API.
*
* This class is experimental itself and can only be used with the compiler argument `-Xuse-experimental=kotlin.Experimental`.
*/
@Target(CLASS, PROPERTY, LOCAL_VARIABLE, VALUE_PARAMETER, CONSTRUCTOR, FUNCTION, PROPERTY_GETTER, PROPERTY_SETTER, EXPRESSION, FILE)
@Retention(SOURCE)
@SinceKotlin("1.3")
@SinceKotlin("1.2")
@RequireKotlin("1.2.50", versionKind = RequireKotlinVersionKind.COMPILER_VERSION)
annotation class UseExperimental(
vararg val markerClass: KClass<out Annotation>
)
@@ -35,7 +35,7 @@ class RuntimePublicAPITest {
@Test fun kotlinStdlibRuntimeMerged() {
snapshotAPIAndCompare(
"../../stdlib/jvm/build/libs", "kotlin-stdlib",
listOf("../stdlib-declarations.json", "../stdlib-experimental-declarations.json"),
listOf("../stdlib-declarations.json"/*, "../stdlib-experimental-declarations.json"*/),
listOf("kotlin.jvm.internal")
)
}