Docs: Explain Build Configurations

[cinderblock]

In the docs for GYP, the Build Configurations section simply says:

Explain this.

Is there an explanation to be had? I realize that Node-gyp and Gyp are different projects... but haven't seen this discussed anywhere and was hoping for some clarifications. There are some more details about configurations on other documentation pages, but they are insufficient.

Looking through the source code, I see many references to the configurations option but when I try to set even an empty list in binding.gyp I get errors:

make: Entering directory '/mnt/c/Users/camer/git/node-userid/build'
  ACTION Regenerating Makefile
Exception: Attempt to merge dict value of type dict into incompatible type list for key configurations while reading includes of binding.gyp
Traceback (most recent call last):
  File "/mnt/c/Users/camer/git/node-userid/node_modules/node-gyp/gyp/pylib/gyp/input.py", line 523, in CallLoadTargetBuildFile
    result = LoadTargetBuildFile(
  File "/mnt/c/Users/camer/git/node-userid/node_modules/node-gyp/gyp/pylib/gyp/input.py", line 400, in LoadTargetBuildFile
    build_file_data = LoadOneBuildFile(
  File "/mnt/c/Users/camer/git/node-userid/node_modules/node-gyp/gyp/pylib/gyp/input.py", line 255, in LoadOneBuildFile
    LoadBuildFileIncludesIntoDict(
  File "/mnt/c/Users/camer/git/node-userid/node_modules/node-gyp/gyp/pylib/gyp/input.py", line 297, in LoadBuildFileIncludesIntoDict
    MergeDicts(
  File "/mnt/c/Users/camer/git/node-userid/node_modules/node-gyp/gyp/pylib/gyp/input.py", line 2337, in MergeDicts
    MergeDicts(to[k], v, to_file, fro_file)
  File "/mnt/c/Users/camer/git/node-userid/node_modules/node-gyp/gyp/pylib/gyp/input.py", line 2318, in MergeDicts
    raise TypeError(
TypeError: Attempt to merge dict value of type dict into incompatible type list for key configurations while reading includes of binding.gyp

make: *** [Makefile:313: Makefile] Error 1
make: Leaving directory '/mnt/c/Users/camer/git/node-userid/build'

I see that BUILDTYPE=Release is getting passed to make and that CONFIGURATION_NAME = BUILDTYPE so maybe this is "only" for Release/Debug "configurations"?

---

Ultimately, the reason I'm asking is because I'm exploring having an alternate "configuration" of my build script that enables gcov coverage. I'd like this to be indistinguishable from the Release configuration for testing purposes. I've considered repurposing the "Debug" configuration for this but, if possible, I'd rather have a separate "Coverage" configuration because I think it doesn't need to be conflated with debug symbols. Although, I'm sure node-gyp's --debug wouldn't automagically work for --coverage too. Maybe this could be a full on "Feature Request" to make --coverage linking automatic?

Of course, the "standard" way to do this is with conditions and "User-Defined Variables" but that doesn't play as well as I'd like with automatic rebuilding of only files that need to be rebuild when using a build command.

I have successfully used multiple "targets" to build two versions but these targets then also have different names which adds other complications. But maybe that is worth it...

In any case, this issue is not about my particular decision. It's just about hoping for some clarity on this possible feature. Cheers!