Skip to content

Commit 1458c5c

Browse files
twesterhouttwesterhout
committed
More docs
1 parent b900b9c commit 1458c5c

File tree

9 files changed

+59
-123
lines changed

9 files changed

+59
-123
lines changed

‎README.md

Lines changed: 0 additions & 79 deletions
This file was deleted.

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
test-readme/README.lhs

‎flake.nix

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,7 @@
177177
nativeBuildInputs = with pkgs; with ps; [
178178
cabal-install
179179
doctest
180+
markdown-unlit
180181
haskell-language-server
181182
# Formatters
182183
fourmolu

‎halide-haskell.cabal

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,11 @@ description:
1313
This package provides Haskell bindings that allow to write Halide embedded in
1414
Haskell without C++.
1515

16+
The best way to learn Halide is to have a look at the
17+
[tutorials](https://github.com/twesterhout/halide-haskell/tree/master/tutorials).
18+
Reference documentation is provided by the haddocks of the 'Language.Halide'
19+
module.
20+
1621
homepage: https://github.com/twesterhout/halide-haskell
1722
bug-reports: https://github.com/twesterhout/halide-haskell/issues
1823
license: BSD-3-Clause
@@ -48,8 +53,6 @@ common common-options
4853
DerivingStrategies
4954
FunctionalDependencies
5055
LambdaCase
51-
LambdaCase
52-
LambdaCase
5356
OverloadedRecordDot
5457
OverloadedStrings
5558
TypeFamilies

‎src/Language/Halide.hs

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
-- |
2+
-- Module : Language.Halide
3+
-- Copyright : (c) Tom Westerhout, 2023
4+
--
5+
-- This package provides Haskell bindings that allow to write Halide embedded in Haskell without C++.
6+
--
7+
-- This module contains the reference documentation for Halide. If you're new, the best way to learn Halide is to have a look at the [tutorials](https://github.com/twesterhout/halide-haskell/tree/master/tutorials).
18
module Language.Halide
29
( -- * Scalar expressions
310

@@ -201,8 +208,8 @@ module Language.Halide
201208
)
202209
where
203210

204-
import GHC.TypeLits (KnownNat)
205211
import Foreign.Ptr (Ptr)
212+
import GHC.TypeLits (KnownNat)
206213
import Language.Halide.Buffer
207214
import Language.Halide.Context
208215
import Language.Halide.Dimension

‎src/Language/Halide/Expr.hs

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -68,16 +68,16 @@ import Data.Int (Int32)
6868
import Data.Proxy
6969
import Data.Ratio (denominator, numerator)
7070
import Data.Text (Text, unpack)
71-
import qualified Data.Text.Encoding as T
72-
import qualified Data.Vector.Storable.Mutable as SM
71+
import Data.Text.Encoding qualified as T
72+
import Data.Vector.Storable.Mutable qualified as SM
7373
import Foreign.ForeignPtr
7474
import Foreign.Marshal (alloca, allocaArray, peekArray, toBool, with)
7575
import Foreign.Ptr (Ptr, castPtr, nullPtr)
7676
import Foreign.Storable (peek)
7777
import GHC.Stack (HasCallStack)
78-
import qualified Language.C.Inline as C
79-
import qualified Language.C.Inline.Cpp.Exception as C
80-
import qualified Language.C.Inline.Unsafe as CU
78+
import Language.C.Inline qualified as C
79+
import Language.C.Inline.Cpp.Exception qualified as C
80+
import Language.C.Inline.Unsafe qualified as CU
8181
import Language.Halide.Buffer
8282
import Language.Halide.Context
8383
import Language.Halide.Type
@@ -150,6 +150,8 @@ mkVar (T.encodeUtf8 -> s) = fmap Var . cxxConstruct $ \ptr ->
150150
new ($(Halide::Var* ptr)) Halide::Var{std::string{$bs-ptr:s, static_cast<size_t>($bs-len:s)}} } |]
151151

152152
-- | Create a named reduction variable.
153+
--
154+
-- For more information about reduction variables, see [@Halide::RDom@](https://halide-lang.org/docs/class_halide_1_1_r_dom.html).
153155
mkRVar
154156
:: Text
155157
-- ^ name
@@ -253,7 +255,9 @@ bool condExpr trueExpr falseExpr = unsafePerformIO $
253255
Halide::select(*$(Halide::Expr* p),
254256
*$(Halide::Expr* t), *$(Halide::Expr* f))} } |]
255257

256-
-- | Evaluate a scalar expression. It should contain no parameters.
258+
-- | Evaluate a scalar expression.
259+
--
260+
-- It should contain no parameters. If it does contain parameters, an exception will be thrown.
257261
evaluate :: forall a. IsHalideType a => Expr a -> IO a
258262
evaluate expr =
259263
asExpr expr $ \e -> do
@@ -270,6 +274,10 @@ evaluate expr =
270274
} |]
271275
SM.read out 0
272276

