Skip to content

Commit 4e28928

Browse files
simeonschaubsimeonschaub
committed
set up Documenter
closes #354
1 parent 7a7b8e9 commit 4e28928

File tree

5 files changed

+249
-0
lines changed

5 files changed

+249
-0
lines changed

‎.github/workflows/Docs.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- "docs/**"
9+
- "src/**"
10+
- "*.toml"
11+
tags: ["*"]
12+
pull_request:
13+
branches:
14+
- main
15+
paths:
16+
- "docs/**"
17+
- "src/**"
18+
- "*.toml"
19+
types: [opened, synchronize, reopened]
20+
21+
concurrency:
22+
# Skip intermediate builds: always.
23+
# Cancel intermediate builds: only if it is a pull request build.
24+
group: ${{ github.workflow }}-${{ github.ref }}
25+
cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
26+
27+
jobs:
28+
docs:
29+
name: Documentation
30+
runs-on: ubuntu-latest
31+
steps:
32+
- uses: actions/checkout@v4
33+
- uses: julia-actions/setup-julia@v2
34+
with:
35+
version: "1"
36+
- name: Use Julia cache
37+
uses: julia-actions/cache@v2
38+
- name: Instantiate environment with development version of the package
39+
run: |
40+
julia --project=docs -e '
41+
using Pkg
42+
Pkg.develop(PackageSpec(path=pwd()))
43+
Pkg.instantiate()'
44+
- name: Run doctest
45+
run: |
46+
julia --project=docs -e '
47+
using Documenter: DocMeta, doctest
48+
using OpenCL
49+
DocMeta.setdocmeta!(OpenCL, :DocTestSetup, :(using OpenCL); recursive=true)
50+
doctest(OpenCL)'
51+
- name: Generate and deploy documentation
52+
run: julia --project=docs docs/make.jl
53+
env:
54+
JULIA_PKG_SERVER: ""
55+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
56+
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

‎docs/Project.toml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[deps]
2+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3+
LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
4+
OpenCL = "08131aa3-fb12-5dee-8b74-c09406e224a2"
5+
pocl_jll = "627d6b7a-bbe6-5189-83e7-98cc0a5aeadd"
6+
7+
[compat]
8+
Documenter = "1"

‎docs/make.jl‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
using OpenCL
2+
using Documenter
3+
4+
DocMeta.setdocmeta!(OpenCL, :DocTestSetup, :(using OpenCL, pocl_jll); recursive = true)
5+
6+
const page_rename = Dict("developer.md" => "Developer docs") # Without the numbers
7+
const numbered_pages = [
8+
file for file in readdir(joinpath(@__DIR__, "src")) if
9+
file != "index.md" && splitext(file)[2] == ".md"
10+
]
11+
12+
makedocs(;
13+
modules = [OpenCL],
14+
authors = "Jake Bolewski, JuliaHub and other contributors",
15+
repo = "https://github.com/JuliaGPU/OpenCL.jl/blob/{commit}{path}#{line}",
16+
sitename = "OpenCL.jl",
17+
format = Documenter.HTML(; canonical = "https://JuliaGPU.github.io/OpenCL.jl"),
18+
pages = ["index.md"; numbered_pages],
19+
)
20+
21+
deploydocs(; repo = "github.com/JuliaGPU/OpenCL.jl")

‎docs/src/95-reference.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# [Reference](@id reference)
2+
3+
## Contents
4+
5+
```@contents
6+
Pages = ["95-reference.md"]
7+
```
8+
9+
## Index
10+
11+
```@index
12+
Pages = ["95-reference.md"]
13+
```
14+
15+
```@autodocs
16+
Modules = [OpenCL, OpenCL.cl]
17+
```

