doc: update dev note examples for CMake #30739

Update the examples in the developer notes to work with CMake. Also added an explicit -DCMAKE_EXPORT_COMPILE_COMMANDS=ON for clarity.

<!--e57a25ab6845829454e8d69fc972939a-->

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

<!--006a51241073e994b41acfe9ec718e94-->

Code Coverage

For detailed information about the code coverage, see the test coverage report.

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

See the guideline for information on the review process.

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

ACK 7de0c99804bca98ef159b7b778e6f5b602507d2c

Tested ACK 7de0c99804bca98ef159b7b778e6f5b602507d2c on arm64 macOS 14.6.1

(modulo local issue with the third incantation that is unrelated to this change, with my machine not finding clang-tidy-diff zsh: command not found: clang-tidy-diff)

Do you want to add https://github.com/TheCharlatan/bitcoin/commit/17f6ecd1470c07a3bf26a08e6d1a55ed2f8486ca? I guess we should update all scripts and examples to use the build directory for executing the binaries? Edit: Ah, nevermind I missed #30741

Tested ACK https://github.com/bitcoin/bitcoin/commit/7de0c99804bca98ef159b7b778e6f5b602507d2c

Used the invocation provided here on a clean git clone of bitcoin core, and these instructions worked for generating the needed compile_commands.json for clang-tidy, and the arguments provided here help clang-tidy find the compile commands.

This bit of the docs is also helpful for anyone wanting to use their ide/editor's lsp client with the clangd server which also requires compile_commands.json.

<details>

<summary>

clang-tidy-diff

</summary>

I had the same issue with clang-tidy-diff as @jonatack, but I tested that the invocation provided here works with the out-of-$PATH-for-me clang-tidy-diff.py:

git diff | ( cd ./src/ && /usr/share/clang/clang-tidy-diff.py -p2 -path ../build -j $(nproc) )

This actually seems like it might be partly llvm's issue, as there's a ~10 year old FIXME comment asking for the clang-tidy-diff.py stuff to get rolled into run-clang-tidy.

Initially running into issues building with Debian (12.6) default clang 14.0.6 and with 18.1.8. Fresh clone. Hope to revisit soon. No issues seen with gcc (following https://github.com/bitcoin/bitcoin/blob/master/doc/build-unix.md#to-build).

cmake -B build -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build build -j 18

-- Found Boost: /usr/include (found suitable version "1.74.0", minimum required is "1.73.0")
...
$ clang --version
Debian clang version 18.1.8 (++20240731024826+3b5b5c1ec4a3-1~exp1~20240731144843.145)
Target: x86_64-pc-linux-gnu

With 18.1.8

In file included from /usr/include/boost/mpl/integral_c.hpp:32:
/usr/include/boost/mpl/aux_/integral_wrapper.hpp:73:31: error: integer value -1 is outside the valid range of values [0, 3] for the enumeration type 'udt_builtin_mixture_enum' [-Wenum-constexpr-conversion]
   73 |     typedef AUX_WRAPPER_INST( BOOST_MPL_AUX_STATIC_CAST(AUX_WRAPPER_VALUE_TYPE, (value - 1)) ) prior;
      |                               ^
/usr/include/boost/mpl/aux_/static_cast.hpp:24:47: note: expanded from macro 'BOOST_MPL_AUX_STATIC_CAST'
   24 | #   define BOOST_MPL_AUX_STATIC_CAST(T, expr) static_cast<T>(expr)
      |                                               ^
In file included from ../../../src/test/validation_chainstatemanager_tests.cpp:8:
In file included from ../../../src/node/chainstatemanager_args.h:9:
In file included from ../../../src/validation.h:28:
In file included from ../../../src/txmempool.h:26:
In file included from /usr/include/boost/multi_index/hashed_index.hpp:38:
In file included from /usr/include/boost/multi_index/detail/node_handle.hpp:22:
In file included from /usr/include/boost/multi_index_container_fwd.hpp:18:
In file included from /usr/include/boost/multi_index/indexed_by.hpp:17:
In file included from /usr/include/boost/mpl/vector.hpp:36:
In file included from /usr/include/boost/mpl/vector/vector20.hpp:18:
In file included from /usr/include/boost/mpl/vector/vector10.hpp:18:
In file included from /usr/include/boost/mpl/vector/vector0.hpp:24:
In file included from /usr/include/boost/mpl/vector/aux_/clear.hpp:18:
In file included from /usr/include/boost/mpl/vector/aux_/vector0.hpp:22:
In file included from /usr/include/boost/mpl/vector/aux_/iterator.hpp:19:
In file included from /usr/include/boost/mpl/plus.hpp:19:
In file included from /usr/include/boost/mpl/aux_/arithmetic_op.hpp:17:
In file included from /usr/include/boost/mpl/integral_c.hpp:32:
/usr/include/boost/mpl/aux_/integral_wrapper.hpp:73:31: error: integer value -1 is outside the valid range of values [0, 3] for the enumeration type 'int_float_mixture_enum' [-Wenum-constexpr-conversion]
/usr/include/boost/mpl/aux_/static_cast.hpp:24:47: note: expanded from macro 'BOOST_MPL_AUX_STATIC_CAST'
   24 | #   define BOOST_MPL_AUX_STATIC_CAST(T, expr) static_cast<T>(expr)
      |                                               ^
2 errors generated.

/usr/include/boost/mpl/aux_/integral_wrapper.hpp:73:31: error: integer value -1 is outside the valid range of values [0, 3] for the enumeration type 'udt_builtin_mixture_enum' [-Wenum-constexpr-conversion]

That is just a boost issue, unrelated to cmake. It should happen with autotools as well. I think you can fix it by upgrading your distro (or boost)

Initially running into issues building

Opened an issue to track this: #30751 , as it needs fixing in some way (also for 28.x).

Thank you 👍

Thank you

It may not be clear to all readers of this document that -B will instruct cmake to create a directory and that the argument could be anything. This information may be useful for people that want to maintain multiple build directories.

cmake --build is useful in generic scripts that handle multiple build systems.

On the command line, invoking the underlying commands explicitly is both easier to understand and faster to type:

mkdir build
cd build
cmake -GNinja ..
ninja

Users that prefer using clang, may set CC=clang and CXX=clang++ as environment variables. Users that need the compile commands, can set the CMAKE_EXPORT_COMPILE_COMMANDS=1 environment variable. Other useful environment variables are CMAKE_C_COMPILER_LAUNCHER and CMAKE_CXX_COMPILER_LAUNCHER. (By the way, it is not a good idea that the project sets these, because it may interfere with user preferences).

On the command line, invoking the underlying commands explicitly is both easier to understand and faster to type:

mkdir build
cd build
cmake -GNinja ..
ninja

I would advise against this approach, as it may inadvertently lead to the use of an incorrect build tool.

For instance, on macOS, when GNU Make is installed via Homebrew, two build tools become available:

% which -a make                 
/usr/bin/make
% make --version                                                                                                                
GNU Make 3.81
Copyright (C) 2006  Free Software Foundation, Inc.
This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.

This program built for i386-apple-darwin11.3.0
% which -a gmake                
/opt/homebrew/bin/gmake
% gmake --version               
GNU Make 4.4.1
Built for aarch64-apple-darwin24.0.0
Copyright (C) 1988-2023 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

While CMake selects /opt/homebrew/bin/gmake, there remains a risk that the user might inadvertently execute /usr/bin/make manually.