Given the following API definition:
```cs
[Protocol]
public interface Protocol {
[Abstract]
[Export ("requiredMethod")]
void RequiredMethod ();
[Export ("optionalMethod")]
void OptionalMethod ();
}
```
we're now binding it like this:
```cs
[Protocol ("Protocol")]
public interface IProtocol : INativeObject {
[RequiredMember]
[Export ("requiredMethod")]
public void RequiredMethod () { /* default implementation */ }
[OptionalMember]
[Export ("optionalMethod")]
public void OptionalMethod () { /* default implementation */ }
}
```
The main difference from before is that the only difference between required
and optional members is the [RequiredMember]/[OptionalMember] attributes.
This has one major advantage: it's now possible to switch a member from being
required to being optional, or vice versa, without breaking neither source nor
binary compatibility.
It also improves intellisense for optional members. In the past optional
members were implemented using extension methods, which were not very
discoverable when you were supposed to implement a protocol in your own class.
The main downside is that the C# compiler won't enforce developers to
implement required protocol members (which is a necessary side effect of the
fact that we want to be able to switch members between being required and
optional without breaking compatibility). If this turns out to be a problem,
we can implement a custom source analyzer and/or linker step that detects
missing implementations and issue warnings/errors.
This PR also:
* Adds numerous tests.
* Updates the requiredness of a few members in Metal to test that it works as
expected.
* Adds documentation.
* Handles numerous corner cases, which are documented in code and docs.
This PR is probably best reviewed commit-by-commit.
Fixes https://github.com/xamarin/xamarin-macios/issues/13294.
Add support for binding constructors in protocols.
Given the api definition:
```cs
[Protocol]
public interface Protocol {
[Abstract]
[Export ("init")]
IntPtr Constructor ();
[Export ("initWithValue:")]
IntPtr Constructor (IntPtr value);
[BindAs ("Create")]
[Export ("initWithPlanet:")]
IntPtr Constructor ();
}
```
we're binding it like this:
```cs
[Protocol ("Protocol")]
public interface IProtocol : INativeObject {
[Export ("init")]
public static T CreateInstance<T> () where T: NSObject, IProtocol { /* default implementation */ }
[Export ("initWithValue:")]
public static T CreateInstance<T> () where T: NSObject, IProtocol { /* default implementation */ }
[Export ("initWithPlanet:")]
public static T Create<T> () where T: NSObject, IProtocol { /* default implementation */ }
}
```
Also add documentation and tests.
Fixes https://github.com/xamarin/xamarin-macios/issues/14039.
---------
Co-authored-by: Manuel de la Pena <mandel@microsoft.com>
Co-authored-by: Alex Soto <alex@soto.dev>
The enum value MethodAttributes.IsFamily is 'internal' in C#, which is not exposed
outside an assembly, so don't count such members as exposed. On the other hand, MethodAttributes.IsAssembly
is 'protected' in C#, which *is* exposed, so these members are included.
Update tests accordingly.
The generator needs a library name for the generated `_domain` field.
Here's an example for the generated `ARErrorCodeExtensions` class ("ARKit" is
the library name):
```cs
[Field ("ARErrorDomain", "ARKit")]
static NSString? _domain;
```
In order to find the library name, the generator would look at the first enum
field with a `[Field]` attribute, and get the `LibraryName` property from that
`[Field]` attribute. Unfortunately error enums don't necessarily have `[Field]`
attributes on their enum fields. This works fine for our own bindings, because
the generator will fall back to the enum's namespace, but for third-party
bindings this would be the result:
> error BI1042: bgen: Missing '[Field (LibraryName=value)]' for ErrorDomainNS.EWithDomain. (e.g."__Internal")
Note that the error message is rather confusing: it's trying to report a
missing `LibraryName` property for a `[Field]` attribute, but there's no `[Field]`
attribute anywhere in the enum in question.
So fix this by:
* Adding the `LibraryName` property on the `[ErrorDomain]` attribute.
* Implement support for looking at this new property in the generator.
* Report a better error if it's not there.
* Enable generation of the documentation file (.xml) by the C# compiler when building projects (by passing the `DocumentationFlag` argument to the Csc task).
* Also disable the CSC1591 warning, which complains about having public APIs without xml documentation; it just turns out to be annoying rather than helpful, since most APIs won't be documented.
* Add support in the generator for reading the .xml file next to the compiled api definition assembly, and then looking for documentation there when generating binding code.
* When enabled, enable generation of the documentation file if the generator is compiling the api definitions.
* Make it an opt-out, in case the new code causes problems.
* Add tests.
Fixes https://github.com/xamarin/xamarin-macios/issues/17397.
---------
Co-authored-by: Haritha Mohan <harithamohan@microsoft.com>
The generator needs these attributes in certain cases when a third-party library implements a protocol that subclasses a platform protocol where members of the platform protocol has members with parameters with these attributes.
That's a rather long sentence: in fact there are fewer words in the test verifying this behavior!
Remove support for the Protocolize attribute from the generator, and remove
all usages of it in our api definitions - just use the protocol interface.
The Protocolize attribute was used to support binding stuff using the Model
class with Classic Xamarin code + and binding stuff using the protocol
interface with Unified Xamarin code, using the same source code.
Classic Xamarin has been dead for quite a few years ago now though, so there's
no need to keep his code around anymore, we can just upgrade the api
definitions to use the protocol interface directly.
Fixes https://github.com/xamarin/xamarin-macios/issues/14585.
---------
Co-authored-by: Alex Soto <alex@soto.dev>
This fixes a regression in .NET 8, where we changed the temporary assembly name when
building using a project file / MSBuild - we started compiling the temporary binding
code in MSBuild instead of in the generator, and in the process we changed the name
of the temporary assembly. This broke logic in bgen that compared the assembly name
to check if a given type is from the temporary assembly or not.
Fix this by checking the actual temporary assembly instead of the name of the assembly
instead.
Fixes https://github.com/xamarin/xamarin-macios/issues/19612.
Remove the need to pass the BT. More importantly fix an issue with the
errors when more than one attribute was expected. The eng that wrote the
code did not consider translations, and therefore the current errors
seen by a non-english speaker will result in part of the error in her
native language and the rest in english. On top of that, in english the
error is broken with words repited or broken sentences.
---------
Co-authored-by: GitHub Actions Autoformatter <github-actions-autoformatter@xamarin.com>
First take at refactoring parts of the Generator:
1. RemoveArity() is now a string extension method with a test
2. FormatType, FormatTypeUsedIn, and part of PrimitiveType methods have
been moved into the TypeManager class.
3. TypeManager now has access to BindingTouch (similar to the other
Manager classes) so that it may call methods from NamespaceManager,
which also had to be made into a public property of BindingTouch vs
being passed through the Generator constructor.
---------
Co-authored-by: Manuel de la Pena <mandel@microsoft.com>
Co-authored-by: GitHub Actions Autoformatter <github-actions-autoformatter@xamarin.com>
Co-authored-by: Alex Soto <alex@alexsoto.me>
This means:
* Change all bool and char arguments in P/Invokes to be byte and ushort, respectively.
* Change all out/ref arguments to be pointers instead.
* Update managed binding code accordingly.
* Update a struct (GKTriangle) to not use a MarshalAs field, but instead only use blittable fields.
* Update tests accordingly.
One side effect is that legacy binding projects may need a reference to
the `System.Runtime.CompilerServices.Unsafe` NuGet now (this is a
built-in dependency in .NET) in order to compile successfully.
Fixes https://github.com/xamarin/xamarin-macios/issues/18685.
We'll soon change the generator to execute locally on Windows, even for
remote builds. As a stepping stone towards that goal, this PR adds the
generator tests to the list of tests we run on Windows.
Change all null checking expressions to use 'is null' and 'is not null'
instead of '== null' and '!= null'.
This was mostly done with sed, so code can probably be improved in many
other ways with manual inspection, but that will come over time.
Also add code to the autoformat script to automatically fix these issues in the future.
I started fixing nullability in one place, and then it snowballed a bit
and I had to fix nullability in a lot of places.
Most are trivial, except for the `generate-frameworks-constants`
project: I had to create a .NET version of the project in order to
compile a .NET version of the tool.
Also fix a nullability warning.
Fixes these warnings:
"tests/generator/generator-tests.csproj" (default target) (1:7) ->
(CoreCompile target) ->
tests/generator/AttributeFactoryTests.cs(43,29): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/AttributeFactoryTests.cs(44,29): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/AttributeFactoryTests.cs(45,29): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/ConstructorArgumentsTests.cs(17,19): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/ConstructorArgumentsTests.cs(34,19): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/AttributeFactoryTests.cs(53,39): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/AttributeFactoryTests.cs(54,39): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/AttributeFactoryTests.cs(55,39): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/AttributeFactoryTests.cs(56,39): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/AttributeFactoryTests.cs(64,34): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/AttributeFactoryTests.cs(69,11): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/AttributeFactoryTests.cs(76,34): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/ConstructorArgumentsTests.cs(55,19): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/AttributeFactoryTests.cs(83,34): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/ConstructorArgumentsTests.cs(78,19): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/AttributeFactoryTests.cs(111,16): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/AttributeFactoryTests.cs(138,16): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/ConstructorArgumentsTests.cs(95,19): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/AttributeFactoryTests.cs(178,16): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.
tests/generator/ConstructorArgumentsTests.cs(116,19): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.]
tests/generator/ConstructorArgumentsTests.cs(194,18): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.]
tests/generator/ConstructorArgumentsTests.cs(210,18): warning CS0436: The type 'AttributeFactory' in 'tests/generator/../../src/bgen/AttributeFactory.cs' conflicts with the imported type 'AttributeFactory' in 'bgen, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null'. Using the type defined in 'tests/generator/../../src/bgen/AttributeFactory.cs'.]
tests/generator/ConstructorArgumentsTests.cs(197,44): warning CS8602: Dereference of a possibly null reference.
tests/generator/ConstructorArgumentsTests.cs(201,43): warning CS8602: Dereference of a possibly null reference.
Rolf Bjarne Kvinge
Manuel de la Pena
dustin-wojciechowski