Annotating C APIs without changing the original header files

Using Swift
1

Hi everyone,

I’m about to start on another big project with Swift on Android and would like to annotate that JNI headers as much as possible before I do: specifically I’d like to make _Nonnull and CF_SWIFT_NAME annotations to the headers found in a user's jni.h.

The question is: is it possible to annotate headers this without changing the original header files? Specifically I’m looking for an options that allows annotations in a separate file, probably one that is read when loading the package’s module.modulemap.

I’d like to distribute the annotations in a SwiftPM package that also exposes the original (hopefully annotated) headers. Up until now I’ve been using Swift to override methods in code, but this isn’t as clean or extensible and I fear it may have other (particularly performance) implications.

I guess the alternative would be to just maintain and distribute a modified version of jni.h with the annotations, but that would be a "last resort” option.

Thanks in advance,
Geordie

2 Likes
2

This is the role of API notes, which you can see here:

  https://github.com/apple/swift/tree/master/apinotes

with some rough documentation-in-source here:

  https://github.com/apple/swift-clang/blob/stable/lib/APINotes/APINotesYAMLCompiler.cpp

  - Doug

···

On May 3, 2017, at 4:10 PM, Geordie J via swift-users <swift-users@swift.org> wrote:

Hi everyone,

I’m about to start on another big project with Swift on Android and would like to annotate that JNI headers as much as possible before I do: specifically I’d like to make _Nonnull and CF_SWIFT_NAME annotations to the headers found in a user's jni.h.

The question is: is it possible to annotate headers this without changing the original header files? Specifically I’m looking for an options that allows annotations in a separate file, probably one that is read when loading the package’s module.modulemap.

I’d like to distribute the annotations in a SwiftPM package that also exposes the original (hopefully annotated) headers. Up until now I’ve been using Swift to override methods in code, but this isn’t as clean or extensible and I fear it may have other (particularly performance) implications.

I guess the alternative would be to just maintain and distribute a modified version of jni.h with the annotations, but that would be a "last resort” option.

1 Like
3

Great, thanks for reminding me of this feature. I couldn't see how it could
be used outside of the stdlib though, is it possible to use apinotes when
simply linking a C module via its modulemap ?

···

Douglas Gregor <dgregor@apple.com> schrieb am Fr. 5. Mai 2017 um 01:55: > > On May 3, 2017, at 4:10 PM, Geordie J via swift-users < > swift-users@swift.org> wrote:

Hi everyone,

I’m about to start on another big project with Swift on Android and would
like to annotate that JNI headers as much as possible before I do:
specifically I’d like to make _Nonnull and CF_SWIFT_NAME annotations to the
headers found in a user's jni.h.

The question is: is it possible to annotate headers this without changing
the original header files? Specifically I’m looking for an options that
allows annotations in a separate file, probably one that is read when
loading the package’s module.modulemap.

I’d like to distribute the annotations in a SwiftPM package that also
exposes the original (hopefully annotated) headers. Up until now I’ve been
using Swift to override methods in code, but this isn’t as clean or
extensible and I fear it may have other (particularly performance)
implications.

I guess the alternative would be to just maintain and distribute a
modified version of jni.h with the annotations, but that would be a "last
resort” option.

This is the role of API notes, which you can see here:

https://github.com/apple/swift/tree/master/apinotes

with some rough documentation-in-source here:

https://github.com/apple/swift-clang/blob/stable/lib/APINotes/APINotesYAMLCompiler.cpp

- Doug

4

I'm trying to use apinotes for this third-party C library (call it "Lib.dylib"). It has an enum lgs_error_t:

typedef enum {
    lgs_error_none = 0,
    lgs_error_invalid_handle = -1,
    lgs_error_null = -2,
    lgs_error_invalid_parameter = -3,
    lgs_error_invalid_operation = -4,
    lgs_error_queue_full = -5
} lgs_error_t;

So I wrote apinotes ("Lib.apinotes") that look like this, next to the .dylib, and part of my Xcode iOS app target:

Enumerators:
# lgs_error_t

- Name: lgs_error_none
  SwiftName: lgs_error_t.none
