# use

> Declares a capability your app depends on, written inside the `app { }` manifest block. It provisions the capability (its tables and types become available) and, for a kit, pins a version. It is the dependency; a `using` in a source file then imports the capability's names.

<!-- id: types-use · area: types · stability: preview · html: https://osysharp.com/reference/types/use/ -->

## Summary        {#summary}
**`use`** declares a **capability your app depends on**. It goes inside the `app { }` manifest block — the one
place a project says what it is built from:

```osy syntax
app Shop {
  model "model/**/*.osy";
  use Osysharp.Memory;      // depend on the Memory capability
  use Osysharp.Ui@2;        // depend on the UI kit, pinned to major 2
}
```

A `use` is your app's **dependency** — the equivalent of a package reference. It provisions the capability (its
tables and types become part of your app) and, for a versioned kit, records which version you want. To actually
**reference** a capability's names in a file, add a [`using`](#using-vs-use) for it there.

## Signature      {#signature}
```osy syntax
use Osysharp.Memory;        // a platform capability — version-neutral
use Osysharp.Ui@2;          // a kit — pinned to a major (@2 = any 2.x; @2.3 = ≥ 2.3 within 2.x; @2.4.1 = exact)
```

`use` is only valid **inside the `app { }` block**. A version pin (`@…`) is only meaningful on a **kit** — pinning
a version-neutral platform capability (which rides the platform binary) is an error.

## Description    {#description}

### What a dependency does   {#dependency}
Declaring `use Osysharp.Memory;` makes the Memory capability part of your app: its entities and types are
provisioned, its features (here, semantic `[Searchable]` fields and `Memory.Search`) become available. Remove the
`use` and the capability — and everything that needs it — is gone. The manifest is the single, authoritative list
of what your app depends on.

### `using` vs `use`     {#using-vs-use}
They are two different things, exactly as a C# project separates its **package references** from its **imports**:

| | Where | What it does |
|---|---|---|
| **`use Osysharp.Memory;`** | inside `app { }` | the **dependency** — provisions the capability, pins a kit version |
| **`using Osysharp.Memory;`** | at the top of any source file | the **import** — brings the capability's names into that file's scope |

A file that references a capability's names imports them with `using`, just like reaching any other namespace:

```osy syntax
// model/note.osy
using Osysharp.Memory;

entity Note {
  [Searchable] string Body;      // the [Searchable] feature comes from the Memory capability
}
```

If your app declares an `app { }` manifest, that manifest is **authoritative for CAPABILITIES**: a
`using Osysharp.X;` for a capability you did not `use` is an error — the same way C# rejects a `using` for an assembly
you never referenced. Add the matching `use` to the manifest to fix it. (A quick throwaway snippet with no manifest
at all is unconstrained — there, a `using` provisions on its own.)

### A bundled KIT needs no `use` — the `using` is enough, and `Osysharp.Ui` needs neither   {#kits-self-provision}
`Osysharp.Ui`, `Osysharp.Markdown` and `Osysharp.Charts` **ship inside the platform**. There is nothing to fetch and
nothing to choose, so for `Osysharp.Markdown` and `Osysharp.Charts` the `using` is the whole declaration — the kit
composes for the files that import it, and an app that never imports it pays nothing.

**`Osysharp.Ui` goes one step further: it is in scope for EVERY app, with nothing written at all.** No `using`, no
`use`. It is the kit almost every app reaches for, and `using` is FILE-scoped — so the opt-in was not one line per
app but one line per file, and the line you forget is in the file you wrote last. Both spellings stay legal; an
explicit `using Osysharp.Ui;` is simply redundant.

**A `use` for a kit is a version PIN, not a permission.** Write it when you want one:

```osy syntax
app Shop {
  model "model/**/*.osy";
  use Osysharp.Ui@2;        // pin the kit — not needed just to USE it
  use Osysharp.Memory;      // a CAPABILITY: still declared, because it stands up a vector store
}
```

The line between them is what the dependency DOES. A kit is syntax you import; a capability changes the shape of
your app — `Osysharp.Memory` a vector store, `Osysharp.Storage` a blob store, `Osysharp.Observability` audit tables — and
the manifest is where an app's shape is declared.

### Version pins live on `use`   {#versions}
A version belongs on the dependency, never on the import. `use Osysharp.Ui@2;` pins the kit; a `@version` written
on a `using` is an error that points you back to the `use`.

## Examples       {#examples}
```osy title="the manifest declares the dependency" test app=use-manifest-declares
// app.osy — the manifest declares the app's dependencies with `use`.
app Shop {
  model "model/**/*.osy";
  use Osysharp.Ui@2;
  use Osysharp.Memory;
}
```

```osy title="each file imports what it references" test app=use-file-imports
// model/catalog.osy — a file imports what it references with `using`.
using Osysharp.Ui;
using Osysharp.Memory;

entity Product {
  [Required] string Name;
  [Searchable] string Description;
}
```

## See also       {#see-also}
- [namespace](https://osysharp.com/reference/types/namespace/) — how a bare name resolves through the namespaces you import and the `Osyrin` core.
- [Osysharp.Ui (the UI kit)](https://osysharp.com/reference/ui/kit/) — the UI kit you depend on with `use Osysharp.Ui;` and import with `using Osysharp.Ui;`.
- [Pinning a kit version (using Ui@2)](https://osysharp.com/reference/ui/kit-versioning/) — pinning a kit's major version on the `use`.