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

# Local development of kernels

## 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.

It is recommended to do an editable install of the generated project into
your Python virtual environment for development:

```bash
$ pip install wheel # Needed once to enable bdist_wheel.
$ pip install --no-build-isolation -e .
```

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.

## 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
```