refactor(dx): Add structured Makefile with usage description

[github-actions]

Note

The pull request "refactor(dx): Add structured Makefile with usage description" was created by @philprime but did not reference an issue. Therefore this issue was created for better visibility in external tools like Linear.

Summary

This PR refactors the Makefile to provide better structure, documentation, and developer experience.

Changes

• CONFIGURATION section: Added platform-specific variables for iOS, tvOS, visionOS, and watchOS
• Structured sections: Organized targets into clear sections (SETUP, BUILDING, TESTING, LINTING & FORMATTING, ANALYSIS, CODE GENERATION, VERSION MANAGEMENT, VALIDATION, XCODE PROJECT GENERATION, HELP & DOCUMENTATION)
• Comprehensive documentation: Added documentation comments (## for summaries, # for details) following best practices
• Help system: Added make help command with detailed help for each target
• Platform build targets: Added make build convenience target and individual platform builds (build-ios, build-macos, build-catalyst, build-tvos, build-visionos, build-watchos)
• Platform test targets: Added make test convenience target and individual platform tests (test-ios, test-macos, test-catalyst, test-tvos, test-visionos)
• watchOS support: Added build-watchos target (tests not available as XCTest is not supported on watchOS)
• Improved consistency: Platform-specific variable naming for better maintainability

Example: make help Output

==============================================
🚀 SENTRY COCOA SDK DEVELOPMENT COMMANDS
==============================================

init                    Setup the project by installing dependencies, pre-commit hooks, rbenv, and bundler
init-local              Setup local development environment
init-ci-build           Install CI build dependencies
init-ci-format          Install CI format dependencies
update-versions         Update tooling versions
check-versions          Check tooling versions
build                   Build all platforms
build-ios               Build iOS target
build-macos             Build macOS target
build-catalyst          Build Catalyst target
build-tvos              Build tvOS target
build-visionos          Build visionOS target
build-watchos           Build watchOS target
build-xcframework       Build XCFramework for distribution
build-signed-xcframework Build signed XCFramework for distribution
build-xcframework-sample Build XCFramework validation sample
test                    Run all platform tests
test-ios                Run iOS tests
test-macos              Run macOS tests
test-catalyst           Run Catalyst tests
test-tvos               Run tvOS tests
test-visionos           Run visionOS tests
run-test-server         Run test server in background
run-test-server-sync    Run test server synchronously
test-ui-critical        Run critical UI tests
lint                    Run linting checks on all files
lint-staged             Run linting checks on staged files only
format                  Format all files
format-clang            Format Objective-C, C, and C++ files
format-swift-all        Format all Swift files
format-swift-staged     Format staged Swift files
format-markdown         Format Markdown files
format-json             Format JSON files
format-yaml             Format YAML files
analyze                 Run static analysis
generate-public-api     Generate public API documentation
bump-version            Bump version to specified version
verify-version          Verify version matches specified version
clean-version-bump      Clean and build VersionBump tool
release                 Release new version
git-commit-add          Commit version changes and create tag
pod-lint                Lint CocoaPods podspec
xcode                   Generate Xcode projects and open workspace
xcode-ci                Generate all sample Xcode projects
help                    Show this help message with all available commands

💡 Use 'make <command>' to run any command above.
📖 For detailed help on a command, run: make help-<command>  (e.g., make help-build-ios)
📖 Or: make help name=<command>      (e.g., make help name=build-ios)

Benefits

• Better discoverability with make help
• Clearer organization makes it easier to find targets
• Platform-specific variables allow easy customization
• Consistent structure improves maintainability

Testing

• Verified make help works correctly
• Verified all existing targets still function
• Verified help system shows all targets with descriptions

[linear]

COCOA-1127