diff options
Diffstat (limited to 'Etc')
| -rw-r--r-- | Etc/zsh-development-guide | 69 |
1 files changed, 48 insertions, 21 deletions
diff --git a/Etc/zsh-development-guide b/Etc/zsh-development-guide index 75a82bd35..e1be18646 100644 --- a/Etc/zsh-development-guide +++ b/Etc/zsh-development-guide @@ -147,16 +147,26 @@ C coding style groups of statements in the interests of clarity. There should never be two consecutive blank lines. +* Each .c file *must* #include the .mdh header for the module it is a + part of and then its own .pro file (for local prototypes). It may + also #include other system headers. It *must not* #include any other + module's headers or any other .pro files. + Modules ------- -Modules are described by a file named `foo.mdd' for a module -`foo'. This file is actually a shell script that will sourced when zsh -is build. To describe the module it can/should set the following shell -variables: +Modules have hierarchical names. Name segments are separated by `/', and +each segment consists of alphanumerics plus `_'. Relative names are never +used; the naming hierarchy is strictly for organisational convenience. + +Each module is described by a file with a name ending in `.mdd' somewhere +under the Src directory. This file is actually a shell script that will +sourced when zsh is build. To describe the module it can/should set the +following shell variables: + - name name of the module - moddeps modules on which this module depends (default none) - - nozshdep non-empty indicates no dependence on the `zsh' pseudo-module + - nozshdep non-empty indicates no dependence on the `zsh/main' pseudo-module - alwayslink if non-empty, always link the module into the executable - autobins builtins defined by the module, for autoloading - autoinfixconds infix condition codes defined by the module, for @@ -170,25 +180,25 @@ variables: - hdrdeps extra headers on which the .mdh depends (default none) - otherincs extra headers that are included indirectly (default none) -Be sure to put the values in quotes. For further enlightenment have a -look at the `mkmakemod.sh' script in the Src directory of the -distribution. +Be sure to put the values in quotes. For further enlightenment have a look +at the `mkmakemod.sh' script in the Src directory of the distribution. Modules have to define four functions which will be called automatically -by the zsh core. The first one, named `setup_foo' for a module named -`foo', should set up any data needed in the module, at least any data -other modules may be interested in. The second one, named `boot_foo', -should register all builtins, conditional codes, and function wrappers -(i.e. anything that will be visible to the user) and will be called -after the `setup'-function. -The third one, named `cleanup_foo' for module `foo' is called when the -user tries to unload a module and should de-register the builtins -etc. The last function, `finish_foo' is called when the module is -actually unloaded and should finalize all the data initialized in the -`setup'-function. -In short, the `cleanup'-function should undo what the `boot'-function -did, and the `finish'-function should undo what the `setup'-function +by the zsh core. The first one, named `setup_', should set up any data +needed in the module, at least any data other modules may be interested +in. The second one, named `boot_', should register all builtins, +conditional codes, and function wrappers (i.e. anything that will be +visible to the user) and will be called after the `setup_'-function. + +The third one, named `cleanup_', is called when the user tries to unload +a module and should de-register the builtins etc. The last function, +`finish_' is called when the module is actually unloaded and should +finalize all the data initialized in the `setup_'-function. + +In short, the `cleanup_'-function should undo what the `boot_'-function +did, and the `finish_'-function should undo what the `setup_'-function did. + All of these functions should return zero if they succeeded and non-zero otherwise. @@ -788,3 +798,20 @@ Documentation All the above should appear on their own, separated by newlines from the surrounding text. No extra newlines after the opening or before the closing parenthesis are required. + +Module names +------------ + +Modules have hierarchical names. Name segments are separated by `/', and +each segment consists of alphanumerics plus `_'. Relative names are never +used; the naming hierarchy is strictly for organisational convenience. + +Top-level name segments should be organisational identifiers, assigned +by the Zsh Development Group and recorded here: + +top-level identifier organisation +-------------------- ------------ +x_* reserved for private experimental use +zsh The Zsh Development Group (contact: <coordinator@zsh.org>) + +Below the top level, naming authority is delegated. |