Custom Relocation: documented command is wrong and a dotted RELOCATION_PREFIX fails the build

Hi! We tried Custom Relocation for our KMP library catrobat-ai-tutor in this PR to relocate Koin under our own org package. We got it working in the end, but only after adjusting the scripts, because the documented steps don't match what the scripts actually do.

Reporting it here since the feature is still in beta. Happy to open a PR for any of these.

Environment: Koin 3.5.6, JDK 17,
KOIN_MODULES=core/koin-core;android/koin-android

1. The documented command doesn't exist, and fails silently

The docs say:

./scripts/relocate.sh com.acme.sdk.internal.koin

There is no scripts/ folder: relocate.sh, clone_koin.sh, relocate-packages.sh and relocate-module.sh are all at the repo root.

relocate.sh also never reads its arguments. It only reads relocate.properties:

PROPERTIES_FILE="relocate.properties"
if [ ! -f "$PROPERTIES_FILE" ]; then
    echo "Error: Properties file '$PROPERTIES_FILE' not found!"
    exit 1
fi

So running the documented command exits 0 and relocates to whatever is in the properties file (relocated by default).

The README is correct here ("Just run ./relocate.sh"), it's the docs page that's out of sync.

Suggested fix: update the docs page to match the README, or have relocate.sh accept an optional prefix argument that overrides the properties file (the docs' interface is arguably the nicer one).

2. The documented example prefix would double the .koin segment

relocate-packages.sh appends .koin itself:

TARGET_PACKAGE="$RELOCATION_PREFIX.koin"

So using the docs' com.acme.sdk.internal.koin as the prefix produces com.acme.sdk.internal.koin.koin.*. The prefix needs to be com.acme.sdk.internal, which isn't stated anywhere.

Suggested fix: make it explicit in the docs that RELOCATION_PREFIX must not include .koin.

3. A dotted RELOCATION_PREFIX fails the build

This is the blocking one. RELOCATION_PREFIX is used both for the package name and for Gradle project names:

./relocate-module.sh ${KOIN_MODULE_PARTS[0]}/${KOIN_MODULE_PARTS[1]} $RELOCATION_PREFIX/$RELOCATION_PREFIX-${KOIN_MODULE_PARTS[1]}

Gradle requires project names to match [a-zA-Z]([A-Za-z0-9\-_])* so no dots. With RELOCATION_PREFIX=org.catrobat.aitutor.internal, install.sh fails:

* What went wrong:
org.gradle.api.InvalidUserDataException: Cannot generate project dependency accessors:
  - Cannot generate project dependency accessors because project
    'org.catrobat.aitutor.internal-koin-core' doesn't follow the naming convention:
    [a-zA-Z]([A-Za-z0-9\-_])*
  - Cannot generate project dependency accessors because project
    'org.catrobat.aitutor.internal-koin-android' doesn't follow the naming convention:
    [a-zA-Z]([A-Za-z0-9\-_])*
  - ... (one per module)

Most SDK namespaces are dotted, and the docs example is dotted too, so this affects the main use case. The prebuilt artifacts use embedded, which is a single word and is presumably why it hasn't come up.

Our workaround: a separate ARTIFACT_PREFIX key for the artifact/module naming, leaving RELOCATION_PREFIX for packages only.

RELOCATION_PREFIX=org.catrobat.aitutor.internal
ARTIFACT_PREFIX=aitutor

# relocate.sh
./relocate-module.sh ${KOIN_MODULE_PARTS[0]}/${KOIN_MODULE_PARTS[1]} $ARTIFACT_PREFIX/$ARTIFACT_PREFIX-${KOIN_MODULE_PARTS[1]}
...
cp -Rf ~/.m2/repository/io/insert-koin/$ARTIFACT_PREFIX* $BUILD_DIR

relocate.sh already exports every key it reads, so no other changes were needed. With that, the build succeeds and produces correctly relocated artifacts:

aitutor-koin-core-jvm-3.5.6.jar  -> 0 org/koin entries, 233 org/catrobat/aitutor/internal/koin
aitutor-koin-android-3.5.6.aar   -> 0 org/koin entries, 222 org/catrobat/aitutor/internal/koin
aitutor-koin-android-3.5.6.pom   -> depends on aitutor-koin-core

A default of RELOCATION_PREFIX with dots replaced by - would keep this backwards compatible.

--

Thanks for the project! The relocation itself works well once set up.

Read the custom relocation documentation alongside README, then inspect relocate.sh, relocate-packages.sh, relocate-module.sh and install.sh. Reproduce the documented command and a dotted RELOCATION_PREFIX, then verify that the documentation matches the scripts and the relocation build completes with valid package and artifact names.