runtime(doc): clarify C99 constraints and portability assumptions
Commit:
https://github.com/vim/vim/commit/689f3bf3139bf8124adfa4bea3d4d8a438b9feb2
Author: Damien Lejay <dam...@lejay.be>
Date: Mon Jul 21 21:12:39 2025 +0200
runtime(doc): clarify C99 constraints and portability assumptions
closes: https://github.com/vim/vim/issues/17748
Co-authored-by: dkearns <dougkea...@gmail.com>
Signed-off-by: Damien Lejay <dam...@lejay.be>
Signed-off-by: Christian Brabandt <c...@256bit.org>
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 726a59778..9fae2692f 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -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
@@ -10,9 +10,9 @@ This text is important for those who want to be involved in
further developing
Vim.
1. Design goals |design-goals|
-2. Coding style |coding-style|
-3. Design decisions |design-decisions|
-4. Assumptions |design-assumptions|
+2. Design decisions |design-decisions|
+3. Assumptions |design-assumptions|
+4. Coding style |coding-style|
See the file README.txt in the "src" directory for an overview of the source
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
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.
-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*
Try to avoid putting multiline comments inside a function body: if the
@@ -513,153 +694,4 @@ OK: do
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:
diff --git a/runtime/doc/tags b/runtime/doc/tags
index b34b79a42..8e2fb0e96 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -3991,6 +3991,8 @@ C change.txt /*C*
C-editing tips.txt /*C-editing*
C-indenting indent.txt /*C-indenting*
C89 develop.txt /*C89*
+C90 develop.txt /*C90*
+C95 develop.txt /*C95*
C99 develop.txt /*C99*
COMSPEC starting.txt /*COMSPEC*
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_removeCRwhenUnix indent.txt /*PHP_removeCRwhenUnix*
PHP_vintage_case_default_indent indent.txt
/*PHP_vintage_case_default_indent*
+POSIX.1-2001 develop.txt /*POSIX.1-2001*
Partial eval.txt /*Partial*
Pattern pattern.txt /*Pattern*
Perl if_perl.txt /*Perl*
@@ -6170,6 +6173,9 @@ assert_notequal() testing.txt /*assert_notequal()*
assert_notmatch() testing.txt /*assert_notmatch()*
assert_report() testing.txt /*assert_report()*
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*
asy.vim syntax.txt /*asy.vim*
at motion.txt /*at*
@@ -10407,7 +10413,6 @@ style-changes develop.txt /*style-changes*
style-clang-format develop.txt /*style-clang-format*
style-comments develop.txt /*style-comments*
style-common-functions develop.txt /*style-common-functions*
-style-compiler develop.txt /*style-compiler*
style-declarations develop.txt /*style-declarations*
style-examples develop.txt /*style-examples*
style-functions develop.txt /*style-functions*
diff --git a/runtime/doc/version8.txt b/runtime/doc/version8.txt
index 1d36c78b1..cfb6f1e3d 100644
--- a/runtime/doc/version8.txt
+++ b/runtime/doc/version8.txt
@@ -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
@@ -14558,7 +14558,7 @@ Changed
*changed-8.1*
-------
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
MS-Windows XP and later are supported.
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to vim_dev+unsubscr...@googlegroups.com.
To view this discussion visit
https://groups.google.com/d/msgid/vim_dev/E1udvya-0028X4-Ah%40256bit.org.
