What exactly does the `-arch` argument on the `candle` command line do?

Question

I'm setting up 32- and 64-bit builds in WiX version 3.7. The WiX documentation is defective in explaining this adequately. In the documentation for Package/@Platform, it says "Use of this attribute is discouraged; instead, specify the -arch switch at the candle.exe command line", but there's no explanation of what this argument actually does (at least none that I can locate). The "documentation" for the compiler completely deserves the air-quotes around the word "documentation", as it's basically a stub (unlike the linker documentation, for example). For the historical record, here's the entirely of the compiler documentation:

The Windows Installer XML compiler is exposed by candle.exe. Candle is responsible for preprocessing the input .wxs files into valid well-formed XML documents against the WiX schema, wix.xsd. Then, each post-processed source file is compiled into a .wixobj file.

The compilation process is relatively straight forward. The WiX schema lends itself to a simple recursive descent parser. The compiler processes each element in turn creating new symbols, calculating the necessary references and generating the raw data for the .wixobj file.

The command line help offers a bit, but not enough.

-arch      set architecture defaults for package, components, etc.
           values: x86, x64, or ia64 (default: x86)

In a related question, Platform identification in WiX 3.0, there's one answer with a sliver of hint about what might be going on, but it's hardly sufficient, and I don't know if it's accurate.

• Does the -arch argument have the same effect as setting the Package/@Platform attribute, or does it do more?
• Does the argument affect anything available in the preprocessor? In particular, does it set the PLATFORM preprocessor variable? Does it set anything else?
• What's an architecture "default"? Does an explicit Package/@Platform attribute override the command-line? Or vice-versa? Or (better yet) is there an error if there's an inconsistent platform declaration?

Some of these questions have answers that seem like they ought to be obvious, and indeed I've learned something just writing the question. But I'd like a definitive answer, preferably (hint) a link to an updated and accurate documentation page for the candle command line. I do expect to have solved this by the time anybody answers, however, but I'd just as soon save other people the time I'll have spent figuring this out.

---

Another related question, WIX: is the Platform attribute of the Package element truly deprecated?, talks about the Package/@Platform attribute, but doesn't address the command line argument.

---

About that PLATFORM preprocessor variable. It's now apparently BUILDARCH, though you'd be hard pressed to know it from the documentation.

warning CNDL1034 : The built-in preprocessor variable '$(sys.PLATFORM)' is 
deprecated. Please correct your authoring to use the new '$(sys.BUILDARCH)' 
preprocessor variable instead.

Answer 1

The following code snippets enable compile-time configuration between 32-bit and 64-bit versions without introducing a user variable representing the platform but rather using the one provided by the system. Both defined variables are generic to ordinary installs. The minimum version is higher for 64-bit systems. The base program files directory differs between 32- and 64-bit versions.

<?if $(sys.BUILDARCH)="x86"?>
    <?define Minimum_Version="100"?>
    <?define Program_Files="ProgramFilesFolder"?>
<?elseif $(sys.BUILDARCH)="x64"?>
    <?define Minimum_Version="200"?>
    <?define Program_Files="ProgramFiles64Folder"?>
<?else?>
    <?error Unsupported value of sys.BUILDARCH=$(sys.BUILDARCH)?>
<?endif?>

---

Use these definitions later in the WiX source.

<Package [...]
    InstallerVersion="$(var.Minimum_Version)"
/>

<Directory Id="$(var.Program_Files)">
    [...]
</Directory>