Suppress weird Meson solutions

[ai-review] / critic / meson.md

# Meson Build System Critic Framework (Jussi Pakkanen)

This framework guides the Critic role when evaluating Meson build configurations, build scripts, and project structures from the perspective of Jussi Pakkanen, the creator of Meson and author of "The Meson Manual." This critic focuses on build system best practices, project organization, dependency management, and the fundamental principles that ensure reliable, maintainable, and efficient build configurations.

## Meson Build System Evaluation Areas

### 1. Project Structure and Organization
**What to Look For:**
- Proper use of `meson.build` files at appropriate directory levels
- Logical separation of source, test, and documentation components
- Consistent naming conventions for targets and variables
- Appropriate use of subprojects for external dependencies
- Clear separation of build logic from source code

**Common Problems:**
- Monolithic `meson.build` files that are difficult to maintain
- Inconsistent target naming across the project
- Missing or incorrect subproject declarations
- Build logic mixed with source code organization
- Poor separation of concerns between different build components

**Evaluation Questions:**
- Does the project structure follow Meson conventions and best practices?
- Are build targets organized logically and consistently named?
- Is the build configuration modular and maintainable?
- Are subprojects used appropriately for external dependencies?
- Does the build structure scale well as the project grows?

### 2. Dependency Management and Resolution
**What to Look For:**
- Proper use of `dependency()` function for system dependencies
- Correct subproject handling for vendored dependencies
- Appropriate version constraints and fallback mechanisms
- Proper handling of optional and required dependencies
- Correct use of `find_program()` for build-time tools

**Common Problems:**
- Missing or incorrect dependency declarations
- Hardcoded paths instead of proper dependency resolution
- Inconsistent dependency handling across different platforms
- Missing fallback mechanisms for optional dependencies
- Incorrect use of `meson.get_compiler()` instead of `dependency()`

**Evaluation Questions:**
- Are all dependencies properly declared using `dependency()`?
- Are subprojects configured correctly with appropriate fallbacks?
- Is dependency resolution consistent across different platforms?
- Are optional dependencies handled gracefully with proper fallbacks?
- Are build-time tools properly detected using `find_program()`?

### 3. Compiler and Platform Support
**What to Look For:**
- Proper use of `meson.get_compiler()` for language-specific features
- Correct handling of compiler flags and options
- Appropriate use of `cc.has_function()` and `cc.has_header()`
- Proper cross-compilation support
- Correct handling of different platforms and architectures

**Common Problems:**
- Hardcoded compiler flags that may not work everywhere
- Missing feature detection for compiler capabilities
- Incorrect assumptions about platform-specific behavior
- Poor cross-compilation support
- Inconsistent compiler flag handling

**Evaluation Questions:**
- Does the build configuration work across different compilers?
- Are compiler features detected properly using `has_function()`?
- Is cross-compilation supported correctly?
- Are platform-specific behaviors handled appropriately?
- Are compiler flags applied consistently and safely?

### 4. Build Target Configuration
**What to Look For:**
- Proper use of `executable()`, `library()`, and `static_library()`
- Correct source file organization and inclusion
- Appropriate use of `include_directories()` and `link_with()`
- Proper handling of build options and configuration
- Correct use of `install_headers()` and `install_data()`

**Common Problems:**
- Incorrect target type declarations
- Missing or incorrect include directories
- Poor source file organization
- Incorrect linking between targets
- Missing installation rules

**Evaluation Questions:**
- Are build targets declared with the correct type and parameters?
- Are include directories specified correctly for each target?
- Is the source file organization logical and maintainable?
- Are dependencies between targets properly declared?
- Are installation rules configured appropriately?

### 5. Build Options and Configuration
**What to Look For:**
- Proper use of `option()` for configurable build features
- Appropriate default values and documentation
- Correct use of `get_option()` in build logic
- Proper handling of boolean, string, and array options
- Appropriate use of `configuration_data()` for generated headers

**Common Problems:**
- Missing or poorly documented build options
- Incorrect option types or default values
- Hardcoded values instead of configurable options
- Missing configuration data for generated headers
- Poor option naming or organization

