ruslo/cgold

:whale2: The Hitchhiker’s Guide to the CMake

cgold's Issues

Custom targets

• http://stackoverflow.com/questions/24416133

need to fix alot of broken links

fix is needed

Linking static libraries into shared

https://gitlab.kitware.com/cmake/cmake/issues/16324

C++14 Modules?

Is this in the guide or can it be addressed?

Documentation for static checks

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/

Is it possible to send return value via argument?

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?

It should be "cmake -S src -B build" instead of "cmake -H src -B build"

in https://cgold.readthedocs.io/en/latest/tutorials/out-of-source.html

OBJECTS library

https://gitlab.kitware.com/cmake/cmake/issues/14778

Working with debug symbols

• #6 (lldb)
• #7 (gdb)
• #8 (PDB)

Set warning flags

• https://cmake.org/pipermail/cmake-developers/2016-April/028279.html

RPATH

Not working for Android:

• http://stackoverflow.com/a/13637143/2288008

Build types

• http://stackoverflow.com/a/28124715/2288008
• https://gitlab.kitware.com/cmake/cmake/merge_requests/591#note_244652

lldb: working with debug symbols

Migrated from: https://github.com/ruslo/hunter/issues/359#issuecomment-240917420:

lldb [ for OSX mostly, I guess] would require a . lldbinit file with contents along the lines of:

settings set target.source-map <old-build-directory>/Build <root-id>/Install

in its project directory [ Xcode needs the plugin https://github.com/alloy/lldb-is-it-not for this to work ]. Information from stackoverflow

Scopes for function/macro

http://www.mail-archive.com/[email protected]/msg55884.html

Could I translate this guide to Chinese

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

gdb: working with debug symbols

Migrated from https://github.com/ruslo/hunter/issues/359#issuecomment-240917420:

gdb would require a .gdbinit file in the debugging directory with:

set substitute-path <old-build-directory>/Build <root-id>/Install

Source: https://sourceware.org/gdb/onlinedocs/gdb/Source-Path.html

3.11.1. Static and 3.11.2 Shared chapters are missing

https://cgold.readthedocs.io/en/latest/tutorials/libraries/static.html
https://cgold.readthedocs.io/en/latest/tutorials/libraries/shared.html

PDB: working with debug symbols

OpenCV example: https://github.com/opencv/opencv/blob/bf4c5bef7fa254e996f31d3e3d7f81ce63716c13/cmake/OpenCVModule.cmake#L827-L836

CMake variables:

• https://cmake.org/cmake/help/latest/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.html
• https://cmake.org/cmake/help/latest/variable/CMAKE_PDB_OUTPUT_DIRECTORY.html

Ch 3.7.3: path to mymodule

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?

Using 'macro'

The only way to set variable to parent of the parent scope.

Enable epub/pdf generation on readthedocs.io

It would be fantastic to be able to download a current version as a epub.
AFAIU, it's something in readthedocs.io project settings.
Thank you.

Target(s) to generate Doxygen documentation

Take a look:

• https://github.com/ruslo/sugar/blob/master/cmake/core/sugar_doxygen_generate.cmake
• ruslo/polly#91 (comment)
• https://majewsky.wordpress.com/2010/08/14/tip-of-the-day-cmake-and-doxygen/

Uploading:

• https://github.com/miloyip/rapidjson/blob/master/travis-doxygen.sh

Source property is visible only for current directory

• https://cmake.org/cmake/help/latest/command/set_property.html
• https://cmake.org/cmake/help/latest/command/set_source_files_properties.html

API for other languages

• Python: https://gitlab.kitware.com/cmake/cmake/merge_requests/389
• http://www.mail-archive.com/[email protected]/msg17607.html

Don't use the -H and -B flags for specifiying the source and build directory

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.

Add overview of usefull variables/functions

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

MSYS/MinGW

• MSYS -> make.exe
• MinGW -> mingw-make.exe

PUBLIC/PRIVATE linking

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

• hunter-packages/prometheus-cpp#1 (comment)

configure_file

Always use @ONLY form.

# CMakeLists.txt
set(A "0")
configure_file(foo.cmake.in foo.cmake)

# foo.cmake.in
set(A "1")
message("A = ${A}") # A from CMakeLists.txt will be used!

# foo.cmake
message("A = ")

Is there any way to contribute to Chinese translation?

Your tutorial is brilliant, and I want to contribute a Chinese translation. Is there any guidance to follow?

Local includes vs system includes priority

See https://github.com/ruslo/hunter/issues/368

CMAKE_CURRENT_SOURCE_DIR vs CMAKE_CURRENT_LIST_DIR

• http://stackoverflow.com/q/15662497/2288008
• https://cgold.readthedocs.io/en/latest/tutorials/control-structures.html#cmake-current-list-dir

CMAKE_MODULE_LINKER_FLAGS

Hi Ruslan,

Could you add at some point information about CMAKE_MODULE_LINKER_FLAGS?

I read the docs, but they are not clear to me as to what is meant by modules in this context.

Thanks

Object libraries

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.

ASM sources

• http://stackoverflow.com/questions/25418967
• qedsoftware/crashpad@2a11fe5

Missing back cover

Wrong source link

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.