From 3683f208381bc43163d0e4bfbf1f41206eefad19 Mon Sep 17 00:00:00 2001 From: Richard Feldman Date: Sat, 12 Jun 2021 22:37:19 -0400 Subject: [PATCH 1/2] Add hello-zig (clone of hello-world) example --- examples/hello-zig/.gitignore | 1 + examples/hello-zig/Hello.roc | 12 +++ examples/hello-zig/README.md | 48 +++++++++++ .../hello-zig/platform/Package-Config.roc | 10 +++ examples/hello-zig/platform/host.zig | 79 +++++++++++++++++++ 5 files changed, 150 insertions(+) create mode 100644 examples/hello-zig/.gitignore create mode 100644 examples/hello-zig/Hello.roc create mode 100644 examples/hello-zig/README.md create mode 100644 examples/hello-zig/platform/Package-Config.roc create mode 100644 examples/hello-zig/platform/host.zig diff --git a/examples/hello-zig/.gitignore b/examples/hello-zig/.gitignore new file mode 100644 index 0000000000..6b820fd903 --- /dev/null +++ b/examples/hello-zig/.gitignore @@ -0,0 +1 @@ +hello-world diff --git a/examples/hello-zig/Hello.roc b/examples/hello-zig/Hello.roc new file mode 100644 index 0000000000..24a02e7823 --- /dev/null +++ b/examples/hello-zig/Hello.roc @@ -0,0 +1,12 @@ +app "hello-world" + packages { base: "platform" } + imports [] + provides [ main ] to base + +greeting = + hi = "Hello" + name = "World" + + "\(hi), \(name)!!!!!!!!!!!!!" + +main = greeting diff --git a/examples/hello-zig/README.md b/examples/hello-zig/README.md new file mode 100644 index 0000000000..a2890f03ed --- /dev/null +++ b/examples/hello-zig/README.md @@ -0,0 +1,48 @@ +# Hello, World! + +To run, `cd` into this directory and run: + +```bash +$ cargo run run Hello.roc +``` + +To run in release mode instead, do: + +```bash +$ cargo run --release run Hello.roc +``` + +## Troubleshooting + +If you encounter `cannot find -lc++`, run the following for ubuntu `sudo apt install libc++-dev`. + +## Design Notes + +This demonstrates the basic design of hosts: Roc code gets compiled into a pure +function (in this case, a thunk that always returns `"Hello, World!"`) and +then the host calls that function. Fundamentally, that's the whole idea! The host +might not even have a `main` - it could be a library, a plugin, anything. +Everything else is built on this basic "hosts calling linked pure functions" design. + +For example, things get more interesting when the compiled Roc function returns +a `Task` - that is, a tagged union data structure containing function pointers +to callback closures. This lets the Roc pure function describe arbitrary +chainable effects, which the host can interpret to perform I/O as requested by +the Roc program. (The tagged union `Task` would have a variant for each supported +I/O operation.) + +In this trivial example, it's very easy to line up the API between the host and +the Roc program. In a more involved host, this would be much trickier - especially +if the API were changing frequently during development. + +The idea there is to have a first-class concept of "glue code" which host authors +can write (it would be plain Roc code, but with some extra keywords that aren't +available in normal modules - kinda like `port module` in Elm), and which +describe both the Roc-host/C boundary as well as the Roc-host/Roc-app boundary. +Roc application authors only care about the Roc-host/Roc-app portion, and the +host author only cares about the Roc-host/C bounary when implementing the host. + +Using this glue code, the Roc compiler can generate C header files describing the +boundary. This not only gets us host compatibility with C compilers, but also +Rust FFI for free, because [`rust-bindgen`](https://github.com/rust-lang/rust-bindgen) +generates correct Rust FFI bindings from C headers. diff --git a/examples/hello-zig/platform/Package-Config.roc b/examples/hello-zig/platform/Package-Config.roc new file mode 100644 index 0000000000..377d5c0994 --- /dev/null +++ b/examples/hello-zig/platform/Package-Config.roc @@ -0,0 +1,10 @@ +platform examples/hello-world + requires {}{ main : Str } + exposes [] + packages {} + imports [] + provides [ mainForHost ] + effects fx.Effect {} + +mainForHost : Str +mainForHost = main diff --git a/examples/hello-zig/platform/host.zig b/examples/hello-zig/platform/host.zig new file mode 100644 index 0000000000..d1a563a68e --- /dev/null +++ b/examples/hello-zig/platform/host.zig @@ -0,0 +1,79 @@ +const std = @import("std"); +const str = @import("str"); +const RocStr = str.RocStr; +const testing = std.testing; +const expectEqual = testing.expectEqual; +const expect = testing.expect; + +comptime { + // This is a workaround for https://github.com/ziglang/zig/issues/8218 + // which is only necessary on macOS. + // + // Once that issue is fixed, we can undo the changes in + // 177cf12e0555147faa4d436e52fc15175c2c4ff0 and go back to passing + // -fcompiler-rt in link.rs instead of doing this. Note that this + // workaround is present in many host.zig files, so make sure to undo + // it everywhere! + if (std.builtin.os.tag == .macos) { + _ = @import("compiler_rt"); + } +} + +extern fn malloc(size: usize) callconv(.C) ?*c_void; +extern fn realloc(c_ptr: [*]align(@alignOf(u128)) u8, size: usize) callconv(.C) ?*c_void; +extern fn free(c_ptr: [*]align(@alignOf(u128)) u8) callconv(.C) void; + +export fn roc_alloc(size: usize, alignment: u32) callconv(.C) ?*c_void { + return malloc(size); +} + +export fn roc_realloc(c_ptr: *c_void, old_size: usize, new_size: usize, alignment: u32) callconv(.C) ?*c_void { + return realloc(@alignCast(16, @ptrCast([*]u8, c_ptr)), new_size); +} + +export fn roc_dealloc(c_ptr: *c_void, alignment: u32) callconv(.C) void { + free(@alignCast(16, @ptrCast([*]u8, c_ptr))); +} + +const mem = std.mem; +const Allocator = mem.Allocator; + +extern fn roc__mainForHost_1_exposed(*RocCallResult) void; + +const RocCallResult = extern struct { flag: usize, content: RocStr }; + +const Unit = extern struct {}; + +pub export fn main() i32 { + const stdout = std.io.getStdOut().writer(); + const stderr = std.io.getStdErr().writer(); + + // make space for the result + var callresult = RocCallResult{ .flag = 0, .content = RocStr.empty() }; + + // start time + var ts1: std.os.timespec = undefined; + std.os.clock_gettime(std.os.CLOCK_REALTIME, &ts1) catch unreachable; + + // actually call roc to populate the callresult + roc__mainForHost_1_exposed(&callresult); + + // stdout the result + stdout.print("{s}\n", .{callresult.content.asSlice()}) catch unreachable; + + callresult.content.deinit(); + + // end time + var ts2: std.os.timespec = undefined; + std.os.clock_gettime(std.os.CLOCK_REALTIME, &ts2) catch unreachable; + + const delta = to_seconds(ts2) - to_seconds(ts1); + + stderr.print("runtime: {d:.3}ms\n", .{delta * 1000}) catch unreachable; + + return 0; +} + +fn to_seconds(tms: std.os.timespec) f64 { + return @intToFloat(f64, tms.tv_sec) + (@intToFloat(f64, tms.tv_nsec) / 1_000_000_000.0); +} From 2fc33054238215236ccb842f8406120bc60645dc Mon Sep 17 00:00:00 2001 From: Richard Feldman Date: Sat, 12 Jun 2021 22:37:31 -0400 Subject: [PATCH 2/2] Have hello-world example use C --- examples/hello-world/platform/host.c | 76 +++++++++++++++++++++++++ examples/hello-world/platform/host.zig | 79 -------------------------- 2 files changed, 76 insertions(+), 79 deletions(-) create mode 100644 examples/hello-world/platform/host.c delete mode 100644 examples/hello-world/platform/host.zig diff --git a/examples/hello-world/platform/host.c b/examples/hello-world/platform/host.c new file mode 100644 index 0000000000..076f6ca1a4 --- /dev/null +++ b/examples/hello-world/platform/host.c @@ -0,0 +1,76 @@ +#include +#include +#include +#include + +void* roc_alloc(size_t size, unsigned int alignment) { + return malloc(size); +} + +void* roc_realloc(void* ptr, size_t old_size, size_t new_size, unsigned int alignment) { + return realloc(ptr, new_size); +} + +void roc_dealloc(void* ptr, unsigned int alignment) { + free(ptr); +} + +struct RocStr { + char* bytes; + size_t len; +}; + +struct RocCallResult { + size_t flag; + struct RocStr content; +}; + +extern void roc__mainForHost_1_exposed(struct RocCallResult *re); + +const size_t MAX_STACK_STR_BYTES = 1024; + +int main() { + // make space for the result + struct RocCallResult callresult; + + // call roc to populate the callresult + roc__mainForHost_1_exposed(&callresult); + struct RocStr str = callresult.content; + + // Convert from RocStr to C string (null-terminated char*) + size_t len = str.len; + char* c_str; + + // Allocate on the stack unless the string is particularly big. + // (Don't want a stack overflow!) + if (len <= MAX_STACK_STR_BYTES) { + c_str = (char*)alloca(len + 1); + } else { + c_str = (char*)malloc(len + 1); + } + + memcpy(c_str, str.bytes, len); + + // null-terminate + c_str[len] = 0; + + // Print the string to stdout + printf("%s\n", c_str); + + // Pointer to the beginning of the RocStr's actual allocation, which is + // the size_t immediately preceding the first stored byte. + size_t* str_base_ptr = (size_t*)str.bytes - 1; + + // If *str_base_ptr is equal to 0, then the string is in the + // read-only data section of the binary, and can't be freed! + if (*str_base_ptr != 0) { + roc_dealloc(str_base_ptr, 8); + } + + // If we malloc'd c_str, free it. + if (len > MAX_STACK_STR_BYTES) { + free(c_str); + } + + return 0; +} diff --git a/examples/hello-world/platform/host.zig b/examples/hello-world/platform/host.zig deleted file mode 100644 index d1a563a68e..0000000000 --- a/examples/hello-world/platform/host.zig +++ /dev/null @@ -1,79 +0,0 @@ -const std = @import("std"); -const str = @import("str"); -const RocStr = str.RocStr; -const testing = std.testing; -const expectEqual = testing.expectEqual; -const expect = testing.expect; - -comptime { - // This is a workaround for https://github.com/ziglang/zig/issues/8218 - // which is only necessary on macOS. - // - // Once that issue is fixed, we can undo the changes in - // 177cf12e0555147faa4d436e52fc15175c2c4ff0 and go back to passing - // -fcompiler-rt in link.rs instead of doing this. Note that this - // workaround is present in many host.zig files, so make sure to undo - // it everywhere! - if (std.builtin.os.tag == .macos) { - _ = @import("compiler_rt"); - } -} - -extern fn malloc(size: usize) callconv(.C) ?*c_void; -extern fn realloc(c_ptr: [*]align(@alignOf(u128)) u8, size: usize) callconv(.C) ?*c_void; -extern fn free(c_ptr: [*]align(@alignOf(u128)) u8) callconv(.C) void; - -export fn roc_alloc(size: usize, alignment: u32) callconv(.C) ?*c_void { - return malloc(size); -} - -export fn roc_realloc(c_ptr: *c_void, old_size: usize, new_size: usize, alignment: u32) callconv(.C) ?*c_void { - return realloc(@alignCast(16, @ptrCast([*]u8, c_ptr)), new_size); -} - -export fn roc_dealloc(c_ptr: *c_void, alignment: u32) callconv(.C) void { - free(@alignCast(16, @ptrCast([*]u8, c_ptr))); -} - -const mem = std.mem; -const Allocator = mem.Allocator; - -extern fn roc__mainForHost_1_exposed(*RocCallResult) void; - -const RocCallResult = extern struct { flag: usize, content: RocStr }; - -const Unit = extern struct {}; - -pub export fn main() i32 { - const stdout = std.io.getStdOut().writer(); - const stderr = std.io.getStdErr().writer(); - - // make space for the result - var callresult = RocCallResult{ .flag = 0, .content = RocStr.empty() }; - - // start time - var ts1: std.os.timespec = undefined; - std.os.clock_gettime(std.os.CLOCK_REALTIME, &ts1) catch unreachable; - - // actually call roc to populate the callresult - roc__mainForHost_1_exposed(&callresult); - - // stdout the result - stdout.print("{s}\n", .{callresult.content.asSlice()}) catch unreachable; - - callresult.content.deinit(); - - // end time - var ts2: std.os.timespec = undefined; - std.os.clock_gettime(std.os.CLOCK_REALTIME, &ts2) catch unreachable; - - const delta = to_seconds(ts2) - to_seconds(ts1); - - stderr.print("runtime: {d:.3}ms\n", .{delta * 1000}) catch unreachable; - - return 0; -} - -fn to_seconds(tms: std.os.timespec) f64 { - return @intToFloat(f64, tms.tv_sec) + (@intToFloat(f64, tms.tv_nsec) / 1_000_000_000.0); -}