Description
What language does this apply to?
C++
Describe the problem you are trying to solve.
Developers trying to install Protobuf from source may miss critical dependencies and/or fail to notice that some dependencies need to be installed too. The top-level instructions redirect to the src directory which redirect to the cmake directory.
The instructions there are a bit scattered. They mention Abseil being installed in passing. And they mention -Dprotobuf_ABSL_PROVIDER=package only for Windows. The instructions for Linux are near the bottom and one needs to skip stuff about running unit tests, getting submodules, DLLs, compiler warnings, etc.
It is too easy for developers on other platforms to miss the Abseil flags, and get confused using Abseil as a submodule.
Describe the solution you'd like
I think you should break your build instructions into separate use-cases. The instructions to compile Protobuf as a contributor (with the intention of running tests and sending patches) should be separate from the instructions to compile the code as a consumer (with the intention of just using Protobuf).
For example, the how-to guides for contributors could start with:
**ATTENTION:** These are instructions to compile Protobuf as a contributor to the project.
If you want to use Abseil in your own project use [these instructions](/path/to/doc.md) instead.
while the instructions for consumers of the library could start with:
**ATTENTION:** These are instructions to compile Protobuf as a consumer of the libraries.
If you want to contribute to the project use [these instructions](/path/to/doc.md) instead.
The instructions for each platform should be complete. Ideally tested, I have used Docker scripts to test the instructions and then treat the Dockerfiles as the source of truth to ensure they stay in sync. They should say something like:
## Linux
To compile and install Protobuf on Linux you must have Abseil installed. Follow [Abseil's instructions](link here) to do so.
Then compile the project with
cmake -S . -B .build -D...<all necessary flags here>
cmake --build .build
cmake --install .build
## Windows
<repeat for windows with whatever variations>
## macOS
<again>
Only once you have completed the instructions for the easy case you may want to discuss variations (using ZLIB, using DLLs, etc.)
Describe alternatives you've considered
Additional context
N/A