Documentation issues

[philandstuff]

This is a description of some issues I found with the documentation on first readthrough.

the first example doesn't work

I downloaded the latest release and ran the following command:

echo 'fs default() { scratch; mkfile "/output" 0o644 "hello world"; }' | hlb run --target default,download=.

[+] Building 0.0s (0/0)
target "default,download=." is not defined in build.hlb

As an aside, although the release is labeled "0.4.0" on github, if you interrogate the binary itself it has a different version:

hlb version
0.3-218-g1bc8728.dirty

There seems to be no documented way to get any output from a build

I've been through the tutorial, the reference, the specification, and the CLI help, and I haven't found anywhere that tells me how to actually build an OCI image. There's something that tells me how to download some filesystem, but as shown above, it doesn't work.

Incidentally, later in the tutorial there's a different way to download a piece of filesystem:

hlb run --target localModules --download node_modules node.hlb
Incorrect Usage: flag provided but not defined: -download

NAME:
   hlb run - compiles and runs a hlb program

USAGE:
   hlb run [command options] <uri>

OPTIONS:
   --target value, -t value  specify target filesystem to solve (default: "localModules")
   --debug                   attach a debugger (default: false)
   --dap                     set debugger fronted to DAP over stdio (default: false)
   --tree                    print out the request tree without solving (default: false)
   --log-output value        set type of log output (auto, tty, plain) (default: "auto")
   --backtrace               print out the backtrace when encountering an error (default: false) [$HLB_BACKTRACE]
   --platform value          set default platform for image resolution
   --help, -h                show help (default: false)

flag provided but not defined: -download

So I'm completely stumped. I can construct builds and run them, but I have no idea how to inspect any of the outputs or use them to any practical purpose.

context: why I'm excited by HLB

I'm interested in building OCI images that are more reproducible and/or have better caching, so that if dependencies change I don't have to recompile code and also if code changes I don't have to redownload dependencies. I've learned about LLB and MergeOp/DiffOp,, and that HLB supports these operations, so I was hoping that it might be able to support my use cases. I still think it can, but I have no idea how to proceed from here other than reading the hlb source code 😬