- Name: lgs_error_invalid_handle
  SwiftName: lgs_error_t.invalidHandle
- Name: lgs_error_null
  SwiftName: lgs_error_t.nullParameter
- Name: lgs_error_invalid_parameter
  SwiftName: lgs_error_t.invalideParameter
- Name: lgs_error_invalid_operation
  SwiftName: lgs_error_t.invalidOperation
- Name: lgs_error_queue_full
  SwiftName: lgs_error_t.queueFull

But this line of code fails:

var err: lgs_error_t = .nullParameter
Type 'lgs_error_t' has no member 'nullParameter'

Am I missing something else?

···

On May 4, 2017, at 16:55 , Douglas Gregor via swift-users <swift-users@swift.org> wrote:

On May 3, 2017, at 4:10 PM, Geordie J via swift-users <swift-users@swift.org> wrote:

Hi everyone,

I’m about to start on another big project with Swift on Android and would like to annotate that JNI headers as much as possible before I do: specifically I’d like to make _Nonnull and CF_SWIFT_NAME annotations to the headers found in a user's jni.h.

The question is: is it possible to annotate headers this without changing the original header files? Specifically I’m looking for an options that allows annotations in a separate file, probably one that is read when loading the package’s module.modulemap.

I’d like to distribute the annotations in a SwiftPM package that also exposes the original (hopefully annotated) headers. Up until now I’ve been using Swift to override methods in code, but this isn’t as clean or extensible and I fear it may have other (particularly performance) implications.

I guess the alternative would be to just maintain and distribute a modified version of jni.h with the annotations, but that would be a "last resort” option.

This is the role of API notes, which you can see here:

  https://github.com/apple/swift/tree/master/apinotes

with some rough documentation-in-source here:

  https://github.com/apple/swift-clang/blob/stable/lib/APINotes/APINotesYAMLCompiler.cpp

  - Doug

_______________________________________________
swift-users mailing list
swift-users@swift.org
https://lists.swift.org/mailman/listinfo/swift-users

--
Rick Mann
rmann@latencyzero.com

5

Great, thanks for reminding me of this feature. I couldn't see how it could be used outside of the stdlib though, is it possible to use apinotes when simply linking a C module via its modulemap ?

You can put

  <modulename>.apinotes

into the same directory as the module map.

  - Doug

···

On May 4, 2017, at 4:57 PM, Geordie Jay <geojay@gmail.com> wrote:

Douglas Gregor <dgregor@apple.com <mailto:dgregor@apple.com>> schrieb am Fr. 5. Mai 2017 um 01:55: > >> On May 3, 2017, at 4:10 PM, Geordie J via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:

Hi everyone,

I’m about to start on another big project with Swift on Android and would like to annotate that JNI headers as much as possible before I do: specifically I’d like to make _Nonnull and CF_SWIFT_NAME annotations to the headers found in a user's jni.h.

The question is: is it possible to annotate headers this without changing the original header files? Specifically I’m looking for an options that allows annotations in a separate file, probably one that is read when loading the package’s module.modulemap.

I’d like to distribute the annotations in a SwiftPM package that also exposes the original (hopefully annotated) headers. Up until now I’ve been using Swift to override methods in code, but this isn’t as clean or extensible and I fear it may have other (particularly performance) implications.

I guess the alternative would be to just maintain and distribute a modified version of jni.h with the annotations, but that would be a "last resort” option.

This is the role of API notes, which you can see here:

  https://github.com/apple/swift/tree/master/apinotes

with some rough documentation-in-source here:

  https://github.com/apple/swift-clang/blob/stable/lib/APINotes/APINotesYAMLCompiler.cpp

  - Doug

6

Fantastic! Thanks for the info, this is great news.

While I have you, I'm interested in annotating function pointers.
Specifically, the JNI environment instance is a pointer to a pointer, so as
is you have to type env.pointee.pointee.FunctionName(env, param1, param2)

Ideally this would just look like env.FunctionName(param1, param2). It's a
long shot but is this goal at all reasonable via annotations alone?

Cheers,
Geordie

···

