document configure flags

[barbeque-squared]

Sure, there are a lot of flags strewn throughout the dist folder, but most of these aren't really documented anywhere. It's fine for the generic or really optional stuff, but some things come up in issues and it would be useful to document at least these.

So this list isn't exhaustive, instead it lists the most important (and/or less intuitive) ones:

• --without-portaudio because it's in a dozen issues
• --with-opencv-cxx-api because webcams (on linux only?) will probably not work at all without this flag

[s09bQ5]

--with-portaudio is how it was always done in the past. That's why it is still the default.
--without-portaudio uses SDL2 instead of PortAudio for recording audio. SDL2 supports newer stuff like PulseAudio and PipeWire. Also someone reported that mixing SDL2 audio output and PortAudio audio input on macOS caused them problems. Using PulseAudio through SDL2 had the problem that we don't know how many channels to record to avoid PulseAudio mixing the channels. I don't know if SDL2 fixed this. Maybe we have to use one of the newer SDL2 API functions to query the native number of channels.

--without-opencv-cxx-api is how it was always done in the past. That's why it is still the default. It tries to load OpenCV at runtime and uses the deprecated C API. OpenCV does not need to be present at build time. Current Linux distributions do not provide a version that still supports this API. We only notice that a suitable OpenCV can't be found when the user tries to use the camera.
--with-opencv-cxx-api uses the current C++ API and links to the OpenCV library at build time. When USDX is built with this flag and later OpenCV is missing, USDX doesn't start.

[barbeque-squared]

Hmm. Your comment provides good information (also regarding things that would need to be looked at going forward) but I'm not sure if putting all of it in the Readme would be useful? I wrote the PR trying to restrict the Readme to "if you're missing some functionality, you're probably missing one of these flags".
Would putting it on a wiki page work, and then point to that page from the Readme if people want to get at the extended information?

[s09bQ5]

I'd prefer all documentation for the configure flags to be kept inside the source repository.

[barbeque-squared]

Oh right, that's currently two different repo's, good catch. I'll update the PR to incorporate the information. I might pull it all out into a separate COMPILING.md or something because it's quite a big section already, and then maybe just have a small section with the main steps/dependencies in the Readme, but point towards wherever for the detailed steps (but all in this repo)

[barbeque-squared]

Moved the section on compilation to a dedicated .md, and put a much shorter version (that also refers and links to the new .md) in the README. I'm not sure how up-to-date the intro text (lines 2-13) still is, but it's just a plain copy from how the readme used to be.
The only actual changes compared to the previous commit are:

• README.md: completely replaced section
• COMPILING.md: configure flags described in more detail

@s09bQ5 do you see anything that needs fixing or changing?

[barbeque-squared]

Considering this has been open for a month now, I'm going to merge it, considering it's just some documentation.