Luke Boswell (Nov 16 2022 at 19:48): Luke Boswell (Nov 16 2022 at 19:48):I have a particular use case for packages in mind. Is this possible/compatible with the current design?
A package will contain more than one binary, or Roc app, which targets different Roc platforms. The details of how the platforms are managed or referenced is beyond the scope of this idea, I assume this will be handled seamlessly by the package manager with packages in a common cache. Each of these "apps" will have a different purpose but all are associated in some way and so should live and ship with the package.
I'll give some examples of different Roc apps that live in the same package;
These ideas all need a lot of work, but the general idea here is that we will want multiple apps sitting next to each other, in the same module space, in the same package.
The associated idea which derives from this is that having a few platforms the community standardises around means that the ecosystem can work together more easily. For example, this implies that the editor will see all the packages which expose plugins (apps) which target the editor platform and so can make these available to the user when editing files. Likewise, the online Roc tutorial can see all of the packages which have a guide which targets the tutorial platform, so it can index these and provide a good experience around this.
Georges Boris (Nov 16 2022 at 19:56):I wonder if docs/notebook wouldn't benefit from the platform/plugin mindset in a more centralized way. So instead of something more abstract as "one package many apps" we would have something more like "package + apps + plugins + docs/guides/notebooks"
I agree that the idea of package+apps makes sense for things like a fullstack web platform with backend/frontend apps for example. But docs+plugins seems like something different and more common.
Luke Boswell (Nov 16 2022 at 21:47):I'm riffing off an idea that isn't well formed here so forgive me if this is a bit too far.
Conceptually markdown is structured text and then you can add code snippets using three ``. Code is, well, code and then we add comments using #`. But they both can convey the same information. What if a Roc app was able to bring this boundary closer, or make it disappear altogether somehow? The intent here is to make Roc great for story telling. The question I'm exploring is what 'is' code, and what is it not. How far can we take this idea to the limit? If Roc code describes data and behaviour, the platform manages effects and provides an implementation, then maybe we have a pattern that supports all kinds of interactive experiences; notebooks, ui widget libraries, logistic simulations etc?
One way I have thought of, is maybe you could have a platform that accepts something like the following and renders it as a text document.
program = [
Heading "A guide to using Roc",
Paragraph "This guide ... ",
Code myFunction,
FigureTitle "Example 1",
]
Another idea was that there may be a way to support text alongside code, maybe it has start and end blocks similar to C++ multiline maybe #* lines go here *#. Then maybe you can also have a convention such as heading levels to organise text i.e. a table of contents or similar.
I must confess that I think there is a killer app here for Roc that I have in mind. In summary doing Model Based Systems Engineering correctly. The usual tooling is based on object oriented diagram modelling ala UML, and it becomes a mess when working on models that need to scale to thousands of engineers. From what I can see Roc feels pretty close to the holy grail.
Brendan Hansknecht (Nov 17 2022 at 01:32):I am definitely a bit confused as what you define as apps and what you define as a package in general. As stated above it looks like you have describe documentation/notebooks as apps.
As you have described it:
Luke Boswell (Nov 17 2022 at 08:12):Thank you @Brendan Hansknecht for letting me know. I will try and clarify and explain some of these ideas. Apologies if this is a bit long winded, there’s a few ideas here.
In short, my hypothesis was along the lines of; "can we make notebooks, guides and tutorials using Roc apps?", and "can we make this a really delightful experience to do?", "where else might these ideas be related; simulations, plans, specs, reports, papers?" etc.
At the moment our Roc tutorial is being migrated from Github markdown to html… and so I was thinking is there a way we do this using a Roc app? How will a Roc package provide other text oriented information for users in the future? What about guides… could a package write a short cheatsheet, and then maybe other tutorials to support users from different backgrounds or use cases? Can we take advantage of being inside the module and use the code itself to help?
One idea was that you could keep any strictly non-code information completely separate in other formats such as text files. For example write content in markdown files and then insert code snippets where needed. Include copies of vector files to provide illustrations or images where needed etc.
An alternative idea is to write code which can generate information in a format most suitable for the user e.g. html on the web. For example, if you write code to generate an svg library it might have guardrails which improve/ensure accessibility in metadata. Or perhaps describe a state diagram using code, and then it is displayed in an interactive widget or as a static image if printed. This approach can provide additional context by being integrated with the code; it can take advantage of the Roc projectional editor and plugins/libraries ecosystem to provide different representations or views; and it can make more advanced interactive experiences possible.
To do this I imagine that we could use a platform which takes a Roc app file and produces a binary (executable or shared library). I’m not sure what would be most appropriate here; maybe this produces an executable that starts a web server and binds to port 8080? Or perhaps a shared library which can be loaded into another thing like The Editor? One advantage of this is that the platform could provide functionality such as a built-in REPL with debugging or variable inspection, or perhaps it could provide a simulation environment, or an interface for charts to show visualisations etc, i.e. like a significantly more capable notebook.
Doc comments on functions and types provide additional context, and when combined with module docs they can provide excellent documentation for a library or package. I really like the way Elm packages do this.
I have been thinking about the concept of package specific integrations and trying to understand what that means or might look like in future. I currently understand that a package will be a collection of Roc modules that are contained in separate .roc files. A Platform package will contain the host files (in source for now or cross-compiled in future) and any platform API modules. A Library or Application package contains Roc interface modules, and app module(s). I would like to understand this more. How does a package specific integration work? Is it a separate Roc app module that gets compiled into a shared library i.e. .dll and then loaded into the editor when used? Can a package contain multiple apps which target different platforms?
Brendan Hansknecht (Nov 17 2022 at 15:52):I see. That makes sense. Sounds like a lot of work, but i can see how it could be very useful for some projects.
Brendan Hansknecht (Nov 17 2022 at 15:55):I have no idea how that should/shouldn't fit with the default package manager. Hopefully someone else has some good insight.
Anton (Nov 18 2022 at 09:51):My current thinking is that "notebooks, guides and tutorials" should use a notebook-like file format and not be a roc app.
I think the UX would be better without roc syntax distractions. We could include functionality in the roc cli to extract code snippets from this format and support building and testing.
Georges Boris (Nov 18 2022 at 10:23):there could be a platform that takes these formats and parses them into whatever - docs, interactive guides, etc.
and, through editor plugins, we could also have some way to see/interact with them directly from the code that parses them.
so maybe this could live 100% on user land? seems interesting since by living in user land it opens up room for new approaches/competitors to emerge.
Anton (Nov 18 2022 at 10:46):Parsing and rendering docs and guides would make sense to implement in rust for speed and complete access to editor types. But once we have a standardized file format anyone can build stuff with it.
Last updated: Jun 16 2026 at 16:19 UTC