kernels/pr_676/en/builder/local-dev.md

# Develop locally

## Introduction

`kernel-builder` builds kernels in a sandbox. This has various benefits,
such as building kernels for a wide range of Torch versions, compatibility
with older C library versions and avoiding accidental dependencies.

However, this is not ideal during kernel development, since language
servers and IDEs do not interpret the `build.toml` file. As a result,
code completion will typically not work. `kernel-builder` provides the
`kernel-builder` utility to generate CMake files to build native code and
setuptools files for building the kernel as a regular Python package.
Since CMake and setuptools are widely supported by IDEs, this provides
a much-improved development experience.

## Generating a Python project with `kernel-builder`

`kernel-builder` can create CMake/Python project files for a kernel with
a [`build.toml`](./writing-kernels) file. The `create-pyproject`
command will create the files for the kernel in the current directory:

```bash
$ kernel-builder create-pyproject -f
```

The `-f` flag is optional and instructs `kernel-builder` to overwrite
existing files.

You can build the kernel with

```bash
$ python setup.py build_kernel
```

This builds the kernel and puts the variant that is compatible with the build
environment in `build`. The build can then be loaded directly with `kernels`:

```shell
$ python -c 'import pathlib; import kernels; k = kernels.get_local_kernel(pathlib.Path("build")); print(k)'
```

For AOT kernels, if you want to skip the CMake configuration step in subsequent
builds, you can also run Ninja directly to do incremental builds:

```shell
$ ninja -C _cmake_build local_install
```

You can also create a Python project for a kernel in another directory:

```bash
$ kernel-builder create-pyproject -f path/to/kernel
```

**Warnings:**

- Kernels built in this way should **not** be published on the Kernel
  Hub. They do not fulfill the [kernel requirements](../kernel-requirements).
- Do not add the generated files to Git. `kernel-builder` has regular updates
  and you generally want to use files generated by the latest version.

See [IDE Setup](./ide-setup) for wiring the generated project into
VS Code with direnv.

## Testing kernel builds before publishing

Once you have built a kernel with kernel builder, you may want to test it
locally with software that uses `get_kernel` or `LayerRepository` before
publishing. This can be done using the `LOCAL_KERNELS` variable, which
maps a repository ID to a local kernel directory. For example, you could
use the kernel in `devel/activation` for any use of the
`kernels-community/activation` repository with:

```bash
$ LOCAL_KERNELS="kernels-community/activation=devel/activation" \
  python my_app.py
```

It is also possible to map multiple repositories to local kernel directories
by separating the entries with a colon (`:`):

```bash
$ LOCAL_KERNELS="kernels-community/activation=devel/activation:kernels-community/flash-attn2=devel/flash-attn2" \
  python my_app.py
```