Environment variables¶

Scaly's environment settings select the compiler used for Python evaluation, locate cached artifacts and visualization recordings, and configure native solver discovery. They apply to the Python process that reads them. Setting them before starting that process avoids a mixture of old and new settings in already loaded functions.

For example, this command reports the toolchain with Clang selected:

SCALY_CC=clang uv run scaly_toolchain

The report includes the resolved compiler path, cache location, and available solver libraries. These settings do not change how your application's build system compiles exported C.

Compiler selection and optimization¶

An explicit SCALY_CC takes precedence over CC. Its value is an executable name or path, such as clang or /usr/bin/clang, rather than a shell command with additional flags. If the selected executable cannot be found, Scaly does not silently try another compiler.

SCALY_CC_OPT=-O3 selects a different optimization level. It is a single compiler argument, not a space-separated list of flags. Scaly also adds -march=native, or -mcpu=native on AArch64, and -fno-math-errno.

The Python compiler detects a fixed lane width for the native CPU. On supported x86-64 hosts with glibc 2.35 or newer, it also selects the libmvec vector math library. SCALY_VECTOR_LIBM=none forces scalar math calls. SCALY_VECTOR_LIBM=glibc requests libmvec explicitly and requires a compatible target. Vector and scalar math implementations can produce different rounded results. scaly_toolchain reports the detected native build recipe.

The build recipe and compiler flags contribute to the cache key. Changing the optimization level therefore produces a different artifact when the function is compiled again. An already loaded function continues using its current library. The key does not identify the compiler executable or the CPU that -march=native resolved to. After pointing SCALY_CC at another compiler, or when several machines share one cache directory, clear the cache or call recompile() on the affected functions. See compilation and caching.

Cache directory¶

SCALY_CACHE_DIR holds generated source and compiled function libraries. It defaults to $XDG_CACHE_HOME/scaly/jit, otherwise ~/.cache/scaly/jit. A path beginning with ~ expands to the user's home directory. Compiled artifacts can be deleted and are rebuilt on a later compilation.

Visualization recordings¶

SCALY_VIZ_DIR holds the recordings that scaly.viz writes for marked functions. It defaults to $XDG_CACHE_HOME/scaly/viz, otherwise ~/.cache/scaly/viz.

Native solver builds¶

SCALY_BUILD_SOLVERS controls the PIQP and IPOPT plugin build hooks when installing from source. It does not rebuild libraries in an installed wheel.

Skipping a build does not provide a Python solver alternative. Solver calls still need the native libraries. This setting is mainly relevant to source checkouts and custom packaging. Installation covers normal package installation, and Contributing lists the source-build requirements.

Custom solver-library locations¶

Installed plugins normally supply the required headers and libraries. The following settings select custom builds or help diagnose library discovery:

The include and library overrides add locations before the plugin's locations. A custom library still needs matching headers and its own native dependencies. An exact library path alone does not supply those headers. uv run scaly_toolchain shows the resolved locations and whether the libraries can be loaded.