1# Tips about CMake 2 3## Don't be afraid to nuke your build dir 4 5CMake likes to cache options and other things in the build dir... if you stop 6asserting the state of something like `-DMY_OPTION=1`, then the last way it was 7set it cached. On order to keep track of what you have set and not set, it's 8very advisable to explicitly keep all your options and set them all on one cmake 9line. 10 11Then, when you meet a situation you changed something but somehow cmake is 12sticking with what it knew before, you can fearlessly delete your build dir 13and create a new one with your explicit config. 14 15On Linux, it's usually enough to delete `CMakeCache.txt` to trigger it to config 16from the start again, but on, eg, windows, it isn't, for whatever reason it 17literally needs the build dir removing. 18 19## CMake presence tests that fail 20 21Lws makes use of various CMake features to figure out what apis your libraries 22offer, eg, OpenSSL has many different apis based on version, lws knows how to 23work around most of the changes, but to do it it must find out what apis are 24available first on your build environment. 25 26CMake basically builds little throwaway test programs using each api in turn, and 27if it builds, it understands that the api was available and sets a preprocessor 28symbol that's available in the main build accordingly. Then we can do `#if xxx` 29to figure out if we can use `xxx` or need to do a workaround at build-time. 30 31This works very well, but unfortunately if the program didn't build, there are 32many possible ways for the build to break even if the api being tested is 33really available... for example, some library in your toolchain isn't being 34linked for the throwaway test program. 35 36When this happens, cmake indicates that apis that must be available are not available... 37CMake keeps a log of what happened with the failed test programs in 38`./build/CMakeFiles/CMakeError.log`. This is appeneded to, so the best way is blow 39away the build dir and reconfig a new one from scratch, and go look in there to 40find out what the compiler or linker was complaining about. 41 42