In https://cgold.readthedocs.io/en/latest/tutorials/out-of-source.html (and on other pages), the -H. and -B flags are used.

According to http://stackoverflow.com/a/31092052, this is undocumented because it shouldn't be used. The answer links to https://cmake.org/pipermail/cmake-developers/2016-June/028843.html, it says

These are undocumented because they are internal options that
are not meant for public use.

So I guess the flags shouldn't be used in the tutorial.

I though it would be useful to people trying to figure out exactly what changes in the install layout on the different platforms.

I took the Windows layout from the appveyor run so it is correct :-)

Feel free to edit and/or squash.

In Return Value, it recommends to set a variable to the parent scope to return a value from function.

But I am wondering if it is possible to return a value via argument of function. It is more commonly seen in CMake for example: ProcessorCount(N), N is a output argument of function.

Is the function argument in CMake passed by reference?

In preparation for the 3.13 release I want to update the CGold documentation on the -H and -B flags as CMake now has support for explicit source and build directories with -S and -B.

Changes: https://gitlab.kitware.com/cmake/cmake/merge_requests/2358/diffs

Note: I did the editing locally and didn't verify the rst is valid.

In this file: CGold/docs/tutorials/libraries/symbols/tools.rst

The link duplicates: /examples/library-examples/library-symbols/Boo.cpp

It seems to me, Foo.cpp must be in the second case.

The example in cmake-sources/with-external-module-good doesn't work because the path to mymodule.cmake isn't fully specified (CMAKE Error: include could not find load file: mymodule).

How should the include statement look correctly? Add the line list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/../external") before?

No significant content changes/updates. Some slight sentence & punctuation restructuring in order to improve readability. Some rewording to make the statements more precise.

Hi! First of all, a huge thanks for the work you've done. It's a real timesaver and an interesting and convenient way to learn CMake.

I thought it would be nice to refine docs a little bit since it could be read by many english speakers as well (:

cmake-can-not - removed redundant "useful" cmake-can - replaced rhetorical question, corrected grammar version-policies - improved readability workflow - grammer

Thank you for the great CMake resource! It helped me a lot.

In docs/rejected/object-libraries.rst, the affirmation that "library can't be used on the right hand side of target_link_libraries command" is wrong since CMake 3.12.

I've read many cmake guide or tutorial, but many of them are old-fashioned. I find what i need in your guide. And i wanna to share this to my Chinese friends. Is this fine to translate it

Woud it be possible to add some shortlist of usefull variables/functions.

Perhaps something like this: https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/Useful-Variables

cmake_minimum_required(VERSION 3.2)
project(foo)

add_library(foo foo.cpp)
target_compile_definitions(foo PUBLIC FOO_FEATURE)

add_library(baz_1 baz_1.cpp)
target_link_libraries(baz_1 PUBLIC foo) # Case 1

add_library(baz_2 baz_2.cpp)
target_link_libraries(baz_2 PRIVATE foo) # Case 2

add_executable(boo_1 boo_1.cpp)
target_link_libraries(boo_1 PRIVATE baz_1)

add_executable(boo_2 boo_2.cpp)
target_link_libraries(boo_2 PRIVATE baz_2)

/usr/bin/c++ -DFOO_FEATURE -o foo.cpp.o -c foo.cpp

/usr/bin/c++ -DFOO_FEATURE -o baz_1.cpp.o -c baz_1.cpp
/usr/bin/c++ -DFOO_FEATURE -o boo_1.cpp.o -c boo_1.cpp # FOO_FEATURE added, foo headers can be used in boo_1.cpp
/usr/bin/c++ boo_1.cpp.o -o boo_1 libbaz_1.a libfoo.a  # libfoo.a added, linking is static, we may need symbols

/usr/bin/c++ -DFOO_FEATURE -o baz_2.cpp.o -c baz_2.cpp
/usr/bin/c++ -o boo_2.cpp.o -c boo_2.cpp               # FOO_FEATURE is missing, can't use foo headers in boo_2.cpp
/usr/bin/c++ boo_2.cpp.o -o boo_2 libbaz_2.a libfoo.a  # libfoo.a added even if PRIVATE used

• https://github.com/hunter-packages/prometheus-cpp/pull/1#issuecomment-448426639

Would be nice to have information on how to use static checks within CMake for projects.

https://blog.kitware.com/static-checks-with-cmake-cdash-iwyu-clang-tidy-lwyu-cpplint-and-cppcheck/