runtime(doc): document use of proto files in develop.txt
Commit:
https://github.com/vim/vim/commit/0ed08788a1f8ef89360e8c3dda522aaf2a4971f8
Author: Damien Lejay <dam...@lejay.be>
Date: Mon Sep 1 21:02:19 2025 +0200
runtime(doc): document use of proto files in develop.txt
closes: https://github.com/vim/vim/issues/17973
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 deb40445e..2d486b6ba 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 Aug 11
+*develop.txt* For Vim version 9.1. Last change: 2025 Sep 01
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -362,6 +362,34 @@ We follow POSIX.1-2001 (SUSv3) for type sizes, which in
practice means:
unsigned 32-bit or larger unsigned
+FUNCTION PROTOTYPES *assumptions-prototypes*
+
+Vim currently does not use conventional header files (`.h`) for most internal
+function prototypes. Instead, the current architecture uses individual `.pro`
+files in the `src/proto/` directory, with one `.pro` file per `.c` file.
+
+Unlike traditional self-contained header files, these `.pro` files do not
+contain API documentation, struct and enum definitions, or other declaration;
+only function prototypes.
+
+The bundling of these files is not automated. The `src/proto.h` header is
+composed of a list of manual `#include` directives, one for each individual
+`.pro` file.
+
+Due to this design, integrating a new source file within this architecture
+involves creating a corresponding `.pro` file, manually adding a new `#include`
+directive to `proto.h` and manually adding this file to both `src/Makefile` and
+`src/Make_mvc.mak`.
+
+A `make proto` target exists in `src/Makefile` with the original goal of
+automating the process of updating the `.pro` files. However, this target is
+unreliable, fails on major platforms (e.g., macOS), and is only part of the
+new release workflow. In practice, contributors edit the relevant `.pro` files
+by hand when adding, removing, or modifying a function signatures.
+
+This system has been in place since at least v1.24, when Vim’s functions were
+still written in K&R style.
+
==============================================================================
4. Coding style *coding-style*
diff --git a/runtime/doc/tags b/runtime/doc/tags
index 617753221..e988ffb57 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -6228,6 +6228,7 @@ 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-prototypes develop.txt /*assumptions-prototypes*
assumptions-variables develop.txt /*assumptions-variables*
astro.vim syntax.txt /*astro.vim*
asy.vim syntax.txt /*asy.vim*
--
--
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/E1ut9zb-00Fghz-98%40256bit.org.