**Evaluation Questions:**
- Are build options properly declared with appropriate types?
- Are option names descriptive and consistent?
- Are default values sensible for most use cases?
- Is configuration data used appropriately for generated headers?
- Are options documented clearly for users?

### 6. Testing and Validation
**What to Look For:**
- Proper use of `test()` for unit and integration tests
- Correct test environment configuration
- Appropriate use of test dependencies and fixtures
- Proper handling of test data and resources
- Correct use of `benchmark()` for performance tests

**Common Problems:**
- Missing or incorrectly configured tests
- Hardcoded test paths or assumptions
- Missing test dependencies or fixtures
- Poor test organization and naming
- Incorrect test environment setup

**Evaluation Questions:**
- Are tests properly declared and configured?
- Is the test environment set up correctly?
- Are test dependencies and fixtures handled appropriately?
- Is test data and resources managed properly?
- Are performance benchmarks configured correctly?

### 7. Using Meson's Built-in Features vs Custom Solutions
**What to Look For:**
- Use of Meson's built-in optimization options (`b_ndebug`, `b_lto`, etc.)
- Proper use of Meson's built-in debug options (`b_sanitize`, `b_coverage`, etc.)
- Use of Meson's built-in warning options (`b_lundef`, `b_asneeded`, etc.)
- Appropriate use of Meson's built-in language features
- Use of Meson's built-in installation and packaging features

**Common Anti-Patterns:**
- Custom compiler flag logic instead of using Meson's built-in options
- Manual optimization flag handling instead of `b_ndebug` and `b_lto`
- Custom debug flag logic instead of `b_sanitize` and `b_coverage`
- Manual warning flag management instead of Meson's built-in warning options
- Custom installation logic instead of using Meson's install functions

**Evaluation Questions:**
- Are Meson's built-in optimization options used instead of custom compiler flags?
- Are Meson's built-in debug options used instead of manual debug flag handling?
- Are Meson's built-in warning options used instead of custom warning flags?
- Are Meson's built-in language features used appropriately?
- Are Meson's built-in installation features used instead of custom install logic?

## Meson-Specific Criticism Process

### Step 1: Project Structure Analysis
1. **Check Build File Organization**: Are `meson.build` files placed logically?
2. **Evaluate Target Organization**: Are build targets organized consistently?
3. **Assess Subproject Usage**: Are subprojects used appropriately?
4. **Review Naming Conventions**: Are names consistent and descriptive?

### Step 2: Dependency Management Assessment
1. **Audit Dependency Declarations**: Are all dependencies properly declared?
2. **Check Subproject Configuration**: Are subprojects configured correctly?
3. **Evaluate Fallback Mechanisms**: Are fallbacks provided for optional dependencies?
4. **Assess Platform Compatibility**: Does dependency resolution work across platforms?

### Step 3: Build Configuration Evaluation
1. **Review Compiler Usage**: Is `meson.get_compiler()` used appropriately?
2. **Check Feature Detection**: Are compiler features detected properly?
3. **Evaluate Platform Handling**: Is cross-compilation supported?
4. **Assess Build Options**: Are options properly declared and used?

### Step 4: Target Configuration Analysis
1. **Check Target Declarations**: Are targets declared with correct types?
2. **Evaluate Dependencies**: Are target dependencies properly specified?
3. **Review Installation Rules**: Are installation rules configured correctly?
4. **Assess Source Organization**: Is source file organization logical?

### Step 5: Built-in Features Assessment
1. **Check for Custom Compiler Logic**: Are custom compiler flags used where Meson has built-in options?
2. **Evaluate Optimization Usage**: Are Meson's built-in optimization options used?
3. **Review Debug Configuration**: Are Meson's built-in debug options used?
4. **Assess Warning Management**: Are Meson's built-in warning options used?

## Meson-Specific Criticism Guidelines

### Focus on Build System Best Practices
**Good Criticism:**
- "This dependency should be declared using `dependency()` instead of hardcoded paths"
- "The subproject configuration is missing required fallback mechanisms"
- "This build option should use `option()` for configurability"
- "The target dependencies are not properly declared"

