Use Preferences.jl for compile-time CPU configuration

[ChrisRackauckas-Claude]

Summary

This PR replaces the runtime __init__ function configuration with compile-time preferences using Preferences.jl, as requested in the issue. This allows users to override CPU detection values at compile time rather than runtime.

Changes

• Added Preferences.jl as a dependency
• Modified the __init__ function to remove runtime evaluation (lines 55-69)
• Load preferences at compile time before including platform-specific files
• Conditionally define functions based on whether preferences are set
• Added set_cpu_preferences() function for user convenience
• Updated both x86.jl and generic_topology.jl to respect preferences

Key Benefits

1. Eliminates runtime overhead - No more @eval in __init__
2. Better optimization opportunities - Values are known at compile time
3. Backward compatible - Works exactly as before when no preferences are set
4. User-friendly API - Simple function to set preferences

Usage Example

using CPUSummary, Preferences

# Set custom CPU configuration
CPUSummary.set_cpu_preferences(num_cores=8, num_l1cache=8, sys_threads=16)

# Restart Julia or trigger recompilation for changes to take effect

Testing

• ✅ Tests pass with default values (no preferences set)
• ✅ Preferences correctly override detection when set
• ✅ Code formatted with JuliaFormatter using SciMLStyle

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 61.53846% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 8.06%. Comparing base (10e48a2) to head (9bdb075).
⚠️ Report is 22 commits behind head on main.

Files with missing lines	Patch %	Lines
src/x86.jl	66.66%	3 Missing ⚠️
src/generic_topology.jl	50.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff            @@
##             main     #31      +/-   ##
=========================================
- Coverage   16.74%   8.06%   -8.69%     
=========================================
  Files           5       5              
  Lines         209     186      -23     
=========================================
- Hits           35      15      -20     
+ Misses        174     171       -3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[maleadt]

Do we actually need the configurability (to set the number of threads, etc) or would it suffice to have something like #ifdef TRIMMING to switch to a generic, trim-compatible fallback?

[ChrisRackauckas]

Test Summary: | Pass  Fail  Total  Time
All           |    4     1      5  1.1s
  part1       |    1            1  0.0s
  part2       |    1            1  0.0s
  part3       |    1            1  0.0s
  part4       |          1      1  1.0s
  part5       |    1            1  0.0s

Part 4 Loopvectorization fails downstream JuliaSIMD/LoopVectorization.jl#551.

