Project: mesos
Issue MESOS-3107: Define CMake style guide
The short story is that it is important to be principled about how the CMake build system is maintained, because there CMake language makes it difficult to statically verify that a configuration is correct. It is not unique in this regard, but (make is arguably even worse) but it is something that's important to make sure we get right. The longer story is, CMake's language is dynamically scoped and often has somewhat odd defaults for variable values (_e.g._, IIRC, target names passed to ExternalProject_Add default to "PREFIX" instead of erroring out). This means that it is rare to get a configuration-time error (_i.e._, CMake usually doesn't say something like "hey this variable isn't defined"), and in large projects, this can make it very difficult to know where definitions come from, or whether it's important that one config routine runs before another. Dynamic scoping also makes it particularly easy to write spaghetti code, which is clearly undesirable for something as important as a build system. Thus, it is particularly important that we lay down our expectations for how the CMake system is to be structured. This might include: * Function naming (_e.g._, making it easy to tell whether a function was defined by us, and where it was defined; so we might say that we want our functions to have an underscore to start, and start with the package the come from, like libprocess, so that we know where to look for the definition.) * What assertions we want to check variable values against, so that we can replace subtle errors (_e.g._, a library is accidentally named something silly like "PREFIX.0.0.1") with an obvious ones (_e.g._, "You have failed to define your target name, so CMake has defaulted to 'PREFIX'; please check your configuration routines") * Decisions of what goes where. (_e.g._, the most complex parts of the CMake MVPs is in the configuration routines, like `MesosConfigure.cmake`; to curb this, we should have strict rules about what goes in that file vs other files, and how we know what is to be run before what. Part of this should probably be prominent comments explaining the structure of the project, so that people aren't confused!) * And so on.
Story points: 3