Clean up CLI usage/help output, standardize flag naming

[bendmorris]

Implements parts of #6613

• Standardizes flags: - for targets or single letter flags, -- for everything else.
• Allow multiple variants of some flags, and support deprecated versions which will show a warning when used.
• Groups flags by function.
• Cleans up/aligns the output.

There should be no change in behavior, although everyone will start getting compiler warnings on -main, -cp etc. which are deprecated in favor of the standardized versions. The warnings go to stderr so it shouldn't impact tools consuming haxe's stdout.

Example output:

Haxe Compiler 4.0.0 - (C)2005-2018 Haxe Foundation
Usage: haxe <target> [options] [hxml files...]

Target
  --js <file>                                   compile code to JavaScript file
  --lua <file>                                  compile code to Lua file
  --swf <file>                                  compile code to Flash SWF file
  --as3 <directory>                             generate AS3 code into target directory
  --neko <file>                                 compile code to Neko Binary
  --php <directory>                             generate PHP code into target directory
  --cpp <directory>                             generate C++ code into target directory
  --cppia <file>                                generate Cppia code into target file
  --cs <directory>                              generate C# code into target directory
  --java <directory>                            generate Java code into target directory
  --python <file>                               generate Python code as target file
  --hl <file>                                   compile HL code as target file
  -x, --execute <class>                         interpret the program using internal macro system
Compilation
  -p, --class-path <path>                       add a directory to find source files
  -m, --main <class>                            select startup class
  -L, --library <library[:version]>             use a haxelib library
  -D, --define <var[=value]>                    define a conditional compilation flag
  -r, --resource <file>[@name]                  add a named resource file
  --cmd <command>                               run the specified command after successful compilation
  --remap <package:target>                      remap a package to another one
  --macro <macro>                               call the given macro before typing anything else
  -C, --cwd <dir>                               set current working directory
Optimization
  --dce, --dead-code-elimination [std|full|no]  set the dead code elimination mode (default std)
  --no-traces                                   don't compile trace calls in the program
  --no-output                                   compiles but does not generate any file
  --no-inline                                   disable inlining
  --no-opt                                      disable code optimizations
Debug
  -v, --verbose                                 turn on verbose mode
  --debug                                       add debug information to the compiled code
  --prompt                                      prompt on error
  --times                                       measure compilation times
Batch
  --next                                        separate several haxe compilations
  --each                                        append preceding parameters to all haxe compilations separated by --next
Services
  --display                                     display code tips
  --xml <file>                                  generate XML types description
  --gen-hx-classes                              generate hx headers for all input classes
Compilation Server
  --wait [[host:]port]|stdio]                   wait on the given port (or use standard i/o) for commands to run)
  --connect <[host:]port>                       connect on the given port and run commands there)
Target-specific
  --swf-version <version>                       change the SWF version
  --swf-header <header>                         define SWF header (width:height:fps:color)
  --swf-lib <file>                              add the SWF library to the compiled SWF
  --swf-lib-extern <file>                       use the SWF library for type checking
  --flash-strict                                more type strict flash API
  --java-lib <file>                             add an external JAR or class directory library
  --net-lib <file>[@std]                        add an external .NET DLL file
  --net-std <file>                              add a root std .NET DLL search path
  --c-arg <arg>                                 pass option <arg> to the native Java/C# compiler
Miscellaneous
  --version                                     print version and exit
  help, -h, --help                              show extended help information
  --help-defines                                print help for all compiler specific defines
  --help-metas                                  print help for all compiler metadatas
  --run <module> [args...]                      compile and execute a Haxe module with command line arguments
  -- [args...]                                  args that will be passed to the macro interpreter

[ncannasse]

While I can agree with the goal, merging this would cause a huge collapse of all of our IDE support and prevent compilation for all existing users, so I don't think that's worth the cost just for the sake of having more clean flags.

Please resubmit another PR with full backward compatibility mode.

[bendmorris]

