doc: add note in BUILDING.md about running make distclean

[swagatata]

Fixes: #28675

Checklist

• documentation is changed or added
• commit message follows commit guidelines

[mscdex]

May want to also mention the need to re-run the make command after make distclean.

[Trott]

Welcome @swagatata and thanks for the pull request. Small documentation pull requests can attract a lot of comments, so your patience is appreciated!

[mhdawson]

LGTM after suggestions.

[Trott]

I went ahead and applied the earlier nits via --fixup.. So, revising, here are the remaining suggestions:

• I think this suggestion is in the wrong place. It appears in the build flow description so it looks like it's part of the happy path. It should be in a troubleshooting section instead, or at least at the very, very end of the section.

• It should explain to people what make distclean does.

• It should warn the user that after running make distclean, they will have to run ./configure again if they had any non-default options because make distclean removes config.mk (unlike make clean).

• It should warn the user that after running make distclean, they will need to do a full build so it will take a long time.

• This should probably document make clean as well, along with the difference between clean and distclean.

[swagatata]

I have tried to follow @Trott 's suggestions, adding a "cleaning up the build" section and "troubleshooting" section.

I'm not very well versed with what exactly "make clean" does and how it differs from "make distclean" so I'd welcome some notes to add there.

[Trott]

Needs a little bit more editing. Just leaving this here so no one lands this without those edits.

[Trott]

I moved stuff around, changed headers, but the basic gist and fundamental wording is all still there, I think. PTAL.

[swagatata]

Who can merge this?

[Trott]

Landed in a733c18