Skip to content

update relative paths and readme cleanups #240

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
drbh merged 1 commit into from
Jan 27, 2026
Merged

update relative paths and readme cleanups #240

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# kernels

<div align="center">
<img src="https://github.com/user-attachments/assets/64a652f3-0cd3-4829-b3c1-df13f7933569" width="450" height="450" alt="kernel-builder logo">
<img src="https://github.com/user-attachments/assets/4b5175f3-1d60-455b-8664-43b2495ee1c3" width="450" height="450" alt="kernel-builder logo">
<p align="center">
<a href="https://pypi.org/project/kernels"><img alt="PyPI - Version" src="https://img.shields.io/pypi/v/kernels"></a>
<a href="https://github.com/huggingface/kernels/tags"><img alt="GitHub tag" src="https://img.shields.io/github/v/tag/huggingface/kernels"></a>
<a href="https://github.com/huggingface/kernels/actions/workflows/docker-build-push.yaml"><img alt="Test kernels" src="https://img.shields.io/github/actions/workflow/status/huggingface/kernels/test.yml?label=test"></a>
<a href="https://github.com/huggingface/kernels/actions/workflows/test_kernels.yaml"><img alt="Test kernels" src="https://img.shields.io/github/actions/workflow/status/huggingface/kernels/test_kernels.yaml?label=test"></a>

</p>
</div>
Expand Down
28 changes: 12 additions & 16 deletions builder/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,10 @@
# kernel-builder

<div align="center">
<img src="https://github.com/user-attachments/assets/4b5175f3-1d60-455b-8664-43b2495ee1c3" width="450" height="450" alt="kernel-builder logo">
<p align="center">
<a href="https://github.com/huggingface/kernel-builder/actions/workflows/docker-build-push.yaml"><img alt="Build and Push Docker Image" src="https://img.shields.io/github/actions/workflow/status/huggingface/kernel-builder/docker-build-push.yaml?label=docker"></a>
<a href="https://github.com/huggingface/kernel-builder/tags"><img alt="GitHub tag" src="https://img.shields.io/github/v/tag/huggingface/kernel-builder"></a>
<a href="https://github.com/huggingface/kernel-builder/pkgs/container/kernel-builder"><img alt="GitHub package" src="https://img.shields.io/badge/container-ghcr.io-blue"></a>
</p>
</div>
<hr/>
The kernel-builder is a build system for creating Hub-compatible compute kernels. It handles the complexity of building kernels that are:

- Portable: kernels can be loaded from paths outside `PYTHONPATH`.
- Unique: multiple versions of the same kernel can be loaded in the same Python process.
- Compatible: kernels support all recent versions of Python and the different PyTorch build configurations (various CUDA versions and C++ ABIs).

**Note:** Torch 2.10 builds are still based on PyTorch release candidates.
Typically the ABI does not break during release candidates. If it does,
Expand Down Expand Up @@ -70,14 +66,14 @@ See [dockerfiles/README.md](./dockerfiles/README.md) for more options, including

# 📚 Documentation

- [Writing Hub kernels](./docs/writing-kernels.md)
- [Building kernels with Nix](./docs/nix.md)
- [Writing Hub kernels](../docs/source/builder/writing-kernels.md)
Copy link
Member

@danieldk danieldk Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can be a separate PR, but I think in the future we could link these out to the hf.co documentation pages, since it renders more nicely?

Copy link
Collaborator Author

@drbh drbh Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah yea great point, i'll open a small PR with that improvement soon

- [Building kernels with Nix](../docs/source/builder/nix.md)
- Framework-specific notes:
- [Metal](docs/metal.md)
- [Building kernels with Docker](./docs/docker.md) (for systems without Nix)
- [Local kernel development](docs/local-dev.md) (IDE integration)
- [Kernel security](./docs/security.md)
- [Why Nix?](./docs/why-nix.md)
- [Metal](../docs/source/builder/metal.md)
- [Building kernels with Docker](../docs/source/builder/docker.md) (for systems without Nix)
- [Local kernel development](../docs/source/builder/local-dev.md) (IDE integration)
- [Kernel security](../docs/source/builder/security.md)
- [Why Nix?](../docs/source/builder/why-nix.md)

## Credits

Expand Down
2 changes: 1 addition & 1 deletion docs/source/builder/local-dev.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,6 @@ $ pip install --no-build-isolation -e .
**Warnings:**

- Kernels built in this way should **not** be published on the Kernel
Hub. They do not fulfill the [kernel requirements](https://github.com/huggingface/kernels/blob/main/docs/kernel-requirements.md).
Hub. They do not fulfill the [kernel requirements](../kernel-requirements.md).
- Do not add the generated files to Git. `build2cmake` has regular updates
and you generally want to use files generated by the latest version.
2 changes: 1 addition & 1 deletion docs/source/builder/nix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ We recommend installing Nix in the following way:

The easiest way get all the Nix functionality is by putting a
`flake.nix` in your kernel repository. To do so, copy
[`examples/relu/flake.nix`](../examples/relu/flake.nix) into the
[`examples/relu/flake.nix`](https://github.com/huggingface/kernels/blob/main/builder/examples/relu/flake.nix) into the
same directory as your `build.toml` file. Then run `nix flake update`.
This generates a `flake.lock` file that pins the kernel builder
and _all_ its transitive dependencies. Commit both `flake.nix`
Expand Down
10 changes: 5 additions & 5 deletions docs/source/builder/writing-kernels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,9 @@ of CMake or setuptools.

This page describes the directory layout of a kernel-builder project, the
format of the `build.toml` file, and some additional Python glue that
`kernel-builder` provides. We will use a [simple ReLU kernel](../examples/relu)
`kernel-builder` provides. We will use a [simple ReLU kernel](https://github.com/huggingface/kernels/tree/main/builder/examples/relu)
as the running example. After reading this page, you may also want to have
a look at the more realistic [ReLU kernel with backprop and `torch.compile`](../examples/relu-backprop-compile)
a look at the more realistic [ReLU kernel with backprop and `torch.compile`](https://github.com/huggingface/kernels/tree/main/builder/examples/relu-backprop-compile)
support.

## Kernel project layout
Expand Down Expand Up @@ -107,12 +107,12 @@ depends = [ "torch" ]

- `maxver`: the maximum CUDA toolkit version (inclusive). This option
_must not_ be set under normal circumstances, since it can exclude Torch
build variants that are [required for compliant kernels](https://github.com/huggingface/kernels/blob/main/docs/kernel-requirements.md).
build variants that are [required for compliant kernels](../kernel-requirements.md).
This option is provided for kernels that cause compiler errors on
newer CUDA toolkit versions.
- `minver`: the minimum required CUDA toolkit version. This option
_must not_ be set under normal circumstances, since it can exclude Torch
build variants that are [required for compliant kernels](https://github.com/huggingface/kernels/blob/main/docs/kernel-requirements.md).
build variants that are [required for compliant kernels](../kernel-requirements.md).
This option is provided for kernels that require functionality only
provided by newer CUDA toolkits.

Expand Down Expand Up @@ -145,7 +145,7 @@ The following options can be set for a kernel:
supported backends are `cpu`, `cuda`, `metal`, `rocm`, and `xpu`.
**The `cpu` backend is currently experimental and might still change.**
- `depends` (required): a list of dependencies. The supported dependencies
are listed in [`deps.nix`](../lib/deps.nix).
are listed in [`deps.nix`](https://github.com/huggingface/kernels/blob/main/builder/lib/deps.nix).
- `src` (required): a list of source files and headers.
- `include` (optional): include directories relative to the project root.
Default: `[]`.
Expand Down
Loading