Undocumented compiler define flags

[tobil4sk]

There are a number of defines that are not documented on the page in the manual.

Furthermore, in the compiler code they are access via a raw string rather than a strict value, so even if some should be hidden from documentation it would be good to add them to defines.json for cleaner and slightly safer code.

Is there any reason why any of these should not be documented?

Here are the lists:

• net-loader-debug
• java-loader-debug
• cs-safe-casts
• gen-hx-classes
• haxe.noNativeLibsCache
• hl-no-opt
• hl-check
• hl-no-debug
• run (Running .hl file after compilation)
• jvm-times
• nodejs

Mentioned in #7965:

• analyzer-no-const-propagation
• analyzer-no-copy-propagation
• analyzer-no-local-dce
• analyzer-no-fusion
• analyzer-no-purity-inference
• analyzer-times
• analyzer-user-var-fusion
• analyzer-no-user-var-fusion

These might be deprecated:

• haxe3
• haxe4
• js-es5

And these are related to version numbers:

• java7, java6 etc
• NET_50, NET_45 etc (documented here actually)
• flash10, flash9 etc

Defines that are documented but don't generate automatically and are accessed internally via raw strings:

• target.static
• target.sys
• target.utf16
• target.threaded
• target.unicode
• target.name

[jdonaldson]

Just wanted to say... I looked into this a long time ago, and came away thinking:

1. There's not a lot of naming consistency, but all of the names of things make sense in context.
2. You need to really know the context if you're going to use the flag properly.
3. The context for a flag is often tied to a platform or framework, and the flag is often automatically set for you in associated build tooling... meaning a platform/framework author worries about it so that you don't have to.

Messing around with undocumented Haxe flags is really pretty dangerous IMHO, and if one wants to do something very specific that requires some kind of undocumented flag feature, one should be checking in with someone from the compiler team for advice (hop on discord, slack, etc)... almost like checking in with a park ranger before going on a long hike. Because, projects relying on certain flag behaviors can quickly turn into an unforgiving wilderness.

[Aurel300]

@jdonaldson Such flags can be marked "internal" in their doc, as is already the case for some of them. Having all the defines in a single JSON document (and therefore shown in the manual) seems like an improvement.

[tobil4sk]

If the deprecated ones were going to be added, might be good for them to be marked as such for the documentation along with haxe --help-defines output.

[Gama11]

Doesn't really make sense to "deprecate" haxe3 and haxe4 - both of those pretty much need to stay defined for all future Haxe versions. They're used as "haxe >= 3/4", so any code with backwards-compatibility checks using them would break if they were removed.

[tobil4sk]

I don't think any flags at all can really be removed, because even if they aren't as integral as haxe4, removing them would result in silently ignored or broken code. But it would be good in the documentation to separate the defines that are there just for backwards compatability, and perhaps give an indication of the replacement that should be used. This way in the future there won't have to be a haxe5 define for example, as it will be established in the documentation that now haxe is the more consistent long term way to check compiler versions. So maybe deprecated isn't the right word?

[tobil4sk]

Also: HaxeFoundation/HaxeManual/issues/413