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 the toolchain extra and CC. Its value is an executable name or path, such as clang or /usr/bin/clang, or a command with arguments, such as zig cc. Quote an executable path containing spaces. Arguments are passed directly to the compiler without a shell. 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. With Clang on x86-64 it adds -mno-gather -mno-scatter when that Clang accepts them, and with zig cc the same setting as CPU features, because vector gather loads made the generated matrix-vector loops slower than scalar code.

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. With libmvec selected, Clang and zig cc also get -fveclib=libmvec, so loops that they vectorize call libmvec too. Vector and scalar math implementations can produce different rounded results. scaly_toolchain reports the detected native build recipe.

The build recipe, the compiler and its flags, and the CPU that -march=native resolves to contribute to the cache key. Changing the optimization level or pointing SCALY_CC at another compiler therefore produces a different artifact when the function is compiled again, and several machines can share one cache directory. An already loaded function continues using its current library. 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.

SCALY_SOLVER_CACHE sets the directory where the build hooks keep finished builds, shared by every source checkout on the machine. It defaults to $XDG_CACHE_HOME/scaly/solvers, otherwise ~/.cache/scaly/solvers.

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.