Stale module resolution after repository restore in Ceylon

Question

Local Repository Metadata Consistency
Ceylon utilizes a local repository (typically ~/.ceylon/repo) to store compiled module artifacts. When restoring this repository from a backup to maintain build reproducibility or migrate environments, the directory structure is restored to its original location to allow the toolchain to locate dependencies.
While the physical artifacts are restored, there is uncertainty regarding the behavior of the internal metadata cache. If the restored repository contains metadata files that do not align with the current environment or if the cache is not automatically invalidated upon restoration, the toolchain may attempt to resolve modules using stale data.
Given that the toolchain lacks a dedicated automated verification command for repository integrity, it is unclear how the system handles these cached states during a manual restore process.

Does the Ceylon toolchain automatically detect and refresh the internal metadata cache after a repository restoration?
Is a manual clearing of the .ceylon metadata files required to prevent stale module resolution?

Tasadduq Burney · Answer

Direct Answer
The Ceylon CLI does not maintain a persistent metadata cache or index for the local repository (~/.ceylon/repo). Module resolution walks the repository filesystem at each invocation, reading descriptor files and .car archives directly. Restoring the repository tree to its original path makes the modules visible on the next command without any cache-clearing step.
Do not delete .ceylon descriptor files inside the restored repository. Those files are part of the published module artifact; removing them breaks resolution for that module.

Where Stale Resolution Actually Comes From

Cache repository (~/.ceylon/cache): holds modules downloaded from remote repositories. If the same module+version exists in both the restored local repo and the cache, the resolver may pick the cached copy depending on repository priority in ~/.ceylon/config.
Repository overrides in config: a repositories section that reorders or adds remotes can change which source wins.
IDE or long-running build process: an IDE that indexed the repo before the restore holds in-memory module models until refreshed or restarted.

Steps to Verify a Clean Restore

Confirm each module directory in the restored tree contains its descriptor, .car, and (if present) source archive from the same backup generation. Mixed generations cause descriptor/archive mismatches.
Run a resolution-only command (e.g., ceylon info com.example/1.0.0 on versions that support it) and check the reported repository path—it should point at the restored local repo, not the cache.
Compile a tiny module that depends on a restored module. Then temporarily rename ~/.ceylon/cache and repeat; the resolved version and repository should not change.
If using an IDE, use its repository-refresh action and restart the workspace before trusting displayed versions.

One Diagnostic Detail That Changes the Recommendation
Which Ceylon version (1.1, 1.2, or 1.3.x) and whether you are invoking the CLI directly or relying on an IDE/build-tool integration? The exact repository priority defaults and ceylon info availability differ across versions, and IDEs introduce their own caching layer.

Stale module resolution after repository restore in Ceylon

Local Repository Metadata Consistency

1 answer

Direct Answer

Where Stale Resolution Actually Comes From

Steps to Verify a Clean Restore

One Diagnostic Detail That Changes the Recommendation

Your perspective belongs here.

0 question comments