Instructions for AIs

# Instructions for AIs

This repository contains .NET for iOS, Mac Catalyst, macOS, and tvOS.

This is the main branch targeting .NET 9.

## Comment Handling

Ignore comments from the user 'vs-mobiletools-engineering-service2' when processing issues and pull requests.

## Repository Overview

This repository provides C# bindings and tooling for Apple platforms:
- **.NET for iOS**: iPhone and iPad applications
- **.NET for macOS**: Native Mac applications  
- **.NET for tvOS**: Apple TV applications
- **.NET for Mac Catalyst**: iOS apps running on macOS

### Key Directories

- `src/` - Apple API bindings (Foundation, UIKit, AppKit, etc.)
- `tools/` - Development tools (mtouch, mmp, linker, bgen)
- `tests/` - Test suites (unit, introspection, extrospection)
- `msbuild/` - MSBuild tasks and targets
- `docs/` - Documentation and guides
- `runtime/` - Runtime components and native code

## Build System

This project uses a Make-based build system. Key commands:

- `make all` and `make install` - Both required to get a complete build
- `make world` - Reset, build, and install everything  
- `make check-system` - Verify system dependencies
- `make show-versions` - Display version information

### Platform-Specific Building

The build system supports multiple platforms simultaneously:
- iOS: iPhone and iPad (device and simulator)
- macOS: Native Mac applications
- tvOS: Apple TV applications  
- Mac Catalyst: iOS apps adapted for macOS

The `configure` script is used to select which platforms to build. This script must be run before `make`.

## Binding System

### bgen (Binding Generator)

The `src/bgen/` tool generates C# bindings from Objective-C APIs:
- Processes binding definition files (`*.cs`) with binding attributes
- Generates P/Invoke declarations and managed wrappers
- Handles memory management and type marshaling

### Common Binding Patterns

```csharp
// Platform availability attributes
[NoTV, NoMac, iOS (14, 0)]
[Native]
public enum SomeEnum : long {
    Value1 = 0,
    Value2,
}

// Basic class binding
[BaseType (typeof (NSObject))]
interface SomeClass {
    [Export ("someMethod:")]
    void SomeMethod (string parameter);
    
    [Export ("someProperty")]
    string SomeProperty { get; set; }
}
```

### Platform Attributes

Use these attributes to specify platform availability:
- `[iOS (version)]` - Available on iOS from specified version
- `[Mac (version)]` - Available on macOS from specified version
- `[TV (version)]` - Available on tvOS from specified version
- `[MacCatalyst (version)]` - Available on Mac Catalyst from specified version
- `[NoiOS]`, `[NoMac]`, `[NoTV]`, `[NoMacCatalyst]` - Not available on specified platforms

## Testing Strategy

### Test Types

1. **Unit Tests**: NUnit-based regression tests for specific functionality
2. **Introspection Tests**: Runtime validation comparing managed and native APIs
3. **Extrospection Tests**: Validation against external sources (headers, rules)

### Test Execution

- Tests run on simulators and physical devices
- Different linking modes: "Don't link", "Link SDK only", "Link all"
- Platform-specific test projects generated by xharness tool

### Running Tests

It's typically `make run-tests` in the directory with the test project.

## Apple Platform Integration

### Xcode Requirements

- Latest Xcode version typically required for latest platform features
- Xcode Command Line Tools must be installed
- Multiple Xcode versions may be needed for different platform support

### Framework Dependencies

Apple frameworks are referenced using:
```csharp
[BaseType (typeof (NSObject))]
interface SomeClass {
    // Framework linking handled automatically via binding definitions
}
```

### Memory Management

- Proper `[Export]` declarations for Objective-C methods
- `using` statements for `IDisposable` resources

## MSBuild Integration

### Custom MSBuild Tasks

Located in `msbuild/` directory:
- `Xamarin.MacDev.Tasks` - Shared Apple development tasks

### Project Templates

Common project structure for Apple platform apps:
```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net9.0-ios</TargetFramework>
    <!-- Platform-specific properties -->
  </PropertyGroup>
</Project>
```

## Development Workflow

### Making Changes

1. Modify bindings in `src/` directory
2. Run `make` to rebuild affected components
3. Test changes using appropriate test suite
4. Verify on both simulator and device when possible

### Code Style

- Follow existing patterns in binding definitions
- Use consistent naming conventions matching Apple's APIs
- Add appropriate platform availability attributes
- Use the code style as defined in .editorconfig

