[cmake-developers] module proposal: PreventInSourceBuilds

[Joachim Wuttke]

In all my projects, the top-level CMakeLists.txt contains the line

include(PreventInSourceBuilds)

to protect users (and myself) from unintentionally running CMake
in the source directory.

Would you consider adding this little module to the CMake code base?

I would then add an option so that users can override the not-in-source policy.

/Joachim

---

#.rst:
# PreventInSourceBuilds
# ---------------------
#
# Prevent in-source builds
#
# It is generally acknowledged that it is preferable to run CMake out of source,
# in a dedicated build directory. To prevent users from accidentally running
# CMake in the source directory, just include this module.

# make sure the user doesn't play dirty with symlinks
get_filename_component(srcdir "${CMAKE_SOURCE_DIR}" REALPATH)
get_filename_component(bindir "${CMAKE_BINARY_DIR}" REALPATH)

# disallow in-source builds
if("${srcdir}" STREQUAL "${bindir}")
message(FATAL_ERROR "\

CMake must not to be run in the source directory. \
Rather create a dedicated build directory and run CMake there. \
To clean up after this aborted in-source compilation:
rm -r CMakeCache.txt CMakeFiles
")
endif()

[Roger Leigh]

Post by Joachim Wuttke
In all my projects, the top-level CMakeLists.txt contains the line
include(PreventInSourceBuilds)
to protect users (and myself) from unintentionally running CMake
in the source directory.

I for one have an equivalent to this logic in all my projects to prevent
in-source builds. Having a standardised version would be very useful,
and I would certainly make use of it.


Thanks,
Roger
--
Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake-developers

[Brad King]

Post by Joachim Wuttke
include(PreventInSourceBuilds)
to protect users (and myself) from unintentionally running CMake
in the source directory.
Would you consider adding this little module to the CMake code base?

If we are going to offer an upstream solution for this I think
it should be done in a way that avoids ever creating any files
(like CMakeCache.txt or CMakeFiles) in the first place. This
could be achieved by looking for a `.cmake/init.json` file
at the top of the source tree with declarative information
about the project's preferences. One of those settings could
reject in-source builds.

-Brad
--
Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake-developers

[Taylor Holberton]

A lot of projects that use CMake already have a `./cmake` directory, I
would think `./cmake/init.json` would fit nicer as opposed to the hidden
directory. I'm not a fan of hidden directories in software projects anyway.

I would prefer an init file be written as a CMake file instead of JSON.
JSON is nice because it plays well with GUIs, but I think using CMake
syntax will function better if the file ever needs to be a bit more
complicated.

Post by Brad King

Post by Joachim Wuttke
include(PreventInSourceBuilds)
to protect users (and myself) from unintentionally running CMake
in the source directory.
Would you consider adding this little module to the CMake code base?

If we are going to offer an upstream solution for this I think
it should be done in a way that avoids ever creating any files
(like CMakeCache.txt or CMakeFiles) in the first place. This
could be achieved by looking for a `.cmake/init.json` file
at the top of the source tree with declarative information
about the project's preferences. One of those settings could
reject in-source builds.
-Brad
--
Powered by www.kitware.com
http://www.cmake.org/Wiki/CMake_FAQ
Kitware offers various services to support the CMake community. For more
CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html
Visit other Kitware open-source projects at
http://www.kitware.com/opensource/opensource.html
https://cmake.org/mailman/listinfo/cmake-developers

[Brad King]

Post by Taylor Holberton
A lot of projects that use CMake already have a `./cmake` directory,
I would think `./cmake/init.json` would fit nicer as opposed to the
hidden directory.

We could have a list of supported places so projects can choose.

Post by Taylor Holberton
I would prefer an init file be written as a CMake file instead of JSON.

We need to be able to load the file without initializing much.
If it is a CMake language file then people will try to write `if`
conditions to check things that we wouldn't provide access to at
that point. The idea of this file is to have a purely declarative
specification. A format like JSON will work well for that.

-Brad
--
Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake-developers

[Ben Boeckel]

Post by Taylor Holberton
A lot of projects that use CMake already have a `./cmake` directory, I
would think `./cmake/init.json` would fit nicer as opposed to the hidden
directory. I'm not a fan of hidden directories in software projects anyway.

There are also `./CMake` directories. HDF5 uses `./config/cmake`. I
think just claiming a "hidden" directory with exact casing is better.

--Ben
--
Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake-developers

[Eric Noulard]

Just a small remark to say this request of "builtin" way to forbid
in-source is quite old:
https://gitlab.kitware.com/cmake/cmake/issues/6672
which find its origin in:
https://cmake.org/Bug/view.php?id=6672

I don't know if the note from that initial discussion are valid nowadays
but the fact that:
"Code in CMakeLists.txt is not even executed until after the cache is
initialized so there would have to be some other way to indicate in the
source tree that it should not be built in-source."
and the fact that
"The cache is initialized before the procedural steps start to run. With
cmake-gui or the cmake command-line "-D" option it is even possible to
store entries in the cache before CMake even parses CMakeLists.txt"
almost implies that this should be done outside CMakeLists.txt

That said, I think that
I would rather have some obviously visible and fixed place like
CMakeInit.json that should be located in the very same directory as the
concerned CMakeLists.txt rather than some list of possible places (cmake/,
cmake/init, .cmake, etc...). The exact path to CMakeInit.json could be
overwritten by some new command line option, like --init-file if for some
reason we want
a configurable place (may be used in various CI scripts occasion).
This file could hold more options than "just forbid in-source" it could
indicate a default generator (which may be different from the usual default
generator on the concerned platform),
some a toolchain. It's usage would be different than the initial cache
precisely because it could work before cache is created.

Post by Taylor Holberton

Post by Taylor Holberton
A lot of projects that use CMake already have a `./cmake` directory, I
would think `./cmake/init.json` would fit nicer as opposed to the hidden
directory. I'm not a fan of hidden directories in software projects

anyway.
There are also `./CMake` directories. HDF5 uses `./config/cmake`. I
think just claiming a "hidden" directory with exact casing is better.
--Ben
--
Powered by www.kitware.com
http://www.cmake.org/Wiki/CMake_FAQ
Kitware offers various services to support the CMake community. For more
CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html
Visit other Kitware open-source projects at
http://www.kitware.com/opensource/opensource.html
https://cmake.org/mailman/listinfo/cmake-developers

[Rolf Eike Beer]

(correct list this time)

Post by Joachim Wuttke
# disallow in-source builds
if("${srcdir}" STREQUAL "${bindir}")

if(srcdir STREQUAL bindir)

HTH

Eike
--
--
Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake-developers

[Joachim Wuttke]

Post by Rolf Eike Beer

Post by Joachim Wuttke
if("${srcdir}" STREQUAL "${bindir}")

if(srcdir STREQUAL bindir)

looks more idiomatic, thank you Eike -

But can we be sure that srcdir contains no blank?
Or does STREQUAL work even for argument strings
that contain blanks?

- Joachim

[Rolf Eike Beer]

Post by Joachim Wuttke

Post by Rolf Eike Beer

Post by Joachim Wuttke
if("${srcdir}" STREQUAL "${bindir}")

if(srcdir STREQUAL bindir)

looks more idiomatic, thank you Eike -
But can we be sure that srcdir contains no blank?
Or does STREQUAL work even for argument strings
that contain blanks?

If you pass in only the variable names CMake will do the expansion only
internally, so this is save. It just works (tm).

Eike
--
--
Powered by www.kitware.com

Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ

Kitware offers various services to support the CMake community. For more information on each offering, please visit:

CMake Support: http://cmake.org/cmake/help/support.html
CMake Consulting: http://cmake.org/cmake/help/consulting.html
CMake Training Courses: http://cmake.org/cmake/help/training.html

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
https://cmake.org/mailman/listinfo/cmake-developers