From 9499a01eb923be13e626888edf292dd408ca5d94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20de=20Kok?= Date: Wed, 19 Nov 2025 13:01:57 +0000 Subject: [PATCH 1/2] Describe new flattened layout and dependencies --- docs/source/kernel-requirements.md | 31 +++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/source/kernel-requirements.md b/docs/source/kernel-requirements.md index b7cb6b0..eefb2a3 100644 --- a/docs/source/kernel-requirements.md +++ b/docs/source/kernel-requirements.md @@ -15,11 +15,16 @@ following the template `-cxx---`. For example `build/torch26-cxx98-cu118-x86_64-linux`. -Each variant directory must contain a single directory with the same name -as the repository (replacing `-` by `_`). For instance, kernels in the -`kernels-community/activation` repository have a directories like -`build//activation`. This directory -must be a Python package with an `__init__.py` file. +The kernel is in the build variant directory and must contain a +`__init__.py` file. For compatibility with older versions of the +`kernels` package, each variant directory must also contain a single +directory with the same name as the repository (replacing `-` by `_`). +For instance, kernels in the `kernels-community/activation` repository +have a directories like `build//activation`. This directory +must contain an `__init__.py` file that exports the same symbols as +`__init__.py` in the build variant directory `build/`. +[This example](https://huggingface.co/kernels-test/flattened-build/blob/main/build/torch-universal/flattened_build/__init__.py) +shows how this can be done. ## Build variants @@ -28,6 +33,18 @@ architecture (e.g. x86_64). For compliance with a compute framework and architecture combination, all the variants from the [build variant list](https://github.com/huggingface/kernel-builder/blob/main/docs/build-variants.md) must be available for that combination. +## Kernel metadata + +The build variant directory can optionally contain a `metadata.json` file. +Currently the only purpose of the metadata is to specify kernel +dependencies, for example: + +```json +{ "python-depends": ["nvidia-cutlass-dsl"] } +``` + +The following dependencies are allowed: `einops` and `nvidia-cutlass-dsl` + ## Versioning Kernels are versioned on the Hub using Git tags. Version tags must be of @@ -50,10 +67,10 @@ have dynamic library dependencies outside: The Kernel Hub also encourages to write the kernels in a `torch.compile` compliant way. This helps to ensure that the kernels are compatible with -`torch.compile` without introducing any graph breaks and triggering +`torch.compile` without introducing any graph breaks and triggering recompilation which can limit the benefits of compilation. -[Here](https://github.com/huggingface/kernel-builder/blob/d1ee9bf9301ac8c5199099d90ee1c9d5c789d5ba/examples/relu-backprop-compile/tests/test_relu.py#L162) is a simple test example which checks for graph breaks and +[Here](https://github.com/huggingface/kernel-builder/blob/d1ee9bf9301ac8c5199099d90ee1c9d5c789d5ba/examples/relu-backprop-compile/tests/test_relu.py#L162) is a simple test example which checks for graph breaks and recompilation triggers during `torch.compile`. ### Linux From 3f399a5f19e26d87e6db16fc43bbd822ae1e60b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20de=20Kok?= Date: Wed, 19 Nov 2025 15:01:09 +0100 Subject: [PATCH 2/2] Fixes Co-authored-by: Mohamed Mekkouri <93391238+MekkCyber@users.noreply.github.com> --- docs/source/kernel-requirements.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/kernel-requirements.md b/docs/source/kernel-requirements.md index eefb2a3..c8a6872 100644 --- a/docs/source/kernel-requirements.md +++ b/docs/source/kernel-requirements.md @@ -20,11 +20,12 @@ The kernel is in the build variant directory and must contain a `kernels` package, each variant directory must also contain a single directory with the same name as the repository (replacing `-` by `_`). For instance, kernels in the `kernels-community/activation` repository -have a directories like `build//activation`. This directory +have a directory like `build//activation`. This directory must contain an `__init__.py` file that exports the same symbols as `__init__.py` in the build variant directory `build/`. [This example](https://huggingface.co/kernels-test/flattened-build/blob/main/build/torch-universal/flattened_build/__init__.py) -shows how this can be done. +shows how this can be done. This compatibility directory is +automatically created by `kernel-builder`. ## Build variants @@ -36,14 +37,13 @@ must be available for that combination. ## Kernel metadata The build variant directory can optionally contain a `metadata.json` file. -Currently the only purpose of the metadata is to specify kernel -dependencies, for example: +Currently the only purpose of the metadata is to specify the kernel python dependencies, for example: ```json { "python-depends": ["nvidia-cutlass-dsl"] } ``` -The following dependencies are allowed: `einops` and `nvidia-cutlass-dsl` +The following dependencies are the only ones allowed at this stage: `einops` and `nvidia-cutlass-dsl` ## Versioning