Platform Cookbook · ideas · Zulip Chat Archive

I could see in the future people wanting to add some high performance functions or libraries functions for their roc code to call. I was thinking it could be useful to have a “cookbook” that guides you on how to add custom functions to a platform and/or make a platform from scratch with a bunch of code snippets.

witoldsz (Oct 20 2024 at 10:13):

Agree! From my perspective, writing any more complicated software in Roc would start from tinkering with some platform (C and Zig would be cool to have as a base) to enhance the IO capabilities, like databases, monitoring tools, messaging queues, etc.

Maybe even some higher level languages like Go, F#, Ocaml, C# or Java... (hell even Python?) could be great as a base? Node/Deno integration could also be nice.

All this to be able to quickly get a kickstart a project and move into Roc as fast as possible.

Brendan Hansknecht (Oct 20 2024 at 15:59):

This has always been one of those back burner things. Platforms have been pretty stable for quite a while, but roc still has c abi bugs and glue is very very limited today. So working on a platform today is a lot of trial and error and asking questions to understand types and bugs better

Brendan Hansknecht (Oct 20 2024 at 16:00):

Makes it hard to really concretely write anything out today, but we definitely could document a lot better.

Tanner Nielsen (Oct 20 2024 at 16:32):

I pop in every month or so to check on the state of platform development in Roc, and the lack of guides is on this topic is one of the reasons I struggle to justify exploring Roc further. I understand the hesitance to create documentation around something that is still evolving, but perhaps very high-level documentation would be a good place to start? The closest thing I could find is https://www.roc-lang.org/platforms#implementation, but it's just a subsection within a larger article about what platforms are and their benefits, not really focused on development.

My suggestion (take with a grain of salt) is to extract the linked section above into the beginnings of an official platform development guide. The guide could be entirely high-level for the time being and plastered with warnings like "all of this is subject to change, proceed at your own risk" but to me this is much better than "there is no guide, but someone in Zulip will be happy to help." As much as I appreciate the friendly and helpful community, what I really want is docs, even if they are incomplete and subject to change. That said, I suspect that high-level docs would remain relevant even as platform development continues to evolve, whereas a more concrete "cookbook" probably would not.

Brendan Hansknecht (Oct 20 2024 at 16:53):

Yeah, high level along with a guide on the basic mapping + how to debug may be useful.

Brendan Hansknecht (Oct 20 2024 at 16:54):

John Konecny (Oct 20 2024 at 16:58):

How difficult is it to write a platform? I could try to write one myself and document along the way the process and then make a PR for a page on the website.
It might be better if a complete beginner tries to do it and you guys can correct any misunderstanding I have.

Richard Feldman (Oct 20 2024 at 16:58):

John Konecny (Oct 20 2024 at 16:59):

Tanner Nielsen (Oct 20 2024 at 17:01):

To Brendan's point, perhaps high-level docs alone wouldn't be enough. Topics I'd like to see in a platform dev guide might be (again, take with a grain of salt):

Brendan Hansknecht (Oct 20 2024 at 17:14):

:point_up: Yeah, that sounds roughly what would be most useful right now. Probably along with some basic info on the layout of common types.

Jasper Woudenberg (Oct 20 2024 at 17:16):

I'm going through writing a platform for the first time at the moment. I don't know how generalizable that experience is, but my experience is that it's slow-going in a good way, i.e. not banging my head against the wall, moving forward steadily, learning things.

I'm trying it out in Zig, which based on reading what others are saying I imagine is 'medium' difficulty :), since it's not as easy as doing a Roc platform (for which glue is available), but there are some examples available from folks having done it before.

Roc glue was giving me some trouble today because I had trouble finding an example of generating glue code. I found generated glue code in a couple of places, but not a script folks were using for generating it. Found one in basic-webserver eventually and that helped!

Brendan Hansknecht (Oct 20 2024 at 17:20):

Personally, I find myself workounding around glue a lot, so I prefer zig (really should write zig glue at some point). That said, I know essentially all the low level details. I know that @Luke Boswell successfully uses glue.

Jasper Woudenberg (Oct 20 2024 at 17:29):

Yeah, I don't mind writing some helper types in Zig matching the ones I got in Roc, but not knowing the low level details I wanted glue to tell me what those Zig types should look like, to make sure I get things like union order right.

The glue spec I ended up with just prints the information glue produces. I think I got the trick from @Luke Boswell somewhere. This is the spec in case it's useful for someone else:

# glue.roc
app [makeGlue] {
    pf: platform "https://github.com/lukewilliamboswell/roc/releases/download/test/olBfrjtI-HycorWJMxdy7Dl2pcbbBoJy4mnSrDtRrlI.tar.br",
}

import pf.Types exposing [Types]
import pf.File exposing [File]

makeGlue : List Types -> Result (List File) Str
makeGlue = \types ->
    Ok [
        {
            name: "types.txt",
            content: List.map types Inspect.toStr |> Str.joinWith "\n",
        },
    ]

# glue-main.roc
platform "glue-types"
    requires {} { main : _ }
    exposes []
    packages {}
    imports []
    provides [mainForHost]

GlueTypes : {
    a : SomeType,
    b : AnotherType,
}

mainForHost : GlueTypes
mainForHost = main

roc glue glue.roc . glue-main.roc

That will put a types.txt file in your current working directory with some info.

Brendan Hansknecht (Oct 20 2024 at 17:35):

We should check that file into the repo (preferably with a short readme). Mind making a PR? Would be great to have it right next to RustGlue.roc just to help people with debugging

Richard Feldman (Oct 20 2024 at 18:01):

Jasper Woudenberg (Oct 20 2024 at 18:34):

Luke Boswell (Oct 20 2024 at 18:38):

I've been doing a bunch of work to try and learn enough to write this kind of documentation. There is a lot though. I never realised just how massive and ambitious the vision for roc was until I started exploring all the different ways you can use it.

Luke Boswell (Oct 20 2024 at 18:39):

Luke Boswell (Oct 20 2024 at 18:40):

These will need a little cleanup -- any assistance is always appreciated. :grinning:

Basically there's the purity inference stuff about to land that is definitely worth updating (or at least staging a PR) ... which also helps give Agus feedback on any bugs.

Stream: ideas

Topic: Platform Cookbook

John Konecny (Oct 20 2024 at 09:56):