Mercurial > vim
view runtime/doc/gui_w32.txt @ 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 | a9b5ffbc0428 |
children | 4635e43f2c6f |
line wrap: on
line source
*gui_w32.txt* For Vim version 9.0. Last change: 2022 Mar 09 VIM REFERENCE MANUAL by Bram Moolenaar Vim's Win32 Graphical User Interface *gui-w32* *win32-gui* 1. Starting the GUI |gui-w32-start| 2. Vim as default editor |vim-default-editor| 3. Using the clipboard |gui-clipboard| 4. Shell Commands |gui-shell-win32| 5. Special colors |win32-colors| 6. Windows dialogs & browsers |gui-w32-dialogs| 7. Command line arguments |gui-w32-cmdargs| 8. Various |gui-w32-various| Other relevant documentation: |gui.txt| For generic items of the GUI. |os_win32.txt| For Win32 specific items. ============================================================================== 1. Starting the GUI *gui-w32-start* The Win32 GUI version of Vim will always start the GUI, no matter how you start it or what it's called. The GUI will always run in the Windows subsystem. Mostly shells automatically return with a command prompt after starting gvim. If not, you should use the "start" command: > start gvim [options] file .. < *E988* The console version with the |-g| option may also start the GUI by executing gvim.exe: > vim -g [options] file .. To make this work, gvim.exe must exist in the same directory as the vim.exe, and this feature must be enabled at compile time. One may also use `:gui` from the console version. However, this is an experimental feature and this feature must be enabled at compile time. It uses a session file to recreate the current state of the console Vim in the GUI Vim. Note: All fonts (bold, italic) must be of the same size!!! If you don't do this, text will disappear or mess up the display. Vim does not check the font sizes. It's the size in screen pixels that must be the same. Note that some fonts that have the same point size don't have the same pixel size! Additionally, the positioning of the fonts must be the same (ascent and descent). The Win32 GUI has an extra menu item: "Edit/Select Font". It brings up the standard Windows font selector. Setting the menu height doesn't work for the Win32 GUI. *gui-win32-maximized* If you want Vim to start with a maximized window, add this command to your vimrc or gvimrc file: > au GUIEnter * simalt ~x < Using Vim as a plugin *gui-w32-windowid* When gvim starts up normally, it creates its own top level window. If you pass Vim the command-line option |--windowid| with a decimal or hexadecimal value, Vim will create a window that is a child of the window with the given ID. This enables Vim to act as a plugin in another application. This really is a programmer's interface, and is of no use without a supporting application to spawn Vim correctly. ============================================================================== 2. Vim as default editor *vim-default-editor* To set Vim as the default editor for a file type: 1. Start a Windows Explorer 2. Choose View/Options -> File Types 3. Select the path to gvim for every file type that you want to use it for. (you can also use three spaces in the file type field, for files without an extension). In the "open" action, use: > gvim "%1" < The quotes are required for using file names with embedded spaces. You can also use this: > gvim "%L" < This should avoid short (8.3 character) file names in some situations. But I'm not sure if this works everywhere. When you open a file in Vim by double clicking it, Vim changes to that file's directory. If you want Vim to start full-screen, use this for the Open action: > gvim -c "simalt ~x" "%1" Another method, which also works when you put Vim in another directory (e.g., when you have got a new version): 1. select a file you want to use Vim with 2. <Shift-F10> 3. select "Open With..." menu entry 4. click "Other..." 5. browse to the (new) location of Vim and click "Open" 6. make "Always Use this program..." checked 7. <OK> *send-to-menu* *sendto* You can also install Vim in the "Send To" menu: 1. Start a Windows Explorer 2. Navigate to your sendto directory: C:\Users\%user%\AppData\Roaming\Microsoft\Windows\SendTo . 3. Right-click in the file pane and select New->Shortcut 4. Follow the shortcut wizard, using the full path to VIM/GVIM. When you 'send a file to Vim', Vim changes to that file's directory. Note, however, that any long directory names will appear in their short (MS-DOS) form on some Windows versions. This is a limitation of the Windows "Send To" mechanism. *notepad* You could replace notepad.exe with gvim.exe, but that has a few side effects. Some programs rely on notepad arguments, which are not recognized by Vim. For example "notepad -p" is used by some applications to print a file. It's better to leave notepad where it is and use another way to start Vim. *win32-popup-menu* A more drastic approach is to install an "Edit with Vim" entry in the popup menu for the right mouse button. With this you can edit any file with Vim. This can co-exist with the file associations mentioned above. The difference is that the file associations will make starting Vim the default action. With the "Edit with Vim" menu entry you can keep the existing file association for double clicking on the file, and edit the file with Vim when you want. For example, you can associate "*.mak" with your make program. You can execute the makefile by double clicking it and use the "Edit with Vim" entry to edit the makefile. You can select any files and right-click to see a menu option called "Edit with gvim". Choosing this menu option will invoke gvim with the file you have selected. If you select multiple files, you will find two gvim-related menu options: "Edit with multiple gvims" -- one gvim for each file in the selection "Edit with single gvim" -- one gvim for all the files in the selection And if there already is a gvim running: "Edit with existing gvim" -- edit the file with the running gvim The "edit with existing Vim" entries can be disabled by adding an entry in the registry under HKLM\Software\Vim\Gvim, named DisableEditWithExisting, and with any value. *install-registry* You can add the "Edit with Vim" menu entry in an easy way by using the "install.exe" program. It will add several registry entries for you. You can also do this by hand. This is complicated! Use the install.exe if you can. 1. Start the registry editor with "regedit". 2. Add these keys: key value name value ~ HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99} {default} Vim Shell Extension HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}\InProcServer32 {default} {path}\gvimext.dll ThreadingModel Apartment HKEY_CLASSES_ROOT\*\shellex\ContextMenuHandlers\gvim {default} {51EEE242-AD87-11d3-9C1E-0090278BBD99} HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved {51EEE242-AD87-11d3-9C1E-0090278BBD99} Vim Shell Extension HKEY_LOCAL_MACHINE\Software\Vim\Gvim path {path}\gvim.exe HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\vim 8.2 DisplayName Vim 8.2: Edit with Vim popup menu entry UninstallString {path}\uninstall.exe Replace {path} with the path that leads to the executable. Don't type {default}, this is the value for the key itself. To remove "Edit with Vim" from the popup menu, just remove the registry entries mentioned above. The "uninstall.exe" program can do this for you. You can also use the entry in the Windows standard "Add/Remove Programs" list. If you notice that this entry overrules other file type associations, set those associations again by hand (using Windows Explorer, see above). This only seems to happen on some Windows NT versions (Windows bug?). Procedure: 1. Find the name of the file type. This can be done by starting the registry editor, and searching for the extension in \\HKEY_CLASSES_ROOT 2. In a Windows Explorer, use View/Options/File Types. Search for the file type in the list and click "Edit". In the actions list, you can select on to be used as the default (normally the "open" action) and click on the "Set Default" button. Vim in the "Open With..." context menu *win32-open-with-menu* If you use the Vim install program you have the choice to add Vim to the "Open With..." menu. This means you can use Vim to edit many files. Not every file (for unclear reasons...), thus the "Edit with Vim" menu entry is still useful. One reason to add this is to be able to edit HTML files directly from Internet Explorer. To enable this use the "Tools" menu, "Internet Options..." entry. In the dialog select the "Programs" tab and select Vim in the "HTML editor" choice. If it's not there then installing didn't work properly. Doing this manually can be done with this script: ---------------------------------------------------------- REGEDIT4 [HKEY_CLASSES_ROOT\Applications\gvim.exe] [HKEY_CLASSES_ROOT\Applications\gvim.exe\shell] [HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit] [HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit\command] @="c:\\vim\\vim82\\gvim.exe \"%1\"" [HKEY_CLASSES_ROOT\.htm\OpenWithList\gvim.exe] [HKEY_CLASSES_ROOT\*\OpenWithList\gvim.exe] ---------------------------------------------------------- Change the "c:\\vim\\vim82" bit to where gvim.exe is actually located. To uninstall this run the Vim uninstall program or manually delete the registry entries with "regedit". ============================================================================== 3. Using the clipboard *gui-clipboard* Windows has a clipboard, where you can copy text to, and paste text from. Vim supports this in several ways. For other systems see |gui-selections|. The "* register reflects the contents of the clipboard. |quotestar| When the "unnamed" string is included in the 'clipboard' option, the unnamed register is the same. Thus you can yank to and paste from the clipboard without prepending "* to commands. If this doesn't work use the "unnamedplus" string in the 'clipboard' option. The 'a' flag in 'guioptions' is not included by default. This means that text is only put on the clipboard when an operation is performed on it. Just Visually selecting text doesn't put it on the clipboard. When the 'a' flag is included, the text is copied to the clipboard even when it is not operated upon. *mswin.vim* To use the standard MS-Windows way of CTRL-X, CTRL-C and CTRL-V, use the $VIMRUNTIME/mswin.vim script. You could add this line to your _vimrc file: > source $VIMRUNTIME/mswin.vim Since CTRL-C is used to copy the text to the clipboard, it can't be used to cancel an operation. Use CTRL-Break for that. CTRL-Z is used for undo. This means you can't suspend Vim with this key, use |:suspend| instead (if it's supported at all). *CTRL-V-alternative* *CTRL-Q* Since CTRL-V is used to paste, you can't use it to start a blockwise Visual selection. You can use CTRL-Q instead. You can also use CTRL-Q in Insert mode and Command-line mode to get the old meaning of CTRL-V. But CTRL-Q doesn't work for terminals when it's used for control flow. NOTE: The clipboard support still has a number of bugs. See |todo|. ============================================================================== 4. Shell Commands *gui-shell-win32* Vim uses another window for external commands, to make it possible to run any command. The external command gets its own environment for running, just like it was started from a DOS prompt. *win32-vimrun* Executing an external command is done indirectly by the "vimrun" command. The "vimrun.exe" must be in the path for this to work. Or it must be in the same directory as the Vim executable. If "vimrun" cannot be found, the command is executed directly, but then the DOS window closes immediately after the external command has finished. WARNING: If you close this window with the "X" button, and confirm the question if you really want to kill the application, Vim may be killed too! (This does not apply to commands run asynchronously with ":!start".) The window in which the commands are executed will be the default you have set up for "Console" in Control Panel. *win32-!start* Normally, Vim waits for a command to complete before continuing (this makes sense for most shell commands which produce output for Vim to use). If you want Vim to start a program and return immediately, you can use the following syntax: > :!start [/min] {command} The optional "/min" causes the window to be minimized. ============================================================================== 5. Special colors *win32-colors* On Win32, the normal DOS colors can be used. See |dos-colors|. Additionally the system configured colors can also be used. These are known by the names Sys_XXX, where XXX is the appropriate system color name, from the following list (see the Win32 documentation for full descriptions). Case is ignored. Sys_3DDKShadow Sys_3DFace Sys_BTNFace Sys_3DHilight Sys_3DHighlight Sys_BTNHilight Sys_BTNHighlight Sys_3DLight Sys_3DShadow Sys_BTNShadow Sys_ActiveBorder Sys_ActiveCaption Sys_AppWorkspace Sys_Background Sys_Desktop Sys_BTNText Sys_CaptionText Sys_GrayText Sys_Highlight Sys_HighlightText Sys_InactiveBorder Sys_InactiveCaption Sys_InactiveCaptionText Sys_InfoBK Sys_InfoText Sys_Menu Sys_MenuText Sys_ScrollBar Sys_Window Sys_WindowFrame Sys_WindowText Probably the most useful values are Sys_Window Normal window background Sys_WindowText Normal window text Sys_Highlight Highlighted background Sys_HighlightText Highlighted text These extra colors are also available: Gray, Grey, LightYellow, SeaGreen, Orange, Purple, SlateBlue, Violet, *rgb.txt* Additionally, colors defined by a default color list can be used. For more info see |:colorscheme|. These colors used to be defined in $VIMRUNTIME/rgb.txt, now they are in |v:colornames| which is initialized from $VIMRUNTIME/colors/lists/default.vim. ============================================================================== *gui-w32-dialogs* *dialog* 6. Windows dialogs & browsers The Win32 GUI can use familiar Windows components for some operations, as well as the traditional interface shared with the console version. 6.1 Dialogs The dialogs displayed by the "confirm" family (i.e. the 'confirm' option, |:confirm| command and |confirm()| function) are GUI-based rather than the console-based ones used by other versions. The 'c' flag in 'guioptions' changes this. 6.2 File Browsers When prepending ":browse" before file editing commands, a file requester is used to allow you to select an existing file. See |:browse|. 6.3 Tearoff Menus The Win32 GUI emulates Motif's tear-off menus. At the top of each menu you will see a small graphic "rip here" sign. Selecting it will cause a floating window to be created with the same menu entries on it. The floating menu can then be accessed just as if it was the original (including sub-menus), but without having to go to the menu bar each time. This is most useful if you find yourself using a command buried in a sub-menu over and over again. The tearoff menus can be positioned where you like, and always stay just above the Main Vim window. You can get rid of them by closing them as usual; they also of course close when you exit Vim. *:tearoff* *:te* :te[aroff] {name} Tear-off the menu {name}. The menu named must have at least one subentry, but need not appear on the menu-bar (see |win32-hidden-menus|). Example: > :tearoff File will make the "File" menu (if there is one) appear as a tearoff menu. > :amenu ]Toolbar.Make :make<CR> :tearoff ]Toolbar This creates a floating menu that doesn't exist on the main menu-bar. Note that a menu that starts with ']' will not be displayed. ============================================================================== 7. Command line arguments *gui-w32-cmdargs* Command line arguments behave the same way as with the console application, see |win32-cmdargs|. ============================================================================== 8. Various *gui-w32-various* *gui-w32-printing* The "File/Print" menu prints the text with syntax highlighting, see |:hardcopy|. If you just want to print the raw text and have a default printer installed this should also work: > :w >>prn Vim supports a number of standard MS-Windows features. Some of these are detailed elsewhere: see |'mouse'|, |win32-hidden-menus|. *drag-n-drop-win32* You can drag and drop one or more files into the Vim window, where they will be opened as normal. See |drag-n-drop|. *:simalt* *:sim* :sim[alt] {key} simulate pressing {key} while holding Alt pressed. {only for Win32 versions} Note: ":si" means ":s" with the "i" flag. Normally, Vim takes control of all Alt-<Key> combinations, to increase the number of possible mappings. This clashes with the standard use of Alt as the key for accessing menus. The quick way of getting standard behavior is to set the 'winaltkeys' option to "yes". This however prevents you from mapping Alt keys at all. Another way is to set 'winaltkeys' to "menu". Menu shortcut keys are then handled by windows, other ALT keys can be mapped. This doesn't allow a dependency on the current state though. To get round this, the :simalt command allows Vim (when 'winaltkeys' is not "yes") to fake a Windows-style Alt keypress. You can use this to map Alt key combinations (or anything else for that matter) to produce standard Windows actions. Here are some examples: > :map <M-f> :simalt f<CR> This makes Alt-F pop down the 'File' menu (with the stock Menu.vim) by simulating the keystrokes Alt, F. > :map <M-Space> :simalt ~<CR> This maps Alt-Space to pop down the system menu for the Vim window. Note that ~ is used by simalt to represent the <Space> character. > :map <C-n> :simalt ~n<CR> Maps Control-N to produce the keys Alt-Space followed by N. This minimizes the Vim window via the system menu. Note that the key changes depending on the language you are using. *intellimouse-wheel-problems* When using the Intellimouse mouse wheel causes Vim to stop accepting input, go to: ControlPanel - Mouse - Wheel - UniversalScrolling - Exceptions And add gvim to the list of applications. This problem only appears to happen with the Intellimouse driver 2.2 and when "Universal Scrolling" is turned on. XPM support *w32-xpm-support* GVim can be built on MS-Windows with support for XPM files. |+xpm_w32| See the Make_mvc.mak file for instructions, search for XPM. To try out if XPM support works do this: > :help :let runtime = escape($VIMRUNTIME, ' \') :exe 'sign define vimxpm icon=' .. runtime .. '\\vim16x16.xpm' :exe 'sign place 1 line=1 name=vimxpm file=' .. expand('%:p') < You may need to get the vim16x16.xpm file from github: https://github.com/vim/vim/blob/master/runtime/vim16x16.xpm vim:tw=78:sw=4:ts=8:noet:ft=help:norl: