From 28b9de623f6914f21ab2664ffcbe9273c2db655e Mon Sep 17 00:00:00 2001 From: Simeon David Schaub Date: Tue, 12 Aug 2025 11:21:41 +0200 Subject: [PATCH 1/2] set up Documenter closes #354 --- .github/workflows/Docs.yml | 56 ++++++++++++++ docs/Project.toml | 8 ++ docs/make.jl | 21 ++++++ docs/src/95-reference.md | 17 +++++ docs/src/index.md | 146 +++++++++++++++++++++++++++++++++++++ 5 files changed, 248 insertions(+) create mode 100644 .github/workflows/Docs.yml create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/src/95-reference.md create mode 100644 docs/src/index.md diff --git a/.github/workflows/Docs.yml b/.github/workflows/Docs.yml new file mode 100644 index 00000000..ffa6fbe7 --- /dev/null +++ b/.github/workflows/Docs.yml @@ -0,0 +1,56 @@ +name: Docs + +on: + push: + branches: + - main + paths: + - "docs/**" + - "src/**" + - "*.toml" + tags: ["*"] + pull_request: + branches: + - main + paths: + - "docs/**" + - "src/**" + - "*.toml" + types: [opened, synchronize, reopened] + +concurrency: + # Skip intermediate builds: always. + # Cancel intermediate builds: only if it is a pull request build. + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }} + +jobs: + docs: + name: Documentation + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: julia-actions/setup-julia@v2 + with: + version: "1" + - name: Use Julia cache + uses: julia-actions/cache@v2 + - name: Instantiate environment with development version of the package + run: | + julia --project=docs -e ' + using Pkg + Pkg.develop(PackageSpec(path=pwd())) + Pkg.instantiate()' + - name: Run doctest + run: | + julia --project=docs -e ' + using Documenter: DocMeta, doctest + using OpenCL + DocMeta.setdocmeta!(OpenCL, :DocTestSetup, :(using OpenCL); recursive=true) + doctest(OpenCL)' + - name: Generate and deploy documentation + run: julia --project=docs docs/make.jl + env: + JULIA_PKG_SERVER: "" + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 00000000..3a2e3607 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,8 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589" +OpenCL = "08131aa3-fb12-5dee-8b74-c09406e224a2" +pocl_jll = "627d6b7a-bbe6-5189-83e7-98cc0a5aeadd" + +[compat] +Documenter = "1" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 00000000..d276bfe8 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,21 @@ +using OpenCL +using Documenter + +DocMeta.setdocmeta!(OpenCL, :DocTestSetup, :(using OpenCL, pocl_jll); recursive = true) + +const page_rename = Dict("developer.md" => "Developer docs") # Without the numbers +const numbered_pages = [ + file for file in readdir(joinpath(@__DIR__, "src")) if + file != "index.md" && splitext(file)[2] == ".md" +] + +makedocs(; + modules = [OpenCL], + authors = "Jake Bolewski, JuliaHub and other contributors", + repo = "https://github.com/JuliaGPU/OpenCL.jl/blob/{commit}{path}#{line}", + sitename = "OpenCL.jl", + format = Documenter.HTML(; canonical = "https://JuliaGPU.github.io/OpenCL.jl"), + pages = ["index.md"; numbered_pages], +) + +deploydocs(; repo = "github.com/JuliaGPU/OpenCL.jl") diff --git a/docs/src/95-reference.md b/docs/src/95-reference.md new file mode 100644 index 00000000..e88779f0 --- /dev/null +++ b/docs/src/95-reference.md @@ -0,0 +1,17 @@ +# [Reference](@id reference) + +## Contents + +```@contents +Pages = ["95-reference.md"] +``` + +## Index + +```@index +Pages = ["95-reference.md"] +``` + +```@autodocs +Modules = [OpenCL, OpenCL.cl] +``` diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 00000000..9bfbdaea --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,146 @@ +```@meta +CurrentModule = OpenCL +``` + +# OpenCL + +*Julia interface for the OpenCL parallel computation API* + +This package aims to be a complete solution for OpenCL programming in Julia, similar in +scope to [PyOpenCL] for Python. It provides a high level API for OpenCL to make programing +hardware accelerators, such as GPUs, FPGAs, and DSPs, as well as multicore CPUs much less +onerous. + + +!!! note "OpenCL.jl needs your help!" + If you can help maintain this package, please reach out on the [JuliaLang Slack](https://julialang.org/slack/) #gpu channel. + +!!! warning "OpenCL.jl is currently undergoing major changes." + If you have old code developed for OpenCL.jl v0.9, please check [`NEWS.md`](https://github.com/JuliaGPU/OpenCL.jl/blob/master/NEWS.md) for an overview of the changes. + + +## Installation + +1. Install an OpenCL driver. You can install one system-wide, i.e., using your package + manager, or use `pocl_jll.jl` for a CPU back-end. +2. Add OpenCL to your Julia environment: + +```julia +using Pkg +Pkg.add("OpenCL") +``` + +3. Test your installation: + +```julia-repl +julia> OpenCL.versioninfo() +OpenCL.jl version 0.10.0 + +Toolchain: + - Julia v1.10.5 + - OpenCL_jll v2024.5.8+1 + +Available platforms: 3 + - Portable Computing Language + version: OpenCL 3.0 PoCL 6.0 Linux, Release, RELOC, SPIR-V, LLVM 15.0.7jl, SLEEF, DISTRO, POCL_DEBUG + · cpu-haswell-AMD Ryzen 9 5950X 16-Core Processor (fp64, il) + - NVIDIA CUDA + version: OpenCL 3.0 CUDA 12.6.65 + · NVIDIA RTX 6000 Ada Generation (fp64) + - Intel(R) OpenCL Graphics + version: OpenCL 3.0 + · Intel(R) Arc(TM) A770 Graphics (fp16, il) +``` + +!!! warning "Platform list is only computed once" + OpenCL is only computing the list of platforms [once](https://github.com/KhronosGroup/OpenCL-ICD-Loader/blob/d547426c32f9af274ec1369acd1adcfd8fe0ee40/loader/linux/icd_linux.c#L234-L238). + Therefore if `using pocl_jll` is executed after `OpenCL.versioninfo()` or other calls to the OpenCL API then it won't affect the list of platforms available and you will need to restart the Julia session and run `using pocl_jll` before `OpenCL` is used. + +## Basic example: vector add + +The traditional way of using OpenCL is by writing kernel source code in OpenCL C. For +example, a simple vector addition: + +```julia +using OpenCL, pocl_jll + +const source = """ + __kernel void vadd(__global const float *a, + __global const float *b, + __global float *c) { + int gid = get_global_id(0); + c[gid] = a[gid] + b[gid]; + }""" + +a = rand(Float32, 50_000) +b = rand(Float32, 50_000) + +d_a = CLArray(a) +d_b = CLArray(b) +d_c = similar(d_a) + +p = cl.Program(; source) |> cl.build! +k = cl.Kernel(p, "vadd") + +clcall(k, Tuple{CLPtr{Float32}, CLPtr{Float32}, CLPtr{Float32}}, + d_a, d_b, d_c; global_size=size(a)) + +c = Array(d_c) + +@assert a + b ≈ c +``` + + +## Native example: vector add + +If your platform supports SPIR-V, it's possible to use Julia functions as kernels: + +```julia +using OpenCL, pocl_jll + +function vadd(a, b, c) + gid = get_global_id(1) + @inbounds c[gid] = a[gid] + b[gid] + return +end + +a = rand(Float32, 50_000) +b = rand(Float32, 50_000) + +d_a = CLArray(a) +d_b = CLArray(b) +d_c = similar(d_a) + +@opencl global_size=size(a) vadd(d_a, d_b, d_c) + +c = Array(d_c) + +@assert a + b ≈ c +``` + + +## More examples + +You may want to check out the `examples` folder. Either `git clone` the repository to your +local machine or navigate to the OpenCL.jl install directory via: + +```julia +using OpenCL +cd(joinpath(dirname(pathof(OpenCL)), "..")) +``` + +Otherwise, feel free to take a look at the Jupyter notebooks below: + + * [Julia set fractals](https://github.com/JuliaGPU/OpenCL.jl/blob/master/examples/notebooks/julia_set_fractal.ipynb) + * [Mandlebrot fractal](https://github.com/JuliaGPU/OpenCL.jl/blob/master/examples/notebooks/mandelbrot_fractal.ipynb) + * [Transpose bandwidth](https://github.com/JuliaGPU/OpenCL.jl/blob/master/examples/notebooks/Transpose.ipynb) + + +## Credit + +This package is heavily influenced by the work of others: + + * [PyOpenCL](http://mathema.tician.de/software/pyopencl/) by Andreas Klockner + * [oclpb](https://github.com/srossross/oclpb) by Sean Ross + * [Boost.Compute](https://github.com/kylelutz/compute) by Kyle Lutz + * [rust-opencl](https://github.com/luqmana/rust-opencl) From f0720282b5e277116e9d63f76132ff719caaa604 Mon Sep 17 00:00:00 2001 From: Simeon David Schaub Date: Tue, 19 Aug 2025 13:39:37 +0200 Subject: [PATCH 2/2] remove unneeded dependency --- docs/Project.toml | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/Project.toml b/docs/Project.toml index 3a2e3607..2c0cafd8 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,6 +1,5 @@ [deps] Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" -LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589" OpenCL = "08131aa3-fb12-5dee-8b74-c09406e224a2" pocl_jll = "627d6b7a-bbe6-5189-83e7-98cc0a5aeadd"