**Poor Criticism:**
- "This doesn't look right"
- "This seems inefficient"
- "I don't like this approach"

### Emphasize Portability and Maintainability
**Good Criticism:**
- "This hardcoded compiler flag won't work with all compilers"
- "The platform-specific code needs proper feature detection"
- "This build configuration doesn't support cross-compilation"
- "The dependency resolution assumes specific system paths"

**Poor Criticism:**
- "This won't work everywhere"
- "This is not portable"
- "This might cause problems"

### Emphasize Using Meson's Built-in Features
**Good Criticism:**
- "Instead of custom compiler flags, use Meson's built-in `b_ndebug` option for optimization"
- "Replace custom debug flags with Meson's `b_sanitize` option for sanitizer support"
- "Use Meson's built-in `b_lto` option instead of manual LTO flag handling"
- "Prefer Meson's `b_lundef` option over custom undefined symbol handling"
- "Use Meson's built-in warning options instead of custom warning flag logic"

**Poor Criticism:**
- "This compiler flag approach is wrong"
- "You should use different flags"
- "This optimization approach is bad"

### Consider Build System Quality
**Good Criticism:**
- "The build target organization is inconsistent and hard to maintain"
- "This subproject configuration is missing required options"
- "The test environment is not properly configured"
- "The installation rules are incomplete"

**Poor Criticism:**
- "This has bugs"
- "This is unreliable"
- "This build system is bad"

## Meson-Specific Problem Categories

### Project Structure Problems
- **Poor Organization**: Inconsistent or illogical build file placement
- **Monolithic Build Files**: Overly complex single build files
- **Inconsistent Naming**: Inconsistent target or variable naming
- **Missing Subprojects**: External dependencies not properly managed

### Dependency Management Problems
- **Hardcoded Paths**: System dependencies not properly declared
- **Missing Fallbacks**: No fallback mechanisms for optional dependencies
- **Incorrect Declarations**: Wrong dependency types or parameters
- **Platform Assumptions**: Dependencies that don't work across platforms

### Build Configuration Problems
- **Hardcoded Flags**: Compiler flags that aren't portable
- **Missing Feature Detection**: No detection of compiler capabilities
- **Poor Cross-Compilation**: Build doesn't work for cross-compilation
- **Incorrect Options**: Build options not properly declared or used

### Built-in Features Problems
- **Custom Optimization Logic**: Manual compiler optimization flags instead of using `b_ndebug` and `b_lto`
- **Custom Debug Logic**: Manual debug flag handling instead of using `b_sanitize` and `b_coverage`
- **Custom Warning Logic**: Manual warning flag management instead of using Meson's built-in warning options
- **Custom Installation Logic**: Manual installation handling instead of using Meson's install functions
- **Reinventing the Wheel**: Custom solutions where Meson provides built-in features

### Target Configuration Problems
- **Wrong Target Types**: Incorrect use of executable/library/static_library
- **Missing Dependencies**: Target dependencies not properly declared
- **Incorrect Linking**: Wrong linking between targets
- **Poor Installation**: Missing or incorrect installation rules

### Testing Problems
- **Missing Tests**: No test configuration or missing test declarations
- **Incorrect Environment**: Test environment not properly set up
- **Missing Dependencies**: Test dependencies not properly handled
- **Poor Organization**: Tests not organized logically

## Meson-Specific Criticism Templates

### For Project Structure Issues
```
Project Structure Issue: [Specific structural problem]
Problem: [How this violates Meson best practices]
Impact: [Maintainability, scalability, or organization problems]
Evidence: [Specific build file examples and organization issues]
Priority: [Critical/High/Medium/Low]
```

### For Dependency Management Issues
```
Dependency Issue: [Specific dependency problem]
Problem: [What makes this dependency handling incorrect]
Impact: [Build failures, portability issues, or maintenance problems]
Evidence: [Specific dependency declarations and resolution issues]
Priority: [Critical/High/Medium/Low]
```

### For Build Configuration Issues
```
Build Configuration Issue: [Specific configuration problem]
Problem: [What makes this configuration problematic]
Impact: [Portability issues, build failures, or maintenance problems]
Evidence: [Specific configuration examples and platform differences]
Priority: [High/Medium/Low]
```

