You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+29-13Lines changed: 29 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,27 +11,43 @@ It's designed to make use of Scala's type system, macros, and runtime multi-stag
11
11
12
12
## Quickstart
13
13
14
-
Slinc is published to Maven Central for Scala 3. It is built to take advantage of the cutting edge of Scala functionality and features, so your project will most certainly need to track the latest Scala version if you want to use the latest version of Slinc. Currently, the Scala version in use is `3.2.0`.
14
+
Slinc is published to Maven Central for Scala 3. It is built to take advantage of the cutting edge of Scala functionality and features, so your project will most certainly need to track the latest Scala version if you want to use the latest version of Slinc. Currently, the Scala version in use is `3.3.0-RC3`.
15
15
16
-
In order to test Slinc quick, one can use scala-cli:
val (quot, rem) =Tuple.fromProduct(myLib.div(5,2))
48
+
println(s"Got a quotient of $quot and a remainder of $rem")
33
49
```
34
50
35
-
You can run this program with Java 19 via `scala-cli -j 19 -J --enable-native-access=ALL-UNNAMED test.scala` or with Java 17 via `scala-cli -j 17 -J --enable-native-access=ALL-UNNAMED -J --add-modules=jdk.incubator.foreign test.scala`.
51
+
This library relies on the user importing the runtime from `fr.hammons.slinc.runtime`.
36
52
37
53
To learn more about the library, refer to the documentation website for Slinc [here](https://slinc.hammons.fr/docs/index.html)
Copy file name to clipboardExpand all lines: core/docs/_docs/index.md
+9-7Lines changed: 9 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,14 +8,14 @@ It's designed to make use of Scala's type system, macros, and runtime multi-stag
8
8
9
9
## Quickstart
10
10
11
-
Slinc is published to Maven Central for Scala 3. It is built to take advantage of the cutting edge of Scala functionality and features, so your project will most certainly need to track the latest Scala version if you want to use the latest version of Slinc. Currently, the Scala version in use is `3.2.1`.
11
+
Slinc is published to Maven Central for Scala 3. It is built to take advantage of the cutting edge of Scala functionality and features, so your project will most certainly need to track the latest Scala version if you want to use the latest version of Slinc. Currently, the Scala version in use is `3.3.0-RC3`.
Library modules are groupings of functions in Slinc. Each can be configured in a number of ways.
6
+
7
+
A library module is a Scala `trait` that derives the `Lib` type class. Method declarations within it are used as a template for the bindings to C that the Slinc runtime will generate.
8
+
9
+
## Module Declarations
10
+
11
+
Module declarations are declarations of C library bindings without any entanglement in runtime details. This means that a module declaration only requires the use of the Slinc core library, and does not effect the runtime requirements of users of the module.
12
+
13
+
### Module naming
14
+
15
+
The type name of the module does not matter to Slinc.
16
+
17
+
### Method naming
18
+
19
+
The name of method declarations within a library module should reflect the name of the C function you wish to bind to. If a method name is not found in the C namespace, this will cause a runtime error when you try to summon the module implementation.
20
+
21
+
Example:
22
+
23
+
```scala
24
+
traitLderivesLib:
25
+
defabs(i: CInt):CInt
26
+
```
27
+
28
+
This library module `L` has a binding to `abs` in the C standard library namespace.
29
+
30
+
#### Naming overrides
31
+
32
+
You can override the C name lookup for a method declaration on a host dependent basis with the `@NameOverride` annotation. You provide the `@NameOverride` annotation with the alternative name, and an OS and architecture tuple where the name should be used. An example follows:
33
+
34
+
```scala
35
+
traitLderivesLib:
36
+
@NameOverride("_time64", OS.Windows->Arch.X64)
37
+
deftime(timer: Ptr[TimeT]):TimeT
38
+
```
39
+
40
+
This function is helpful when you have a function symbol that should be present on a platform, but has an alternative name for some reason. In the case with Windows, the `time` function in the C standard library is a macro that points to `_time64` on 64-bit platforms, and `_time32` on 32-bit platforms. Since macros do not exist as symbols in the C standard library namespace, this `NameOverride` makes the Slinc platform choose the right function name on Windows X64.
41
+
42
+
## Summoning Module Implementations
43
+
44
+
Module declarations have been shown above, but they are not useable without being summoned. Doing so requires the Slinc runtime on your classpath, and makes the JAR and class files generated dependent on a specific JVM.
45
+
46
+
To summon a module implementation, you use the `Lib.instance[?]` method as shown in the following example:
47
+
48
+
```scala
49
+
importfr.hammons.slinc.types.CInt
50
+
importfr.hammons.slinc.Lib
51
+
importfr.hammons.slinc.runtime.given
52
+
53
+
traitLderivesLib:
54
+
defabs(i: CInt):CInt
55
+
56
+
vall=Lib.instance[L]
57
+
58
+
@main defprogram= println(l.abs(4))
59
+
```
60
+
61
+
Note the assignment of the instance to a `val`. This is not strictly necessary, and `Lib.instance` will always return the same module instance, but re-summoning is more expensive than storing the summoned module implementation.
Copy file name to clipboardExpand all lines: core/docs/_docs/reference/usage.md
+7-46Lines changed: 7 additions & 46 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,14 +4,14 @@ title: Usage
4
4
5
5
## Introduction to Library Definitions
6
6
7
-
All bindings by Slinc take place in library objects, groups of like methods that reflect C functions. When defining a library object, name is not particularly important. One merely defines an object that derives `Library`. Method bindings are done via a method binding with a name matching the C function in question, and parameters with types that match the C function in question.
7
+
All bindings by Slinc take place in library traits, groups of like methods that reflect C functions. When defining a library trait, name is not particularly important. One merely defines an object that derives `Lib`. Method bindings are done via a method binding with a name matching the C function in question, and parameters with types that match the C function in question.
8
8
9
9
```scala
10
-
objectStdLibderivesLibrary:
11
-
defabs(i: Int):Int=Library.binding
10
+
traitStdLibderivesLib:
11
+
defabs(i: CInt):CInt
12
12
```
13
13
14
-
The above defines a binding to the C standard library's `abs` method. Since the C definition of `abs` is defined like `int abs(int i)`, the scala version of the method is defined with a single input that has the type `Int` and the return type `Int`. The method is defined with `Library.binding` which is a macro that connects the inputs and outputs to the C world.
14
+
The above defines a binding to the C standard library's `abs` method. Since the C definition of `abs` is defined like `int abs(int i)`, the scala version of the method is defined with a single input that has the type `CInt` and the return type `CInt`.
15
15
16
16
## Types
17
17
@@ -45,52 +45,13 @@ Using the built in JVM primitives for a binding is quick and easy if you know th
45
45
|TimeT|time_t|
46
46
47
47
48
-
Since these types are only guaranteed to be defined at runtime, interacting with them can be difficult. There are three ways at present to interact with these types:
49
-
50
-
* Assured Conversion
51
-
* Potential Conversion
52
-
* Platform focus
53
-
54
-
### Assured Conversion
55
-
56
-
Assured conversion is done via the `.as` extension method on a compatible type, or to a compatible type. This method is generally available when there's some baseline guarantee about the kind and width of the type in question. For example, `CLong` is at minimum a 32-bit wide integer type, so `Int.as[CLong]` exists. It is also (for now) at maximum a 64-bit wide integer type, so `CLong.as[Long]` exists.
57
-
58
-
### Potential Conversion
59
-
60
-
Potential conversion is generally more available than the assured conversions. Potential conversion is done via the `maybeAs` extension method that will return an `Option` result indicating whether the conversion is valid on the current host.
61
-
62
-
As an example, `Long.maybeAs[CLong]` will return `Some(l: CLong)` on X64 Linux, but `None` on X64 Windows.
63
-
64
-
### Platform Focus
65
-
66
-
The `platformFocus` method takes a platform instance and a section of code where the host dependent types have automatic conversions to and from their definitions on the host platform. As an example:
67
-
68
-
```scala
69
-
deflabs(l: CLong):CLong=Library.binding
70
-
71
-
platformFocus(x64.Linux){
72
-
//this line works here
73
-
labs(-13l) ==-13l//true
74
-
}
75
-
76
-
//this line doesn't work here, cause outside of the above zone
77
-
// CLong isn't equivalent to Long
78
-
labs(-13l) ==-13l
79
-
```
80
-
81
-
The `platformFocus` method returns `Option[A]` where `A` is the return type of the platform focus zone. The method returns `None` if the platform selected for the zone doesn't match the host. This allows you to chain together platform specific code via `.orElse`.
82
-
83
-
The C types are meant to be analogues to the primitive types defined for C. In the table above, a number have equivalents to JVM types right now, but that may change in future versions of Slinc. If your wish is to write platform independent bindings to C libraries, then you should use the C types and forgo the standard JVM primitives. Usage of the standard JVM primitives will make your bindings brittle and platform specific at some point.
48
+
Since these types are only guaranteed to be defined at runtime, interacting with them can be difficult.
84
49
85
50
## Pointers
86
51
87
52
Pointers are represented in Slinc with the `Ptr` type. For example, `Ptr[Int]` is a pointer to native memory that should be readable as a JVM Int.
88
53
89
-
The pointer class' operations are powered by three type classes:
90
-
91
-
*`LayoutOf` - this type class provides layout information about the type in question, if it exists.
92
-
*`Send` - this type class shows how to copy data of type `A` from the JVM into native memory.
93
-
*`Receive` - this type class shows how to copy data of type `A` from native memory into the JVM heap.
54
+
The pointer class' operations are powered by the `DescriptorOf` typeclass.
94
55
95
56
The list of operations available on a `Ptr[A]`:
96
57
@@ -110,4 +71,4 @@ The analog for C structs in Slinc are case classes that derive the `Struct` type
110
71
caseclassdiv_t(quot: Int, rem: Int) derivesStruct
111
72
```
112
73
113
-
These struct analogs can be composed with any type that has a Send and/or Receive defined for it.
74
+
These struct analogs can be composed with any type that has a `DescriptorOf` defined for it.
0 commit comments