Test Summary:                                                         |    Pass  Fail    Total      Time
VectorizationBase.jl                                                  | 2306732     2  2306734  13m55.3s
  Method ambiguity                                                    |       1              1      7.4s
  Unbound type parameters                                             |       1              1      0.1s
  Undefined exports                                                   |       1              1      0.0s
  Compare Project.toml and test/Project.toml                          |       1              1      0.1s
  Stale dependencies                                                  |       1              1      1.4s
  Compat bounds                                                       |       3     1        4      1.8s
    julia                                                             |       1              1      0.0s
    VectorizationBase [3d5dd08c-fd9d-11e8-17fa-ed28[360](https://github.com/JuliaSIMD/VectorizationBase.jl/actions/runs/16806503903/job/47600211991?pr=120#step:6:363)48c2f] deps     |       1              1      0.1s
    VectorizationBase [3d5dd08c-fd9d-11e8-17fa-ed2836048c2f] extras   |             1        1      1.7s
    VectorizationBase [3d5dd08c-fd9d-11e8-17fa-ed2836048c2f] weakdeps |       1              1      0.0s
  Piracy                                                              |             1        1      0.3s
  Persistent tasks                                                    |       1              1      5.5s
  Struct-Wrapped Vec                                                  |      22             22      0.5s
  alignment.jl                                                        |     674            674      0.1s
  masks.jl                                                            |     112            112      2.3s
  vector_width.jl                                                     |      55             55      0.3s
  Memory                                                              |   52080          52080   8m12.8s
  Grouped Strided Pointers                                            |     102            102      1.5s
  Adjoint VecUnroll                                                   |      15             15      0.8s
  Unary Functions                                                     |     805            805      4.3s
  Binary Functions                                                    | 2252174        2252174   1m02.3s
  Ternary Functions                                                   |     492            492     38.0s
  Special functions                                                   |       3              3      0.9s
  Non-broadcasting operations                                         |      26             26      0.7s
  broadcasting                                                        |      11             11      0.1s
  CartesianVIndex                                                     |       9              9      0.1s
  Promotion                                                           |      27             27      1.1s
  Lazymul                                                             |      37             37      0.1s
  Static Zero and One                                                 |      38             38      0.3s
  Defining log.                                                       |       1              1      0.6s
  Saturated add                                                       |       3              3      0.1s
  Special Functions                                                   |      10             10   3m27.4s
  fix stackoverflow for `vmax_fast` et al.                            |       8              8      0.0s
  vmax/vmin Bool                                                      |       6              6      0.1s
  Generic strided pointer                                             |       6              6      0.4s
  NullStep                                                            |       4              4      0.4s
ERROR: LoadError: Some tests did not pass: 2306732 passed, 2 failed, 0 errored, 0 broken.

Same two failures downstream. So let's do it.

[topolarity]

I don't think this should have been merged as-is.

Right now if someone, e.g., uses PackageCompiler on a large machine, you can end up with CPUSummary.sys_threads() and CPUSummary.num_cores() grossly over-estimated (e.g. 128 HW threads vs. 8 actual HW threads), which could lead to over-subscription and other hard-to-diagnose issues.

[ChrisRackauckas]

Didn't the other form just error? This unblocks a lot of code while keeping the same assumptions it had before. Those assumptions might not be great but it's keeping to the current design of the package

[topolarity]

No, before the number of HW threads would be measured at run-time via the __init__(), so it wouldn't be incorrect.

[ChrisRackauckas]

That case had some odd behavior though? Since the package was written with that information all static, it would effectively invalidate all code in the built binary. Also, I thought the most recent tests had showed CPUSummary would break PackageCompiler builds?

I kind of think that if this made only runtime, that would almost be a different library. All things built on this (VectorizationBase, Polyester, PolyesterWeave, LoopVectorization, RecursiveFactorization, etc.) all. rely on the assumption of it being static information. Changing this to runtime information would be a major breaking change that would require rewriting all of those libraries, which is a major overhaul that I don't think anyone is up for.

I think it could be reasonable for this to be a v0.3, or v1.0, though. I had debated it but ultimately thought it was non-breaking because all downstream integrations tests pass, since indeed the only thing that changed was some form of relocatability.

[topolarity]

What about a compromise solution that sets the value eagerly with a measurement at precompile-time, and then only invalidates in the __init__ if (1) the values have changes, and (2) the values were not taken from Preferences in the first place.

That way:

1. The common user who doesn't relocate anything sees no invalidations
2. Naively relocated images pay an invalidation cost but remain correct
3. juliac.jl / PackageCompiler can both provide "generic" values via Preferences, so that these are guaranteed not to invalidate (and remain --trim compatible)

It's still not perfect (in particular for juliac.jl, it means that almost none of your existing pkgimages can be used now, so we'll have to do almost a full re-compile like we do for ] test), but it seems like an improvement.

[topolarity]

Looking at this, that's actually how this code already worked before (except for the Preferences pieces)

I think it would be sufficient to have:

1. Preferences to override the auto-detected number of cores, threads, etc. (which this PR does)
2. Instead of removing the __init__ invalidation, add a preference to disable the runtime invalidation like invalidate_with_runtime_cpuinfo = false or similar (opt-out, not opt-in)

If you're seeing invalidations in the wild from this, then that means that one of the pieces of information is not stable from pre-compile-time, which should be investigated instead of keeping it fixed and hoping for the best (I don't think it's expected that any of this changes on a given machine?)

[ChrisRackauckas]

That wasn't trim compatible though?

[topolarity]

It is trim compatible if you set the preference invalidate_with_runtime_cpuinfo = false, which we can have --trim do by default