277+
-- | Convert expression to integer immediate.
278+
--
279+
-- Tries to extract the value of an expression if it is a compile-time constant. If the expression
280+
-- isn't known at compile-time of the Halide pipeline, returns 'Nothing'.
273281
toIntImm :: IsHalideType a => Expr a -> Maybe Int
274282
toIntImm expr = unsafePerformIO $
275283
asExpr expr $ \expr' -> do

‎src/Language/Halide/Func.hs

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -73,15 +73,15 @@ import Data.IORef
7373
import Data.Kind (Type)
7474
import Data.Proxy
7575
import Data.Text (Text)
76-
import qualified Data.Text.Encoding as T
76+
import Data.Text.Encoding qualified as T
7777
import Foreign.ForeignPtr
7878
import Foreign.Marshal (toBool, with)
7979
import Foreign.Ptr (Ptr, castPtr)
8080
import GHC.Stack (HasCallStack)
8181
import GHC.TypeLits
82-
import qualified Language.C.Inline as C
83-
import qualified Language.C.Inline.Cpp.Exception as C
84-
import qualified Language.C.Inline.Unsafe as CU
82+
import Language.C.Inline qualified as C
83+
import Language.C.Inline.Cpp.Exception qualified as C
84+
import Language.C.Inline.Unsafe qualified as CU
8585
import Language.Halide.Buffer
8686
import Language.Halide.Context
8787
import Language.Halide.Dimension
@@ -101,7 +101,8 @@ importHalide
101101
-- | A function in Halide. Conceptually, it can be thought of as a lazy
102102
-- @n@-dimensional buffer of type @a@.
103103
--
104-
-- This is a wrapper around @Halide::Func@ C++ type.
104+
-- This is a wrapper around the [@Halide::Func@](https://halide-lang.org/docs/class_halide_1_1_func.html)
105+
-- C++ type.
105106
data Func (t :: FuncTy) (n :: Nat) (a :: Type) where
106107
Func :: {-# UNPACK #-} !(ForeignPtr CxxFunc) -> Func 'FuncTy n a
107108
Param :: {-# UNPACK #-} !(IORef (Maybe (ForeignPtr CxxImageParam))) -> Func 'ParamTy n a

‎test-readme/README.lhs

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,10 @@ the same process.
1515
**This package provides Haskell bindings that allow to write Halide embedded in
1616
Haskell without C++** 😋.
1717

18-
- [Tutorials](./tutorials)
19-
- Reference documentation
20-
- Tests
18+
- [Tutorials](https://github.com/twesterhout/halide-haskell/tree/master/tutorials)
19+
- [Reference documentation](https://hackage.haskell.org/package/halide-haskell-0.0.1.0)
2120

22-
## Getting started
21+
## 🚀 Getting started
2322

2423
As a simple example, here's how you could implement array addition with halide-haskell:
2524

@@ -58,7 +57,9 @@ main = do
5857
print =<< peekToList out'
5958
```
6059
61-
## Contributing
60+
For more examples, have a look a the [tutorials](https://github.com/twesterhout/halide-haskell/tree/master/tutorials).
61+
62+
## 🔨 Contributing
6263
6364
Currently, the best way to get started is to use Nix:
6465

‎tutorials/01-Basics/halide-tutorial01.cabal

Lines changed: 15 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,27 @@
11
cabal-version: 3.0
22
name: halide-tutorial01
33
version: 0.1.0.0
4-
5-
-- synopsis:
6-
-- description:
74
license: BSD-3-Clause
85
license-file: LICENSE
96
author: twesterhout
107
maintainer: [email protected]
11-
12-
-- copyright:
138
build-type: Simple
14-
extra-doc-files: CHANGELOG.md
15-
16-
-- extra-source-files:
17-
18-
common warnings
19-
ghc-options: -Wall
209

21-
executable halide-tutorial01-dummy
22-
import: warnings
23-
main-is: Main.hs
24-
build-depends: base >=4.16.0.0 && <5
25-
hs-source-dirs: app
10+
common setup
11+
ghc-options: -W -pgmL markdown-unlit
2612
default-language: GHC2021
13+
build-depends: base >=4.16.0.0 && <5
14+
, vector
15+
, halide-haskell
16+
, hspec
17+
-- build-tools-depends: markdown-unlit:exe:markdown-unlit
18+
19+
executable halide-tutorial01
20+
import: setup
21+
main-is: README.lhs
22+
hs-source-dirs: .
2723

2824
test-suite halide-tutorial01-test
29-
import: warnings
30-
type: exitcode-stdio-1.0
31-
default-language: GHC2021
32-
ghc-options: -pgmL markdown-unlit
33-
main-is: README.lhs
34-
build-tools-depends: markdown-unlit:exe:markdown-unlit
35-
build-depends: base >=4.16.0.0 && <5
36-
, halide-haskell
37-
, hspec
25+
import: setup
26+
main-is: README.lhs
27+
type: exitcode-stdio-1.0

‎tutorials/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Tutorials
2+
3+
- [1 Getting started with `Func`s, `Var`s, and `Expr`s](./01-Basics)

0 commit comments

Comments
 (0)