Douglas Gregor <dgregor@apple.com> schrieb am Fr. 5. Mai 2017 um 01:59: > On May 4, 2017, at 4:57 PM, Geordie Jay <geojay@gmail.com> wrote:

Great, thanks for reminding me of this feature. I couldn't see how it
could be used outside of the stdlib though, is it possible to use apinotes
when simply linking a C module via its modulemap ?

You can put

<modulename>.apinotes

into the same directory as the module map.

- Doug

Douglas Gregor <dgregor@apple.com> schrieb am Fr. 5. Mai 2017 um 01:55: > >> >> On May 3, 2017, at 4:10 PM, Geordie J via swift-users < >> swift-users@swift.org> wrote:

Hi everyone,

I’m about to start on another big project with Swift on Android and would
like to annotate that JNI headers as much as possible before I do:
specifically I’d like to make _Nonnull and CF_SWIFT_NAME annotations to the
headers found in a user's jni.h.

The question is: is it possible to annotate headers this without changing
the original header files? Specifically I’m looking for an options that
allows annotations in a separate file, probably one that is read when
loading the package’s module.modulemap.

I’d like to distribute the annotations in a SwiftPM package that also
exposes the original (hopefully annotated) headers. Up until now I’ve been
using Swift to override methods in code, but this isn’t as clean or
extensible and I fear it may have other (particularly performance)
implications.

I guess the alternative would be to just maintain and distribute a
modified version of jni.h with the annotations, but that would be a "last
resort” option.

This is the role of API notes, which you can see here:

https://github.com/apple/swift/tree/master/apinotes

with some rough documentation-in-source here:

https://github.com/apple/swift-clang/blob/stable/lib/APINotes/APINotesYAMLCompiler.cpp

- Doug

7

I'm having the same issue. The renames seem to work, as in they disappear
from the global scope with a fixit to rename to the new (namespaced)
version if I type in the name manually, but they don't appear as static
members of the enum type, regardless of how I call them. Would appreciate
some help with this too.

Cheers,
Geordie

···

Rick Mann <rmann@latencyzero.com> schrieb am So. 7. Mai 2017 um 23:06: > I'm trying to use apinotes for this third-party C library (call it > "Lib.dylib"). It has an enum lgs_error_t:

typedef enum {
    lgs_error_none = 0,
    lgs_error_invalid_handle = -1,
    lgs_error_null = -2,
    lgs_error_invalid_parameter = -3,
    lgs_error_invalid_operation = -4,
    lgs_error_queue_full = -5
} lgs_error_t;

So I wrote apinotes ("Lib.apinotes") that look like this, next to the
.dylib, and part of my Xcode iOS app target:

Enumerators:
# lgs_error_t

- Name: lgs_error_none
  SwiftName: lgs_error_t.none
- Name: lgs_error_invalid_handle
  SwiftName: lgs_error_t.invalidHandle
- Name: lgs_error_null
  SwiftName: lgs_error_t.nullParameter
- Name: lgs_error_invalid_parameter
  SwiftName: lgs_error_t.invalideParameter
- Name: lgs_error_invalid_operation
  SwiftName: lgs_error_t.invalidOperation
- Name: lgs_error_queue_full
  SwiftName: lgs_error_t.queueFull

But this line of code fails:

var err: lgs_error_t = .nullParameter
Type 'lgs_error_t' has no member 'nullParameter'

Am I missing something else?

> On May 4, 2017, at 16:55 , Douglas Gregor via swift-users < > swift-users@swift.org> wrote:
>
>
>> On May 3, 2017, at 4:10 PM, Geordie J via swift-users < > swift-users@swift.org> wrote:
>>
>> Hi everyone,
>>
>> I’m about to start on another big project with Swift on Android and
would like to annotate that JNI headers as much as possible before I do:
specifically I’d like to make _Nonnull and CF_SWIFT_NAME annotations to the
headers found in a user's jni.h.
>>
>> The question is: is it possible to annotate headers this without
changing the original header files? Specifically I’m looking for an options
that allows annotations in a separate file, probably one that is read when
loading the package’s module.modulemap.
>>
>> I’d like to distribute the annotations in a SwiftPM package that also
exposes the original (hopefully annotated) headers. Up until now I’ve been
using Swift to override methods in code, but this isn’t as clean or
extensible and I fear it may have other (particularly performance)
implications.
>>
>> I guess the alternative would be to just maintain and distribute a
modified version of jni.h with the annotations, but that would be a "last
resort” option.
>
>
> This is the role of API notes, which you can see here:
>
> https://github.com/apple/swift/tree/master/apinotes
>
> with some rough documentation-in-source here:
>
>
https://github.com/apple/swift-clang/blob/stable/lib/APINotes/APINotesYAMLCompiler.cpp
>
> - Doug
>
> _______________________________________________
> swift-users mailing list
> swift-users@swift.org
> https://lists.swift.org/mailman/listinfo/swift-users

