# Installed SDKs and build caches

Keep the installed CLI, JavaScript API, templates, and native libraries together. Runtime 0.2 builds applications using writable project staging without writing into read-only SDK inputs. Host SDKs, tools, and caches still need writable locations when installation or updates require them.

## Locate toolchain configuration

The npm launcher stores new first-run configuration outside the installed package:

| Override or host | Configuration location |
| --- | --- |
| `ORO_ENV_FILE` | Explicit file; relative values resolve against the invoking directory |
| `ORO_CONFIG_HOME` | Directory containing the user configuration |
| Linux default | `$XDG_CONFIG_HOME/oro` or `~/.config/oro` |
| macOS default | `~/Library/Application Support/oro` |
| Windows default | `%LOCALAPPDATA%\oro` or `~/AppData/Local/oro` |

The filename defaults to `.oro.env`; `ORO_ENV_FILENAME` selects another name. An existing user file takes precedence over legacy SDK-local configuration. Without an explicit override or user file, an existing SDK-local file remains readable for compatibility and is not rewritten. `--version` and `--help` do not run setup or create configuration.

The native CLI fills unset values from the project's `.oro.env`, then the selected `ORO_ENV_FILE`, then legacy SDK defaults. Existing process environment values win. This toolchain configuration is separate from the application's [`oro.toml` and `.ororc`](/runtime/docs/config/overview/).

If a compiled CLI/template or Android API/source fingerprint mismatch is reported, reinstall or rebuild the matching SDK. Do not bypass the mismatch by mixing files from unrelated installations. Unix Android setup can reuse complete installed-package metadata and required tools offline; it still provisions missing packages and cannot acquire missing Gradle dependencies offline.

## Opt into build result caches

```bash
oroc build --cache .
oroc build --platform=android --cache --no-android-configuration-cache .
```

Optional build result caches default to **off**. A project can opt in:

```toml
[build]
cache = true

[android]
configuration_cache = false

[ios]
cache = false
```

| Cache | Project settings | CLI override |
| --- | --- | --- |
| Supported result caches | `build.cache`, platform `cache` | `--cache` / `--no-cache` |
| Native object compilation | `build.compiler_cache`, platform `compiler_cache` | `--compiler-cache` / `--no-compiler-cache` |
| Android cache family | `android.cache` | `--android-cache` / `--no-android-cache` |
| Gradle task outputs | `android.build_cache` | `--android-build-cache` / `--no-android-build-cache` |
| Gradle configuration | `android.configuration_cache` | `--android-configuration-cache` / `--no-android-configuration-cache` |

CLI cache-specific flags override Android-family flags, which override general flags; supplying positive and negative forms of the same flag is an error. Platform-specific configuration overrides corresponding build defaults. Android emulator targets inherit Android settings; iOS Simulator inherits iOS settings. Desktop platform sections are `linux`, `mac`, and `win`.

Native compiler caching uses `ccache`, falling back to `sccache`; Windows prefers `sccache`. Without either tool, Oro reports the missing cache and compiles directly. A selected launcher/compiler failure still fails the build. Custom hooks receive `ORO_BUILD_CACHE` and `ORO_COMPILER_CACHE` as `1` or `0` and must configure their own tools. These options do not clear entries or control dependency downloads, runtime data caches, or source bootstrap.

## Linux source-development SDKs

For Runtime contributors, `pnpm relink` / `npm run relink` publishes a copied, verified Linux SDK under `.local/share/oro-sdk/linux`; `ORO_LOCAL_SDK_HOME` overrides that location. Immutable generations contain matched CLI/API/native inputs. Activation is atomic, active-command leases retain in-use generations, failed activation can roll back, and unused generations/interrupted staging are collected under the retention policy.

Editing a source checkout does not change an activated generation: rebuild and relink. This workflow is separate from npm publication and ordinary npm installation. See the [source-build, retention, and cleanup reference](https://github.com/oro-computer/runtime/blob/v0.2.1/docs/BUILD_ENVIRONMENT.md).