build: further improvements for passthrough functionality

[medubelko]

• Make *DIR and venv vars conditional. This further helps projects that call the Makefile from a root build system.
• Add a DOCS_ prefix to common vars in Makefile. The build environment has several variables with popular names such as BUILDDIR and SOURCEDIR. These can confuse developers of projects where the docs aren't at the root, and could collide with their root build systems.

---

• Have you updated CHANGELOG.md with relevant non-documentation file changes?
  [ ] Have you updated the documentation for this change?

[dwilding]

This seems like a reasonable change, thanks.

I was wondering whether it's worth introducing the DOCS_... variables in one release and then removing the old variables in a subsequent release. I guess it depends how much people have hardcoded the variable names outside the Makefile.

E.g., I searched for uses of BUILDDIR in YAML files and got two results:

• In ops, which I can update in tandem with the next starter pack version
• In starbase, which I'm sure you already know about

There are also projects such as microcloud, which has a custom Makefile that calls Makefile.sp with BUILDDIR set - but this is an older setup of the starter pack.

These are the uses I could find after a couple of quick searches. Do you have a better feel for how disruptive the changes might be? If it's not much more than what I found, I don't think there's any need for a staged rollout.

[medubelko]

Do you have a better feel for how disruptive the changes might be?

I searched for BUILDDIR and make docs in Makefiles. There are a few projects that call the docs Makefile, but I couldn't find any that deliberately use BUILDDIR. The majority of non-SP uses were from projects that use that name in their own build namespace.

I want to roll out a doc this week that will guide developers on how to consume the Makefile, so the intent of this PR is to get the ducks lined up before we describe the activity.

[akcano]

Do you have a better feel for how disruptive the changes might be?

I searched for BUILDDIR and make docs in Makefiles. There are a few projects that call the docs Makefile, but I couldn't find any that deliberately use BUILDDIR. The majority of non-SP uses were from projects that use that name in their own build namespace.

For added security, consider having the Makefile look for defined BUILDDIR, SOURCEDIR, etc. and say something, e.g.:

ifdef SOURCEDIR
    $(error "SOURCEDIR is deprecated")
endif

[medubelko]

or added security, consider having the Makefile look for defined BUILDDIR, SOURCEDIR, etc. and say something, e.g.:

ifdef SOURCEDIR
    $(error "SOURCEDIR is deprecated")
endif

I don't think we should, since the purpose of these changes is to make it's so it's not possible to collide with these names. If a var like BUILDDIR (used by at least one project at Canonical) is exported to the host's environment, they'll get a warning when it calls the docs.

[akcano]

LGTM, one minor nitpick.