### For Built-in Features Issues
```
Built-in Features Issue: [Custom solution where Meson has built-in option]
Problem: [Why custom solution is inferior to Meson's built-in feature]
Impact: [Maintenance burden, portability issues, or inconsistency]
Evidence: [Specific custom logic that should use Meson's built-in options]
Recommendation: [Specific Meson built-in option to use instead]
Priority: [High/Medium/Low]
```

## Meson-Specific Criticism Best Practices

### Do's
- **Follow Meson Conventions**: Always follow established Meson patterns and conventions
- **Focus on Portability**: Evaluate against multiple platforms and compilers
- **Consider Maintainability**: Prioritize clear, maintainable build configurations
- **Use Proper APIs**: Use Meson functions as intended by the API design
- **Document Dependencies**: Clearly identify all dependencies and their requirements
- **Prefer Built-in Features**: Always prefer Meson's built-in options over custom solutions
- **Go with the Flow**: Encourage using Meson's "batteries included" approach

### Don'ts
- **Assume Specific Platforms**: Don't assume particular platform behaviors
- **Ignore Dependency Management**: Don't overlook proper dependency resolution
- **Accept Hardcoded Values**: Don't tolerate non-portable hardcoded paths or flags
- **Skip Feature Detection**: Don't ignore proper compiler feature detection
- **Overlook Testing**: Don't accept incomplete or missing test configurations
- **Encourage Custom Solutions**: Don't suggest custom logic where Meson has built-in features
- **Reinvent the Wheel**: Don't encourage manual handling of what Meson provides automatically

## Meson-Specific Criticism Checklist

### Project Structure Assessment
- [ ] Does the project structure follow Meson conventions?
- [ ] Are build targets organized logically and consistently named?
- [ ] Is the build configuration modular and maintainable?
- [ ] Are subprojects used appropriately for external dependencies?
- [ ] Does the build structure scale well as the project grows?

### Dependency Management Assessment
- [ ] Are all dependencies properly declared using `dependency()`?
- [ ] Are subprojects configured correctly with appropriate fallbacks?
- [ ] Is dependency resolution consistent across different platforms?
- [ ] Are optional dependencies handled gracefully with proper fallbacks?
- [ ] Are build-time tools properly detected using `find_program()`?

### Build Configuration Assessment
- [ ] Does the build configuration work across different compilers?
- [ ] Are compiler features detected properly using `has_function()`?
- [ ] Is cross-compilation supported correctly?
- [ ] Are platform-specific behaviors handled appropriately?
- [ ] Are compiler flags applied consistently and safely?

### Built-in Features Assessment
- [ ] Are Meson's built-in optimization options used instead of custom compiler flags?
- [ ] Are Meson's built-in debug options used instead of manual debug flag handling?
- [ ] Are Meson's built-in warning options used instead of custom warning flags?
- [ ] Are Meson's built-in language features used appropriately?
- [ ] Are Meson's built-in installation features used instead of custom install logic?

### Target Configuration Assessment
- [ ] Are build targets declared with the correct type and parameters?
- [ ] Are include directories specified correctly for each target?
- [ ] Is the source file organization logical and maintainable?
- [ ] Are dependencies between targets properly declared?
- [ ] Are installation rules configured appropriately?

### Build Options Assessment
- [ ] Are build options properly declared with appropriate types?
- [ ] Are option names descriptive and consistent?
- [ ] Are default values sensible for most use cases?
- [ ] Is configuration data used appropriately for generated headers?
- [ ] Are options documented clearly for users?

### Testing Assessment
- [ ] Are tests properly declared and configured?
- [ ] Is the test environment set up correctly?
- [ ] Are test dependencies and fixtures handled appropriately?
- [ ] Is test data and resources managed properly?
- [ ] Are performance benchmarks configured correctly?

## Meson-Specific Evaluation Questions

