Correct and improve CMake documentation

[dhdaines]

A number of issues are fixed:

• --config doesn't at all do what the doc said, as it is not accepted at configuration (generation) time and only works at build time on multi-target builds. Best not to mention it at all.
• no need to pass -G Unix Makefiles as that is the default, but maybe you want to use Ninja
• everything about CMAKE_MODULE_PATH was wrong, add the correct way to point to an installed PortAudio

Fixes: #745

[philburk]

@generic-pers0n - Hello Avery, can you please take a look at this?

[generic-pers0n]

Changes look good! I approve! 😄

[RossBencina]

With respect to single configuration/multi-configuration generators, I think your suggestion of switching to describe single-cofiguration generators (e.g. Makefile generator) is certainly the simplest path, however both Xcode and Visual Studio generators are going to be common and both of those are multi-config (as is Ninja multi-config, which is what I usually use). So if you want to describe only single-config generators that at least needs to be mentioned I think (it also makes sense to be explicit about -G Makefile to avoid confusion.) An alternative is to add separate sections for single-config and multi-config generators, or just a single sentence about multi-config so that people at least know that it's a thing.

[generic-pers0n]

With respect to single configuration/multi-configuration generators, I think your suggestion of switching to describe single-cofiguration generators (e.g. Makefile generator) is certainly the simplest path, however both Xcode and Visual Studio generators are going to be common and both of those are multi-config (as is Ninja multi-config, which is what I usually use). So if you want to describe only single-config generators that at least needs to be mentioned I think (it also makes sense to be explicit about -G Makefile to avoid confusion.) An alternative is to add separate sections for single-config and multi-config generators, or just a single sentence about multi-config so that people at least know that it's a thing.

I agree in that switching to describing single-config generators is an easier route to take. I also do find it important to briefly discuss single-config and multi-config generators too, mentioning that both Visual Studio and Xcode are multi-config while Makefiles are single config, due to notable differences between the two types. I would also be okay with a simple and brief mention of the difference too, but such a difference may be good to bring up.

(I just saw @RossBencina's comment after I approved, but even without these changes I think things would at least be okay. It's still an improvement over before after all! 😄)

[dhdaines]

I agree in that switching to describing single-config generators is an easier route to take. I also do find it important to briefly discuss single-config and multi-config generators too, mentioning that both Visual Studio and Xcode are multi-config while Makefiles are single config, due to notable differences between the two types. I would also be okay with a simple and brief mention of the difference too, but such a difference may be good to bring up.

Makes sense! I will put back something like the previous mention of the use of --config when building.

I have to admit that I was unaware of Ninja multi-config, and will probably use it all the time now that I know that it exists.