RFC: CPM_<dependency>_SOURCE precedence policy (explicit vs env)

[CraigHutchinson]

Decision requested first

Choose one policy direction for future consistency, specifically around CPM_<dependency>_SOURCE:

1. Standardize cascading precedence (explicit -> env -> default) where applicable.
2. Keep environment influence behind explicit opt-in gates for selected features.

Specifically related to the gap #406 and the rebased #696 intend to address.

Why this matters

• CPM_<dependency>_SOURCE is currently explicit-only and is the main outlier compared with adjacent CPM_* controls.
• CPM already has a mixed set of precedence patterns that are useful but not always obvious.
• Some IDE and indirect-build workflows cannot reliably inject explicit -D... arguments.
• Explicit-only users prioritize predictability/debuggability.
• Environment-driven users prioritize practical control across many builds.

Master inventory table (current runtime CPM_* controls)

Control	Explicit input available	Environment path	Effective pattern today	Alignment note
CPM_USE_LOCAL_PACKAGES	Yes	Yes	Env-seeded option default, explicit can override	Aligned
CPM_LOCAL_PACKAGES_ONLY	Yes	Yes	Env-seeded option default, explicit can override	Aligned
CPM_DOWNLOAD_ALL	Yes	Yes	Env-seeded option default, explicit can override	Aligned
CPM_DONT_UPDATE_MODULE_PATH	Yes	Yes	Env-seeded option default, explicit can override	Aligned
CPM_DONT_CREATE_PACKAGE_LOCK	Yes	Yes	Env-seeded option default, explicit can override	Aligned
CPM_INCLUDE_ALL_IN_PACKAGE_LOCK	Yes	Yes	Env-seeded option default, explicit can override	Aligned
CPM_USE_NAMED_CACHE_DIRECTORIES	Yes	Yes	Env-seeded option default, explicit can override	Aligned
CPM_SOURCE_CACHE (main CPM)	Yes	Yes	Explicit/cache var, env fallback via default seed	Aligned
CPM_SOURCE_CACHE (get_cpm.cmake)	Yes	Yes	Explicit var -> env -> built-in path	Aligned
CPM_DOWNLOAD_<name>	Yes	Yes	Per-package explicit -> env fallback	Aligned
CPM_<dependency>_SOURCE	Yes	No (today)	Explicit-only manual override	Primary alignment gap

Inventory result

• Exhaustive scan of runtime CPM_* env usage on current master found no env-only controls.
• Main consistency gap is CPM_<dependency>_SOURCE being explicit-only while adjacent controls already support explicit+env patterns.

Scope

• No runtime code changes in this PR
• No behavior changes
• RFC/policy discussion only

Points of interest (for quick discussion)

• Setting CPM_SOURCE_ROOT from the environment #82
• Add CPM_SOURCE_CACHE environmental variable support and keep existing sources #83
• Support CPM_SOURCE_CACHE on windows #109
• Add option for local package override #123
• CPMAddPackage: Parameter EXCLUDE_FROM_ALL has no effect when Local package override is given on the cmdline #260
• Forward exclude and subdir options when using local package override #261
• Support CPM_<dependency name>_SOURCE local package override from ENV #406
• Allow users to override the default path for CPM_SOURCE_CACHE #669
• Users in enterprise environments require the ability to add custom URI schemes and override standard URI schemes #564
• Implementation of "Users in enterprise environments require the ability to add custom URI schemes and override standard URI schemes" #567

[TheLartians]

Hey @CraigHutchinson thanks for opening this discussion and the related code change! I see the inconsistency in the way CPM_<dependency>_SOURCE is treated. My main concern with this specific parameter is the high impact it has when set to an unexpected source and the environment is usually not very transparent. However I see the advantages in being able to override this from the env just like the other parameters listed.

Given that's it's expected to be used in development setups only, how about we emit a warning whenever CPM_${CPM_ARGS_NAME}_SOURCE is specified (either from a variable or the env)? That way such overrides would at least be very visible to the developer when configuring a project and mitigating the risk of building a project with an unexpected dependency.

[CraigHutchinson]

Thanks, it's been a bug bear in using cpm for me for a long time and realising it was just an inconsistency was a revelation!

I really love the idea of emitting the message if it helps move things forwards for consistency and will see about getting a chance to update this week.

The other (somewhat dirty) idea was having a global config flag somehwere (use/don't use env first) - so you could project wide disable use of env/dev sources etc. I think this could be something very separate though on an as needed basis as not sure if it's ever really an issue for any real work flow and atm feels overengineered!

As another as side, I did try and check to see if there are other consustency/method consistency architecture decisions that could be made to ensure the cpm 'api' remains relevant across use cases - not spotted any so far.