.hhconfig documentation

[connorgurney]

Is there any documentation on options in .hhconfig, please?

[lexidor]

It would indeed be a good move to document these settings. I reverse engineered what most of them do from this exhaustive list. https://github.com/facebook/hhvm/blob/master/hphp/hack/src/options/globalOptions.ml

[fredemmott]

We definitely need to document the 'essential' ones (like allowed_fixmes_*), though fwiw, I recommend keeping your .hhconfig as empty as possible; it's the most-tested configuration. With the HSL being built-in, empty .hhconfig projects should become practical again starting with 4.108

Most of the other options are meant to be temporary - either experimental, or migration aids. They're not intended to be used to offer a 'super strict' mode, for example.

[lexidor]

Living the 4.108+ life and can confirm, you can avoid all settings that haven't been mentioned on the blog at one point or another.

[AndrewDiMola]

@lexidor going to sort through the blog, but do you have recommendations on a shortlist of settings that would be useful in a v.1 page? Feel free to chime in if you found anything particularly useful @connordoner

While recommending against using a ton of the settings, and keeping it sparse, would probably be useful to have any amount of content, rather than none.

[lexidor]

The biggest QoL setting is auto_namespace_map. It works like this:

auto_namespace_map = {"C": "HH\Lib\C", "AmLib": "Vendor\AmazingLibraryWithLongTopLevelNamespace"}

in your in file
hhvm.aliased_namespaces["C"] = "HH\\Lib\\C"
hhvm.aliased_namespaces["AmLib"] = "Vendor\AmazingLibraryWithLongTopLevelNamespace"

Every file in your project will now resolve partially qualified entities against this list as-if you had use namespace HH\Lib\C as C and use namespace Vendor\AmazingLibraryWithLongTopLevelNamespace as AmLib at the top of each file. This is a very shiny very hidden gem.

Vscode-hack can't do typescript style auto imports. This setting makes working with and in namespaces a pleasure.

[fredemmott]

auto_namespace_map

FWIW, if we document stuff like this, we should have a big warning saying that it should not be used in public projects where you expect others to depend on it. For example, open source libraries should never use this.

This is because:

• it requires global, not per-project configuration, both in HHVM and the typechecker
• there is no conflict resolution method. If one project has Foo => SomeCorp\Foo and another has Foo => SomeOtherCorp\Foo, this can not be resolved.

I'm not against documenting it, and I wouldn't really call it discouraged in the situations where it is not problematic, but we need to be very clear about when it's appropriate, and that it's not a 'best practice' (or an antipattern)

[lexidor]

For example, open source libraries should never use this.

Agreed, I should have to mess with my hhvm and hhconfig configuration to composer require happycorp/yaml-parser. Just a convenience feature for monorepos and top level applications.

[connorgurney]

“auto_namespace_map”

Truthfully, I was blissfully unaware of this setting, which underscores why documentation is so important! Good spot, @lexidor.

[connorgurney]

Where are we up to on this?

[connorgurney]

It seems there's been nothing further on this so, unless I have any opposition, I'm going to close it for now.