Repository navigation
docs(emitters): state Kotlin's reserved sets for units - #1335
Open
OmarAlJarrah wants to merge 6 commits into
Open
OmarAlJarrah wants to merge 6 commits into
OmarAlJarrah wants to merge 6 commits into
Conversation
Kotlin's naming document stated only the members it gives every type, so a Kotlin emitter had no names to reserve for a group's module or for the declarations a unit holds beside the spec's, and T-19 no fixture. Measured with Kotlin 2.4.0 and Gradle 9.8.2: a module named build sits in the root project's output, which clean deletes with the module's sources; one named buildsrc is taken for Gradle's buildSrc on a case-insensitive file system and fails the build; gradle and src share the wrapper's and the root sources' directories. Those four are the units set, and a group's module is placed at the build root so the set applies. Hard keywords need no reservation: backticked as package segments they compile on the JVM, JS and Native and link into a framework, and kotlin is refused only as the first segment, which the options name. The unit set is Client, a group's sub-client and the runtime names the root unit declares.
This was referenced Nov 2, 2026
…into docs/emitters-kotlin-reserved-sets
…into docs/emitters-kotlin-reserved-sets
…into docs/emitters-kotlin-reserved-sets
…into docs/emitters-kotlin-reserved-sets
…into docs/emitters-kotlin-reserved-sets
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/emitters/refine/reserved-names.mdleaves three scopes to each target. Kotlin's naming document stated only the type scope, so a Kotlin emitter had nothing to reserve for a group's module or package (the units) or for what the SDK declares beside the spec's names in a unit, and T-19 had no fixture to name. The issue asked for a measured answer on what Gradle and kotlinc refuse, so each set below comes from a build, not from documentation.The units:
build,buildsrcin any letter case,gradle,src. These are the names Gradle gives a meaning at a build's root, where a group's module now explicitly sits (targets/kotlin/overview.md).buildlives inside the root project's output directory. It builds, butgradle cleanon the root deleted the module's sources.buildsrcfailed the build on macOS. Gradle found it asbuildSrc, its build-logic build, since the file system is case-insensitive.gradle(the wrapper and version catalog) andsrc(the root project's sources) built, but a module there shares their directory. They are reserved so that a later wrapper or root source file never lands inside a module.Not units names: hard keywords and
kotlin.packageand animport.fun,object,when,is,inandtypealiascompiled for the JVM, JS and macOS Native and linked into an Objective-C framework. Twelve more (class,val,interface,as,true,null,this,super,package,return,throw,try) compiled on the JVM. So keywords take the existing escape, and renaming them would be needless.kotlinonly as a package's first segment ("Only the Kotlin standard library is allowed to use the 'kotlin' package"). That segment is the root's, which the options name.probe.kotlincompiled.A unit:
Client, a group unit's sub-client, and the runtime names the root unit declares. These areApiFailure,ApiException,ClientException,ServerException, each taxonomy kind's exception,Fault,OtherResponse,OtherResponseException,Response,RawBody,Optional,Duration,AuthenticatorandTransport, plusDecimalandOffsetDateTimeon Multiplatform. That is every runtime type the Kotlin documents name. The list is held the way a function's bound names are: each runtime template declares what it declares, so it is derived from the templates rather than kept apart from them.T-19 now names a group after each units name, and requires that a Kotlin
cleanleave every module's sources.On the golden spec (spec @319dc756, morphic @b206dc99), no group's name normalizes to any units name but
shared, which the shared reservation already covers.Closes #1187
Test plan
compileKotlinJvm,compileKotlinJs,compileKotlinMacosArm64andlinkDebugFrameworkMacosArm64pass, and the header declares the classes;package kotlin.probefails with the error quoted above, andpackage probe.kotlincompiles;build,gradle,src,sharedandfunbuild;buildSrcandbuildsrcfail;gradle cleanon thebuildprobe removedbuild/src/main/kotlin.Stacked on #1334, so it lands after the other emitter-design PRs (#1329 ← #1331 ← #1332 ← #1334). It edits
targets/kotlinand T-19 only. After each base lands, "Update branch" is a merge ofmainthat conflicts nowhere.