Mercurial > vim
view runtime/doc/xxd-fr.1 @ 32936:c517845bd10e v9.0.1776
patch 9.0.1776: No support for stable Python 3 ABI
Commit: https://github.com/vim/vim/commit/c13b3d1350b60b94fe87f0761ea31c0e7fb6ebf3
Author: Yee Cheng Chin <ychin.git@gmail.com>
Date: Sun Aug 20 21:18:38 2023 +0200
patch 9.0.1776: No support for stable Python 3 ABI
Problem: No support for stable Python 3 ABI
Solution: Support Python 3 stable ABI
Commits:
1) Support Python 3 stable ABI to allow mixed version interoperatbility
Vim currently supports embedding Python for use with plugins, and the
"dynamic" linking option allows the user to specify a locally installed
version of Python by setting `pythonthreedll`. However, one caveat is
that the Python 3 libs are not binary compatible across minor versions,
and mixing versions can potentially be dangerous (e.g. let's say Vim was
linked against the Python 3.10 SDK, but the user sets `pythonthreedll`
to a 3.11 lib). Usually, nothing bad happens, but in theory this could
lead to crashes, memory corruption, and other unpredictable behaviors.
It's also difficult for the user to tell something is wrong because Vim
has no way of reporting what Python 3 version Vim was linked with.
For Vim installed via a package manager, this usually isn't an issue
because all the dependencies would already be figured out. For prebuilt
Vim binaries like MacVim (my motivation for working on this), AppImage,
and Win32 installer this could potentially be an issue as usually a
single binary is distributed. This is more tricky when a new Python
version is released, as there's a chicken-and-egg issue with deciding
what Python version to build against and hard to keep in sync when a new
Python version just drops and we have a mix of users of different Python
versions, and a user just blindly upgrading to a new Python could lead to
bad interactions with Vim.
Python 3 does have a solution for this problem: stable ABI / limited API
(see https://docs.python.org/3/c-api/stable.html). The C SDK limits the
API to a set of functions that are promised to be stable across
versions. This pull request adds an ifdef config that allows us to turn
it on when building Vim. Vim binaries built with this option should be
safe to freely link with any Python 3 libraies without having the
constraint of having to use the same minor version.
Note: Python 2 has no such concept and this doesn't change how Python 2
integration works (not that there is going to be a new version of Python
2 that would cause compatibility issues in the future anyway).
---
Technical details:
======
The stable ABI can be accessed when we compile with the Python 3 limited
API (by defining `Py_LIMITED_API`). The Python 3 code (in `if_python3.c`
and `if_py_both.h`) would now handle this and switch to limited API
mode. Without it set, Vim will still use the full API as before so this
is an opt-in change.
The main difference is that `PyType_Object` is now an opaque struct that
we can't directly create "static types" out of, and we have to create
type objects as "heap types" instead. This is because the struct is not
stable and changes from version to version (e.g. 3.8 added a
`tp_vectorcall` field to it). I had to change all the types to be
allocated on the heap instead with just a pointer to them.
Other functions are also simply missing in limited API, or they are
introduced too late (e.g. `PyUnicode_AsUTF8AndSize` in 3.10) to it that
we need some other ways to do the same thing, so I had to abstract a few
things into macros, and sometimes re-implement functions like
`PyObject_NEW`.
One caveat is that in limited API, `OutputType` (used for replacing
`sys.stdout`) no longer inherits from `PyStdPrinter_Type` which I don't
think has any real issue other than minor differences in how they
convert to a string and missing a couple functions like `mode()` and
`fileno()`.
Also fixed an existing bug where `tp_basicsize` was set incorrectly for
`BufferObject`, `TabListObject, `WinListObject`.
Technically, there could be a small performance drop, there is a little
more indirection with accessing type objects, and some APIs like
`PyUnicode_AsUTF8AndSize` are missing, but in practice I didn't see any
difference, and any well-written Python plugin should try to avoid
excessing callbacks to the `vim` module in Python anyway.
I only tested limited API mode down to Python 3.7, which seemes to
compile and work fine. I haven't tried earlier Python versions.
2) Fix PyIter_Check on older Python vers / type##Ptr unused warning
For PyIter_Check, older versions exposed them as either macros (used in
full API), or a function (for use in limited API). A previous change
exposed PyIter_Check to the dynamic build because Python just moved it
to function-only in 3.10 anyway. Because of that, just make sure we
always grab the function in dynamic builds in earlier versions since
that's what Python eventually did anyway.
3) Move Py_LIMITED_API define to configure script
Can now use --with-python-stable-abi flag to customize what stable ABI
version to target. Can also use an env var to do so as well.
4) Show +python/dyn-stable in :version, and allow has() feature query
Not sure if the "/dyn-stable" suffix would break things, or whether we
should do it another way. Or just don't show it in version and rely on
has() feature checking.
5) Documentation first draft. Still need to implement v:python3_version
6) Fix PyIter_Check build breaks when compiling against Python 3.8
7) Add CI coverage stable ABI on Linux/Windows / make configurable on Windows
This adds configurable options for Windows make files (both MinGW and
MSVC). CI will also now exercise both traditional full API and stable
ABI for Linux and Windows in the matrix for coverage.
Also added a "dynamic" option to Linux matrix as a drive-by change to
make other scripting languages like Ruby / Perl testable under both
static and dynamic builds.
8) Fix inaccuracy in Windows docs
Python's own docs are confusing but you don't actually want to use
`python3.dll` for the dynamic linkage.
9) Add generated autoconf file
10) Add v:python3_version support
This variable indicates the version of Python3 that Vim was built
against (PY_VERSION_HEX), and will be useful to check whether the Python
library you are loading in dynamically actually fits it. When built with
stable ABI, it will be the limited ABI version instead
(`Py_LIMITED_API`), which indicates the minimum version of Python 3 the
user should have, rather than the exact match. When stable ABI is used,
we won't be exposing PY_VERSION_HEX in this var because it just doesn't
seem necessary to do so (the whole point of stable ABI is the promise
that it will work across versions), and I don't want to confuse the user
with too many variables.
Also, cleaned up some documentation, and added help tags.
11) Fix Python 3.7 compat issues
Fix a couple issues when using limited API < 3.8
- Crash on exit: In Python 3.7, if a heap-allocated type is destroyed
before all instances are, it would cause a crash later. This happens
when we destroyed `OptionsType` before calling `Py_Finalize` when
using the limited API. To make it worse, later versions changed the
semantics and now each instance has a strong reference to its own type
and the recommendation has changed to have each instance de-ref its
own type and have its type in GC traversal. To avoid dealing with
these cross-version variations, we just don't free the heap type. They
are static types in non-limited-API anyway and are designed to last
through the entirety of the app, and we also don't restart the Python
runtime and therefore do not need it to have absolutely 0 leaks.
See:
- https://docs.python.org/3/whatsnew/3.8.html#changes-in-the-c-api
- https://docs.python.org/3/whatsnew/3.9.html#changes-in-the-c-api
- PyIter_Check: This function is not provided in limited APIs older than
3.8. Previously I was trying to mock it out using manual
PyType_GetSlot() but it was brittle and also does not actually work
properly for static types (it will generate a Python error). Just
return false. It does mean using limited API < 3.8 is not recommended
as you lose the functionality to handle iterators, but from playing
with plugins I couldn't find it to be an issue.
- Fix loading of PyIter_Check so it will be done when limited API < 3.8.
Otherwise loading a 3.7 Python lib will fail even if limited API was
specified to use it.
12) Make sure to only load `PyUnicode_AsUTF8AndSize` in needed in limited API
We don't use this function unless limited API >= 3.10, but we were
loading it regardless. Usually it's ok in Unix-like systems where Python
just has a single lib that we load from, but in Windows where there is a
separate python3.dll this would not work as the symbol would not have
been exposed in this more limited DLL file. This makes it much clearer
under what condition is this function needed.
closes: #12032
Signed-off-by: Christian Brabandt <cb@256bit.org>
Co-authored-by: Yee Cheng Chin <ychin.git@gmail.com>
author | Christian Brabandt <cb@256bit.org> |
---|---|
date | Sun, 20 Aug 2023 21:30:04 +0200 |
parents | c725b8e17f1f |
children | 33cbd544dc46 |
line wrap: on
line source
.TH XXD 1 "août 1996" "Page de manuel pour xxd" .\" .\" 21st May 1996 .\" Man page author: .\" Tony Nugent <tony@sctnugen.ppp.gu.edu.au> <T.Nugent@sct.gu.edu.au> .\" Changes by Bram Moolenaar <Bram@vim.org> .\" French translation by David Blanchet <david.blanchet@free.fr> 2005-03 .SH NOM .I xxd \- convertit en représentation hexadécimale et inversement. .SH SYNOPSIS .B xxd \-h[elp] .br .B xxd [options] [fichier_entree [fichier_sortie]] .br .B xxd \-r[evert] [options] [fichier_entree [fichier_sortie]] .SH DESCRIPTION .I xxd crée un fichier contenant la représentation hexadécimale d'un fichier binaire ou de l'entrée standard. Il peut également convertir un fichier de codes hexadécimaux en un fichier binaire. Comme .BR uuencode (1) et .BR uudecode (1) il permet la transmission de données binaires dans une représentation ASCII compatible avec le courrier électronique, mais a l'avantage de décoder la sortie standard. De plus, il peut être utilisé pour appliquer des rustines à des fichiers binaires. .SH OPTIONS Si aucun .I fichier_entree n'est spécifié, l'entrée standard est utilisée. Si .I fichier_entree correspond au caractère .RB '\-' \, l'entrée standard est employée comme source des données en entrée. Si aucun .I fichier_sortie n'est spécifié (ou qu'un caractère .RB '\-' est donné à sa place), le résultat est envoyé sur la sortie standard. .PP NOTE : un analyseur paresseux est utilisé. Il ne vérifie pas au-delà de la première lettre de l'option, à moins que cette dernière ne requiert un paramètre. L'espace entre l'option et son paramètre est optionnel. Les paramètres des options peuvent être spécifiés en notation décimale, hexadécimale ou octale. Ainsi .BR \-c8 , .BR "\-c 8" , .B \-c 010 et .B \-cols 8 sont tous équivalents. .TP .IR \-a " | " \-autoskip active la fonctionnalité "autoskip" : le caractère '*' remplace les lignes d'octets nuls. Désactivée par défaut. .TP .IR \-b " | " \-bits Convertit en binaires plutôt qu'en hexadécimal. Cette option écrit les octets comme une séquence de "1" et de "0" au lieu d'une conversion en hexadécimal traditionnel. Chaque ligne est précédée par un numéro de ligne en hexadécimal et suivie de la représentation ASCII (ou EBCDIC) correspondante. Les options \-r, \-p, \-i ne fonctionnent pas dans ce mode. .TP .IR "\-c cols " | " \-cols cols" place .RI < cols > octets par ligne. 16 par défaut (\-i : 12, \-ps : 30, \-b : 6). Maximum 256. .TP .IR \-E " | " \-EBCDIC Passe le codage des caractères de la colonne de droite de ASCII à EBCDIC. Cela ne change pas la représentation hexadécimale. Cette option est sans effet quand elle est utilisée avec \-r, \-p or \-i. .TP .IR "\-g octets " | " \-groupsize octets" Regroupe les octets (deux chiffres hexadécimaux ou huit chiffres binaires) par groupe de .RI < octets > \, séparés par des espaces blancs. Spécifiez .I \-g 0 pour supprimer le regroupement. .RI < octets > vaut 2 par défaut dans le mode normal et \fI1\fP en représentation binaire. Le regroupement ne s'applique pas aux styles Postscript et Include. .TP .IR \-h " | " \-help Affiche un résumé des commandes disponibles et quitte. Aucune conversion n'est effectuée. .TP .IR \-i " | " \-include produit une sortie dans le style #include (fichier C à inclure). La définition complète d'un tableau statique est écrite et est nommée d'après le fichier d'origine, à moins que xxd lise depuis l'entrée standard. .TP .IR "\-l long " | " \-len long" Arrête après l'écriture de .RI < long > octets. .TP .IR \-p " | " \-ps " | " \-postscript " | " \-plain Produit une conversion continue dans le style Postscript (postscript continuous hexdump style). Également connu sous le nom de « conversion brute » (plain hexdump style). .TP .IR \-r " | " \-revert Opération inverse : convertit un fichier hexadécimal en un fichier binaire (ou applique une rustine à un fichier binaire). Si l'écriture n'a pas lieu sur la sortie standard, xxd écrit dans le fichier qu'il produit sans le tronquer. Utilisez la combinaison .I \-r \-p pour lire de l'hexadécimal brut sans information sur le numéro des lignes et sans format de colonnes particulier. Des espaces blancs et coupures de lignes supplémentaires sont autorisés à n'importe quel endroit. .TP .I \-seek décalage Utilisé après l'option .IR \-r : inverse la conversion en ajoutant .RI < décalage > aux positions dans le fichier données dans le code hexadécimal. .TP .I \-s [+][\-]décalage Débute au .RI < décalage > absolu ou relatif dans fichier_entree. \fI+ \fRindique que le décalage est relatif à la position courante dans l'entrée standard (sans effet si la lecture n'a pas lieu sur l'entrée standard). \fI\- \fRindique un décalage en caractères depuis la fin de l'entrée (utilisé avec \fI+\fR, désigne la position avant la position actuelle de l'entrée standard). Sans l'option \-s, xxd démarre à la position courante du fichier. .TP .I \-u Utilise des chiffres hexadécimaux majuscules. La casse par défaut est minuscule. .TP .IR \-v " | " \-version Affiche la version de xxd. .SH MISE EN GARDE .I xxd \-r effectue des opérations internes un peu obscures lors de l'évaluation des informations sur les numéros de lignes. Si le fichier de sortie est adressable, alors les numéros de lignes au début de chaque ligne d'hexadécimal peuvent être désordonnées, des lignes peuvent manquer ou se chevaucher. Dans ces cas, xxd utilisera lseek(2) pour déterminer la prochaine position. Si le fichier n'est pas adressable, seuls les vides sont autorisés, et ils seront comblés par des octets nuls. .PP .I xxd \-r ne génère aucune erreur lors de l'analyse. Les problèmes sont passés silencieusement. .PP Lors de l'édition de la représentation hexadécimale, veuillez noter que .I xxd \-r ignore tout ce qui se trouve sur la ligne après avoir lu suffisamment de données hexadécimales (voir l'option \-c). Cela signifie également que les modifications dans la colonne ASCII (ou EBCDIC) sont toujours ignorées. La conversion inverse de données hexadécimales brutes (postscript) avec xxd \-r \-p ne dépend pas d'un nombre correct de colonnes. Dans ce cas, tout ce qui ressemble à une paire de chiffres hexadécimaux est interprété. .PP Remarquez la différence entre .br \fI% xxd \-i fichier\fR .br et .br \fI% xxd \-i < fichier\fR .PP .I xxd \-s \+seek peut différer de .IR "xxd \-s seek" , car lseek(2) est utilisé pour « revenir en arrière ». Le '+' fait une différence quand la source des données est l'entrée standard et si la position dans le fichier de l'entrée standard n'est pas au début du fichier lorsque xxd est démarré et qu'il reçoit ses données. L'exemple suivant peut vous aider à comprendre (ou bien vous perdre davantage encore !)... .PP Remettre l'entrée standard au départ avant de lire ; nécessaire car 'cat' a déjà lu jusqu'à la fin de l'entrée standard. .br \fI% sh \-c 'cat > donnees_binaires; xxd \-s 0 > donnees_hexa' < fichier\fR .PP Convertir à partir de la position 0x480 (= 1024 + 128) du fichier. Le symbole '+' signifie "relativement à la position actuelle', ainsi 128 est ajouté aux 1024 octets comptabilisés pour dd. .br \fI% sh \-c 'dd of=donnees_binaires bs=1k count=1; xxd \-s +128 > donnees_hexa' < fichier\fR .PP Convertir de fichier depuis la position 0x100 (= 1024 \- 768) du fichier. .br \fI% sh \-c 'dd of=donnees_binaires bs=1k count=1; xxd \-s +\-768 > donnees_hexa' < fichier\fR .PP Toutefois, cette situation est peu fréquente et l'utilisation de '+' est rarement requise. L'auteur préfère surveiller les effets de xxd avec strace(1) ou truss(1) quand \-s est employé. .SH EXEMPLES Afficher la totalité du .B fichier sauf les trois premières lignes (0x30 octets en hexadécimal). .br \fI% xxd \-s 0x30 fichier\fR .PP afficher les trois dernières lignes (0x30 octets en hexadécimal) du .B fichier \. .br \fI% xxd \-s \-0x30 fichier\fR .PP .br Afficher 120 octets convertis en continu, avec 20 octets par ligne. .br \fI% xxd \-l 120 \-ps \-c 20 xxd\-fr.1\fR .br 2e54482058584420312022616ffb742031393936 .br 22202250616765206465206d616e75656c20706f .br 757220787864220a2e5c220a2e5c222032317374 .br 204d617920313939360a2e5c22204d616e207061 .br 676520617574686f723a0a2e5c2220202020546f .br 6e79204e7567656e74203c746f6e79407363746e .br 204e7567656e74203c746f6e79407363746e7567 .br 2e54482058584420312022417567757374203139 .PP Convertir les 120 premiers octets de cette page de manuel avec 12 octets par ligne. .br \fI% xxd \-l 120 \-c 12 xxd\-fr.1\fR .br 0000000: 2e54 4820 5858 4420 3120 2261 .TH XXD 1 "a .br 000000c: 6ffb 7420 3139 3936 2220 2250 o.t 1996" "P .br 0000018: 6167 6520 6465 206d 616e 7565 age de manue .br 0000024: 6c20 706f 7572 2078 7864 220a l pour xxd". .br 0000030: 2e5c 220a 2e5c 2220 3231 7374 .\"..\" 21st .br 000003c: 204d 6179 2031 3939 360a 2e5c May 1996..\\ .br 0000048: 2220 4d61 6e20 7061 6765 2061 " Man page a .br 0000054: 7574 686f 723a 0a2e 5c22 2020 uthor:..\" .br 0000060: 2020 546f 6e79 204e 7567 656e Tony Nugen .br 000006c: 7420 3c74 6f6e 7940 7363 746e t <tony@sctn .PP Afficher la date écrite au début du fichier xxd\-fr.1. .br \fI% xxd \-s 0x38 \-l 13 \-c 13 xxd.1\fR .br 0000036: 3231 7374 204d 6179 2031 3939 36 21st May 1996 .PP Copier .B fichier_entree vers .B fichier_sortie en ajoutant 100 octets de valeur 0x00 avant. .br \fI% xxd fichier_entree | xxd \-r \-s 100 \> fichier_sortie\fR .PP Patcher la date dans le fichier xxd.1 .br \fI% echo '0000037: 3574 68' | xxd \-r \- xxd\-fr.1\fR .br \fI% xxd \-s 0x38 \-l 13 \-c 13 xxd\-fr.1\fR .br 0000036: 3235 7468 204d 6179 2031 3939 36 25th May 1996 .PP Créer un fichier de 65537 octets tous nuls (0x00), sauf le dernier qui vaut 'A' (0x41 en hexadécimal). .br \fI% echo '010000: 41' | xxd \-r \> fichier\fR .PP .br Convertir le fichier de l'exemple précédent avec la fonctionnalité "autoskip". .br \fI% xxd \-a \-c 12 fichier\fR .br 0000000: 0000 0000 0000 0000 0000 0000 ............ .br * .br 000fffc: 0000 0000 40 ....A .PP Créer un fichier d'un octet, contenant seulement le caractère 'A'. Le nombre après '\-r \-s' s'ajoute aux numéros de lignes trouvées dans le fichier ; les octets initiaux sont supprimés. .br \fI% echo '010000: 41' | xxd \-r \-s \-0x10000 \> fichier\fR .PP Utiliser xxd comme filtre dans un éditeur tel que .B vim(1) pour convertir une zone comprise entre les marques 'a' et 'z'. .br \fI:'a,'z!xxd\fR .PP Utiliser xxd comme filtre dans un éditeur tel que .B vim(1) pour récupérer une conversion binaire comprise entre les marques 'a' et 'z'. .br \fI:'a,'z!xxd \-r\fR .PP Utiliser xxd comme filtre dans un éditeur tel que .B vim(1) pour récupérer une ligne convertie. Placez le curseur sur la ligne et tapez : .br \fI!!xxd \-r\fR .PP Lire des caractères depuis une connexion série : .br \fI% xxd \-c1 < /dev/term/b &\fR .br \fI% stty < /dev/term/b \-echo \-opost \-isig \-icanon min 1\fR .br \fI% echo \-n foo > /dev/term/b\fR .SH VALEURS DE RETOUR Les erreurs suivantes sont rapportées : .TP 0 aucune erreur ne s'est produit. .TP \-1 opération non supportée ( .I xxd \-r \-i reste impossible). .TP 1 erreur lors de l'analyse des options. .TP 2 problème avec le fichier d'entrée. .TP 3 problème avec le fichier de sortie. .TP 4, 5 la position spécifiée n'est pas atteignable. .SH VOIR AUSSI uuencode(1), uudecode(1), patch(1) .SH AVERTISSEMENTS L'étrangeté de cet outil reflète celle du cerveau de ses créateurs. Utilisez cet outil à vos risques et périls. Dupliquez vos fichiers. Surveillez l'outil. Devenez un gourou. .SH VERSION Cette page de manuel documente la version 1.7 de xxd. .SH AUTEUR (c) 1990-1997 par Juergen Weigert .br <jnweiger@informatik.uni-erlangen.de> .LP "Distribute freely and credit me, .br make money and share with me, .br lose money and don't ask me." .PP Distribution libre en citant l'auteur, .br gagnez de l'argent, pensez à moi, .br perdez de l'argent, oubliez-moi. .PP Page de manuel débutée par Tony Nugent .br <tony@sctnugen.ppp.gu.edu.au> <T.Nugent@sct.gu.edu.au> .br Modifications mineures par Bram Moolenaar. Édité par Juergen Weigert. .SH TRADUCTION Cette page de manuel a été traduite par David Blanchet <david.blanchet@free.fr> 2004-12-24. Mise à jour 2013-05-10, Dominique Pellé <dominique.pelle@gmail.com>