Show HN: dk – A script runner and cross-compiler, written in OCaml
diskuv.comI've always found it cool to be in roles where I can help a younger generation learn skills to have a bright future. That role is something I do in a few ways (as a parent, robotics mentor, school board advisor and Sunday school teacher) and I suspect most HN readers share the same role and appreciation. And for developing software skills, it was obvious that both the students and I had to have a productive software environment where we could work together. That theme of experienced/inexperienced engineers working together is the context in which I created `dk` as a scripting tool.
My testing ground has been students with one or two AP CS courses (high school computer science in the US), some of whom interned with me. I had to tackle a few problems:
- The development environment had to be simple to setup and the programming language couldn't be complicated - The recognition that writing small, easily testable units of work (ex. "scripts") has been the only way I've found for very junior programmers to develop a large application - Cheap, locked-down development hardware (ex. school computers with limited RAM and no Administrator privileges) is sometimes used for deployment to cheap hardware targets (ex. hand-me-down Android tablets)
My solution was to write a standalone binary called `dk` that uses scripts as the atom of work, cross-compiles to standalone executables, and downloads the runtimes and sysroots it needs on-demand. It sits roughly in the same space as Python and Go.
`dk` is available for Windows, macOS and Linux/glibc host machines with a growing list of cross-compilation targets. Your `dk` scripts are written in an almost complete subset of OCaml 4: all `dk` scripts are OCaml, but not all OCaml code can run in `dk`. The other differences from conventional OCaml are that `dk` comes with a large library included, and that I treat any feature as buggy if the feature does not work on all supported OS-es.
The above origin of `dk` is admittedly odd (and abbreviated), so I was not expecting that `dk` would now be a general-purpose scripting tool. Yet it is. I can wrap, re-use and organize most of my hand-written software as a set of `dk` scripts.
Fair warning: The cross-compilation support in `dk` has had a recent overhaul and not every bug is closed. The error messages suck (you have to scroll up to see the root cause and resolution) but they will improve. Some progress bars are missing. There are also a few experimental features ... `uv`-style imports and an interactive interpreter are the big ones ... which are purposely under-documented because I am worried about `dk`'s API surface.
But it still works well, and you can see some real applications in the Examples section. I'd love if you could give it a kick in the tires and give `dk` some feedback! The issue list is at <https://github.com/diskuv/dk/issues>.
I'm very confused at first glance. What are "coder scripts"? Why is "std" repeated 3 times in "dk StdStd_Std.Run"? What on earth is "Tr1Stdlib_V414Io"? The entire tool comes off as arbitrary and confusing, at least to me. I would really quite appreciate a brief primer on the language and its design decisions, architecture and syntax. So far, I'm just having assorted bits of information thrown at me with no real structure.
(Note: I have never touched OCaml. Is this some weird OCaml thing?)
It is the OCaml language but it also isn't packaged like conventional OCaml. Please don't blame OCaml for that.
It _does_ need a primer for those unfamiliar with OCaml. I was thinking ... since this is scripting ... part of it will probably take the form of a cheat sheet for people coming from Java/C#, JavaScript and Python backgrounds. And another part of it would be how to read an OCaml expression from left to right. Other suggestions welcome.
Direct answers:
- the full explanation of why Std is repeated three times is covered over the first four sections of the first manpage "dk(1)": <https://diskuv.com/dk/help/latest/manual/dk-1/>. It will go over some of the design behind that and also introduce aliases so that "the tool `StdStd_Std.Run` can be typed as `Run`". Did I unnecessarily expose "StdStd_Std" in the introduction?
- the `Tr1Stdlib_V414Io` is a library described in the first reference manual "dkcoder-libraries(7)": <https://diskuv.com/dk/help/latest/manual/dkcoder-libraries-7...>
Thank you for your response. I don't feel that you unnecessarily exposed anything, just that not much explanation was given. Take a look at The Rust Programming Language's "getting started" section[1]. The installation steps are clear, the code is deconstructed and explained, and you are made familiar with the basic CLI tooling. Looking at yours, installation steps are clear, but I'm just given commands and code to paste with no explanation as to what it all does. Sure, I could go browse the man pages, but it's easier to ease into reading manual pages after a gentle beginner's explanation.
Although, given that you mentioned teaching, maybe the page is intended to be presentation-style (less information on the page, more to be explained vocally)? But you can correct me if I'm wrong.
[1] https://doc.rust-lang.org/book/ch01-00-getting-started.html
Yes, there is always verbal instruction (not really explanation) to start with the students. For example, most students I work with don't know how to open a terminal ... they need top-down guidance with copy and paste. The most explanation they would get at the start is that a terminal is where you can copy text and see a response. Pointing them at a web page with directions (mine or others) has never worked for the vast majority of them. The Rust pages in particular... some of them would not understand that they have to press the greater than symbol (>) to go to the next page, and almost all of them would not know they had to strip $ from the commands (or have a clue what Linux is). I think the success rate would be near zero (0%) for that Rust guide without hand-holding. Of course, once they've seen how to do something, they should not need as much handholding.
So eventually we come back and redo the content ... and that becomes the time that explanations are added.
I do like the Rust doc for experienced devs though, although I'll quibble that the doc is not good for Windows users. I'm add a separate explanatory quick start for experienced devs.
I wouldn't associate having to use `Lwt_main.run` with “a limited background in programming”, but maybe that's just me.
I usually structure teaching the same way done in https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o.... So "the Quick Walkthrough Guide will explain what dk scripts are and give you small examples to run" is simply a learning-oriented tutorial which is mostly about giving students confidence and visual feedback. And simultaneously it an explanation of nothing (the video has a great explanation for why to do that). So, I agree that an explanation of threads + Internet + cross-compilation would quite nuts, but for an experienced developer I'd expect to see a meaty example (take a look at https://ziglang.org/ for comparison).
One concrete action may be to make two distinct Quick Start guides ... one for the experienced and one for the inexperienced students though. Is that your thinking?
You are totally fine, the grandparent comment is just either needlessly nitpicking (“great is the enemy of the perfect”) or misunderstanding what the tool is supposed to be used for.
P.S. Your idea of having two distinct quick start guides (one that goes into the meaty details and another one that is just “run this command and you are good to go”) is great. But imo it is not necessary/crucial, and not having it doesn’t detract from the value proposition of your tool at all either.
Thanks for some of the early feedback. I did a few tweaks: separated the quick start into two (one for students, one for experienced devs), moved up the examples, and duplicated some of HN summary text on the linked page. The latter because I, as an infrequent HN submitter, hadn't realized that some (maybe most?) people don't read the HN summary.
I just couldn't figure out what this was in <60 seconds. Examples and use cases need to be a little more prominent in the docs.