## Nullable Reference Types

When opting C# code into nullable reference types:

Only make the following changes when asked to do so.

* Add `#nullable enable` at the top of the file.

* Don't *ever* use `!` to handle `null`!

* Declare variables non-nullable, and check for `null` at entry points.

* Use `throw new ArgumentNullException (nameof (parameter))` in `netstandard2.0` projects.

* Use `ArgumentNullException.ThrowIfNull (parameter)` in iOS projects that will be .NET 9+.

* `[Required]` properties in MSBuild task classes should always be non-nullable with a default value.

* Non-`[Required]` properties should be nullable and have null-checks in C# code using them.

* For MSBuild task properties like:

```csharp
public string NonRequiredProperty { get; set; }
public ITaskItem [] NonRequiredItemGroup { get; set; }

[Output]
public string OutputProperty { get; set; }
[Output]
public ITaskItem [] OutputItemGroup { get; set; }

[Required]
public string RequiredProperty { get; set; }
[Required]
public ITaskItem [] RequiredItemGroup { get; set; }
```

Fix them such as:

```csharp
public string? NonRequiredProperty { get; set; }
public ITaskItem []? NonRequiredItemGroup { get; set; }

[Output]
public string? OutputProperty { get; set; }
[Output]
public ITaskItem []? OutputItemGroup { get; set; }

[Required]
public string RequiredProperty { get; set; } = "";
[Required]
public ITaskItem [] RequiredItemGroup { get; set; } = [];
```

If you see a `string.IsNullOrEmpty()` check, don't change it.

## Common Objective-C to C# Patterns

### Method Binding

```csharp
// Objective-C: - (void)setTitle:(NSString *)title forState:(UIControlState)state;
[Export ("setTitle:forState:")]
void SetTitle ([NullAllowed] string title, UIControlState state);

// Objective-C: - (NSString *)titleForState:(UIControlState)state;
[Export ("titleForState:")]
[return: NullAllowed]
string GetTitle (UIControlState state);
```

### Property Binding

```csharp
// Objective-C: @property (nonatomic, copy) NSString *title;
[Export ("title")]
string Title { get; set; }

// Objective-C: @property (nonatomic, readonly) BOOL isEnabled;
[Export ("isEnabled")]
bool IsEnabled { get; }
```

### Delegate/Protocol Binding

```csharp
[BaseType (typeof (NSObject))]
[Model]
[Protocol]
interface SomeDelegate {
    [Export ("someMethod:")]
    void SomeMethod (SomeClass sender);
}
```

### Error Handling

```csharp
// Methods that take NSError**
[Export ("doSomething:")]
bool DoSomething (out NSError error);

// Async methods
[Export ("doSomethingWithCompletion:")]
[Async]
void DoSomething (Action<bool, NSError> completion);
```

## Release and Versioning

### Branch Strategy

- `main` - .NET 9 development
- `net10.0` - .NET 10 development  
- `net11.0` - .NET 11 development
- `release/` branches for specific releases
- Platform-specific branches for Xcode updates

### Version Management

- NuGet versions managed in `Make.versions`
- Platform API versions track Apple SDK versions
- Commit distance used for pre-release versioning

## Troubleshooting

### Common Issues

1. **Build Failures**: Check `make check-system` for missing dependencies
2. **Binding Errors**: Review bgen output for binding definition issues  
3. **Runtime Errors**: Use introspection tests to validate binding correctness
4. **Linking Issues**: Test with different linker modes

### Debugging

- Use simulator for initial testing
- Physical device testing for platform-specific features
- Enable verbose logging with `V=1 make` for detailed build output

## Formatting

C# code uses tabs (not spaces) and the Mono code-formatting style defined in `.editorconfig`

* Your mission is to make diffs as absolutely as small as possible, preserving existing code formatting.

* If you encounter additional spaces or formatting within existing code blocks, LEAVE THEM AS-IS.

* If you encounter code comments, LEAVE THEM AS-IS.

* Place a space prior to any parentheses `(` or `[`

* Use `""` for empty string and *not* `string.Empty`

* Use `[]` for empty arrays and *not* `Array.Empty<T>()`

Examples of properly formatted code:

```csharp
Foo ();
Bar (1, 2, "test");
myarray [0] = 1;

if (someValue) {
    // Code here
}

try {
    // Code here
} catch (Exception e) {
    // Code here
}
```