‎docs/src/index.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
```@meta
2+
CurrentModule = OpenCL
3+
```
4+
5+
# OpenCL
6+
7+
*Julia interface for the OpenCL parallel computation API*
8+
9+
This package aims to be a complete solution for OpenCL programming in Julia, similar in
10+
scope to [PyOpenCL] for Python. It provides a high level API for OpenCL to make programing
11+
hardware accelerators, such as GPUs, FPGAs, and DSPs, as well as multicore CPUs much less
12+
onerous.
13+
14+
15+
!!! note "OpenCL.jl needs your help!"
16+
If you can help maintain this package, please reach out on the [JuliaLang Slack](https://julialang.org/slack/) #gpu channel.
17+
18+
!!! warning "OpenCL.jl is currently undergoing major changes."
19+
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.
20+
21+
22+
## Installation
23+
24+
1. Install an OpenCL driver. You can install one system-wide, i.e., using your package
25+
manager, or use `pocl_jll.jl` for a CPU back-end.
26+
2. Add OpenCL to your Julia environment:
27+
28+
```julia
29+
using Pkg
30+
Pkg.add("OpenCL")
31+
```
32+
33+
3. Test your installation:
34+
35+
```julia-repl
36+
julia> OpenCL.versioninfo()
37+
OpenCL.jl version 0.10.0
38+
39+
Toolchain:
40+
- Julia v1.10.5
41+
- OpenCL_jll v2024.5.8+1
42+
43+
Available platforms: 3
44+
- Portable Computing Language
45+
version: OpenCL 3.0 PoCL 6.0 Linux, Release, RELOC, SPIR-V, LLVM 15.0.7jl, SLEEF, DISTRO, POCL_DEBUG
46+
· cpu-haswell-AMD Ryzen 9 5950X 16-Core Processor (fp64, il)
47+
- NVIDIA CUDA
48+
version: OpenCL 3.0 CUDA 12.6.65
49+
· NVIDIA RTX 6000 Ada Generation (fp64)
50+
- Intel(R) OpenCL Graphics
51+
version: OpenCL 3.0
52+
· Intel(R) Arc(TM) A770 Graphics (fp16, il)
53+
54+
!!! warning "Platform list is only computed once"
55+
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).
56+
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.
57+
58+
## Basic example: vector add
59+
60+
The traditional way of using OpenCL is by writing kernel source code in OpenCL C. For
61+
example, a simple vector addition:
62+
63+
```julia
64+
using OpenCL, pocl_jll
65+
66+
const source = """
67+
__kernel void vadd(__global const float *a,
68+
__global const float *b,
69+
__global float *c) {
70+
int gid = get_global_id(0);
71+
c[gid] = a[gid] + b[gid];
72+
}"""
73+
74+
a = rand(Float32, 50_000)
75+
b = rand(Float32, 50_000)
76+
77+
d_a = CLArray(a)
78+
d_b = CLArray(b)
79+
d_c = similar(d_a)
80+
81+
p = cl.Program(; source) |> cl.build!
82+
k = cl.Kernel(p, "vadd")
83+
84+
clcall(k, Tuple{CLPtr{Float32}, CLPtr{Float32}, CLPtr{Float32}},
85+
d_a, d_b, d_c; global_size=size(a))
86+
87+
c = Array(d_c)
88+
89+
@assert a + b ≈ c
90+
```
91+
92+
93+
## Native example: vector add
94+
95+
If your platform supports SPIR-V, it's possible to use Julia functions as kernels:
96+
97+
```julia
98+
using OpenCL, pocl_jll
99+
100+
function vadd(a, b, c)
101+
gid = get_global_id(1)
102+
@inbounds c[gid] = a[gid] + b[gid]
103+
return
104+
end
105+
106+
a = rand(Float32, 50_000)
107+
b = rand(Float32, 50_000)
108+
109+
d_a = CLArray(a)
110+
d_b = CLArray(b)
111+
d_c = similar(d_a)
112+
113+
@opencl global_size=size(a) vadd(d_a, d_b, d_c)
114+
115+
c = Array(d_c)
116+
117+
@assert a + b ≈ c
118+
```
119+
120+
121+
## More examples
122+
123+
You may want to check out the `examples` folder. Either `git clone` the repository to your
124+
local machine or navigate to the OpenCL.jl install directory via:
125+
126+
```julia
127+
using OpenCL
128+
cd(joinpath(dirname(pathof(OpenCL)), ".."))
129+
```
130+
131+
Otherwise, feel free to take a look at the Jupyter notebooks below:
132+
133+
* [Julia set fractals](https://github.com/JuliaGPU/OpenCL.jl/blob/master/examples/notebooks/julia_set_fractal.ipynb)
134+
* [Mandlebrot fractal](https://github.com/JuliaGPU/OpenCL.jl/blob/master/examples/notebooks/mandelbrot_fractal.ipynb)
135+
* [Transpose bandwidth](https://github.com/JuliaGPU/OpenCL.jl/blob/master/examples/notebooks/Transpose.ipynb)
136+
137+
138+
## Credit
139+
140+
This package is heavily influenced by the work of others:
141+
142+
* [PyOpenCL](http://mathema.tician.de/software/pyopencl/) by Andreas Klockner
143+
* [oclpb](https://github.com/srossross/oclpb) by Sean Ross
144+
* [Boost.Compute](https://github.com/kylelutz/compute) by Kyle Lutz
145+
* [rust-opencl](https://github.com/luqmana/rust-opencl)
146+
147+

0 commit comments

Comments
 (0)