adam/vim
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

runtime(doc): clarify C99 constraints and portability assumptions

Browse Source 
closes: #17748

Co-authored-by: dkearns <dougkearns@gmail.com>
Signed-off-by: Damien Lejay <damien@lejay.be>
Signed-off-by: Christian Brabandt <cb@256bit.org>
This commit is contained in:
Damien Lejay
2025-07-21 21:12:39 +02:00
committed by Christian Brabandt
parent e1c507a965
commit 689f3bf313
3 changed files with 211 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

374
runtime/doc/develop.txt
View File

@ -1,4 +1,4 @@
*develop.txt* For Vim version 9.1. Last change: 2025 Jul 18 *develop.txt* For Vim version 9.1. Last change: 2025 Jul 21
VIM REFERENCE MANUAL by Bram Moolenaar VIM REFERENCE MANUAL by Bram Moolenaar
@ -10,9 +10,9 @@ This text is important for those who want to be involved in further developing
Vim. Vim.
1. Design goals |design-goals| 1. Design goals |design-goals|
2. Coding style |coding-style| 2. Design decisions |design-decisions|
3. Design decisions |design-decisions| 3. Assumptions |design-assumptions|
4. Assumptions |design-assumptions| 4. Coding style |coding-style|
See the file README.txt in the "src" directory for an overview of the source See the file README.txt in the "src" directory for an overview of the source
code. code.
@ -159,7 +159,205 @@ VIM IS... NOT *design-not*
============================================================================== ==============================================================================
2. Coding style *coding-style* 2. Design decisions *design-decisions*
Folding
Several forms of folding should be possible for the same buffer. For example,
have one window that shows the text with function bodies folded, another
window that shows a function body.
Folding is a way to display the text. It should not change the text itself.
Therefore the folding has been implemented as a filter between the text stored
in a buffer (buffer lines) and the text displayed in a window (logical lines).
Naming the window
The word "window" is commonly used for several things: A window on the screen,
the xterm window, a window inside Vim to view a buffer.
To avoid confusion, other items that are sometimes called window have been
given another name. Here is an overview of the related items:
screen The whole display. For the GUI it's something like 1024x768
pixels. The Vim shell can use the whole screen or part of it.
shell The Vim application. This can cover the whole screen (e.g.,
when running in a console) or part of it (xterm or GUI).
window View on a buffer. There can be several windows in Vim,
together with the command line, menubar, toolbar, etc. they
fit in the shell.
Spell checking *develop-spell*
When spell checking was going to be added to Vim a survey was done over the
available spell checking libraries and programs. Unfortunately, the result
was that none of them provided sufficient capabilities to be used as the spell
checking engine in Vim, for various reasons:
- Missing support for multibyte encodings. At least UTF-8 must be supported,
so that more than one language can be used in the same file.
Doing on-the-fly conversion is not always possible (would require iconv
support).
- For the programs and libraries: Using them as-is would require installing
them separately from Vim. That's mostly not impossible, but a drawback.
- Performance: A few tests showed that it's possible to check spelling on the
fly (while redrawing), just like syntax highlighting. But the mechanisms
used by other code are much slower. Myspell uses a hashtable, for example.
The affix compression that most spell checkers use makes it slower too.
- For using an external program like aspell a communication mechanism would
have to be setup. That's complicated to do in a portable way (Unix-only
would be relatively simple, but that's not good enough). And performance
will become a problem (lots of process switching involved).
- Missing support for words with non-word characters, such as "Etten-Leur" and
"et al.", would require marking the pieces of them OK, lowering the
reliability.
- Missing support for regions or dialects. Makes it difficult to accept
all English words and highlight non-Canadian words differently.
- Missing support for rare words. Many words are correct but hardly ever used
and could be a misspelled often-used word.
- For making suggestions the speed is less important and requiring to install
another program or library would be acceptable. But the word lists probably
differ, the suggestions may be wrong words.
Spelling suggestions *develop-spell-suggestions*
For making suggestions there are two basic mechanisms:
1. Try changing the bad word a little bit and check for a match with a good
word. Or go through the list of good words, change them a little bit and
check for a match with the bad word. The changes are deleting a character,
inserting a character, swapping two characters, etc.
2. Perform soundfolding on both the bad word and the good words and then find
matches, possibly with a few changes like with the first mechanism.
The first is good for finding typing mistakes. After experimenting with
hashtables and looking at solutions from other spell checkers the conclusion
was that a trie (a kind of tree structure) is ideal for this. Both for
reducing memory use and being able to try sensible changes. For example, when
inserting a character only characters that lead to good words need to be
tried. Other mechanisms (with hashtables) need to try all possible letters at
every position in the word. Also, a hashtable has the requirement that word
boundaries are identified separately, while a trie does not require this.
That makes the mechanism a lot simpler.
Soundfolding is useful when someone knows how the words sounds but doesn't
know how it is spelled. For example, the word "dictionary" might be written
as "daktonerie". The number of changes that the first method would need to
try is very big, it's hard to find the good word that way. After soundfolding
the words become "tktnr" and "tkxnry", these differ by only two letters.
To find words by their soundfolded equivalent (soundalike word) we need a list
of all soundfolded words. A few experiments have been done to find out what
the best method is. Alternatives:
1. Do the sound folding on the fly when looking for suggestions. This means
walking through the trie of good words, soundfolding each word and
checking how different it is from the bad word. This is very efficient for
memory use, but takes a long time. On a fast PC it takes a couple of
seconds for English, which can be acceptable for interactive use. But for
some languages it takes more than ten seconds (e.g., German, Catalan),
which is unacceptably slow. For batch processing (automatic corrections)
it's too slow for all languages.
2. Use a trie for the soundfolded words, so that searching can be done just
like how it works without soundfolding. This requires remembering a list
of good words for each soundfolded word. This makes finding matches very
fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte.
For some languages more than the original word list.
3. Like the second alternative, but reduce the amount of memory by using affix
compression and store only the soundfolded basic word. This is what Aspell
does. Disadvantage is that affixes need to be stripped from the bad word
before soundfolding it, which means that mistakes at the start and/or end
of the word will cause the mechanism to fail. Also, this becomes slow when
the bad word is quite different from the good word.
The choice made is to use the second mechanism and use a separate file. This
way a user with sufficient memory can get very good suggestions while a user
who is short of memory or just wants the spell checking and no suggestions
doesn't use so much memory.
Word frequency
For sorting suggestions it helps to know which words are common. In theory we
could store a word frequency with the word in the dictionary. However, this
requires storing a count per word. That degrades word tree compression a lot.
And maintaining the word frequency for all languages will be a heavy task.
Also, it would be nice to prefer words that are already in the text. This way
the words that appear in the specific text are preferred for suggestions.
What has been implemented is to count words that have been seen during
displaying. A hashtable is used to quickly find the word count. The count is
initialized from words listed in COMMON items in the affix file, so that it
also works when starting a new file.
This isn't ideal, because the longer Vim is running the higher the counts
become. But in practice it is a noticeable improvement over not using the word
count.
==============================================================================
3. Assumptions *design-assumptions*
The following sections define the portability and compatibility constraints that
all Vim code and build tools must adhere to.
MAKEFILES *assumptions-makefiles*
*POSIX.1-2001*
Vim’s main Makefiles target maximum portability, relying solely on features
defined in POSIX.1-2001 `make` and ignoring later POSIX standards or
GNU/BSD extensions. In practical terms, avoid:
– % pattern rules
– modern assignment (`:=`, `::=`) outside POSIX.1-2001
– special targets (`.ONESHELL`, `.NOTPARALLEL`, `.SILENT`, …)
– order-only prerequisites (`|`) or automatic directory creation
– GNU/BSD conditionals (`ifdef`, `ifndef`, `.for`/`.endfor`, …)
Since POSIX.1-2001 supports only traditional suffix rules, every object
built in a separate directory must have an explicit rule. For example:
objects/evalbuffer.o: evalbuffer.c
$(CCC) -o $@ evalbuffer.c
This verbosity ensures that the same Makefile builds Vim unchanged with
the default `make` on Linux, *BSD, macOS, Solaris, AIX, HP-UX and virtually
any Unix-like OS.
Some platform-specific Makefiles (e.g., for Windows, NSIS, or Cygwin) may
use more advanced features when compatibility with basic make is not
required.
C COMPILER *assumptions-C-compiler*
*ANSI-C* *C89* *C90* *C95* *C99*
Vim strives for maximum portability (see |design-multi-platform|) and must
still build with Compaq C V6.4-005 on OpenVMS VAX V7.3.
Therefore, the latest ISO C standard we follow is:
`C95` (ISO/IEC 9899:1990/AMD1:1995)
In addition, the following two `C99` features are explicitly allowed:
– `//` comments, as required by |style-comments|;
– the `_Bool` type.
Platform-specific code may use any newer compiler features supported on
that platform.
SIZE OF VARIABLES *assumptions-variables*
char 8-bit signed
char_u 8-bit unsigned
int 32- or 64-bit signed (16-bit possible on legacy systems)
unsigned 32- or 64-bit unsigned
long at least 32-bit signed (large enough to hold a pointer)
==============================================================================
4. Coding style *coding-style*
These are the rules to use when making changes to the Vim source code. Please These are the rules to use when making changes to the Vim source code. Please
stick to these rules, to keep the sources readable and maintainable. stick to these rules, to keep the sources readable and maintainable.
@ -198,23 +396,6 @@ Other source files do not yet correspond to the .clang-format file. This may
change in the future and they may be reformatted as well. change in the future and they may be reformatted as well.
C COMPILER *style-compiler* *ANSI-C* *C89* *C99*
The minimal C compiler version supported is C89, also known as ANSI C.
Later standards, such as C99, are not widely supported, or at least not 100%
supported. Therefore we use only some of the C99 features and explicitly
disallow some (this will gradually be adjusted over time).
Features not to be used ~
These C99 features are not to be used, because not enough compilers support
them:
- Variable length arrays (even in C11 this is an optional feature).
- C99 _Bool and _Complex types.
- "inline" (it's hardly ever needed, let the optimizer do its work)
- flexible array members: Not supported by HP-UX C compiler (John Marriott)
COMMENTS *style-comments* COMMENTS *style-comments*
Try to avoid putting multiline comments inside a function body: if the Try to avoid putting multiline comments inside a function body: if the
@ -513,153 +694,4 @@ OK: do
while (cond); while (cond);
==============================================================================
3. Design decisions *design-decisions*
Folding
Several forms of folding should be possible for the same buffer. For example,
have one window that shows the text with function bodies folded, another
window that shows a function body.
Folding is a way to display the text. It should not change the text itself.
Therefore the folding has been implemented as a filter between the text stored
in a buffer (buffer lines) and the text displayed in a window (logical lines).
Naming the window
The word "window" is commonly used for several things: A window on the screen,
the xterm window, a window inside Vim to view a buffer.
To avoid confusion, other items that are sometimes called window have been
given another name. Here is an overview of the related items:
screen The whole display. For the GUI it's something like 1024x768
pixels. The Vim shell can use the whole screen or part of it.
shell The Vim application. This can cover the whole screen (e.g.,
when running in a console) or part of it (xterm or GUI).
window View on a buffer. There can be several windows in Vim,
together with the command line, menubar, toolbar, etc. they
fit in the shell.
Spell checking *develop-spell*
When spell checking was going to be added to Vim a survey was done over the
available spell checking libraries and programs. Unfortunately, the result
was that none of them provided sufficient capabilities to be used as the spell
checking engine in Vim, for various reasons:
- Missing support for multibyte encodings. At least UTF-8 must be supported,
so that more than one language can be used in the same file.
Doing on-the-fly conversion is not always possible (would require iconv
support).
- For the programs and libraries: Using them as-is would require installing
them separately from Vim. That's mostly not impossible, but a drawback.
- Performance: A few tests showed that it's possible to check spelling on the
fly (while redrawing), just like syntax highlighting. But the mechanisms
used by other code are much slower. Myspell uses a hashtable, for example.
The affix compression that most spell checkers use makes it slower too.
- For using an external program like aspell a communication mechanism would
have to be setup. That's complicated to do in a portable way (Unix-only
would be relatively simple, but that's not good enough). And performance
will become a problem (lots of process switching involved).
- Missing support for words with non-word characters, such as "Etten-Leur" and
"et al.", would require marking the pieces of them OK, lowering the
reliability.
- Missing support for regions or dialects. Makes it difficult to accept
all English words and highlight non-Canadian words differently.
- Missing support for rare words. Many words are correct but hardly ever used
and could be a misspelled often-used word.
- For making suggestions the speed is less important and requiring to install
another program or library would be acceptable. But the word lists probably
differ, the suggestions may be wrong words.
Spelling suggestions *develop-spell-suggestions*
For making suggestions there are two basic mechanisms:
1. Try changing the bad word a little bit and check for a match with a good
word. Or go through the list of good words, change them a little bit and
check for a match with the bad word. The changes are deleting a character,
inserting a character, swapping two characters, etc.
2. Perform soundfolding on both the bad word and the good words and then find
matches, possibly with a few changes like with the first mechanism.
The first is good for finding typing mistakes. After experimenting with
hashtables and looking at solutions from other spell checkers the conclusion
was that a trie (a kind of tree structure) is ideal for this. Both for
reducing memory use and being able to try sensible changes. For example, when
inserting a character only characters that lead to good words need to be
tried. Other mechanisms (with hashtables) need to try all possible letters at
every position in the word. Also, a hashtable has the requirement that word
boundaries are identified separately, while a trie does not require this.
That makes the mechanism a lot simpler.
Soundfolding is useful when someone knows how the words sounds but doesn't
know how it is spelled. For example, the word "dictionary" might be written
as "daktonerie". The number of changes that the first method would need to
try is very big, it's hard to find the good word that way. After soundfolding
the words become "tktnr" and "tkxnry", these differ by only two letters.
To find words by their soundfolded equivalent (soundalike word) we need a list
of all soundfolded words. A few experiments have been done to find out what
the best method is. Alternatives:
1. Do the sound folding on the fly when looking for suggestions. This means
walking through the trie of good words, soundfolding each word and
checking how different it is from the bad word. This is very efficient for
memory use, but takes a long time. On a fast PC it takes a couple of
seconds for English, which can be acceptable for interactive use. But for
some languages it takes more than ten seconds (e.g., German, Catalan),
which is unacceptably slow. For batch processing (automatic corrections)
it's too slow for all languages.
2. Use a trie for the soundfolded words, so that searching can be done just
like how it works without soundfolding. This requires remembering a list
of good words for each soundfolded word. This makes finding matches very
fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte.
For some languages more than the original word list.
3. Like the second alternative, but reduce the amount of memory by using affix
compression and store only the soundfolded basic word. This is what Aspell
does. Disadvantage is that affixes need to be stripped from the bad word
before soundfolding it, which means that mistakes at the start and/or end
of the word will cause the mechanism to fail. Also, this becomes slow when
the bad word is quite different from the good word.
The choice made is to use the second mechanism and use a separate file. This
way a user with sufficient memory can get very good suggestions while a user
who is short of memory or just wants the spell checking and no suggestions
doesn't use so much memory.
Word frequency
For sorting suggestions it helps to know which words are common. In theory we
could store a word frequency with the word in the dictionary. However, this
requires storing a count per word. That degrades word tree compression a lot.
And maintaining the word frequency for all languages will be a heavy task.
Also, it would be nice to prefer words that are already in the text. This way
the words that appear in the specific text are preferred for suggestions.
What has been implemented is to count words that have been seen during
displaying. A hashtable is used to quickly find the word count. The count is
initialized from words listed in COMMON items in the affix file, so that it
also works when starting a new file.
This isn't ideal, because the longer Vim is running the higher the counts
become. But in practice it is a noticeable improvement over not using the word
count.
==============================================================================
4. Assumptions *design-assumptions*
Size of variables:
char 8 bit signed
char_u 8 bit unsigned
int 32 or 64 bit signed (16 might be possible with limited features)
unsigned 32 or 64 bit unsigned (16 as with ints)
long 32 or 64 bit signed, can hold a pointer
Note that some compilers cannot handle long lines or strings. The C89
standard specifies a limit of 509 characters.
vim:tw=78:ts=8:noet:ft=help:norl: vim:tw=78:ts=8:noet:ft=help:norl:

7
runtime/doc/tags
View File

@ -3991,6 +3991,8 @@ C change.txt /*C*
C-editing tips.txt /*C-editing* C-editing tips.txt /*C-editing*
C-indenting indent.txt /*C-indenting* C-indenting indent.txt /*C-indenting*
C89 develop.txt /*C89* C89 develop.txt /*C89*
C90 develop.txt /*C90*
C95 develop.txt /*C95*
C99 develop.txt /*C99* C99 develop.txt /*C99*
COMSPEC starting.txt /*COMSPEC* COMSPEC starting.txt /*COMSPEC*
CR-used-for-NL pattern.txt /*CR-used-for-NL* CR-used-for-NL pattern.txt /*CR-used-for-NL*
@ -5732,6 +5734,7 @@ PHP_outdentSLComments indent.txt /*PHP_outdentSLComments*
PHP_outdentphpescape indent.txt /*PHP_outdentphpescape* PHP_outdentphpescape indent.txt /*PHP_outdentphpescape*
PHP_removeCRwhenUnix indent.txt /*PHP_removeCRwhenUnix* PHP_removeCRwhenUnix indent.txt /*PHP_removeCRwhenUnix*
PHP_vintage_case_default_indent indent.txt /*PHP_vintage_case_default_indent* PHP_vintage_case_default_indent indent.txt /*PHP_vintage_case_default_indent*
POSIX.1-2001 develop.txt /*POSIX.1-2001*
Partial eval.txt /*Partial* Partial eval.txt /*Partial*
Pattern pattern.txt /*Pattern* Pattern pattern.txt /*Pattern*
Perl if_perl.txt /*Perl* Perl if_perl.txt /*Perl*
@ -6170,6 +6173,9 @@ assert_notequal() testing.txt /*assert_notequal()*
assert_notmatch() testing.txt /*assert_notmatch()* assert_notmatch() testing.txt /*assert_notmatch()*
assert_report() testing.txt /*assert_report()* assert_report() testing.txt /*assert_report()*
assert_true() testing.txt /*assert_true()* assert_true() testing.txt /*assert_true()*
assumptions-C-compiler develop.txt /*assumptions-C-compiler*
assumptions-makefiles develop.txt /*assumptions-makefiles*
assumptions-variables develop.txt /*assumptions-variables*
astro.vim syntax.txt /*astro.vim* astro.vim syntax.txt /*astro.vim*
asy.vim syntax.txt /*asy.vim* asy.vim syntax.txt /*asy.vim*
at motion.txt /*at* at motion.txt /*at*
@ -10407,7 +10413,6 @@ style-changes develop.txt /*style-changes*
style-clang-format develop.txt /*style-clang-format* style-clang-format develop.txt /*style-clang-format*
style-comments develop.txt /*style-comments* style-comments develop.txt /*style-comments*
style-common-functions develop.txt /*style-common-functions* style-common-functions develop.txt /*style-common-functions*
style-compiler develop.txt /*style-compiler*
style-declarations develop.txt /*style-declarations* style-declarations develop.txt /*style-declarations*
style-examples develop.txt /*style-examples* style-examples develop.txt /*style-examples*
style-functions develop.txt /*style-functions* style-functions develop.txt /*style-functions*

4
runtime/doc/version8.txt
View File

@ -1,4 +1,4 @@
*version8.txt* For Vim version 9.1. Last change: 2022 Feb 26 *version8.txt* For Vim version 9.1. Last change: 2025 Jul 21
VIM REFERENCE MANUAL by Bram Moolenaar VIM REFERENCE MANUAL by Bram Moolenaar
@ -14558,7 +14558,7 @@ Changed *changed-8.1*
------- -------
Internal: A few C99 features are now allowed such as // comments and a Internal: A few C99 features are now allowed such as // comments and a
comma after the last enum entry. See |style-compiler|. comma after the last enum entry. See |assumptions-C-compiler|.
Since patch 8.0.0029 removed support for older MS-Windows systems, only Since patch 8.0.0029 removed support for older MS-Windows systems, only
MS-Windows XP and later are supported. MS-Windows XP and later are supported.