Move and deprecate dpctl program

.flake8

@@ -22,7 +22,7 @@ per-file-ignores =
     dpctl/_sycl_queue.pyx: E999, E225, E226, E227
     dpctl/_sycl_queue_manager.pyx: E999, E225
     dpctl/memory/_memory.pyx: E999, E225, E226, E227
-    dpctl/program/_program.pyx: E999, E225, E226, E227
+    dpctl/compiler/_compiler.pyx: E999, E225, E226, E227
     dpctl/tests/_cython_api.pyx: E999, E225, E227, E402
     dpctl/utils/_onetrace_context.py: E501, W505
     examples/cython/sycl_buffer/syclbuffer/_syclbuffer.pyx: E999, E225, E402

CHANGELOG.md

@@ -17,6 +17,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Rewrote USM Python examples into a single example [gh-2292](https://github.com/IntelPython/dpctl/pull/2292)
 * Registered `DPCTL_PARTITION_AFFINITY_DOMAIN_UNKNOWN` enumerator when `DPCTLDevice_GetPartitionAffinityDomains` receives an unrecognized value from the SYCL runtime [gh-2324](https://github.com/IntelPython/dpctl/pull/2324)
 
+### Deprecated
+* Deprecated `dpctl.program` submodule in favor of `dpctl.compiler`, which provides a better description of the purpose of the submodule in exposing DPC++ compilation-related functionality [gh-2317](https://github.com/IntelPython/dpctl/pull/2317)
+* Deprecated `DPCTL_ENABLE_L0_PROGRAM_CREATION` CMake option in favor of `DPCTL_ENABLE_L0_KERNEL_BUNDLE_CREATION` [gh-2317](https://github.com/IntelPython/dpctl/pull/2317)
+
+### Removed
+* Removed Cython API for `dpctl.program` submodule, as the submodule is now deprecated, with functionality migrated to `dpctl.compiler` [gh-2317](https://github.com/IntelPython/dpctl/pull/2317)
+
 ### Fixed
 
 ### Maintenance

docs/doc_sources/api_reference/dpctl/compiler.rst

@@ -0,0 +1,52 @@
+.. _dpctl_compiler_pyapi:
+
+:py:mod:`dpctl.compiler`
+========================
+
+:py:mod:`dpctl.compiler` provides a way to create a SYCL kernel
+from either an OpenCL* program source code represented as a string
+or a SPIR-V binary file.
+
+It implements creation of interoperability
+``sycl::kernel_bundle<sycl::bundle_state::executable>`` (a collection of kernels),
+as well as creation of individual ``sycl::kernel``, suitable for submission for
+execution via :py:meth:`dpctl.SyclQueue.submit`.
+
+.. py:module:: dpctl.compiler
+
+.. currentmodule:: dpctl.compiler
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+
+    create_kernel_bundle_from_source
+    create_kernel_bundle_from_spirv
+    create_kernel_bundle_from_sycl_source
+    is_sycl_source_compilation_available
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+
+    SyclKernelBundle
+    SyclKernel
+    SpecializationConstant
+
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+
+    SyclKernelBundleCompilationError
+
+:py:mod:`dpctl.compiler.utils`
+------------------------------
+
+.. py:module:: dpctl.compiler.utils
+
+.. currentmodule:: dpctl.compiler.utils
+
+.. autofunction:: parse_spirv_specializations
+
+.. autoclass:: SpecializationConstantInfo
+    :members:

docs/doc_sources/api_reference/dpctl/index.rst

@@ -14,8 +14,10 @@
 
     * - :py:mod:`dpctl.memory`
       - Unified Shared Memory operations
-    * - :py:mod:`dpctl.program`
+    * - :py:mod:`dpctl.compiler`
       - Support for working with SYCL kernels
+    * - :py:mod:`dpctl.program`
+      - (deprecated, use :py:mod:`dpctl.compiler`)
     * - :py:mod:`dpctl.utils`
       - A collection of utility functions
 

docs/doc_sources/api_reference/dpctl/program.rst

@@ -1,14 +1,17 @@
 .. _dpctl_program_pyapi:
 
-:py:mod:`dpctl.program`
-=======================
+:py:mod:`dpctl.program` (deprecated)
+=====================================
+
+.. deprecated::
+   :py:mod:`dpctl.program` is deprecated. Use :py:mod:`dpctl.compiler` instead.
 
 :py:mod:`dpctl.program` provides a way to create a SYCL kernel
 from an OpenCL* program source code represented as a string, SYCL
 source code represented as a string, or a SPIR-V binary file.
 
 It implements creation of interoperability
-``sycl::kernel_bundle<sycl::bundle_state_executable>`` (a collection of kernels),
+``sycl::kernel_bundle<sycl::bundle_state::executable>`` (a collection of kernels),
 as well as creation of individual ``sycl::kernel``, suitable for submission for
 execution via :py:meth:`dpctl.SyclQueue.submit`.
 
@@ -20,35 +23,8 @@ execution via :py:meth:`dpctl.SyclQueue.submit`.
     :toctree: generated
     :nosignatures:
 
-    create_kernel_bundle_from_source
-    create_kernel_bundle_from_spirv
-    create_kernel_bundle_from_sycl_source
     create_program_from_source
     create_program_from_spirv
-    is_sycl_source_compilation_available
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-
-    SyclKernelBundle
     SyclKernel
-    SpecializationConstant
-
-.. autosummary::
-    :toctree: generated
-    :nosignatures:
-
-    SyclKernelBundleCompilationError
-
-:py:mod:`dpctl.program.utils`
------------------------------
-
-.. py:module:: dpctl.program.utils
-
-.. currentmodule:: dpctl.program.utils
-
-.. autofunction:: parse_spirv_specializations
-
-.. autoclass:: SpecializationConstantInfo
-    :members:
+    SyclProgram
+    SyclProgramCompilationError

docs/doc_sources/api_reference/dpctl_cython.rst

@@ -6,8 +6,8 @@
 .. role:: python(code)
    :language: python
 
-All Python modules of :py:mod:`dpctl` come with ``__init__.pxd`` alongside ``__init__.py`` files
-permitting doing both :python:`import dpctl` and :code:`cimport dpctl as c_dpctl`.
+Python modules of :py:mod:`dpctl` that expose a Cython API come with ``__init__.pxd`` alongside
+``__init__.py`` files, permitting doing both :python:`import dpctl` and :code:`cimport dpctl as c_dpctl`.
 
 Locations of Cython declaration files in the package installation layout are as follows:
 
@@ -24,12 +24,12 @@ Locations of Cython declaration files in the package installation layout are as
     _sycl_queue_manager.pxd
     sycl.pxd
 
+    compiler/__init__.pxd
+    compiler/_compiler.pxd
+
     memory/__init__.pxd
     memory/_memory.pxd
 
-    program/__init__.pxd
-    program/_program.pxd
-
 File ``_backend.pxd`` redefines symbols from :ref:`DPCTLSyclInterface library <libsyclinterface>` for Cython.
 
 File ``sycl.pxd`` provides casters from opaque types in "DPCTLSyclInterface" C library to SYCL C++ object pointers.

docs/doc_sources/api_reference/index.rst

@@ -9,7 +9,8 @@ The package ``dpctl`` provides
 * Python language bindings for the DPC++ runtime
    - :ref:`API objects <dpctl_pyapi>` in :py:mod:`dpctl` namespace
    - :ref:`API objects <dpctl_memory_pyapi>` in :py:mod:`dpctl.memory` namespace
-   - :ref:`API objects <dpctl_program_pyapi>` in :py:mod:`dpctl.program` namespace
+   - :ref:`API objects <dpctl_compiler_pyapi>` in :py:mod:`dpctl.compiler` namespace
+   - :ref:`API objects <dpctl_program_pyapi>` in :py:mod:`dpctl.program` namespace (deprecated, use :py:mod:`dpctl.compiler`)
    - :ref:`API objects <dpctl_utils_pyapi>` in :py:mod:`dpctl.utils` namespace
 * Python C API
    - :ref:`C API <dpctl_capi>` for working with Python classes defined in :mod:`dpctl`
@@ -31,6 +32,7 @@ The package ``dpctl`` provides
 
    dpctl/index
    dpctl/memory
+   dpctl/compiler
    dpctl/program
    dpctl/utils
    libsyclinterface/index

docs/doc_sources/contributor_guides/building.rst

@@ -250,7 +250,7 @@ library.
         -DCMAKE_CXX_COMPILER=icpx                               \
         -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX}                \
         -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX}                   \
-        -DDPCTL_ENABLE_L0_PROGRAM_CREATION=ON                   \
+        -DDPCTL_ENABLE_L0_KERNEL_BUNDLE_CREATION=ON             \
         -DDPCTL_BUILD_CAPI_TESTS=ON                             \
         -DDPCTL_GENERATE_COVERAGE=ON                            \
         ..

dpctl/CMakeLists.txt

@@ -203,6 +203,6 @@ build_dpctl_ext(${_trgt} ${_cy_file} "dpctl" SYCL)
 target_include_directories(${_trgt} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
 target_link_libraries(DpctlCAPI INTERFACE ${_trgt}_headers)
 
-add_subdirectory(program)
+add_subdirectory(compiler)
 add_subdirectory(memory)
 add_subdirectory(utils)

dpctl/__init__.py

@@ -135,6 +135,7 @@
 # add submodules
 __all__ += [
     "memory",
+    "compiler",
     "program",
     "utils",
 ]

dpctl/_sycl_queue.pxd

@@ -32,7 +32,7 @@ from ._backend cimport (
 from ._sycl_context cimport SyclContext
 from ._sycl_device cimport SyclDevice
 from ._sycl_event cimport SyclEvent
-from .program._program cimport SyclKernel
+from .compiler._compiler cimport SyclKernel
 
 
 cdef public api class _SyclQueue [

dpctl/_sycl_queue.pyx

@@ -386,7 +386,7 @@ kernel_arg_type = _kernel_arg_type()
 cdef class SyclKernelSubmitError(Exception):
     """
     A ``SyclKernelSubmitError`` exception is raised when
-    the provided :class:`.program.SyclKernel` could not be
+    the provided :class:`.compiler.SyclKernel` could not be
     submitted to the :class:`.SyclQueue`.
 
     """
@@ -1249,10 +1249,10 @@ cdef class SyclQueue(_SyclQueue):
         list dEvents=None
     ):
         """
-        Asynchronously submit :class:`dpctl.program.SyclKernel` for execution.
+        Asynchronously submit :class:`dpctl.compiler.SyclKernel` for execution.
 
         Args:
-            kernel (dpctl.program.SyclKernel):
+            kernel (dpctl.compiler.SyclKernel):
                 SYCL kernel object
             args (List[object]):
                 List of kernel arguments
@@ -1410,10 +1410,10 @@ cdef class SyclQueue(_SyclQueue):
         list dEvents=None
     ):
         """
-        Submit :class:`dpctl.program.SyclKernel` for execution.
+        Submit :class:`dpctl.compiler.SyclKernel` for execution.
 
         Args:
-            kernel (dpctl.program.SyclKernel):
+            kernel (dpctl.compiler.SyclKernel):
                 SYCL kernel object
             args (List[object]):
                 List of kernel arguments

dpctl/apis/include/dpctl4pybind11.hpp

@@ -88,7 +88,7 @@ class dpctl_capi
                               DPCTLSyclQueueRef,
                               PyObject *);
 
-    // program
+    // compiler
     DPCTLSyclKernelRef (*SyclKernel_GetKernelRef_)(PySyclKernelObject *);
     PySyclKernelObject *(*SyclKernel_Make_)(DPCTLSyclKernelRef, const char *);
 
@@ -259,7 +259,7 @@ class dpctl_capi
         this->Memory_GetNumBytes_ = Memory_GetNumBytes;
         this->Memory_Make_ = Memory_Make;
 
-        // dpctl.program API
+        // dpctl.compiler API
         this->SyclKernel_GetKernelRef_ = SyclKernel_GetKernelRef;
         this->SyclKernel_Make_ = SyclKernel_Make;
         this->SyclKernelBundle_GetKernelBundleRef_ =
@@ -482,7 +482,7 @@ template <> struct type_caster<sycl::event>
 };
 
 /* This type caster associates ``sycl::kernel`` C++ class with
- * :class:`dpctl.program.SyclKernel` for the purposes of generation of
+ * :class:`dpctl.compiler.SyclKernel` for the purposes of generation of
  * Python bindings by pybind11.
  */
 template <> struct type_caster<sycl::kernel>
@@ -501,7 +501,7 @@ template <> struct type_caster<sycl::kernel>
         }
         else {
             throw py::type_error("Input is of unexpected type, expected "
-                                 "dpctl.program.SyclKernel");
+                                 "dpctl.compiler.SyclKernel");
         }
     }
 
