This content originally appeared on DEV Community and was authored by minerobber
There is a lot to be written up. Starting with “wtf is cosmopolitan?” If you leave this now as it is, it will be essentially wasted effort (except for any enjoyment you got out of doing it) — I barely understand what you did, how you did it, and the implications of it, and nobody else is going to get even that far.
It may seem trivial to you, because you already understand all that. 99.9999% of people don’t.
It doesn’t need to be complicated. Just explain (1) a little background, (2) what you accomplished, (3) how you did it, and (4) why it is interesting/useful.
Then somebody else can come along and appreciate what you’ve done!
~ Joe Strout, August 27, 2025 (bold emphasis mine)
Alright!
Part the First: “a little background”
Firstly, what is MiniScript, and who is Joe Strout? MiniScript is a programming language that was created in 2016 (first released in 2017) by Joe Strout as an alternative to other programming languages that were/are typically used to teach kids how to program. As the MiniScript homepage states:
This is the home page for MiniScript, a clean, simple language for embedding or learning to program.
MiniScript is modern, elegant, easy to learn, and easy to embed in your own C# or C++ projects. (And elsewhere — there are unofficial ports to TypeScript, Kotlin, and more.)
My favorite thing about MiniScript is that a decently full-featured summary of the entire language fits on one side of a sheet of letter paper. The cheat sheet for Mini Micro, a self-described “neo-retro virtual computer” based around MiniScript, only takes 3 more pages of letter paper to cover pretty much every API that it has (except the ones implemented in MiniScript, which you can read the code of yourself; the fourth page in that PDF, fittingly, is the one-page cheat sheet for the language itself).
Secondly, as Joe put it, “wtf is cosmopolitan?” In the words of creator Justine Tunney:
Cosmopolitan Libc makes C/C++ a build-once run-anywhere language, like Java, except it doesn’t need an interpreter or virtual machine. Instead, it reconfigures stock GCC and Clang to output a POSIX-approved polyglot format that runs natively on Linux + Mac + Windows + FreeBSD + OpenBSD 7.3 + NetBSD + BIOS with the best possible performance and the tiniest footprint imaginable.
In layman’s terms, Cosmopolitan takes normal C or C++ code and compiles it into a special file. Windows sees it as a normal .EXE file, the other operating systems see it as a shell script (which does some magic to extract the code into a format the operating system in question understands), and in addition to all of that, it’s also a .ZIP file, which contains all of the files it needs to be truly portable.
Part the Second: “what you accomplished”
This is the MiniScript C++ command-line interpreter (SHA256 hash: 6fdbe7410d79af6c70e7948d31af7b838c1d88eb7679a87ffe100f3737c08ccb). You can run it on your computer (your antivirus might complain, and/or you may need to do some tricks to make it work if you’re on a Mac, but by and large it should Just Work). It contains all of the libraries that “come with” the command-line interpreter (dateTime, grfon, importUtil, json, listUtil, mapUtil, mathUtil, matrixUtil, qa, stringUtil, tsv, and vt) inside the executable (this is where the .ZIP file part above comes in handy).
If you write a script with it and want to share that script as a self-contained executable in its own right, the steps are simple:
- Copy
miniscript.comand rename the copy to something likeMyAwesomeProgram.comor whatever you want (it only really needs a file extension if you’re on Windows). - Change the file extension of
MyAwesomeProgram.comto.zip. - Copy your script (and any libraries you
imported) into the.zip. - Write a
.argsfile containing the filename of your script preceded by/zip/(soMyAwesomeProgram.mswould be put in there as/zip/MyAwesomeProgram.ms), and place that in the.zipfile as well. - Finally, change the file extension back to
.com(or remove it if you don’t need it).
Now, when you run MyAwesomeProgram.com, it should run your script!
Part the Third: “how you did it”
Well, first, compiling a cmake project like MiniScript using Cosmopolitan’s “cosmocc” compiler has been done before; I personally followed (and suggest following to anyone doing something similar) these instructions by Jacob Hummer. I did have to modify MiniScript’s whereami.c to properly handle Cosmopolitan as a platform, but that was really easy and basically amounted to making a WAI-shaped wrapper for the Cosmopolitan function GetProgramExecutableName (after I was told that function existed). Doing just that is enough to get a functional, if odd, MiniScript install; it says it’s running on Linux, for some reason, and it’s missing a lot of features common to Cosmopolitan projects, like support for .args, use of storing files in the ZIP, etc.
Luckily, these features are somewhat easy to add. In the case of “it says it’s a command line interpreter for Linux”, Linux is just what it defaults to if it doesn’t think it’s running on something else, so correctly reporting ourselves as a Cosmopolitan interpreter is as easy as just adding a case for __COSMOPOLITAN__. Storing files in the .ZIP portion of the executable (“ZipFS” in Cosmopolitan parlance) is automatically supported by the runtime, so we just need to tell MiniScript to go look there; in my actual implementation I moved the definition of the default import path into ShellIntrinsics.h, so I could add /zip/lib to the end if and only if we were compiling for Cosmopolitan. As for .args, the function in Cosmopolitan that implements this is called cosmo_args, so it’s just a matter of calling that before we do anything with arguments. I did a little fancy stuff so that argv could be defined as const when not compiling for Cosmopolitan (no reason not to, and that’s what it was before I got to the code), but not be defined as const when we were compiling for Cosmopolitan (since cosmo_args, by definition, modifies argv).
Part the Fourth: “why it is interesting/useful”
With this finished, MiniScript joins the ranks of programming languages like Janet, Lua(JIT), Perl, PHP, Python, and Tcl in having been ported to Cosmopolitan. The idea of being able to package everything you need to write command-line MiniScript programs into a single file–and then package that program as a single-file click-it-and-run executable of its own–well…
This content originally appeared on DEV Community and was authored by minerobber