cli: Add --out-dir flag

[alixander]

d2 ./static/d2/*.d2 ./static/generated/*.svg

[nhooyr]

You'd have to do:

d2 `./static/d2/*.d2` `./static/generated/*.svg`

To avoid the shell interpreting the globs first.

I think instead of dealing with the shadowing globs, this should be achieved as so:

d2 --out-dir ./static/generated ./static/d2/*.d2

Now the shell can interpet the glob and it will work exactly as expected. out-dir also has precedence in tsconfig.json.

You could also now use xargs to run things in parallel:

# Start a process for every 256 .d2 files.
# Run up to 8 processes at a time.
find . -name './static/d2/*.d2' | xargs d2 -P8 -n256 --out-dir ./static/generated

The xargs example is a little contrived as d2 would always compile in parallel anyway but it demonstrates that --out-dir is more composable with other shellisms.

[alixander]

does it even need --out-dir then?

the CLI can check that the second arg (output) is an existing directory, and treat it as out-dir if so.

[nhooyr]

@alixander that wouldn't work with globs. globs are by convention always at the end of a command invocation. that's how xargs works by default, it just appends the list of files to the end of the command as individual args. otherwise you need to use -I{} which is annoying and means that you have to spin up a process per file which is noticably inefficient. i think gnu xargs has a way around that where you can put the list of args anywhere in the command but it's not portable and we should strive for portability when possible.

also the directory may not exist, we ought to create it then instead of interpreting it as a file to be compiled. the dual behaviour would be generally confusing anyway.

[alixander]

okay, this task is to add --out-dir then

[alixander]

will also need --out-format (#1288)

[sdykae]

up