doc: swap CPPFLAGS for APPEND_CPPFLAGS

[fanquake]

APPEND_CPPFLAGS will be understood by our CMake, whereas CPPFLAGS will not. Attempting what is currently documented will just give:

CMake Warning:
  Ignoring extra path from command line:

   "CPPFLAGS=-DDEBUG_LOCKCONTENTION"

[DrahtBot]

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

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/31819.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	hebasto, fjahr

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

[hebasto]

ACK ea687d2.

[purpleKarrot]

Where can I read about the decision to chose CPPFLAGS and APPEND_CPPFLAGS? I think those names are unfortunate and may cause confusion with cmake's default handling of the CXXFLAGS environment variable.

[theuni]

@purpleKarrot It's an artifact of a few things:

• The migration from autotools to CMake. autotools made CPPFLAGS a first-class citizen whereas CMake expects users to just pass them in as CXXFLAGS. APPEND_CPPFLAGS could probably be rolled into APPEND_CXXFLAGS, we just maintain the split because it can be a helpful distinction.
• In many cases CXXFLAGS or CMAKE_CXX_FLAGS or CMAKE_CXX_FLAGS_BUILDTYPE will work, but not always. CMake provides no way to append CXXFLAGS, only to prepend or replace. This is really annoying. Mostly because setting things where position matters (like -Ofoo or -UBAR -DBAR=2) is impossible with the built-in vars. Hence our APPEND variables.

[purpleKarrot]

CMake provides no way to append CXXFLAGS, ...

Not sure I understand. On the first run, CMake initializes CMAKE_CXX_FLAGS by prepending CMAKE_CXX_FLAGS_INIT with the environment variable CXXFLAGS. See: https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS_INIT.html

In other words, CMAKE_CXX_FLAGS_INIT is appended to CXXFLAGS. But you say it provides no way to append to CXXFLAGS?

[theuni]

I didn't mean CXXFLAGS the env var, I meant CXXFLAGS the concept (as-in, what ultimately gets passed to the compiler). There are just some things that either we set internally or that CMake sets that are impossible for the user to override without affecting something else (by using a None build type for example).-Ox is one of them.

So we provide these vars with guaranteed append semantics.

[theuni]

Btw, if your argument is "CXXFLAGS=-DDEBUG_LOCKCONTENTION would work for the sake of this PR", I agree with you there.

[fjahr]

ACK ea687d2

Just used APPEND_CPPFLAGS yesterday for some debugging, so it works :)