--
Rick Mann
rmann@latencyzero.com

8

To continue this thread: I managed to annotate a bunch of C APIs with modulename.apinotes. This works with Xcode (to a certain degree - pointers, enums, and especially OpaquePointers are tricky). I’m now trying to build my package with SwiftPM and it doesn’t seem to recognise the apinotes file.

@Doug Gregor, would you be able to advise as to whether apinotes works with SwiftPM (on Linux) and whether it requires some extra settings that I may be unaware of?

Thanks and best regards for the weekend,
Geordie

···

Am 08.05.2017 um 00:51 schrieb Geordie Jay <geojay@gmail.com>:

I'm having the same issue. The renames seem to work, as in they disappear from the global scope with a fixit to rename to the new (namespaced) version if I type in the name manually, but they don't appear as static members of the enum type, regardless of how I call them. Would appreciate some help with this too.

Cheers,
Geordie
Rick Mann <rmann@latencyzero.com <mailto:rmann@latencyzero.com>> schrieb am So. 7. Mai 2017 um 23:06: > I'm trying to use apinotes for this third-party C library (call it "Lib.dylib"). It has an enum lgs_error_t:

typedef enum {
    lgs_error_none = 0,
    lgs_error_invalid_handle = -1,
    lgs_error_null = -2,
    lgs_error_invalid_parameter = -3,
    lgs_error_invalid_operation = -4,
    lgs_error_queue_full = -5
} lgs_error_t;

So I wrote apinotes ("Lib.apinotes") that look like this, next to the .dylib, and part of my Xcode iOS app target:

Enumerators:
# lgs_error_t

- Name: lgs_error_none
  SwiftName: lgs_error_t.none
- Name: lgs_error_invalid_handle
  SwiftName: lgs_error_t.invalidHandle
- Name: lgs_error_null
  SwiftName: lgs_error_t.nullParameter
- Name: lgs_error_invalid_parameter
  SwiftName: lgs_error_t.invalideParameter
- Name: lgs_error_invalid_operation
  SwiftName: lgs_error_t.invalidOperation
- Name: lgs_error_queue_full
  SwiftName: lgs_error_t.queueFull

But this line of code fails:

var err: lgs_error_t = .nullParameter
Type 'lgs_error_t' has no member 'nullParameter'

Am I missing something else?

> On May 4, 2017, at 16:55 , Douglas Gregor via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:
>
>
>> On May 3, 2017, at 4:10 PM, Geordie J via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:
>>
>> Hi everyone,
>>
>> I’m about to start on another big project with Swift on Android and would like to annotate that JNI headers as much as possible before I do: specifically I’d like to make _Nonnull and CF_SWIFT_NAME annotations to the headers found in a user's jni.h.
>>
>> The question is: is it possible to annotate headers this without changing the original header files? Specifically I’m looking for an options that allows annotations in a separate file, probably one that is read when loading the package’s module.modulemap.
>>
>> I’d like to distribute the annotations in a SwiftPM package that also exposes the original (hopefully annotated) headers. Up until now I’ve been using Swift to override methods in code, but this isn’t as clean or extensible and I fear it may have other (particularly performance) implications.
>>
>> I guess the alternative would be to just maintain and distribute a modified version of jni.h with the annotations, but that would be a "last resort” option.
>
>
> This is the role of API notes, which you can see here:
>
> https://github.com/apple/swift/tree/master/apinotes
>
> with some rough documentation-in-source here:
>
> https://github.com/apple/swift-clang/blob/stable/lib/APINotes/APINotesYAMLCompiler.cpp
>
> - Doug
>
> _______________________________________________
> swift-users mailing list
> swift-users@swift.org <mailto:swift-users@swift.org>
> https://lists.swift.org/mailman/listinfo/swift-users

