Document "build_mode"

[memsharded]

The build_mode attribute is exactly what I was looking for as well. It was hard to find since it's named differently than the other package_id_*_mode attributes.

@memsharded I would like to add my vote to have this attribute added to the doc's. :)

---

I'll add a few details to our use-case for this in case it helps others.

We are packaging an SDK for an embedded device and that SDK contains the compiler tools as well as the libraries. Different teams use the toolchain to develop their own apps, which are then delivered as conan packages to a central repo. That central repo is responsible for creating the flashable image for the embedded device, in addition to some core system apps. Due to the libs/headers in the SDK, as well as some traceability needed regarding the used build tools, we had to prevent people from using the wrong SDK by mistake.

We were considering splitting the SDK into build and host package (like the protobuf example), but

1. We wanted to keep that externally delivered SDK "unmodified" in the sense as being one single directory.
2. Did not want each toolchain consumer having to push (or forget to push) an updated package/recipe to our internal remote.

We settled for deploying a centralized conan config (settings, profiles, etc.), which also would give the flexibility to trigger package updates once the "tool_requires" changes, without needing the package owner's intervention.

This is what we've now come up with:

class ConanPackage(ConanFile):
    name = "my-toolchain"
    version = "1.0.0"
    build_mode = "major_mode"

   # rest as the toolchain example from conan-io
...

And a consumer then gets the info embedded like so:

conan list "my-app:*"
Found 1 pkg/version recipes matching my-app in local cache
Local Cache
  my-app
    my-app/1.0.0
      revisions
        e89b72a36317a374aff4f118694fe1f2 (2025-02-05 08:18:17 UTC)
          packages
            e378b1e80ae9d9cbb0f1883f00a510e9a4e2e0e7
              info
                settings
                  arch: armv8
                  ...
                build_requires
                  my-toolchain/1.Y.Z

Originally posted by @myzb in #17320