[build] CMake options for solver opt-out

[tyler-yankee]

Addresses #22547 by:

• adding options to the top-level CMakeLists.txt for each of the open-source solvers, with default ON, which adjust the corresponding existing bazel flags
• adding documentation on https://drake.mit.edu/from_source.html

Also, fixes a typo in a solver test case.

---

This change is 

[tyler-yankee]

See #370 on drake-ci for the test for this feature.

Reviewable status: needs platform reviewer assigned, needs at least two assigned reviewers, commits need curation (https://drake.mit.edu/reviewable.html#curated-commits), missing label for release notes (waiting on @tyler-yankee)

[tyler-yankee]

@jwnimmer-tri for feature review, please!

Reviewable status: needs platform reviewer assigned, needs at least two assigned reviewers, commits need curation (https://drake.mit.edu/reviewable.html#curated-commits), missing label for release notes (waiting on @tyler-yankee)

[tyler-yankee]

Sorry, that's +@jwnimmer-tri.

[jwnimmer-tri]

Please assign someone from Kitware to feature-review this.

(For build fixes and especially CMake changes, generally that's the procedure we want to follow, to keep things moving and conserve my time commitment. I'm always happy to take a first high level look to make sure it's aimed in the right direction, but iterating on the code to make it clear, correct, and sufficiently tested is something y'all can move forward without me.)

Reviewed 2 of 3 files at r1, all commit messages.
Reviewable status: 1 unresolved discussion, LGTM missing from assignee jwnimmer-tri(platform), needs at least two assigned reviewers, commits need curation (https://drake.mit.edu/reviewable.html#curated-commits), missing label for release notes (waiting on @tyler-yankee)

---

CMakeLists.txt line 480 at r1 (raw file):

set(BAZEL_CONFIG)

option(WITH_CLARABEL "Build with support for Clarabel" ON)

BTW Is there a way to do this with less copy-paste?

For some of the other more nuanced flag handling in other cases, writing them out longhand is probably a benefit for clarity. But here, there is no complexity so probably using a helper function would be an improvement for readability and maintainability?

I'm imagining a helper that takes as an argument the single preferred name like "Clarabel" and from that automatically computes the CMake scream case "WITH_CLARABEL" and the rcfile snake case "with_clarabel".

[tyler-yankee]

CMakeLists.txt line 480 at r1 (raw file):

Previously, jwnimmer-tri (Jeremy Nimmer) wrote…

BTW Is there a way to do this with less copy-paste?

For some of the other more nuanced flag handling in other cases, writing them out longhand is probably a benefit for clarity. But here, there is no complexity so probably using a helper function would be an improvement for readability and maintainability?

I'm imagining a helper that takes as an argument the single preferred name like "Clarabel" and from that automatically computes the CMake scream case "WITH_CLARABEL" and the rcfile snake case "with_clarabel".

My instinct was to use a helper function, but I decided against it for consistency with how the code was written for the closed-source solver options. I agree that there's less complexity here so I'll go ahead and re-write it for clarity.

[tyler-yankee]

That makes sense, thanks @jwnimmer-tri!

+@BetsyMcPhail, would you like feature review this?

Reviewable status: 1 unresolved discussion, LGTM missing from assignees jwnimmer-tri(platform),BetsyMcPhail, commits need curation (https://drake.mit.edu/reviewable.html#curated-commits), missing label for release notes (waiting on @tyler-yankee)

[BetsyMcPhail]

Reviewed 2 of 3 files at r1, 1 of 1 files at r4, all commit messages.
Reviewable status: 2 unresolved discussions, LGTM missing from assignee jwnimmer-tri(platform), commits need curation (https://drake.mit.edu/reviewable.html#curated-commits), missing label for release notes (waiting on @tyler-yankee)

---

CMakeLists.txt line 485 at r4 (raw file):

function(open_solver_option SOLVER)
  string(TOUPPER "WITH_${SOLVER}" OPTION_NAME)
  string(TOLOWER "with_${SOLVER}" OPTION_BAZEL_ARG)

Nit This could be moved inside of the if where it is used.

[jwnimmer-tri]

platform, assuming the DEE CI test is passing.

Reviewed 1 of 1 files at r2, 1 of 1 files at r3, 1 of 1 files at r4, 1 of 1 files at r5, all commit messages.
Reviewable status: 2 unresolved discussions, commits need curation (https://drake.mit.edu/reviewable.html#curated-commits), missing label for release notes (waiting on @tyler-yankee)

---

CMakeLists.txt line 487 at r4 (raw file):

  string(TOLOWER "with_${SOLVER}" OPTION_BAZEL_ARG)
  option("${OPTION_NAME}" "Build with support for ${SOLVER}" ON)
  if(NOT ${OPTION_NAME})

nit I would actually recommend setting to True or False always, not just setting False when OFF. Having only one-sided setting here means that if the Bazel default changes, then this code will be wrong.

(Of course having Bazel and CMake end up with different defaults would not be ideal, but it at least the build would be correct per each one's individual documentation.)

That also provides more effective CI coverage of the TOLOWER spelling check, since now the spelling is being run even in normal Drake CI in the main flow.

It does bloat the bazel rcfile somewhat, but I think that's a fair tradeoff. The extra verbosity might even be a win for debugability for users.

[tyler-yankee]

CMakeLists.txt line 487 at r4 (raw file):

Previously, jwnimmer-tri (Jeremy Nimmer) wrote…

nit I would actually recommend setting to True or False always, not just setting False when OFF. Having only one-sided setting here means that if the Bazel default changes, then this code will be wrong.

(Of course having Bazel and CMake end up with different defaults would not be ideal, but it at least the build would be correct per each one's individual documentation.)

That also provides more effective CI coverage of the TOLOWER spelling check, since now the spelling is being run even in normal Drake CI in the main flow.

It does bloat the bazel rcfile somewhat, but I think that's a fair tradeoff. The extra verbosity might even be a win for debugability for users.

Fair enough. These changes should be all set pending CI checks on the DEE side.

[jwnimmer-tri]

Reviewed 1 of 1 files at r6, all commit messages.
Reviewable status: commits need curation (https://drake.mit.edu/reviewable.html#curated-commits), missing label for release notes (waiting on @tyler-yankee)