What signatures are acceptable for `Run`? How are `argc` and `argv` exposed?

[zygoloid]

Summary of issue:

We need to somehow expose command-line arguments to Carbon programs. So far the toolchain permits fn Run() and fn Run -> i32, with no support for arguments. But even that is not covered by any proposal I can find.

Details:

#2550 established that the entry point is named Run in the Main package, but did not specify what signatures it can have.

Any other information that you want to share?

C++ allows:

int main();
int main() noexcept;
int main(int, char**);
int main(int, char**) noexcept;

Implementations often also allow the return type to be declared as void, and some allow a third char** envp parameter.

Some platforms have their own convention, such as WinMain on Windows.

The toolchain allows the return type to be omitted. When this happens, the return value is currently uninitialized, rather than being set to 0.

[danakj]

As another option, it's possible to have Run() not take any parameters, but provide the arguments through Core. This is the approach taken by Rust.

In particular:

• std::env::args()
• std::env::args_os()

Some advantages:

• You get to work with nice library types for interacting with the arguments: For args() you get the Args type which is iterable.
• It owns the underlying arguments, so there's no unowned pointers provided for the arguments.
• There's no risk of freeing data owned by the OS.
• You can get access to them as UTF-8 (in args()) or in the OS encoding (an OsString, in args_os()).

Some disadvantages:

• Before fn main() something needs to call the stdlib's initialization function so that it can collect the arguments from the OS.
• This makes linking Rust into C++ tricky, as if main function comes from C++ instead of being compiled by rustc, there is nothing to inject the stdlib initialization before main.
• Rust in a DLL has fns to access the program arguments in the stdlib still, but they don't give the correct answer.

Notes:

• Carbon doesn't have strict UTF-8 strings, so would be unlikely to benefit from having multiple views of the program arguments AFAICT.
• Carbon can give unowned pointers to Run with an alias set related to the OS. Presumably we can use some reasonable alias set that we never have to invalidate.

[jonmeow]

I think Python does similar to Rust with sys.argv, and that can be helpful because it means libraries can directly read args without requiring them as a parameter. A downside I've seen is that when testing argument handling, it's extra work to get those same libraries to take argv as input rather than reading directly. (similar might also apply when trying to manipulate arguments for non-test reasons, as for Carbon's own busyboxing)

[geoffromer]

I think we should avoid conflating two separate ideas:

1. Giving arguments a richer and better-encapsulated type.
2. Exposing arguments via a mutable global variable.

The advantages that have been brought up so far are almost all advantages of (1), but the disadvantages are disadvantages of (2). Fortunately, as far as I can tell there's no particular coupling between them, so we don't have to accept the disadvantages of (2) in order to get the advantages of (1).

Also, to amplify @jonmeow's point, a global argument variable tends to to make libraries harder to reuse for the same reason it makes them harder to test.

[zygoloid]

I think for C++ compatibility we should allow something that's compatible with int argc, char **argv -- something along the lines of argc: i32, argv: Optional(char*)* or perhaps argc: i32, argv: ArrayPtr(Optional(ArrayPtr(char))) for some suitable indexable ArrayPtr type. And I think we should also support a cleaner set of arguments, such as args: Span(str), for some suitable array-view Span type. So maybe we pick a few good options along those lines and allow them all.

We should also think a little about how Windows support might one day fit into this, where the command line is passed as a single string (as an array of WCHARs), not as a sequence of arguments, and not as narrow character strings. (Although there are other concerns there too, such as distinguishing between terminal applications and windowed applications.)

I think the arguments that we should not expose argc and argv as global state in Core are compelling. But perhaps we could expose the arguments as a global within the Main package rather than in Core? (That'd mean that the Main package can access them but other packages cannot, as it's not possible to import Main from elsewhere.) I think that'd avoid some of the disadvantages of (2), and it aligns with the idea that the entry point is a predefined function that lives in Main and calls Main.Run. I think it'd be a bit surprising for our standard library to include program-accessible names in the Main package, so I'm leaning against that as a direction too, but if we want globals rather than parameters, I think that'd be an option to consider.

[jonmeow]

Regarding argument structure -- perhaps an Args type that supports conversions to all the variants someone might want, and also supports appropriate iterability/indexing for more Carbon-y things? e.g. supporting something like:

fn Run(args: Core.Args) -> i32 {
  for (arg: str in args) {
    Core.Print(arg);
  }

  return Cpp.Mainish(args.size, args.Argv());
}

But perhaps we could expose the arguments as a global within the Main package rather than in Core?

IIRC, Run must be in Main//default (reference). I think it would be pretty convenient (and hard to misuse) if it were only exposed in Main//default, since that's also where Run must be.

If it were generally in the package, I'd expect people to distribute files like Main//my_arg_parser, possibly standalone, possibly taking advantage of static linking to pass args to their own package.

[geoffromer]

What would be the benefit of having Carbon automatically expose the args as a package- or library-private global, given that the author of Run can trivially do so themselves?

[jonmeow]

What would be the benefit of having Carbon automatically expose the args as a package- or library-private global, given that the author of Run can trivially do so themselves?

Dana's comment above notes some benefits. I would add, it can also be helpful to reduce boilerplate for developers.

[danakj]

FWIW the args: Core.Args idea is appealing to me. It has very low boilerplate, provides an unlimited API surface, and removes issues of globals.

[chandlerc]

Trying to synthesize things a bit...

At a high level, I think we want to track argv and argc as arguments rather than globals. I just don't think the benefits outweigh the costs here.

I also really would like the "normal" Carbon Run function to have a nice and friendly API rather than a very C-ish one.

My suggestion to solve the (real) problem of programs that need to control the low-level C view of this is to do so through interop. We will want some way of exporting C/C++ functions. I think we should allow the Main package to export a main function with a signature accepted by the underlying C/C++ implementation. And doing so should suppress Carbon automatically emitting such a symbol that packages the command line arguments into whatever API we want and calls Run. By default, programs can get the nice clean world. But when necessary, they can dip down to manually control things.

---

Regarding the actual API - I would really hope that we don't need a completely opaque Core.Args. These are always strings at the OS level, and so my inclination is to have a args: slice(str). I don't think there are any conversions we'll want here that we wouldn't want on a general str.

[zygoloid]

I like having a Core.Args type or similar, for a few reasons:

• It lets us provide a nice interface, such as a range of strs that can be indexed and iterated over, much like slice(str).
• It also lets us provide access to something API-compatible with a traditional argv, which we will often want for interop.
• It avoids the need to allocate backing storage for a slice(str). (But that's very minor since this would only happen once per call to main.)
• It avoids the need for nontrivial logic wrapping Run in main -- converting the two arguments into a single Core.Args seems simple enough that we can do it in lowering.

But I also like the programmer-facing simplicity of the arguments simply being a slice(str). Could go either way.

We also talked about the return type for Run. Notably, C and C++ treat it as returning int, but POSIX says only the lowest 8 bits are meaningful. We typically don't allow implicit conversions that perform integer truncation in Carbon, so what should we do? Also, the convention that 0 means success is a bit unusual.

One idea that @chandlerc and I both liked was using an enumerated type for the return type of Run -- something with a suitable underlying type (perhaps u8) with enumerated constants for success and failure, and a way to inject other values in case a single failure status is insufficient. Perhaps Core.ExitCode?