--
Rick Mann
rmann@latencyzero.com <mailto:rmann@latencyzero.com>

9

+Ankit

Michael

···

On May 12, 2017, at 10:10 AM, Geordie J via swift-users <swift-users@swift.org> wrote:

To continue this thread: I managed to annotate a bunch of C APIs with modulename.apinotes. This works with Xcode (to a certain degree - pointers, enums, and especially OpaquePointers are tricky). I’m now trying to build my package with SwiftPM and it doesn’t seem to recognise the apinotes file.

@Doug Gregor, would you be able to advise as to whether apinotes works with SwiftPM (on Linux) and whether it requires some extra settings that I may be unaware of?

Thanks and best regards for the weekend,
Geordie

Am 08.05.2017 um 00:51 schrieb Geordie Jay <geojay@gmail.com <mailto:geojay@gmail.com>>:

I'm having the same issue. The renames seem to work, as in they disappear from the global scope with a fixit to rename to the new (namespaced) version if I type in the name manually, but they don't appear as static members of the enum type, regardless of how I call them. Would appreciate some help with this too.

Cheers,
Geordie
Rick Mann <rmann@latencyzero.com <mailto:rmann@latencyzero.com>> schrieb am So. 7. Mai 2017 um 23:06: >> I'm trying to use apinotes for this third-party C library (call it "Lib.dylib"). It has an enum lgs_error_t:

typedef enum {
    lgs_error_none = 0,
    lgs_error_invalid_handle = -1,
    lgs_error_null = -2,
    lgs_error_invalid_parameter = -3,
    lgs_error_invalid_operation = -4,
    lgs_error_queue_full = -5
} lgs_error_t;

So I wrote apinotes ("Lib.apinotes") that look like this, next to the .dylib, and part of my Xcode iOS app target:

Enumerators:
# lgs_error_t

- Name: lgs_error_none
  SwiftName: lgs_error_t.none
- Name: lgs_error_invalid_handle
  SwiftName: lgs_error_t.invalidHandle
- Name: lgs_error_null
  SwiftName: lgs_error_t.nullParameter
- Name: lgs_error_invalid_parameter
  SwiftName: lgs_error_t.invalideParameter
- Name: lgs_error_invalid_operation
  SwiftName: lgs_error_t.invalidOperation
- Name: lgs_error_queue_full
  SwiftName: lgs_error_t.queueFull

But this line of code fails:

var err: lgs_error_t = .nullParameter
Type 'lgs_error_t' has no member 'nullParameter'

Am I missing something else?

> On May 4, 2017, at 16:55 , Douglas Gregor via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:
>
>
>> On May 3, 2017, at 4:10 PM, Geordie J via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:
>>
>> Hi everyone,
>>
>> I’m about to start on another big project with Swift on Android and would like to annotate that JNI headers as much as possible before I do: specifically I’d like to make _Nonnull and CF_SWIFT_NAME annotations to the headers found in a user's jni.h.
>>
>> The question is: is it possible to annotate headers this without changing the original header files? Specifically I’m looking for an options that allows annotations in a separate file, probably one that is read when loading the package’s module.modulemap.
>>
>> I’d like to distribute the annotations in a SwiftPM package that also exposes the original (hopefully annotated) headers. Up until now I’ve been using Swift to override methods in code, but this isn’t as clean or extensible and I fear it may have other (particularly performance) implications.
>>
>> I guess the alternative would be to just maintain and distribute a modified version of jni.h with the annotations, but that would be a "last resort” option.
>
>
> This is the role of API notes, which you can see here:
>
> https://github.com/apple/swift/tree/master/apinotes
>
> with some rough documentation-in-source here:
>
> https://github.com/apple/swift-clang/blob/stable/lib/APINotes/APINotesYAMLCompiler.cpp
>
> - Doug
>
> _______________________________________________
> swift-users mailing list
> swift-users@swift.org <mailto:swift-users@swift.org>
> https://lists.swift.org/mailman/listinfo/swift-users