Unless I'm missing something, this PR actually is completely backward compatible. All existing flags work as before.

[ncannasse]

Sorry I misread, backward compatibility seems to be included. Can you confirm it's 100% compatible?
I think we should drop the warnings for now.

[EricBishton]

The warnings go to stderr so it shouldn't impact tools consuming haxe's stdout.

The Haxe compiler uses stderr for output when using compiler services, so IDEs and tools will be affected by more/unexpected output there. (I believe this has been changed for Haxe 4.0, the tools have to keep backward compatibility for a looooong time, so they will be affected by a change in output.)

[bendmorris]

Can you confirm it's 100% compatible?

I can confirm best effort + whatever CI reports, but would like to get another pair of eyes on it to be safe.

I think we should drop the warnings for now.

I'll drop them for now. The deprecated flags just won't show up in the usage info, and we can re-enable the warnings in the future if we choose.

[EricBishton]

The deprecated flags just won't show up in the usage info,

And that will confuse people who are trying to read older HXML files, and don't understand what this "undocumented" feature is. Better to leave them in the extended help --help output, marked as deprecated.

[bendmorris]

I'm open to that, but given that the flags never differ by more than a single hyphen, I don't personally think this would be confusing. I think there's value in simplifying the help output which to me is greater than showing all deprecated flags when the mapping is obvious.

[ncannasse]

Few nitpicking:
I think that we should make a difference not between if it's a single char argument but if it's a "short name".
For instance -cp would be kept as-it but we would add --class-path, same of -dce and --dead-code-elim , we would also add --define as a long alternative to -D.

Also, I would maybe use -L as a shortcut for -lib (for GCC familiarity)

Thoughts?

[ncannasse]

PS: your PR also include changes to haxelib, please update it

[bendmorris]

Also, I would maybe use -L as a shortcut for -lib (for GCC familiarity)

I like that one, I'll update. I also like --define in addition to -D.

I think that we should make a difference not between if it's a single char argument but if it's a "short name".

I think it's important to mimic the behavior of other tools in order to match user expectations.

Looking at existing conventions, I can find (1) a lot of tools using the convention I followed above: docker, php, rustc, npm, python, tar and many more. Some of these e.g. tar would see -cp as multiple arguments -c -p. I think this is increasingly becoming a standard and I would guess that > 90% of new CLI tools are using this convention.

(2) A few using only single hyphen flags: java, ocamlc, go

(3) C compilers, which use one hyphen for abbreviations, two elsewhere: gcc -pie -std= --sysroot=

To compare:

Convention	Common?	Predictable/Consistent?
-a --abc --long-thing	Very	Very
-a -abc -long-thing	Not really	Very
-a -abc --long-thing	No	Less

I would vote for the first one, it's both common and intuitive. If we intentionally want to look more like gcc that's fine too.

[RealyUniqueName]

Just a minor suggestion: change --dead-code-elim to --dead-code-elimination to keep it consistent with the "full name" idea. 25 февр. 2018 г. 15:29 пользователь "Nicolas Cannasse" < notifications@github.com> написал:

…

PS: your PR also include changes to haxelib, please update it — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#6862 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ADAm_JmxZMnAWEu3cRupmn66kuJLFt8rks5tYVIagaJpZM4SNOQU> .

[ncannasse]

While we're at it I would do the following additional changes:

• --cp => -p for short name --class-path for long name
• -l=> -L / --library for library
• move all targets-specific commandlines to defines (for example -D swf-target=15) since they were most likely introduced before we had defines values.

Regarding auto execution:

I think we don't need -x to run Neko anymore, we should instead use the internal macro interpreter. So it kind of overlaps with --interp:

haxe -x Main
haxe -main Main --interp

I would only keep the -x/--execute.
I also think we should be able to easily pass commandline arguments this way:

haxe -lib something -x Main arg1 arg2 arg3

But that's maybe outside of the range of the current PR ;)

[bendmorris]

