CLI spec for alternate backends

[f-f]

In #426 we added basic support for alternate backends.

As discussed in #355 we should write down a "CLI spec" that alternate backends can conform to so that they'd work with Spago out of the box.

[csicar]

First idea to get the conversation started:

Option	Default	Description
no option	-	generates files in the target language and saves them in the directory ??? and build the executable (or library) in the directory ???
--src	src/	sets the directories where the purescript source files are located (used for finding FFI files)
-o	output/	sets the directory, where the target files will be written to
--run	Main.main	builds & runs the supplied function. The command expects the function to have type :: Effect Unit
--no-build	-	skips building an executable and only generate files in the target language.

Notes:

• it might be preferable to have --build be the default and --no-build be optional
• I'm not sure about the necessity of --src and -o, but as far as I know, spago supports alternative paths for src and output (is that correct?). Therefore it would make sense, that the backends also respect that.
• pskt writes generated executables in the output/pskt/program.jar file; AFAIK psgo writes the executable to ./Main
• The default value for --output could also be just output/. (That's what psgo does)
• Hooking up to the bundle-app and bundle-module commands would be nice: For the alternative backends bundle-app would mean compiling to a executable (native exe or executable .jar) and bundle-module would mean compiling to a library (shared lib or non-executable jar)
  • The --to option would allow specifying where the compilation result should be saved.

Update:

• output/ as the default target folder instead of output/[compilerName]
• Make building an executable (or library) the default. Add the flag --no-build instead of --build

[f-f]

cc @nwolverson @andyarvanitis

[andyarvanitis]

Looks good to me so far.

1. I would vote for --build being the default (--no-build being optional).
2. I'll look into --src and -o for both of my backends (I can at least provide a warning if one of them needs to be ignored)
3. "The default value for --output could also be just output/. (That's what psgo does)" – Please!
4. I can look into bundle-app and bundle-module

[csicar]

I would say either having the --build or the --no-build flag, but not both as that would be confusing.

I would vote for --build being the default (--no-build being optional).

So you mean, that without any options provided to the compiler it will create the files in the target language and build a binary?

[andyarvanitis]

Right. I'm open to discussing it, though.

[csicar]

No, I'm fine with that. That's probably what the user expects.

[f-f]

@csicar it looks like your first proposal seems good by everyone, so I guess we could proceed to standardize this? 🎉

I guess the next steps would be:

• commit what we have so far to a file and call it v1 or something
• define what the spec entails and guarantees - i.e. "if you conform to this then spago will run your thing just fine"
• define a versioning schema for the spec to handle things like breaking changes

[nwolverson]

Started separating the purerl backend to a separate backend executable rather than a compiler fork. Working great so far

Some thoughts

• Wonder if a command based CLI (like purs and spago) may make sense, otherwise there will end up being irrelevant combinations of options

• Don't think '--src' should be required, the CoreFN representation already specifies the source path of a given module - which when used with spago may be 'src/...' or '.spago/...' q

[nwolverson]

1. Problem in the above scheme, optparse-applicative (which I'm using for argument parsing, same as purs and spago) doesn't support optional values for parameters like --run [Main.main]. I'd suggest splitting out the main argument, as existing tools purs bundle, spago, pulp do. Ideally $BACKEND run [-u Main.main] or such. Alternatively, just make the function mandatory, and spago can do the defaulting part

2. I'm a bit unclear what the spago interface to the --no-build would be - as that's different from spago's own "no build" - I think the common usage would be to perform a PureScript build, generate output but not build a binary (or whatever)

3. Assume we can add a spago flag similar to the --purs-args for backend-specific args

[csicar]

Wonder if a command based CLI (like purs and spago) may make sense, otherwise there will end up being irrelevant combinations of options

I was trying to avoid that to keep the CLI of backends simple. But I do see the problem, that we could easily end up the mutually exclusive arguments and other weird stuff. I guess $BACKEND run and $BACKEND build would be the to sub-commands?

Problem in the above scheme, optparse-applicative (which I'm using for argument parsing, same as purs and spago) doesn't support optional values for parameters

I'm using optparse-applicative as well and ran into the same problem. To fix this, I removed the value option from the parser and added the default value manually after parsing in my program.
In my mind, making the CLI interface more complicated to avoid a problem of optparse-applicative is not worth it.

I think the common usage would be to perform a PureScript build, generate output but not build a binary (or whatever)

So you mean spago build would only generate erlang / go / kotlin files, but no binary?
I also prefer this option, as it would make building quicker. In that case, I would still expect spago bundle-app and spago bundle-module to generate binaries.

Assume we can add a spago flag similar to the --purs-args for backend-specific args

Good point. I'll add that. Should there also be a option in spago.dhall for specifying those options?