--
Rick Mann
rmann@latencyzero.com <mailto:rmann@latencyzero.com>

_______________________________________________
swift-users mailing list
swift-users@swift.org
https://lists.swift.org/mailman/listinfo/swift-users

10

We don't have explicit support for api notes in SwiftPM.

We discussed it, and it something which probably makes sense, but no one has worked on a design or implementation yet.

- Daniel

···

On May 12, 2017, at 11:32 AM, Michael Gottesman via swift-users <swift-users@swift.org> wrote:

+Ankit

Michael

On May 12, 2017, at 10:10 AM, Geordie J via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:

To continue this thread: I managed to annotate a bunch of C APIs with modulename.apinotes. This works with Xcode (to a certain degree - pointers, enums, and especially OpaquePointers are tricky). I’m now trying to build my package with SwiftPM and it doesn’t seem to recognise the apinotes file.

@Doug Gregor, would you be able to advise as to whether apinotes works with SwiftPM (on Linux) and whether it requires some extra settings that I may be unaware of?

Thanks and best regards for the weekend,
Geordie

Am 08.05.2017 um 00:51 schrieb Geordie Jay <geojay@gmail.com <mailto:geojay@gmail.com>>:

I'm having the same issue. The renames seem to work, as in they disappear from the global scope with a fixit to rename to the new (namespaced) version if I type in the name manually, but they don't appear as static members of the enum type, regardless of how I call them. Would appreciate some help with this too.

Cheers,
Geordie
Rick Mann <rmann@latencyzero.com <mailto:rmann@latencyzero.com>> schrieb am So. 7. Mai 2017 um 23:06: >>> I'm trying to use apinotes for this third-party C library (call it "Lib.dylib"). It has an enum lgs_error_t:

typedef enum {
    lgs_error_none = 0,
    lgs_error_invalid_handle = -1,
    lgs_error_null = -2,
    lgs_error_invalid_parameter = -3,
    lgs_error_invalid_operation = -4,
    lgs_error_queue_full = -5
} lgs_error_t;

So I wrote apinotes ("Lib.apinotes") that look like this, next to the .dylib, and part of my Xcode iOS app target:

Enumerators:
# lgs_error_t

- Name: lgs_error_none
  SwiftName: lgs_error_t.none
- Name: lgs_error_invalid_handle
  SwiftName: lgs_error_t.invalidHandle
- Name: lgs_error_null
  SwiftName: lgs_error_t.nullParameter
- Name: lgs_error_invalid_parameter
  SwiftName: lgs_error_t.invalideParameter
- Name: lgs_error_invalid_operation
  SwiftName: lgs_error_t.invalidOperation
- Name: lgs_error_queue_full
  SwiftName: lgs_error_t.queueFull

But this line of code fails:

var err: lgs_error_t = .nullParameter
Type 'lgs_error_t' has no member 'nullParameter'

Am I missing something else?

> On May 4, 2017, at 16:55 , Douglas Gregor via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:
>
>
>> On May 3, 2017, at 4:10 PM, Geordie J via swift-users <swift-users@swift.org <mailto:swift-users@swift.org>> wrote:
>>
>> Hi everyone,
>>
>> I’m about to start on another big project with Swift on Android and would like to annotate that JNI headers as much as possible before I do: specifically I’d like to make _Nonnull and CF_SWIFT_NAME annotations to the headers found in a user's jni.h.
>>
>> The question is: is it possible to annotate headers this without changing the original header files? Specifically I’m looking for an options that allows annotations in a separate file, probably one that is read when loading the package’s module.modulemap.
>>
>> I’d like to distribute the annotations in a SwiftPM package that also exposes the original (hopefully annotated) headers. Up until now I’ve been using Swift to override methods in code, but this isn’t as clean or extensible and I fear it may have other (particularly performance) implications.
>>
>> I guess the alternative would be to just maintain and distribute a modified version of jni.h with the annotations, but that would be a "last resort” option.
>
>
> This is the role of API notes, which you can see here:
>
> https://github.com/apple/swift/tree/master/apinotes
>
> with some rough documentation-in-source here:
>
> https://github.com/apple/swift-clang/blob/stable/lib/APINotes/APINotesYAMLCompiler.cpp
>
> - Doug
>
> _______________________________________________
> swift-users mailing list
> swift-users@swift.org <mailto:swift-users@swift.org>
> https://lists.swift.org/mailman/listinfo/swift-users

