Exemple de Real-World avancé (manuel)
Cet exemple utilise la bibliothèque POP de Facebook.
Cette section décrit une approche plus avancée de la liaison, où nous allons utiliser l’outil d’Apple xcodebuild
pour d’abord générer le projet POP, puis déduire manuellement l’entrée pour Objective Sharpie. Cela couvre essentiellement ce que Objective Sharpie fait sous le capot dans la section précédente.
$ git clone https://github.com/facebook/pop.git
Cloning into 'pop'...
_(more git clone output)_
$ cd pop
Étant donné que la bibliothèque POP a un projet Xcode (pop.xcodeproj
), nous pouvons simplement utiliser xcodebuild
pour générer pop. Ce processus peut à son tour générer des fichiers d’en-tête que Objective Sharpie peut avoir besoin d’analyser. C’est pourquoi la génération avant la liaison est importante. Lors de la génération via xcodebuild
, veillez à transmettre le même identificateur et l’architecture du KIT de développement logiciel (SDK) que vous envisagez de passer à Objective Sharpie (et rappelez-vous, Objective Sharpie 3.0 peut généralement le faire pour vous !) :
$ xcodebuild -sdk iphoneos9.0 -arch arm64
Build settings from command line:
ARCHS = arm64
SDKROOT = iphoneos8.1
=== BUILD TARGET pop OF PROJECT pop WITH THE DEFAULT CONFIGURATION (Release) ===
...
CpHeader pop/POPAnimationTracer.h build/Headers/POP/POPAnimationTracer.h
cd /Users/aaron/src/sharpie/pop
export PATH="/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/usr/bin:/Applications/Xcode.app/Contents/Developer/usr/bin:/Users/aaron/bin::/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/X11/bin:/usr/local/git/bin:/Users/aaron/.rvm/bin"
builtin-copy -exclude .DS_Store -exclude CVS -exclude .svn -exclude .git -exclude .hg -strip-debug-symbols -strip-tool /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/strip -resolve-src-symlinks /Users/aaron/src/sharpie/pop/pop/POPAnimationTracer.h /Users/aaron/src/sharpie/pop/build/Headers/POP
...
** BUILD SUCCEEDED **
Il y aura beaucoup de sorties d’informations de build dans la console dans le cadre de xcodebuild
. Comme indiqué ci-dessus, nous pouvons voir qu’une cible « CpHeader » a été exécutée dans laquelle les fichiers d’en-tête ont été copiés dans un répertoire de sortie de build. C’est souvent le cas et facilite la liaison : dans le cadre de la build de la bibliothèque native, les fichiers d’en-tête sont souvent copiés dans un emplacement consommable « public », ce qui peut faciliter l’analyse de la liaison. Dans ce cas, nous savons que les fichiers d’en-tête pop se trouvent dans le build/Headers
répertoire.
Nous sommes maintenant prêts à lier POP. Nous savons que nous voulons créer pour le KIT de développement logiciel (SDK) iphoneos8.1
avec l’architecture arm64
, et que les fichiers d’en-tête qui nous intéressent se trouvent sous build/Headers
l’extraction git POP. Si nous regardons dans le build/Headers
répertoire, nous voyons un certain nombre de fichiers d’en-tête :
$ ls build/Headers/POP/
POP.h POPAnimationTracer.h POPDefines.h
POPAnimatableProperty.h POPAnimator.h POPGeometry.h
POPAnimation.h POPAnimatorPrivate.h POPLayerExtras.h
POPAnimationEvent.h POPBasicAnimation.h POPPropertyAnimation.h
POPAnimationExtras.h POPCustomAnimation.h POPSpringAnimation.h
POPAnimationPrivate.h POPDecayAnimation.h
Si nous examinons POP.h
, nous pouvons voir qu’il s’agit du fichier d’en-tête main de niveau supérieur de la bibliothèque qui #import
est d’autres fichiers. Pour cette raison, nous n’avons qu’à passer POP.h
à Objective Sharpie, et clang fera le reste en arrière-plan:
$ sharpie bind -output Binding -sdk iphoneos8.1 \
-scope build/Headers build/Headers/POP/POP.h \
-c -Ibuild/Headers -arch arm64
Parsing Native Code...
Binding...
[write] ApiDefinitions.cs
[write] StructsAndEnums.cs
Binding Analysis:
Automated binding is complete, but there are a few APIs which have
been flagged with [Verify] attributes. While the entire binding
should be audited for best API design practices, look more closely
at APIs with the following Verify attribute hints:
ConstantsInterfaceAssociation (1 instance):
There's no fool-proof way to determine with which Objective-C
interface an extern variable declaration may be associated.
Instances of these are bound as [Field] properties in a partial
interface into a near-by concrete interface to produce a more
intuitive API, possibly eliminating the 'Constants' interface
altogether.
StronglyTypedNSArray (4 instances):
A native NSArray* was bound as NSObject[]. It might be possible
to more strongly type the array in the binding based on
expectations set through API documentation (e.g. comments in the
header file) or by examining the array contents through testing.
For example, an NSArray* containing only NSNumber* instances can
be bound as NSNumber[] instead of NSObject[].
MethodToProperty (2 instances):
An Objective-C method was bound as a C# property due to
convention such as taking no parameters and returning a value (
non-void return). Often methods like these should be bound as
properties to surface a nicer API, but sometimes false-positives
can occur and the binding should actually be a method.
Once you have verified a Verify attribute, you should remove it
from the binding source code. The presence of Verify attributes
intentionally cause build failures.
For more information about the Verify attribute hints above,
consult the Objective Sharpie documentation by running 'sharpie
docs' or visiting the following URL:
http://xmn.io/sharpie-docs
Submitting usage data to Xamarin...
Submitted - thank you for helping to improve Objective Sharpie!
Done.
Vous remarquerez que nous avons passé un -scope build/Headers
argument à Objective Sharpie. Étant donné que les bibliothèques C et Objective-C doivent #import
ou #include
d’autres fichiers d’en-tête qui sont des détails d’implémentation de la bibliothèque et non de l’API que vous souhaitez lier, l’argument -scope
indique à Objective Sharpie d’ignorer toute API qui n’est pas définie dans un fichier quelque part dans le -scope
répertoire.
Vous constaterez que l’argument -scope
est souvent facultatif pour les bibliothèques implémentées correctement, mais il n’y a aucun mal à le fournir explicitement.
Conseil
Si les en-têtes de la bibliothèque importent des en-têtes du Kit de développement logiciel (SDK) iOS, par exemple #import <Foundation.h>
, vous devez définir l’étendue, sinon Objective Sharpie génère des définitions de liaison pour l’en-tête du SDK iOS qui a été importé, ce qui entraîne une énorme liaison qui génère probablement des erreurs lors de la compilation du projet de liaison.
En outre, nous avons spécifié -c -Ibuild/headers
. Tout d’abord, l’argument -c
indique à Objective Sharpie d’arrêter l’interprétation des arguments de ligne de commande et de passer les arguments suivants directement au compilateur clang. Par conséquent, -Ibuild/Headers
est un argument du compilateur clang qui indique à clang de rechercher des inclut sous build/Headers
, qui est l’emplacement où résident les en-têtes POP. Sans cet argument, clang ne saurait pas où trouver les fichiers en POP.h
cours #import
.
Presque tous les « problèmes » liés à l’utilisation de l’objectif Sharpie se résument à déterminer ce qu’il faut passer à clang.
Fin de la liaison
Objective Sharpie a maintenant généré Binding/ApiDefinitions.cs
des fichiers et Binding/StructsAndEnums.cs
.
Il s’agit de la première passe de base d’Objective Sharpie à la liaison, et dans quelques cas, il peut s’agir de tout ce dont vous avez besoin. Toutefois, comme indiqué ci-dessus, le développeur doit généralement modifier manuellement les fichiers générés une fois Objective Sharpie terminé pour résoudre les problèmes qui n’ont pas pu être gérés automatiquement par l’outil.
Une fois les mises à jour terminées, ces deux fichiers peuvent maintenant être ajoutés à un projet de liaison dans Visual Studio pour Mac ou passés directement aux btouch
outils ou bmac
pour produire la liaison finale.
Pour obtenir une description complète du processus de liaison, consultez nos instructions de procédure pas à pas complètes.