add FIXME and TODO comments to cmake build tutorial

Author: RossBencina

doc/src/tutorial/compile_cmake.dox

@@ -5,7 +5,9 @@
 
 CMake can be used to generate Visual Studio solutions on Windows, Makefiles (on Linux and OS X) and build metadata for other build systems for PortAudio. You should obtain a recent version of CMake from [http://www.cmake.org] if you do not have one already. If you are unfamiliar with CMake, this section will provide some information on using CMake to build PortAudio.
 
-On Linux, CMake serves a very similar purpose to an autotools "configure" script - except it can generate build metadata apart from Makefiles. The equivalent of the following on POSIX'y systems:
+@section cmake_posix Building on Unix-like Systems
+
+On Unix-like systems such as Linux and macOS, CMake serves a very similar purpose to an autotools "configure" script - except it can generate build metadata apart from Makefiles. The equivalent of the following on POSIX'y systems:
 
     build_path> {portaudio path}/configure --prefix=/install_location
     build_path> make
@@ -23,6 +25,10 @@ The "-G" option specifies the type of build metadata which will be generated. Yo
 
 "make install" should install the same set of files that are installed using the usual configure script included with PortAudio along with a few extra files (similar to pkg-config metadata files) which make it easier for other CMake projects to use the installed libraries.
 
+FIXME: do these instructions still work? do they install static and dynamic libraries as with PortAudio V19.7? #468 implies not.
+
+@section cmake_windows Building on Windows
+
 On Windows, you can use CMake to generate Visual Studio project files which can be used to create the PortAudio libraries. The following serves as an example (and should be done from a directory outside the PortAudio tree) which will create Visual Studio 2015 project files targeting a 64-bit build:
 
     C:\PABUILD> cmake {portaudio path} -G "Visual Studio 14 2015 Win64"
@@ -31,15 +37,26 @@ After executing the above, you can either open the generated solution with Visua
 
     C:\PABUILD> cmake --build . --config Release
 
+FIXME: check whether these windows instructions are still valid
+
+TODO: mention that recent version of PortAudio can open the cmake file directly
+
+TODO: describe how to select between static and dynamic build outputs, and note that this is a change since V19.7
+
+
 If you want ASIO support you need to obtain the ASIO2 SDK from Steinberg and place it according to \ref compile_windows_asio_msvc. Both ASIO and the DirectX SDK are automatically searched for by the CMake script - if they are found, they will be enabled by default.
 
 @section cmake_using Using PortAudio in your CMake project
 
+ FIXME: this section is currently wrong (see ticket #486) not clear whether the cmakelists or documentation should be updated.
+
 PortAudio defines the following CMake targets:
 
  - "portaudio_static" for a static library and
  - "portaudio" for a dynamic library
 
+ TODO: describe how to select between static and dynamic build artifacts
+
 If you installed PortAudio as described above in \ref cmake_building and the install prefix you used (CMAKE_INSTALL_PREFIX) is in your system PATH or CMAKE_MODULE_PATH CMake variable, you should be able to use:
 
     find_package(portaudio)