@@ -514,12 +514,12 @@ template <> struct type_caster<sycl::kernel>
         return handle(reinterpret_cast<PyObject *>(tmp));
     }
 
-    DPCTL_TYPE_CASTER(sycl::kernel, _("dpctl.program.SyclKernel"));
+    DPCTL_TYPE_CASTER(sycl::kernel, _("dpctl.compiler.SyclKernel"));
 };
 
 /* This type caster associates
  * ``sycl::kernel_bundle<sycl::bundle_state::executable>`` C++ class with
- * :class:`dpctl.program.SyclKernelBundle` for the purposes of generation of
+ * :class:`dpctl.compiler.SyclKernelBundle` for the purposes of generation of
  * Python bindings by pybind11.
  */
 template <>
@@ -543,7 +543,7 @@ struct type_caster<sycl::kernel_bundle<sycl::bundle_state::executable>>
         }
         else {
             throw py::type_error("Input is of unexpected type, expected "
-                                 "dpctl.program.SyclKernelBundle");
+                                 "dpctl.compiler.SyclKernelBundle");
         }
     }
 
@@ -558,7 +558,7 @@ struct type_caster<sycl::kernel_bundle<sycl::bundle_state::executable>>
     }
 
     DPCTL_TYPE_CASTER(sycl::kernel_bundle<sycl::bundle_state::executable>,
-                      _("dpctl.program.SyclKernelBundle"));
+                      _("dpctl.compiler.SyclKernelBundle"));
 };
 
 /* This type caster associates

dpctl/apis/include/dpctl_capi.h

@@ -45,8 +45,8 @@
 #include "dpctl/_sycl_queue_api.h"
 #include "dpctl/memory/_memory.h"
 #include "dpctl/memory/_memory_api.h"
-#include "dpctl/program/_program.h"
-#include "dpctl/program/_program_api.h"
+#include "dpctl/compiler/_compiler.h"
+#include "dpctl/compiler/_compiler_api.h"
 
 // clang-format on
 
@@ -66,6 +66,6 @@ static inline void import_dpctl(void)
     import_dpctl___sycl_event();
     import_dpctl___sycl_queue();
     import_dpctl__memory___memory();
-    import_dpctl__program___program();
+    import_dpctl__compiler___compiler();
     return;
 }

dpctl/program/CMakeLists.txt → dpctl/compiler/CMakeLists.txt

@@ -1,7 +1,6 @@
-
 file(GLOB _cython_sources *.pyx)
 foreach(_cy_file ${_cython_sources})
     get_filename_component(_trgt ${_cy_file} NAME_WLE)
-    build_dpctl_ext(${_trgt} ${_cy_file} "dpctl/program" RELATIVE_PATH "..")
+    build_dpctl_ext(${_trgt} ${_cy_file} "dpctl/compiler" RELATIVE_PATH "..")
     target_link_libraries(DpctlCAPI INTERFACE ${_trgt}_headers)
 endforeach()

dpctl/program/__init__.pxd → dpctl/compiler/__init__.pxd

@@ -1,6 +1,6 @@
 #                      Data Parallel Control (dpctl)
 #
-# Copyright 2020 Intel Corporation
+# Copyright 2020-2025 Intel Corporation
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -18,8 +18,15 @@
 # cython: language_level=3
 
 """Declares the extension types and functions for the Cython API
-implemented in dpctl.program._program.pyx.
+implemented in dpctl.compiler._compiler.pyx.
 """
 
 
-from dpctl.program._program cimport *
+from dpctl.compiler._compiler cimport (
+    SyclKernel,
+    SyclKernelBundle,
+    create_kernel_bundle_from_source,
+    create_kernel_bundle_from_spirv,
+    create_kernel_bundle_from_sycl_source,
+    is_sycl_source_compilation_available,
+)