--
Rick Mann
rmann@latencyzero.com <mailto:rmann@latencyzero.com>

_______________________________________________
swift-users mailing list
swift-users@swift.org <mailto:swift-users@swift.org>
https://lists.swift.org/mailman/listinfo/swift-users

_______________________________________________
swift-users mailing list
swift-users@swift.org
https://lists.swift.org/mailman/listinfo/swift-users

11

It would also be useful for cases when the latest versions of clang can’t be counted on for Linux deployments (3.6 is considered cutting-edge by some, heh)

Guillaume Lessard

···

On May 12, 2017, at 12:33, Daniel Dunbar via swift-users <swift-users@swift.org> wrote:

We don't have explicit support for api notes in SwiftPM.

12

Cheers,
Geordie

We don't have explicit support for api notes in SwiftPM.

Does that mean there is "unexplicit" support (maybe via swift build command
line arguments)?

I don't mind if I have to make a build script, but it'd be a major code
compatibility issue across the supported platforms if apinotes didn't work
at all on Linux.

···

Daniel Dunbar <daniel_dunbar@apple.com> schrieb am Fr. 12. Mai 2017 um 20:33:

We discussed it, and it something which probably makes sense, but no one
has worked on a design or implementation yet.

- Daniel

On May 12, 2017, at 11:32 AM, Michael Gottesman via swift-users < > swift-users@swift.org> wrote:

+Ankit

Michael

On May 12, 2017, at 10:10 AM, Geordie J via swift-users < > swift-users@swift.org> wrote:

To continue this thread: I managed to annotate a bunch of C APIs with
modulename.apinotes. This works with Xcode (to a certain degree - pointers,
enums, and especially OpaquePointers are tricky). I’m now trying to build
my package with SwiftPM and it doesn’t seem to recognise the apinotes file.

@Doug Gregor, would you be able to advise as to whether apinotes works
with SwiftPM (on Linux) and whether it requires some extra settings that I
may be unaware of?

Thanks and best regards for the weekend,
Geordie

Am 08.05.2017 um 00:51 schrieb Geordie Jay <geojay@gmail.com>:

I'm having the same issue. The renames seem to work, as in they disappear
from the global scope with a fixit to rename to the new (namespaced)
version if I type in the name manually, but they don't appear as static
members of the enum type, regardless of how I call them. Would appreciate
some help with this too.

Cheers,
Geordie
Rick Mann <rmann@latencyzero.com> schrieb am So. 7. Mai 2017 um 23:06: > >> I'm trying to use apinotes for this third-party C library (call it >> "Lib.dylib"). It has an enum lgs_error_t:

typedef enum {
    lgs_error_none = 0,
    lgs_error_invalid_handle = -1,
    lgs_error_null = -2,
    lgs_error_invalid_parameter = -3,
    lgs_error_invalid_operation = -4,
    lgs_error_queue_full = -5
} lgs_error_t;

So I wrote apinotes ("Lib.apinotes") that look like this, next to the
.dylib, and part of my Xcode iOS app target:

Enumerators:
# lgs_error_t

- Name: lgs_error_none
  SwiftName: lgs_error_t.none
- Name: lgs_error_invalid_handle
  SwiftName: lgs_error_t.invalidHandle
- Name: lgs_error_null
  SwiftName: lgs_error_t.nullParameter
- Name: lgs_error_invalid_parameter
  SwiftName: lgs_error_t.invalideParameter
- Name: lgs_error_invalid_operation
  SwiftName: lgs_error_t.invalidOperation
- Name: lgs_error_queue_full
  SwiftName: lgs_error_t.queueFull

But this line of code fails:

