Forem: Patrick Kilgore

Easy Dune (OCaml): Running a Script

Patrick Kilgore — Sun, 07 Aug 2022 21:06:00 +0000

There's a lot to dune, the OCaml build system. It can probably do what you want, but the documentation—while thorough—never bothers to explain how to complete common tasks in a way a busy developer would find helpful.

This is a "how to" to run a script with dune. By the end, you'll be able to trigger the execution of an arbitrary program with dune to complete a useful task for your code-base. Think "scripts" in a package.json, or a .PHONY target in a Makefile. For example, you might run a code-generation CLI like tailwindcss, or push build artifacts to S3 with an aws CLI invocation. We'll refer to these kinds of things as "scripts", as we might in a node/JavaScript project.

Assumptions

You know your way around a terminal and basic POSIX shell commands
You've got a working installation of dune version 3:

$ dune --version
3.4.1

From Scratch

If you've already got a dune project, locate the dune file in which you'd like to define the command, change directories to that folder, and skip ahead.

Creating Your `dune` File

Scripts are defined in a file named dune at the root of your project (or library, or executable). Dune has a suite of init commands to help create this file, but these create a lot of unnecessary noise too, so let's make the minimum setup manually:

$ mkdir run_task && cd run_task
$ touch dune
$ echo "(lang dune 3.3)" > dune-project

At this point you should be able to run:

$ dune build

Without seeing an error, and a new folder _build appearing, which confirms we're ready to go:

.
├── _build
│   ├── default
│   └── log
├── dune
└── dune-project

Configuring Dune with S-Expressions

Let's quickly look at one of the commands above:

$ echo "(lang dune 3.3)" > dune-project

You might be wondering what lang dune 3.3 means and why it's in parentheses. It's called an S-Expression, and like JSON, YAML or TOML is a language that can be used for, among other things, configuration files. Unlike the latter few formats, S-Expressions are not frequently seen outside OCaml, but they are a common way in OCaml to serialize data, much in the way JSON is a common way to serialize data in JavaScript.

You might find it a bizarre choice for a programming tool and language hoping to attract new users (I do). But regardless, it's how we'll "program" dune to do what we want.

Fortunately, you don't need to know much about s-expressions to do what we need here. For now, you can think of them as named, nested arrays:

(key value value (subkey value))

Here's an imaginary example:

(package (name my-package)(version 1.0))
(dependencies lib-1 lib-2 lib-3 (testing-only tool-a tool-b)(development-only lib-a))

The trick is knowing which keys are significant to dune, and how dune responds to different values for those keys, similar to how you need to know in a npm project that the package.json key "files" requires an array of file patterns as the value.

They can be a pain to read without adding white space, so I suggest adding whatever white space makes it easiest for you. The below is equivalent to the above, made a little easier to read with strategic white space:

(package 
  (name my-package)
  (version 1.0))

(dependencies 
    lib-1 
    lib-2
    lib-3 
    (testing-only tool-a tool-b)
    (development-only lib-a))

Adding a Script: Rules

You define a script in a dune project as a rule.

A Simple Rule

For now, copy this basic "hello world" rule into your dune file and save it:

(rule
  (alias helloworld)
  (deps (universe))
  (action (run echo "Hello World!")))

If you already have entries in your dune file, add this below everything else, un-nested.

You should now be able to run:

$ dune build @helloworld
Hello World!

Awesome! We're 90% of the way there for invoking simple scripts.

Understanding Simple Rules

Aliases

Each rule can have an alias, which you invoke with the build command by prefixing it with an @.

Note that you can alias a lot of things in dune, for example, a set of dependencies. Be careful when referencing the docs!

Action

An action is the command dune runs to satisfy the rule. The basic syntax is demonstrated above, but there's an internal language that can get quite complex. And you can always use the simple syntax to invoke a small program to perform any more complicated build task! For example, if you really like S-Expressions you can write some crazy shell scripts with the shexp library.

Other common actions are:

(action (system <cmd>)): executes <cmd> with sh on unix and cmd on windows.
(action (bash <cmd>)): executes <cmd> in a bash shell

Dependencies

Unlike scripts in the npm ecosystem, rules in dune have dependencies, which are tracked by dune to avoid unnecessary work.