### For Any Meson Project
1. **Does this build configuration follow Meson best practices and conventions?**
2. **Are all dependencies properly declared and resolved?**
3. **Is the build configuration portable across different platforms?**
4. **Are build options properly declared and documented?**
5. **Is the project structure logical and maintainable?**
6. **Are all build targets correctly configured?**
7. **Is cross-compilation supported properly?**
8. **Are tests properly configured and organized?**
9. **Are installation rules complete and correct?**
10. **Is the build system efficient and reliable?**
11. **Are Meson's built-in features used instead of custom solutions?**

### For Library Projects
1. **Are public headers properly installed?**
2. **Is the library API properly exposed?**
3. **Are version information and compatibility handled correctly?**
4. **Is the library properly linked with dependencies?**
5. **Are pkg-config files generated if needed?**

### For Application Projects
1. **Are all required dependencies properly declared?**
2. **Is the executable properly configured with dependencies?**
3. **Are resources and data files handled correctly?**
4. **Is the application properly packaged for distribution?**
5. **Are runtime dependencies properly managed?**

## Meson Build System Principles Applied

### "Simple and Fast"
- Build configurations should be simple to understand and maintain
- Build times should be optimized through proper dependency management
- Avoid unnecessary complexity in build logic
- Use Meson's built-in features to avoid custom complexity

### "Cross-Platform by Default"
- Build configurations should work across different platforms
- Use proper feature detection instead of platform assumptions
- Support cross-compilation from the beginning
- Let Meson handle platform differences through built-in options

### "Dependency Management First"
- Declare all dependencies explicitly using `dependency()`
- Use subprojects for external dependencies when appropriate
- Provide fallback mechanisms for optional dependencies
- Let Meson handle dependency resolution automatically

### "Declarative Over Imperative"
- Use Meson's declarative APIs instead of imperative build logic
- Let Meson handle dependency resolution and build ordering
- Focus on what to build, not how to build it
- Declare intent and let Meson handle the implementation

### "Consistent and Predictable"
- Follow consistent naming conventions throughout the project
- Use predictable build target organization
- Maintain consistent dependency handling patterns
- Use Meson's built-in options for consistent behavior

### "User-Friendly"
- Provide clear and descriptive build options
- Document build requirements and dependencies
- Make the build process transparent and debuggable
- Leverage Meson's built-in features for better user experience

### "Go with the Flow"
- Prefer Meson's built-in features over custom solutions
- Use Meson's "batteries included" approach
- Let Meson handle common build system tasks automatically
- Avoid reinventing functionality that Meson already provides

## Meson API Evaluation Criteria

### Project Configuration Functions
- **`project()`**: Proper project name, version, and language declarations
- **`option()`**: Appropriate option types, defaults, and documentation
- **`get_option()`**: Correct usage in build logic and conditional compilation

### Dependency Management Functions
- **`dependency()`**: Proper dependency declarations with version constraints
- **`find_program()`**: Correct tool detection with fallback mechanisms
- **`subproject()`**: Appropriate subproject configuration and options

### Build Target Functions
- **`executable()`**: Correct executable configuration with dependencies
- **`library()`**: Proper library configuration and linking
- **`static_library()`**: Appropriate static library configuration
- **`shared_library()`**: Correct shared library configuration

### Compiler and Platform Functions
- **`meson.get_compiler()`**: Proper compiler detection and feature testing
- **`has_function()`**: Correct function availability detection
- **`has_header()`**: Proper header file availability checking
- **`has_type()`**: Correct type availability detection

### Testing and Installation Functions
- **`test()`**: Proper test configuration with dependencies and environment
- **`benchmark()`**: Correct performance test configuration
- **`install_headers()`**: Appropriate header file installation
- **`install_data()`**: Correct data file installation

### Built-in Options and Features
- **`b_ndebug`**: Use for optimization instead of custom compiler flags
- **`b_lto`**: Use for link-time optimization instead of manual LTO flags
- **`b_sanitize`**: Use for sanitizer support instead of custom debug flags
- **`b_coverage`**: Use for coverage instead of manual coverage flags
- **`b_lundef`**: Use for undefined symbol handling instead of custom flags
- **`b_asneeded`**: Use for dependency linking instead of manual linking flags