ENH: Add command line option for debug builds

[david-cortes-intel]

Description

This PR adds an option --debug to the setup.py script to generate debug builds (with debugging symbols and other flags set by cmake).

---

PR should start as a draft, then move to ready for review state after CI is passed and all applicable checkboxes are closed.
This approach ensures that reviewers don't spend extra time asking for regular requirements.

You can remove a checkbox as not applicable only if it doesn't relate to this PR in any way.
For example, PR with docs update doesn't require checkboxes for performance while PR with any change in actual code should have checkboxes and justify how this code change is expected to affect performance (or justification should be self-evident).

Checklist to comply with before moving PR from draft:

PR completeness and readability

• I have reviewed my changes thoroughly before submitting this pull request.
• I have updated the documentation to reflect the changes or created a separate PR with update and provided its number in the description, if necessary.
• Git commit message contains an appropriate signed-off-by string (see CONTRIBUTING.md for details).
• I have added a respective label(s) to PR if I have a permission for that.
• I have resolved any merge conflicts that might occur with the base branch.

Testing

• I have run it locally and tested the changes extensively.
• All CI jobs are green or I have provided justification why they aren't.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Flag	Coverage Δ
azure	78.73% <ø> (-0.98%)	⬇️
github	73.59% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

see 59 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[david-cortes-intel]

CI error is not related to the changes here:

x ./oneapi/mkl/2025.1/lib/mkl_sycld.lib: Truncated tar archive detected while reading data: Unknown error
tar: Error exit delayed from previous errors.
"Unzip complete"

[icfaust]

Could you add some commentary in install about the lack of windows debug support?

[david-cortes-intel]

Could you add some commentary in install about the lack of windows debug support?

Added.