[CMake] out of source command line flag

[Brad King]

Eric Noulard wrote:
> Fair enough,
> my tortuous mind was tracking the build tree yours
> is tracking the source tree, this is obviously a
> better choice.
> 
> My E3) case still remains, you really  don't want to mess-up
> an existing build tree with a unrelated source tree.
> 
> I know however that my proposal does not solve the other problem
> regarding ignoring "<path-to-existing-build>" raised in this thread.

That use case will not be dropped.  I think the two-path auto-magic
command line interpretation approach will work well if implemented
correctly, and will happily review a patch.  However, see my other
suggestion below.

> In the current one arg cmake invocation we should have a way to
> detect/avoid an unvoluntary in-source build.
> Currently we cannot.

This is the key idea.  I've thought about possible solutions to this
in the past but never found time to implement any.  My idea is to
have an optional "InSource.cmake" file written by the project in the
source tree.  If CMake sees an attempt to build in-source, it can
load this file before touching the source tree at all.  The file
could do one of the following:

1.) Simply error-out and tell the user to build out-of-source.
    The source tree will remain clean.
2.) Compute the path to a build tree for CMake to auto-magically
    substitute for an in-source build.  Likely it would be just
    "<source-tree>/build" or some convention the project prefers.
3.) Other ideas?

One gotcha with action #2 is that CMake knows nothing about the
target platform at the point the file is loaded, so projects
would be unable to compute a path like "build-x86_64".

-Brad