CMake in ClickHouse

    1. ClickHouse’s source CMake files (located in the root directory and in ).
    2. Arch-dependent CMake files (located in /cmake/*os_name*).
    3. Contrib build CMake files (used instead of libraries’ own CMake files, located in /cmake/modules)
    • This list is auto-generated by this Python script.
    • The flag name is a link to its position in the code.
    • If an option’s default value is itself an option, it’s also a link to its position in this list.

    External libraries

    Note that ClickHouse uses forks of these libraries, see https://github.com/ClickHouse-Extras.

    External libraries system/bundled mode

    Don’t be obvious. Be informative.

    Bad:

    1. option (ENABLE_TESTS "Enables testing" OFF)

    This description is quite useless as is neither gives the viewer any additional information nor explains the option purpose.

    Better:

    1. option(ENABLE_TESTS "Provide unit_test_dbms target with Google.test unit tests" OFF)

    If the option’s purpose can’t be guessed by its name, or the purpose guess may be misleading, or option has some
    pre-conditions, leave a comment above the option() line and explain what it does.
    The best way would be linking the docs page (if it exists).
    The comment is parsed into a separate column (see below).

    1. # implies ${TESTS_ARE_ENABLED}
    2. # see tests/CMakeLists.txt for implementation detail.
    3. option(ENABLE_TESTS "Provide unit_test_dbms target with Google.test unit tests" OFF)

    If the option’s state could produce unwanted (or unusual) result, explicitly warn the user.

    Suppose you have an option that may strip debug symbols from the ClickHouse’s part.
    This can speed up the linking process, but produces a binary that cannot be debugged.
    In that case, prefer explicitly raising a warning telling the developer that he may be doing something wrong.
    Also, such options should be disabled if applies.

    Bad:

    Better:

    1. # Provides faster linking and lower binary size.
    2. # Tradeoff is the inability to debug some source files with e.g. gdb
    3. # (empty stack frames and no local variables)."
    4. option(STRIP_DEBUG_SYMBOLS_FUNCTIONS
    5.     "Do not generate debugger info for ClickHouse functions."
    6.     ${STRIP_DSF_DEFAULT})
    7. if (STRIP_DEBUG_SYMBOLS_FUNCTIONS)
    8.     message(WARNING "Not generating debugger info for ClickHouse functions")
    9.     target_compile_options(clickhouse_functions PRIVATE "-g0")
    10. endif()

    The WHY explanation should be placed in the comment.
    You may find that the option’s name is self-descriptive.

    Bad:

    1. option(ENABLE_THINLTO "Enable Thin LTO. Only applicable for clang. It's also suppressed when building with tests or sanitizers." ON)
    1. # Only applicable for clang.
    2. # Turned off when building with tests or sanitizers.
    3. option(ENABLE_THINLTO "Clang-specific link time optimisation" ON).

    Don’t assume other developers know as much as you do.

    In ClickHouse, there are many tools used that an ordinary developer may not know. If you are in doubt, give a link to
    the tool’s docs. It won’t take much of your time.

    Bad:

    Better (combined with the above hint):

    1. # https://clang.llvm.org/docs/ThinLTO.html
    2. # Only applicable for clang.
    3. # Turned off when building with tests or sanitizers.
    4. option(ENABLE_THINLTO "Clang-specific link time optimisation" ON).

    Other example, bad:

    1. option (USE_INCLUDE_WHAT_YOU_USE "Use 'include-what-you-use' tool" OFF)

    Better:

    1. # https://github.com/include-what-you-use/include-what-you-use
    2. option (USE_INCLUDE_WHAT_YOU_USE "Reduce unneeded #include s (external tool)" OFF)

    Prefer consistent default values.