var err: lgs_error_t = .nullParameter
Type 'lgs_error_t' has no member 'nullParameter'

Am I missing something else?

> On May 4, 2017, at 16:55 , Douglas Gregor via swift-users < >> swift-users@swift.org> wrote:
>
>
>> On May 3, 2017, at 4:10 PM, Geordie J via swift-users < >> swift-users@swift.org> wrote:
>>
>> Hi everyone,
>>
>> I’m about to start on another big project with Swift on Android and
would like to annotate that JNI headers as much as possible before I do:
specifically I’d like to make _Nonnull and CF_SWIFT_NAME annotations to the
headers found in a user's jni.h.
>>
>> The question is: is it possible to annotate headers this without
changing the original header files? Specifically I’m looking for an options
that allows annotations in a separate file, probably one that is read when
loading the package’s module.modulemap.
>>
>> I’d like to distribute the annotations in a SwiftPM package that also
exposes the original (hopefully annotated) headers. Up until now I’ve been
using Swift to override methods in code, but this isn’t as clean or
extensible and I fear it may have other (particularly performance)
implications.
>>
>> I guess the alternative would be to just maintain and distribute a
modified version of jni.h with the annotations, but that would be a "last
resort” option.
>
>
> This is the role of API notes, which you can see here:
>
> https://github.com/apple/swift/tree/master/apinotes
>
> with some rough documentation-in-source here:
>
>
https://github.com/apple/swift-clang/blob/stable/lib/APINotes/APINotesYAMLCompiler.cpp
>
> - Doug
>
> _______________________________________________
> swift-users mailing list
> swift-users@swift.org
> https://lists.swift.org/mailman/listinfo/swift-users

--
Rick Mann
rmann@latencyzero.com

_______________________________________________
swift-users mailing list
swift-users@swift.org
https://lists.swift.org/mailman/listinfo/swift-users

_______________________________________________
swift-users mailing list
swift-users@swift.org
https://lists.swift.org/mailman/listinfo/swift-users

13

.apinotes or .apinotesc ? asking because can't make it work this way.
I have FooKit.apinotes compiled to FooKit.apinotesc. I put it to the FooKit.framework/Modules next to module.modulemap file. Can't make the Swift (Xcode subproject setup) to pick up the SwiftName.
The FooKit.framework is an Objective-C framework.

the minimal apinotes I'm testing right now:

---
Name: FooKit
Classes:
- Name: FOOAnnotation
  SwiftName: Annotation

build with:

xcrun swift -apinotes -yaml-to-binary -target i386-apple-ios7.0 -o FooKit.apinotesc FooKit.apinotes

(swift 4.0.3 macOS)

any advice how to debug what is going on?

14

Put the (textual) FooKit.apinotes into the Headers directory of your framework, and the compiler will pick it up. You can add it to your project and mark it as a public header to get Xcode to do it for you. There shouldn't be any reason to explicitly call -yaml-to-binary; in fact, we've been phasing out the binary format because it's not providing that much value.

  • Doug
15

Great thanks. How about private module? For the FooKit.Private module I tried already:

  • copy FooKit.Private.apinotes in FooKit.framework/Headers and FooKit.framework/PrivateHeaders
  • Tried to combine both modules in single FooKit.apinotes

nothing worked yet. I guess this suppose to work. what I am missing?

16

I haven’t tried this but the module is called either Private or FooKit_Private depending on “who” you ask. Have you tried those variants? (Private.apinotes, FooKit_Private.apinotes)

17

even if this one is called "FooKit.Private" in modulemap file?

explicit framework module FooKit.Private {
    umbrella header "FooKitPrivate.h"

    export *
    module * { export * }
}
18

It’s worth a shot.. But actually now that you mention it I was in almost your exact situation (have restructured our project a bit since then)- in that project we just had one .apinotes file corresponding to the main module but, importantly, all its nested submodules as well.

The whole thing is pretty confusing though I’m sure you will agree, and we had to keep resetting the module cache (aka. deleting Xcode’s DerivedData folder or SwiftPM’s build directory) after every change. I was pretty happy when we could get away with not changing the apinotes every build