To illustrate this, remove this line from the example "hello world" above:

 (rule
   (alias helloworld)
-  (deps (universe))
   (action (run echo "Hello World!")))

And try running dune build @helloworld twice. You'll notice it works as you might expect once, then appears to stop working:

$ dune build @helloworld
Hello World!
$ dune build @helloworld
$ # Huh? No echo?

That's because, without defining the deps as universe, dune knows that since the last time we ran the @helloworld build command... nothing changed! And so dune does not do what it believes to be unnecessary work, and does not run the command we have defined the second time.

This is particularly powerful for something like code generation, where if none of the input files have changed we can avoid wasting time to create build artifacts.

You can check out the full dependency definition specification to experiment, but for now know that (deps (universe)) will act similarly to a npm script or .PHONY target and execute every single time it is invoked.

Elephant In The Room: Targets

There's still once major concept we haven't covered: the (target ...) settings for a rule. Targets are any file(s) you're creating with a rule, and they let do you more advanced things with dune. The good news is that if you don't want or need more advanced dune features, you're fine ignoring this piece of configuration.

For example, the command above is just an ephemeral side effect, so there's no point. Note, however, that dune will actually infer your targets for certain actions, and so the implications of configuring a target might pop up even if you neglect to explicitly set one. Most of the time, things will still "just work". But as you go deeper creating your own rules and you see strange behavior or errors mentioning targets, I would recommend reading up on them.

Summary

Running arbitrary tasks in your projects ("scripts"), is called a dune "rule".
Rules are written in a dune file as S-Expressions.
Rules have names called "aliases".
Rules have dependencies (and will not run if dependencies have not changed since the last time the rule was invoked).
Rules have actions, which define the command that is run to satisfy the rule
Rules can be invoked by running dune build @ with the alias following, like dune build @tailwind.

Remix: Sharing Your Index Layout with Sub-Routes

Patrick Kilgore — Sun, 16 Jan 2022 20:00:34 +0000

I've been poking at Remix as a SSR framework. It appeals because I agree with the philosophy: react focused, leaning into web standards, and with good developer UX.

But, similar to other convention-based frameworks, I quickly ran into a situation where I knew how to write the code but not how to implement it via convention.

The site I'm building with Remix shares a layout between the index and its sub-pages. Essentially the index / route is the home, and shares its layout with any /subpage.

Basically:

What Doesn't Work

Naively, I started building out a layout with this file structure:



routes/
└── index.tsx
└── subpage.tsx

But remix considers /subpage a peer, of /, even if the url reads like subpage is a child of /. And so the subpage route contains none of the shared layout defined in the index file.

So clearly the index.tsx file is not the right place to put shared layout code. But where?

What Does Work

The remix documentation has two other concepts that compose to solve this problem, layout routes and pathless routes.

Layout Routes

A layout route is a file with the same name as a directory:



routes/
├── app
│   ├── index.tsx   # <-- page rendered inside layout
│   └── subpage.tsx # <-- page rendered inside layout
├── app.tsx         # <--- the layout file
└── index.tsx

But that alone doesn't solve my problem unless I want the entire app to exist at a nested route /app (or whatever). I don't.

Pathless Routes

The second concept is the pathless route, which is any folder that starts with __. This allows you to create nesting in the filesystem that isn't reflected in the url, for example:



routes/
├── app
│   ├── __admin
│   │   ├── admin-login.tsx # <-- renders at /app/admin-login
│   │   └── moderation.tsx  # <-- renders at /app/moderation
│   ├── page1.tsx           # <-- renders at /app/page1
│   └── page2.tsx           # <-- renders at /app/page2
├── app.tsx
└── index.tsx               # <-- renders at /

Combining the Two with Index Pages

Frankly, I didn't expect combining pathless and layout routes to work to work with index pages, as index pages are usually a bit special in that they're usually expect to exist as files not directories. And especially not as directories starting with __!

But--credit to remix--the rules here compose well with indexes just as well as they do with other pages and routes. Applying the rules above, I ended up with:



routes/
├── __index
│   ├── index.tsx
│   └── subpage.tsx
└── __index.tsx

Which renders exactly like you think it might:

Code

You can checkout code for the example above on Github.