Given the possibility of multiple targets with shared arguments, and --next/--each etc. I'm not sure how we would formulate this using subcommands without larger breaking changes.

[kevinresol]

I don't mind seeing --next/--each gone. It doesn't work well with completion anyway.
For shared arguments I use args.hxml and include it in every other hxmls.

[Simn]

That's another good point. --next is a huge pain when it comes to completion. I think everyone ends up reverting back to having one hxml per target.

[ncannasse]

The discussion was about having something backward compatible no ? :)

[kevinresol]

I think it is still backward compatible.

1. For sub-commands, which is completely new: drop support for old-style arguments and --next/--each altogether
2. For original command: deprecate whatever have to be and encourage sub-command style

Though we can separate these into two PRs. If it has been diverged too much, I think the sub-command topic can be discussed separately.

[nanjizal]

I pretty much disagree with all of Keven's points and I am beginning to worry :( two versions of hxml is not a good approach.

--target=js stupid change for change sake!

Don't indulge OCD tendencies and mess all our projects up, I use --next and I use recursive hxml, tidy flags where you can and move on to standardising the cross target toolkit build approaches, because that really is where some consistency is needed. My suggestion lock all the cross platform toolkit developers in a room at the Haxe conference and tell them they can't leave until they agree on a standard. Until that happens please don't remove stuff from hxml.

[Simn]

This kind of comment doesn't help. Please focus on the content of the discussion.

[bendmorris]

I think this is venturing out of the scope of the current PR. I'd like to keep it narrowly focused and backward compatible. For now I'll keep --js and -js as target specifiers. Larger changes can be considered separately.

[nanjizal]

I was focused on the discussion, posx sounded good in principle, but the additional stuff would fracture the experience of day to day use so I am in favour of keeping the pr narrowly focused. ( Please before removing --next, get some stats on usage, in TrilateralBazaar I use 27 hxml files half have atleast one --next in them, and the removal proposal does not offer any alternative workflow ).

[Simn]

The only thing I outright dislike here is -c...

[bendmorris]

Nicolas called out -c above, it's already been changed to -p. When I iterate on this again I'll update the description.

[bendmorris]

If no objections, I think this is ready to go.

[nanjizal]

Simn

noticed the xml reference in the change and it reminded me, Nodule is now more robust after I made some changes.

Think I can improve parsing speed below, changing switches to nested if statements and perhaps in a few other areas.

Notice although it takes longer to convert to a Nodule structure ( x3 ), it typically takes '0' time to convert to pretty custom string outputs ( s0 ) after the initial parse to Nodule, so it's ideal for quick querying.

This is the trace for parsing and then converting to string this file.
/usr/local/lib/haxe/std/Any.hx

x0 = Xml.parse(str) took 0.10399985313415527 seconds
16:29:06.746 _.js:91 x1 = haxe.xml.Parser.parse(str) took 0.2650001049041748 seconds
16:29:07.225 _.js:240 x2 = ReadXML.toXml(str) took 0.4779999256134033 seconds
16:29:07.604 _.js:388 x3 = ReadXML.toNodule(str) took 0.38000011444091797 seconds
16:29:08.037 _.js:575 x4 = ReadXML.toNoduleAndXML(str) took 0.4309999942779541 seconds
16:29:08.040 _.js:579 s0 = x3.toStringPretty() took 0.0019998550415039062 seconds
16:29:08.433 _.js:583 s1 = x0.toString() took 0.39300012588500977 seconds

See here ( slow to load as it's parsing lots of the native classes ) is the js demo, times vary between methods of initial parse but speed of converting nodule to pretty string is always fast.
https://rawgit.com/nanjizal/Nodule/master/index.html

I don't know if Nodule can be improved to provide some speed in relation to XML and not looked at c++ speeds, and I am not sure if it's worth it, but I have certainly ironed out more bugs since you last saw it. If you think it's worth exploring let me know what needs to be done, and can try to improve it. Sorry I know off topic but was unsure where to post this as I think you have me on ignore for irc.

Best Justin.