Mercurial > hg > xemacs-beta
annotate man/emodules.texi @ 4981:4aebb0131297
Cleanups/renaming of EXTERNAL_TO_C_STRING and friends
-------------------- ChangeLog entries follow: --------------------
modules/ChangeLog addition:
2010-02-05 Ben Wing <ben@xemacs.org>
* postgresql/postgresql.c:
* postgresql/postgresql.c (CHECK_LIVE_CONNECTION):
* postgresql/postgresql.c (Fpq_connectdb):
* postgresql/postgresql.c (Fpq_connect_start):
* postgresql/postgresql.c (Fpq_lo_import):
* postgresql/postgresql.c (Fpq_lo_export):
* ldap/eldap.c (Fldap_open):
* ldap/eldap.c (Fldap_search_basic):
* ldap/eldap.c (Fldap_add):
* ldap/eldap.c (Fldap_modify):
* ldap/eldap.c (Fldap_delete):
* canna/canna_api.c (Fcanna_initialize):
* canna/canna_api.c (Fcanna_store_yomi):
* canna/canna_api.c (Fcanna_parse):
* canna/canna_api.c (Fcanna_henkan_begin):
EXTERNAL_TO_C_STRING returns its argument instead of storing it
in a parameter, and is renamed to EXTERNAL_TO_ITEXT. Similar
things happen to related macros. See entry in src/ChangeLog.
More Mule-izing of postgresql.c. Extract out common code
between `pq-connectdb' and `pq-connect-start'. Fix places
that signal an error string using a formatted string to instead
follow the standard and have a fixed reason followed by the
particular error message stored as one of the frobs.
src/ChangeLog addition:
2010-02-05 Ben Wing <ben@xemacs.org>
* console-msw.c (write_string_to_mswindows_debugging_output):
* console-msw.c (Fmswindows_message_box):
* console-x.c (x_perhaps_init_unseen_key_defaults):
* console.c:
* database.c (dbm_get):
* database.c (dbm_put):
* database.c (dbm_remove):
* database.c (berkdb_get):
* database.c (berkdb_put):
* database.c (berkdb_remove):
* database.c (Fopen_database):
* device-gtk.c (gtk_init_device):
* device-msw.c (msprinter_init_device_internal):
* device-msw.c (msprinter_default_printer):
* device-msw.c (msprinter_init_device):
* device-msw.c (sync_printer_with_devmode):
* device-msw.c (Fmsprinter_select_settings):
* device-x.c (sanity_check_geometry_resource):
* device-x.c (Dynarr_add_validified_lisp_string):
* device-x.c (x_init_device):
* device-x.c (Fx_put_resource):
* device-x.c (Fx_valid_keysym_name_p):
* device-x.c (Fx_set_font_path):
* dialog-msw.c (push_lisp_string_as_unicode):
* dialog-msw.c (handle_directory_dialog_box):
* dialog-msw.c (handle_file_dialog_box):
* dialog-x.c (dbox_descriptor_to_widget_value):
* editfns.c (Fformat_time_string):
* editfns.c (Fencode_time):
* editfns.c (Fset_time_zone_rule):
* emacs.c (make_argc_argv):
* emacs.c (Fdump_emacs):
* emodules.c (emodules_load):
* eval.c:
* eval.c (maybe_signal_error_1):
* event-msw.c (Fdde_alloc_advise_item):
* event-msw.c (mswindows_dde_callback):
* event-msw.c (mswindows_wnd_proc):
* fileio.c (report_error_with_errno):
* fileio.c (Fsysnetunam):
* fileio.c (Fdo_auto_save):
* font-mgr.c (extract_fcapi_string):
* font-mgr.c (Ffc_config_app_font_add_file):
* font-mgr.c (Ffc_config_app_font_add_dir):
* font-mgr.c (Ffc_config_filename):
* frame-gtk.c (gtk_set_frame_text_value):
* frame-gtk.c (gtk_create_widgets):
* frame-msw.c (mswindows_init_frame_1):
* frame-msw.c (mswindows_set_title_from_ibyte):
* frame-msw.c (msprinter_init_frame_3):
* frame-x.c (x_set_frame_text_value):
* frame-x.c (x_set_frame_properties):
* frame-x.c (start_drag_internal_1):
* frame-x.c (x_cde_transfer_callback):
* frame-x.c (x_create_widgets):
* glyphs-eimage.c (my_jpeg_output_message):
* glyphs-eimage.c (jpeg_instantiate):
* glyphs-eimage.c (gif_instantiate):
* glyphs-eimage.c (png_instantiate):
* glyphs-eimage.c (tiff_instantiate):
* glyphs-gtk.c (xbm_instantiate_1):
* glyphs-gtk.c (gtk_xbm_instantiate):
* glyphs-gtk.c (gtk_xpm_instantiate):
* glyphs-gtk.c (gtk_xface_instantiate):
* glyphs-gtk.c (cursor_font_instantiate):
* glyphs-gtk.c (gtk_redisplay_widget):
* glyphs-gtk.c (gtk_widget_instantiate_1):
* glyphs-gtk.c (gtk_add_tab_item):
* glyphs-msw.c (mswindows_xpm_instantiate):
* glyphs-msw.c (bmp_instantiate):
* glyphs-msw.c (mswindows_resource_instantiate):
* glyphs-msw.c (xbm_instantiate_1):
* glyphs-msw.c (mswindows_xbm_instantiate):
* glyphs-msw.c (mswindows_xface_instantiate):
* glyphs-msw.c (mswindows_redisplay_widget):
* glyphs-msw.c (mswindows_widget_instantiate):
* glyphs-msw.c (add_tree_item):
* glyphs-msw.c (add_tab_item):
* glyphs-msw.c (mswindows_combo_box_instantiate):
* glyphs-msw.c (mswindows_widget_query_string_geometry):
* glyphs-x.c (x_locate_pixmap_file):
* glyphs-x.c (xbm_instantiate_1):
* glyphs-x.c (x_xbm_instantiate):
* glyphs-x.c (extract_xpm_color_names):
* glyphs-x.c (x_xpm_instantiate):
* glyphs-x.c (x_xface_instantiate):
* glyphs-x.c (autodetect_instantiate):
* glyphs-x.c (safe_XLoadFont):
* glyphs-x.c (cursor_font_instantiate):
* glyphs-x.c (x_redisplay_widget):
* glyphs-x.c (Fchange_subwindow_property):
* glyphs-x.c (x_widget_instantiate):
* glyphs-x.c (x_tab_control_redisplay):
* glyphs.c (pixmap_to_lisp_data):
* gui-x.c (menu_separator_style_and_to_external):
* gui-x.c (add_accel_and_to_external):
* gui-x.c (button_item_to_widget_value):
* hpplay.c (player_error_internal):
* hpplay.c (play_sound_file):
* hpplay.c (play_sound_data):
* intl.c (Fset_current_locale):
* lisp.h:
* menubar-gtk.c (gtk_xemacs_set_accel_keys):
* menubar-msw.c (populate_menu_add_item):
* menubar-msw.c (populate_or_checksum_helper):
* menubar-x.c (menu_item_descriptor_to_widget_value_1):
* nt.c (init_user_info):
* nt.c (get_long_basename):
* nt.c (nt_get_resource):
* nt.c (init_mswindows_environment):
* nt.c (get_cached_volume_information):
* nt.c (mswindows_readdir):
* nt.c (read_unc_volume):
* nt.c (mswindows_stat):
* nt.c (mswindows_getdcwd):
* nt.c (mswindows_executable_type):
* nt.c (Fmswindows_short_file_name):
* ntplay.c (nt_play_sound_file):
* objects-gtk.c:
* objects-gtk.c (gtk_valid_color_name_p):
* objects-gtk.c (gtk_initialize_font_instance):
* objects-gtk.c (gtk_font_list):
* objects-msw.c (font_enum_callback_2):
* objects-msw.c (parse_font_spec):
* objects-x.c (x_parse_nearest_color):
* objects-x.c (x_valid_color_name_p):
* objects-x.c (x_initialize_font_instance):
* objects-x.c (x_font_instance_truename):
* objects-x.c (x_font_list):
* objects-xlike-inc.c (XFUN):
* objects-xlike-inc.c (xft_find_charset_font):
* process-nt.c (mswindows_report_winsock_error):
* process-nt.c (nt_create_process):
* process-nt.c (get_internet_address):
* process-nt.c (nt_open_network_stream):
* process-unix.c:
* process-unix.c (allocate_pty):
* process-unix.c (get_internet_address):
* process-unix.c (unix_canonicalize_host_name):
* process-unix.c (unix_open_network_stream):
* realpath.c:
* select-common.h (lisp_data_to_selection_data):
* select-gtk.c (symbol_to_gtk_atom):
* select-gtk.c (atom_to_symbol):
* select-msw.c (symbol_to_ms_cf):
* select-msw.c (mswindows_register_selection_data_type):
* select-x.c (symbol_to_x_atom):
* select-x.c (x_atom_to_symbol):
* select-x.c (hack_motif_clipboard_selection):
* select-x.c (Fx_store_cutbuffer_internal):
* sound.c (Fplay_sound_file):
* sound.c (Fplay_sound):
* sound.h (sound_perror):
* sysdep.c:
* sysdep.c (qxe_allocating_getcwd):
* sysdep.c (qxe_execve):
* sysdep.c (copy_in_passwd):
* sysdep.c (qxe_getpwnam):
* sysdep.c (qxe_ctime):
* sysdll.c (dll_open):
* sysdll.c (dll_function):
* sysdll.c (dll_variable):
* sysdll.c (search_linked_libs):
* sysdll.c (dll_error):
* sysfile.h:
* sysfile.h (PATHNAME_CONVERT_OUT_TSTR):
* sysfile.h (PATHNAME_CONVERT_OUT_UTF_8):
* sysfile.h (PATHNAME_CONVERT_OUT):
* sysfile.h (LISP_PATHNAME_CONVERT_OUT):
* syswindows.h (ITEXT_TO_TSTR):
* syswindows.h (LOCAL_FILE_FORMAT_TO_TSTR):
* syswindows.h (TSTR_TO_LOCAL_FILE_FORMAT):
* syswindows.h (LOCAL_FILE_FORMAT_TO_INTERNAL_MSWIN):
* syswindows.h (LISP_LOCAL_FILE_FORMAT_MAYBE_URL_TO_TSTR):
* text.h:
* text.h (eicpy_ext_len):
* text.h (enum new_dfc_src_type):
* text.h (EXTERNAL_TO_ITEXT):
* text.h (GET_STRERROR):
* tooltalk.c (check_status):
* tooltalk.c (Fadd_tooltalk_message_arg):
* tooltalk.c (Fadd_tooltalk_pattern_attribute):
* tooltalk.c (Fadd_tooltalk_pattern_arg):
* win32.c (tstr_to_local_file_format):
* win32.c (mswindows_lisp_error_1):
* win32.c (mswindows_report_process_error):
* win32.c (Fmswindows_shell_execute):
* win32.c (mswindows_read_link_1):
Changes involving external/internal format conversion,
mostly code cleanup and renaming.
1. Eliminate the previous macros like LISP_STRING_TO_EXTERNAL
that stored its result in a parameter. The new version of
LISP_STRING_TO_EXTERNAL returns its result through the
return value, same as the previous NEW_LISP_STRING_TO_EXTERNAL.
Use the new-style macros throughout the code.
2. Rename C_STRING_TO_EXTERNAL and friends to ITEXT_TO_EXTERNAL,
in keeping with overall naming rationalization involving
Itext and related types.
Macros involved in previous two:
EXTERNAL_TO_C_STRING -> EXTERNAL_TO_ITEXT
EXTERNAL_TO_C_STRING_MALLOC -> EXTERNAL_TO_ITEXT_MALLOC
SIZED_EXTERNAL_TO_C_STRING -> SIZED_EXTERNAL_TO_ITEXT
SIZED_EXTERNAL_TO_C_STRING_MALLOC -> SIZED_EXTERNAL_TO_ITEXT_MALLOC
C_STRING_TO_EXTERNAL -> ITEXT_TO_EXTERNAL
C_STRING_TO_EXTERNAL_MALLOC -> ITEXT_TO_EXTERNAL_MALLOC
LISP_STRING_TO_EXTERNAL
LISP_STRING_TO_EXTERNAL_MALLOC
LISP_STRING_TO_TSTR
C_STRING_TO_TSTR -> ITEXT_TO_TSTR
TSTR_TO_C_STRING -> TSTR_TO_ITEXT
The following four still return their values through parameters,
since they have more than one value to return:
C_STRING_TO_SIZED_EXTERNAL -> ITEXT_TO_SIZED_EXTERNAL
LISP_STRING_TO_SIZED_EXTERNAL
C_STRING_TO_SIZED_EXTERNAL_MALLOC -> ITEXT_TO_SIZED_EXTERNAL_MALLOC
LISP_STRING_TO_SIZED_EXTERNAL_MALLOC
Sometimes additional casts had to be inserted, since the old
macros played strange games and completely defeated the type system
of the store params.
3. Rewrite many places where direct calls to TO_EXTERNAL_FORMAT
occurred with calls to one of the convenience macros listed above,
or to make_extstring().
4. Eliminate SIZED_C_STRING macros (they were hardly used, anyway)
and use a direct call to TO_EXTERNAL_FORMAT or TO_INTERNAL_FORMAT.
4. Use LISP_PATHNAME_CONVERT_OUT in many places instead of something
like LISP_STRING_TO_EXTERNAL(..., Qfile_name).
5. Eliminate some temporary variables that are no longer necessary
now that we return a value rather than storing it into a variable.
6. Some Mule-izing in database.c.
7. Error functions:
-- A bit of code cleanup in maybe_signal_error_1.
-- Eliminate report_file_type_error; it's just an alias for
signal_error_2 with params in a different order.
-- Fix some places in the hostname-handling code that directly
inserted externally-retrieved error strings into the
supposed ASCII "reason" param instead of doing the right thing
and sticking text descriptive of what was going on in "reason"
and putting the external message in a frob.
8. Use Ascbyte instead of CIbyte in process-unix.c and maybe one
or two other places.
9. Some code cleanup in copy_in_passwd() in sysdep.c.
10. Fix a real bug due to accidental variable shadowing in
tstr_to_local_file_format() in win32.c.
| author | Ben Wing <ben@xemacs.org> |
|---|---|
| date | Fri, 05 Feb 2010 11:02:24 -0600 |
| parents | 304aebb79cd3 |
| children | bb6a375da086 |
| rev | line source |
|---|---|
| 428 | 1 \input texinfo @c -*-texinfo-*- |
| 2 | |
| 3 @c %**start of header | |
| 4 @setfilename ../info/emodules.info | |
| 5 @settitle Extending Emacs using C Modules | |
| 721 | 6 @direntry |
| 7 * Emodules: (emodules). XEmacs dynamically loadable module support. | |
| 8 @end direntry | |
| 9 @c footnotestyle separate | |
| 10 @c paragraphindent 2 | |
| 428 | 11 @c %**end of header |
| 12 | |
| 13 @c | |
| 14 @c Use some macros so that we can format for either XEmacs | |
| 15 @c or (shudder) GNU Emacs. | |
| 16 @c | |
| 17 | |
| 18 @ifset XEMACS | |
| 19 @set emacs XEmacs | |
| 20 @clear EMACS | |
| 21 @set HAVE-EMACS | |
| 22 @end ifset | |
| 23 | |
| 24 @ifset EMACS | |
| 25 @set emacs Emacs | |
| 26 @clear XEMACS | |
| 27 @set HAVE-EMACS | |
| 28 @end ifset | |
| 29 | |
| 30 @ifclear HAVE-EMACS | |
| 31 @set XEMACS | |
| 32 @set emacs XEmacs | |
| 33 @end ifclear | |
| 34 | |
| 35 @ifinfo | |
| 36 This file documents the module loading technology of @value{emacs}. | |
| 37 | |
| 38 Copyright @copyright{} 1998 J. Kean Johnston. | |
| 39 | |
| 40 Permission is granted to make and distribute verbatim copies of this | |
| 41 manual provided the copyright notice and this permission notice are | |
| 42 preserved on all copies. | |
| 43 | |
| 44 @ignore | |
| 45 Permission is granted to process this file through TeX and print the | |
| 46 results, provided the printed document carries copying permission notice | |
| 47 identical to this one except for the removal of this paragraph (this | |
| 48 paragraph not being relevant to the printed manual). | |
| 49 | |
| 50 @end ignore | |
| 51 Permission is granted to copy and distribute modified versions of this | |
| 52 manual under the conditions for verbatim copying, provided that the | |
| 53 entire resulting derived work is distributed under the terms of a | |
| 54 permission notice identical to this one. | |
| 55 | |
| 56 Permission is granted to copy and distribute translations of this manual | |
| 57 into another language, under the above conditions for modified versions, | |
| 58 except that this permission notice may be stated in a translation | |
| 59 approved by the Foundation. | |
| 60 | |
| 61 Permission is granted to copy and distribute modified versions of this | |
| 62 manual under the conditions for verbatim copying, provided also that the | |
| 63 section entitled ``GNU General Public License'' is included exactly as | |
| 64 in the original, and provided that the entire resulting derived work is | |
| 65 distributed under the terms of a permission notice identical to this | |
| 66 one. | |
| 67 | |
| 68 Permission is granted to copy and distribute translations of this manual | |
| 69 into another language, under the above conditions for modified versions, | |
| 70 except that the section entitled ``GNU General Public License'' may be | |
| 71 included in a translation approved by the Free Software Foundation | |
| 72 instead of in the original English. | |
| 73 @end ifinfo | |
| 74 | |
| 75 @c Combine indices. | |
| 76 @syncodeindex fn cp | |
| 77 @syncodeindex vr cp | |
| 78 @syncodeindex ky cp | |
| 79 @syncodeindex pg cp | |
| 80 @syncodeindex tp cp | |
| 81 | |
| 82 @setchapternewpage odd | |
| 83 @finalout | |
| 84 | |
| 85 @titlepage | |
| 86 @title Extending @value{emacs} using C and C++ | |
| 87 @subtitle Version 1.0, September 1998 | |
| 88 | |
| 89 @author J. Kean Johnston | |
| 90 @page | |
| 91 @vskip 0pt plus 1fill | |
| 92 | |
| 93 @noindent | |
| 94 Copyright @copyright{} 1998 J. Kean Johnston. @* | |
| 95 | |
| 96 @sp 2 | |
| 97 Version 1.0 @* | |
| 98 September, 1998.@* | |
| 99 | |
| 100 Permission is granted to make and distribute verbatim copies of this | |
| 101 manual provided the copyright notice and this permission notice are | |
| 102 preserved on all copies. | |
| 103 | |
| 104 Permission is granted to copy and distribute modified versions of this | |
| 105 manual under the conditions for verbatim copying, provided also that the | |
| 106 section entitled ``GNU General Public License'' is included | |
| 107 exactly as in the original, and provided that the entire resulting | |
| 108 derived work is distributed under the terms of a permission notice | |
| 109 identical to this one. | |
| 110 | |
| 111 Permission is granted to copy and distribute translations of this manual | |
| 112 into another language, under the above conditions for modified versions, | |
| 113 except that the section entitled ``GNU General Public License'' may be | |
| 114 included in a translation approved by the Free Software Foundation | |
| 115 instead of in the original English. | |
| 116 @end titlepage | |
| 117 @page | |
| 118 | |
| 119 @ifinfo | |
| 120 @node Top, Introduction, (dir), (dir) | |
| 721 | 121 This Info file contains v1.0 of the @value{emacs} dynamically loadable |
| 122 module support documentation. | |
| 428 | 123 @menu |
| 124 * Introduction:: Introducing Emacs Modules | |
| 442 | 125 * Anatomy of a Module:: Basic module layout and technology |
| 428 | 126 * Using ellcc:: How to use the module compiler |
| 2972 | 127 * Distribution with XEmacs:: Adding your module to the distribution |
| 428 | 128 * Defining Functions:: Creating new Lisp primitives |
| 129 * Defining Variables:: Creating new Lisp variables | |
| 130 * Index:: Concept Index | |
| 131 | |
| 132 --- The Detailed Node Listing --- | |
| 133 | |
| 442 | 134 Anatomy of a Module |
| 428 | 135 |
| 136 * Required Header File:: Always include <emodules.h> | |
| 137 * Required Functions:: Functions you must always provide | |
| 138 * Required Variables:: Variables whose values you must provide | |
| 442 | 139 * Loading other Modules:: How to load dependent modules |
| 428 | 140 |
| 141 Using @code{ellcc} | |
| 142 | |
| 143 * Compile Mode:: Compiling modules using ellcc | |
| 144 * Initialization Mode:: Generating documentation and variables | |
| 145 * Link Mode:: Creating the final loadable module | |
| 146 * Other ellcc options:: Other useful options | |
| 147 * Environment Variables:: How to control ellcc | |
| 148 | |
| 149 Defining Functions | |
| 150 | |
| 151 * Using DEFUN:: Using the DEFUN macro to define functions | |
| 152 * Declaring Functions:: Declaring functions to the Lisp reader | |
| 153 @end menu | |
| 154 | |
| 155 @end ifinfo | |
| 156 | |
| 442 | 157 @node Introduction, Anatomy of a Module, Top, Top |
| 428 | 158 @chapter Introduction |
| 159 | |
| 160 @value{emacs} is a powerful, extensible editor. The traditional way of | |
| 161 extending the functionality of @value{emacs} is to use its built-in Lisp | |
| 162 language (called Emacs Lisp, or Elisp for short). However, while Elisp | |
| 163 is a full programming language and capable of extending @value{emacs} in more | |
| 164 ways than you can imagine, it does have its short-comings. | |
| 165 | |
| 166 Firstly, Elisp is an interpreted language, and this has serious speed | |
| 167 implications. Like all other interpreted languages (like Java), Elisp | |
| 168 is often suitable only for certain types of application or extension. | |
| 440 | 169 So although Elisp is a general purpose language, and very high level, |
| 442 | 170 there are times when it is desirable to descend to a lower level compiled |
| 428 | 171 language for speed purposes. |
| 172 | |
| 173 Secondly, Elisp (or Lisp in general) is not a very common language any | |
| 174 more, except for certain circles in the computer industry. C is a far | |
| 442 | 175 more commonly known language, and because it is compiled, more suited to |
| 428 | 176 a wider range of applications, especially those that require low level |
| 177 access to a system or need to be as quick as possible. | |
| 178 | |
| 179 @cindex Emacs Modules | |
| 180 @cindex DLL | |
| 181 @cindex DSO | |
| 182 @cindex shared object | |
| 721 | 183 This manual describes a new way of extending @value{emacs}, by using |
| 184 dynamically loadable modules (also known as dynamically loadable | |
| 185 libraries (DLLs), dynamic shared objects (DSOs) or just simply shared | |
| 186 objects), which can be written in C or C++ and loaded into @value{emacs} | |
| 187 at any time. I sometimes refer to this technology as @dfn{CEmacs}, | |
| 188 which is short for @dfn{C Extensible Emacs}. | |
| 428 | 189 |
| 190 @value{emacs} modules are configured into and installed with @value{emacs} by | |
| 191 default on all systems that support loading of shared objects. From a | |
| 192 users perspective, the internals of @value{emacs} modules are irrelevant. | |
| 193 All a user will ever need to know about shared objects is the name of | |
| 194 the shared object when they want to load a given module. From a | |
| 195 developers perspective though, a lot more is provided. | |
| 196 | |
| 197 @itemize @bullet | |
| 198 @item | |
| 199 @pindex ellcc | |
| 200 @cindex compiler | |
| 201 @cindex linker | |
| 202 Of primary interest is the @code{ellcc} program. This program is | |
| 203 created during compile time, and is intended to abstract compiler | |
| 204 specific characteristics from the developer. This program is called to | |
| 205 compile and link all objects that will make up the final shared object, | |
| 206 and accepts all common C compiler flags. @code{ellcc} also sets up the | |
| 207 correct environment for compiling modules by enabling any special | |
| 442 | 208 compiler modes (such as PIC mode), setting the correct include paths for |
| 428 | 209 the location of @value{emacs} internal header files etc. The program will also |
| 210 invoke the linker correctly to created the final shared object which is | |
| 211 loaded into @value{emacs}. | |
| 212 | |
| 213 @item | |
| 214 @cindex header files | |
| 215 CEmacs also makes all of the relevant @value{emacs} internal header files | |
| 442 | 216 available for module authors to use. This is often required to get data |
| 428 | 217 structure definitions and external variable declarations. The header |
| 218 files installed include the module specific header file | |
| 219 @file{emodules.h}. Due to the nature of dynamic modules, most of the | |
| 220 internals of @value{emacs} are exposed. | |
| 442 | 221 @xref{Top,,,internals,@value{emacs} Internals Manual}, for a |
| 222 more complete discussion on how to extend and understand @value{emacs}. All of | |
| 428 | 223 the rules for C modules are discussed there. |
| 224 | |
| 225 @item | |
| 226 @cindex samples | |
| 227 Part of the @value{emacs} distribution is a set of sample modules. These are | |
| 228 not installed when @value{emacs} is, but remain in the @value{emacs} source tree. | |
| 229 These modules live in the directory @file{modules}, which is a | |
| 230 sub-directory of the main @value{emacs} source code directory. Please look at | |
| 231 the samples carefully, and maybe even use them as a basis for making | |
| 232 your own modules. Most of the concepts required for writing extension | |
| 233 modules are covered in the samples. | |
| 234 | |
| 235 @item | |
| 236 @cindex documentation | |
| 237 @cindex help | |
| 238 Last, but not least is this manual. This can be viewed from within | |
| 239 @value{emacs}, and it can be printed out as well. It is the intention of this | |
| 240 document that it will describe everything you need to know about | |
| 241 extending @value{emacs} in C. If you do not find this to be the case, please | |
| 242 contact the author(s). | |
| 243 @end itemize | |
| 244 | |
| 245 The rest of this document will discuss the actual mechanics of | |
| 246 @value{emacs} modules and work through several of the samples. Please be | |
| 247 sure that you have read the @value{emacs} Internals Manual and understand | |
| 248 everything in it. The concepts there apply to all modules. This | |
| 249 document may have some overlap, but it is the internals manual which | |
| 250 should be considered the final authority. It will also help a great | |
| 251 deal to look at the actual @value{emacs} source code to see how things are | |
| 252 done. | |
| 253 | |
| 442 | 254 @node Anatomy of a Module, Using ellcc, Introduction, Top |
| 255 @chapter Anatomy of a Module | |
| 256 @cindex anatomy | |
| 428 | 257 @cindex module skeleton |
| 258 @cindex skeleton, module | |
| 259 @cindex module format | |
| 260 @cindex format, module | |
| 261 | |
| 442 | 262 Each dynamically loadable @value{emacs} extension (hereafter referred to as a |
| 263 module) has a certain compulsory format, and must contain several | |
| 264 pieces of information and several mandatory functions. This chapter | |
| 428 | 265 describes the basic layout of a module, and provides a very simple |
| 266 sample. The source for this sample can be found in the file | |
| 267 @file{modules/simple/sample.c} in the main @value{emacs} source code tree. | |
| 268 | |
| 269 @menu | |
| 270 * Required Header File:: Always include <emodules.h> | |
| 271 * Required Functions:: Functions you must always provide | |
| 272 * Required Variables:: Variables whose values you must provide | |
| 442 | 273 * Loading other Modules:: How to load dependent modules |
| 428 | 274 @end menu |
| 275 | |
| 442 | 276 @node Required Header File, Required Functions, Anatomy of a Module, Anatomy of a Module |
| 428 | 277 @section Required Header File |
| 278 @cindex required header | |
| 279 @cindex include files | |
| 280 | |
| 281 @cindex emodules.h | |
| 282 @cindex config.h | |
| 283 Every module must include the file @file{<emodules.h>}. This | |
| 442 | 284 will include several other @value{emacs} internal header files, and will set up |
| 428 | 285 certain vital macros. One of the most important files included by |
| 286 @file{emodules.h} is the generated @file{config.h} file, which contains | |
| 287 all of the required system abstraction macros and definitions. Most | |
| 288 modules will probably require some pre-processor conditionals based on | |
| 289 constants defined in @file{config.h}. Please read that file to | |
| 290 familiarize yourself with the macros defined there. | |
| 291 | |
| 442 | 292 Depending on exactly what your module will be doing, you will probably |
| 428 | 293 need to include one or more of the @value{emacs} internal header files. When |
| 442 | 294 you @code{#include <emodules.h>}, you will get a few of the most important |
| 428 | 295 @value{emacs} header files included automatically for you. The files included |
| 296 are: | |
| 297 | |
| 298 @table @file | |
| 299 @item lisp.h | |
| 442 | 300 This file contains most of the macros required for declaring Lisp object |
| 428 | 301 types, macros for accessing Lisp objects, and global variable |
| 302 declarations. | |
| 303 | |
| 304 @item sysdep.h | |
| 442 | 305 All system dependent declarations and abstraction macros live here. You |
| 428 | 306 should never call low level system functions directly. Rather, you |
| 307 should use the abstraction macros provided in this header file. | |
| 308 | |
| 309 @item window.h | |
| 310 This header file defines the window structures and Lisp types, and | |
| 311 provides functions and macros for manipulating multiple @value{emacs} windows. | |
| 312 | |
| 313 @item buffer.h | |
| 314 All macros and function declarations for manipulating internal and user | |
| 315 visible buffers appear in this file. | |
| 316 | |
| 317 @item insdel.h | |
| 318 This header provides the information required for performing text | |
| 319 insertion and deletion. | |
| 320 | |
| 321 @item frame.h | |
| 322 Provides the required structure, macro and function definitions for | |
| 323 manipulating @value{emacs} frames. | |
| 324 @end table | |
| 325 | |
| 442 | 326 @node Required Functions, Required Variables, Required Header File, Anatomy of a Module |
| 428 | 327 @section Required Functions |
| 328 @cindex initialization | |
| 329 @cindex functions, required | |
| 330 @cindex required functions | |
| 331 | |
| 332 Every module requires several initialization functions. It is the | |
| 442 | 333 responsibility of these functions to load in any dependent modules, and to |
| 334 declare all variables and functions which are to be made visible to the | |
| 428 | 335 @value{emacs} Lisp reader. Each of these functions performs a very specific |
| 336 task, and they are executed in the correct order by @value{emacs}. All of | |
| 337 these functions are @code{void} functions which take no arguments. | |
| 338 Here, briefly, are the required module functions. Note that the actual | |
| 339 function names do not end with the string @code{_module}, but rather | |
| 340 they end with the abbreviated module name by which the module is known. | |
| 341 More on the module name and its importance later. Just bear in mind | |
| 342 that the text @code{_module} in the functions below is simply a | |
| 343 place-holder, not an actual function name. | |
| 344 | |
| 345 @table @code | |
| 346 @item syms_of_module | |
| 347 @findex syms_of_module | |
| 442 | 348 This required function is responsible for introducing to the Lisp reader |
| 428 | 349 all functions that you have defined in your module using |
| 350 @code{DEFUN()}. Note that @emph{only} functions are declared here, using | |
| 351 the @code{DEFSUBR()} macro. No variables are declared. | |
| 352 | |
| 353 @item vars_of_module | |
| 354 @findex vars_of_module | |
| 355 This required function contains calls to macros such as | |
| 356 @code{DEFVAR_LISP()}, @code{DEFVAR_BOOL()} etc, and its purpose is to | |
| 357 declare and initialize all and any variables that your module defines. | |
| 358 They syntax for declaring variables is identical to the syntax used for | |
| 450 | 359 all internal @value{emacs} source code. If the module is intended to be |
| 360 usable statically linked into XEmacs, the actions of this function are | |
| 361 severely restricted. @xref{General Coding Rules,,,internals, | |
| 362 @value{emacs} Internals Manual}. Also see the comments in | |
| 363 @file{src/emacs.c} (@code{main_1}). Modules which perform | |
| 364 initializations not permitted by these rules will probably work, but | |
| 365 dual-use (dynamic loading and static linking) modules will require very | |
| 366 careful, and possibly fragile, coding. | |
| 428 | 367 |
| 368 @item modules_of_module | |
| 369 @findex modules_of_module | |
| 370 This optional function should be used to load in any modules which your | |
| 442 | 371 module depends on. The @value{emacs} module loading code makes sure that the |
| 428 | 372 same module is not loaded twice, so several modules can safely call the |
| 373 module load function for the same module. Only one copy of each module | |
| 374 (at a given version) will ever be loaded. | |
| 375 | |
| 376 @item docs_of_module | |
| 377 @findex docs_of_module | |
| 378 This is a required function, but not one which you need ever write. | |
| 379 This function is created automatically by @code{ellcc} when the module | |
| 380 initialization code is produced. It is required to document all | |
| 381 functions and variables declared in your module. | |
| 382 @end table | |
| 383 | |
| 442 | 384 @node Required Variables, Loading other Modules, Required Functions, Anatomy of a Module |
| 428 | 385 @section Required Variables |
| 386 @cindex initialization | |
| 387 @cindex variables, required | |
| 388 @cindex required variables | |
| 389 | |
| 390 Not only does a module need to declare the initialization functions | |
| 391 mentioned above, it is also required to provide certain variables which | |
| 442 | 392 the module loading code searches for in order to determine the viability |
| 428 | 393 of a module. You are @emph{not} required to provide these variables in |
| 394 your source files. They are automatically set up in the module | |
| 395 initialization file by the @code{ellcc} compiler. These variables are | |
| 396 discussed here simply for the sake of completeness. | |
| 397 | |
| 398 @table @code | |
| 399 @item emodules_compiler | |
| 400 This is a variable of type @code{long}, and is used to indicate the | |
| 401 version of the @value{emacs} loading technology that was used to produce the | |
| 402 module being loaded. This version number is completely unrelated to | |
| 403 the @value{emacs} version number, as a given module may quite well work | |
| 442 | 404 regardless of the version of @value{emacs} that was installed at the time the |
| 428 | 405 module was created. |
| 406 | |
| 407 The @value{emacs} modules version is used to differentiate between major | |
| 408 changes in the module loading technology, not versions of @value{emacs}. | |
| 409 | |
| 410 @item emodules_name | |
| 411 This is a short (typically 10 characters or less) name for the module, | |
| 412 and it is used as a suffix for all of the required functions. This is | |
| 442 | 413 also the name by which the module is recognized when loading dependent |
| 428 | 414 modules. The name does not necessarily have to be the same as the |
| 415 physical file name, although keeping the two names in sync is a pretty | |
| 442 | 416 good idea. The name must not be empty, and it must be a valid part of a |
| 417 C function name. The value of this variable is appended to the function | |
| 428 | 418 names @code{syms_of_}, @code{vars_of_}, @code{modules_of_} and |
| 419 @code{docs_of_} to form the actual function names that the module | |
| 420 loading code looks for when loading a module. | |
| 421 | |
| 422 This variable is set by the @code{--mod-name} argument to @code{ellcc}. | |
| 423 | |
| 424 @item emodules_version | |
| 425 This string variable is used to load specific versions of a module. | |
| 426 Rarely will two or more versions of a module be left lying around, but | |
| 427 just in case this does happen, this variable can be used to control | |
| 428 exactly which module should be loaded. See the Lisp function | |
| 429 @code{load-module} for more details. This variable is set by the | |
| 430 @code{--mod-version} argument to @code{ellcc}. | |
| 431 | |
| 432 @item emodules_title | |
| 433 This is a string which describes the module, and can contain spaces or | |
| 434 other special characters. It is used solely for descriptive purposes, | |
| 435 and does not affect the loading of the module. The value is set by the | |
| 436 @code{--mod-title} argument to @code{ellcc}. | |
| 437 @end table | |
| 438 | |
| 442 | 439 @node Loading other Modules, , Required Variables, Anatomy of a Module |
| 428 | 440 @section Loading other Modules |
| 442 | 441 @cindex dependencies |
| 428 | 442 @findex modules_of_module |
| 443 @findex emodules_load | |
| 444 | |
| 445 During the loading of a module, it is the responsibility of the function | |
| 446 @code{modules_of_module} to load in any modules which the current module | |
| 447 depends on. If the module is stand-alone, and does not depend on other | |
| 448 modules, then this function can be left empty or even undeclared. | |
| 442 | 449 However, if it does have dependencies, it must call |
| 428 | 450 @code{emodules_load}: |
| 451 | |
| 452 @example | |
| 453 @cartouche | |
| 442 | 454 int emodules_load (const char *module, |
| 455 const char *modname, | |
| 456 const char *modver) | |
| 428 | 457 @end cartouche |
| 458 @end example | |
| 459 | |
| 442 | 460 The first argument @var{module} is the name of the actual shared object |
| 428 | 461 or DLL. You can omit the @file{.so}, @file{.ell} or @file{.dll} |
| 462 extension of you wish. If you do not specify an absolute path name, | |
| 463 then the same rules as apply to loading Lisp modules are applied when | |
| 464 searching for the module. If the module cannot be found in any of the | |
| 465 standard places, and an absolute path name was not specified, | |
| 442 | 466 @code{emodules_load} will signal an error and loading of the module |
| 428 | 467 will stop. |
| 468 | |
| 469 The second argument (@var{modname}) is the module name to load, and | |
| 470 must match the contents of the variable @var{emodule_name} in the | |
| 442 | 471 module to be loaded. A mis-match will cause the module load to fail. If |
| 428 | 472 this parameter is @code{NULL} or empty, then no checks are performed |
| 473 against the target module's @var{emodule_name} variable. | |
| 474 | |
| 475 The last argument, @var{modver}, is the desired version of the module | |
| 476 to load, and is compared to the target module's | |
| 477 @var{emodule_version} value. If this parameter is not @code{NULL} | |
| 478 or empty, and the match fails, then the load of the module will fail. | |
| 479 | |
| 480 @code{emodules_load} can be called recursively. If, at any point | |
| 442 | 481 during the loading of modules a failure is encountered, then all modules |
| 428 | 482 that were loaded since the top level call to @code{emodules_load} |
| 483 will be unloaded. This means that if any child modules fail to load, | |
| 484 then their parents will also fail to load. This does not include | |
| 485 previous successful calls to @code{emodules_load} at the top level. | |
| 486 | |
| 880 | 487 @strong{Warning:} Modules are @emph{not} loaded with the |
| 488 @code{RTLD_GLOBAL} flag. The practical upshot is that individual | |
| 489 modules do not have access to each other's C symbols. One module cannot | |
| 490 make a C function call to a function defined in another module, nor can | |
| 491 it read or set a C variable in another module. All interaction between | |
| 492 modules must, therefore, take place at the Lisp level. This is by | |
| 493 design. Other projects have attempted to use @code{RTLD_GLOBAL}, only | |
| 494 to find that spurious symbol name clashes were the result. Helper | |
| 495 functions often have simple names, increasing the probability of such a | |
| 496 clash. If you really need to share symbols between modules, create a | |
| 497 shared library containing those symbols, and link your modules with | |
| 498 that library. Otherwise, interactions between modules must take place | |
| 499 via Lisp function calls and Lisp variables accesses. | |
| 500 | |
| 2972 | 501 @node Using ellcc, Distribution with XEmacs, Anatomy of a Module, Top |
| 428 | 502 @chapter Using @code{ellcc} |
| 503 @cindex @code{ellcc} | |
| 504 @cindex module compiler | |
| 505 | |
| 506 Before discussing the anatomy of a module in greater detail, you should | |
| 507 be aware of the steps required in order to correctly compile and link a | |
| 508 module for use within @value{emacs}. There is little difference between | |
| 509 compiling normal C code and compiling a module. In fact, all that | |
| 510 changes is the command used to compile the module, and a few extra | |
| 511 arguments to the compiler. | |
| 512 | |
| 513 @value{emacs} now ships with a new user utility, called @code{ellcc}. This | |
| 514 is the @dfn{Emacs Loadable Library C Compiler}. This is a wrapper | |
| 515 program that will invoke the real C compiler with the correct arguments | |
| 516 to compile and link your module. With the exception of a few command | |
| 517 line options, this program can be considered a replacement for your C | |
| 518 compiler. It accepts all of the same flags and arguments that your C | |
| 519 compiler does, so in many cases you can simply set the @code{make} | |
| 520 variable @code{CC} to @code{ellcc} and your code will be compiled as | |
| 521 an Emacs module rather than a static C object. | |
| 522 | |
| 523 @code{ellcc} has three distinct modes of operation. It can be run in | |
| 442 | 524 compile, link or initialization mode. These modes are discussed in more |
| 428 | 525 detail below. If you want @code{ellcc} to show the commands it is |
| 526 executing, you can specify the option @code{--mode=verbose} to | |
| 527 @code{ellcc}. Specifying this option twice will enable certain extra | |
| 528 debugging messages to be displayed on the standard output. | |
| 529 | |
| 530 @menu | |
| 531 * Compile Mode:: Compiling modules using ellcc | |
| 532 * Initialization Mode:: Generating documentation and variables | |
| 533 * Link Mode:: Creating the final loadable module | |
| 534 * Other ellcc options:: Other useful options | |
| 535 * Environment Variables:: How to control ellcc | |
| 536 @end menu | |
| 537 | |
| 538 @node Compile Mode, Initialization Mode, Using ellcc, Using ellcc | |
| 539 @section Compile Mode | |
| 540 @cindex compiling | |
| 541 | |
| 542 By default, @code{ellcc} is in @dfn{compile} mode. This means that it | |
| 442 | 543 assumes that all of the command line arguments are C compiler arguments, |
| 428 | 544 and that you want to compile the specified source file or files. You |
| 545 can force compile mode by specifying the @code{--mode=compile} argument | |
| 546 to @code{ellcc}. | |
| 547 | |
| 548 In this mode, @code{ellcc} is simply a front-end to the same C compiler | |
| 549 that was used to create the @value{emacs} binary itself. All @code{ellcc} | |
| 550 does in this mode is insert a few extra command line arguments before | |
| 551 the arguments you specify to @code{ellcc} itself. @code{ellcc} will | |
| 552 then invoke the C compiler to compile your module, and will return the | |
| 553 same exit codes and messages that your C compiler does. | |
| 554 | |
| 555 By far the easiest way to compile modules is to construct a | |
| 442 | 556 @file{Makefile} as you would for a normal program, and simply insert, at |
| 428 | 557 some appropriate place something similar to: |
| 558 | |
| 559 @example | |
| 560 @cartouche | |
| 561 CC=ellcc --mode=compile | |
| 562 | |
| 563 .c.o: | |
| 564 $(CC) $(CFLAGS) -c $< | |
| 565 @end cartouche | |
| 566 @end example | |
| 567 | |
| 568 After this, all you need to do is provide simple @code{make} rules for | |
| 569 compiling your module source files. Since modules are most useful when | |
| 570 they are small and self-contained, most modules will have a single | |
| 571 source file, aside from the module specific initialization file (see | |
| 572 below for details). | |
| 573 | |
| 574 @node Initialization Mode, Link Mode, Compile Mode, Using ellcc | |
| 575 @section Initialization Mode | |
| 576 @cindex initialization | |
| 577 @cindex documentation | |
| 578 | |
| 579 @value{emacs} uses a rather bizarre way of documenting variables and | |
| 580 functions. Rather than have the documentation for compiled functions | |
| 581 and variables passed as static strings in the source code, the | |
| 582 documentation is included as a C comment. A special program, called | |
| 583 @file{make-docfile}, is used to scan the source code files and extract | |
| 442 | 584 the documentation from these comments, producing the @value{emacs} @file{DOC} |
| 428 | 585 file, which the internal help engine scans when the documentation for a |
| 586 function or variable is requested. | |
| 587 | |
| 588 Due to the internal construction of Lisp objects, subrs and other such | |
| 589 things, adding documentation for a compiled function or variable in a | |
| 590 compiled module, at any time after @value{emacs} has been @dfn{dumped} is | |
| 442 | 591 somewhat problematic. Fortunately, as a module writer you are insulated |
| 428 | 592 from the difficulties thanks to your friend @code{ellcc} and some |
| 593 internal trickery in the module loading code. This is all done using | |
| 594 the @dfn{initialization} mode of @code{ellcc}. | |
| 595 | |
| 596 The result of running @code{ellcc} in initialization mode is a C source | |
| 597 file which you compile with (you guessed it) @code{ellcc} in compile | |
| 598 mode. Initialization mode is where you set the module name, version, | |
| 442 | 599 title and gather together all of the documentation strings for the |
| 600 functions and variables in your module. There are several options that | |
| 428 | 601 you are required to pass @code{ellcc} in initialization mode, the first |
| 602 of which is the mode switch itself, @code{--mode=init}. | |
| 603 | |
| 604 Next, you need to specify the name of the C source code file that | |
| 605 @code{ellcc} will produce, and you specify this using the | |
| 606 @code{--mod-output=FILENAME} argument. @var{FILENAME} is the name of | |
| 607 the C source code file that will contain the module variables and | |
| 608 @code{docs_of_module} function. | |
| 609 | |
| 610 As discussed previously, each module requires a short @dfn{handle} or | |
| 611 module name. This is specified with the @code{--mod-name=NAME} option, | |
| 612 where @var{NAME} is the abbreviated module name. This @var{NAME} must | |
| 613 consist only of characters that are valid in C function and variable | |
| 614 names. | |
| 615 | |
| 616 The module version is specified using @code{--mod-version=VERSION} | |
| 617 argument, with @var{VERSION} being any arbitrary version string. This | |
| 618 version can be passed as an optional second argument to the Lisp | |
| 619 function @code{load-module}, and as the third argument to the internal | |
| 620 module loading command @code{emodules_load}. This version string is | |
| 621 used to distinguish between different versions of the same module, and | |
| 622 to ensure that the module is loaded at a specific version. | |
| 623 | |
| 624 Last, but not least, is the module title. Specified using the | |
| 625 @code{--mod-title=TITLE} option, the specified @var{TITLE} is used when | |
| 626 the list of loaded modules is displayed. The module title serves no | |
| 627 purpose other than to inform the user of the function of the module. | |
| 628 This string should be brief, as it has to be formatted to fit the | |
| 629 screen. | |
| 630 | |
| 631 Following all of these parameters, you need to provide the list of all | |
| 442 | 632 source code modules that make up your module. These are the files which |
| 633 are scanned by @file{make-docfile}, and provide the information required | |
| 428 | 634 to populate the @code{docs_of_module} function. Below is a sample |
| 635 @file{Makefile} fragment which indicates how all of this is used. | |
| 636 | |
| 637 @example | |
| 638 @cartouche | |
| 639 CC=ellcc --mode=compile | |
| 640 LD=ellcc --mode=link | |
| 641 MODINIT=ellcc --mode=init | |
| 642 CFLAGS=-O2 -DSOME_STUFF | |
| 643 | |
| 644 .c.o: | |
| 645 $(CC) $(CFLAGS) -c $< | |
| 646 | |
| 647 MODNAME=sample | |
| 648 MODVER=1.0.0 | |
| 649 MODTITLE="Small sample module" | |
| 650 | |
| 651 SRCS=modfile1.c modfile2.c modfile3.c | |
| 652 OBJS=$(SRCS:.c=.o) | |
| 653 | |
| 654 all: sample.ell | |
| 655 clean: | |
| 656 rm -f $(OBJS) sample_init.o sample.ell | |
| 657 | |
| 658 install: all | |
| 659 mkdir `ellcc --mod-location`/mymods > /dev/null | |
| 660 cp sample.ell `ellcc --mod-location`/mymods/sample.ell | |
| 661 | |
| 662 sample.ell: $(OBJS) sample_init.o | |
| 663 $(LD) --mod-output=$@ $(OBJS) sample_init.o | |
| 664 | |
| 665 sample_init.o: sample_init.c | |
| 666 sample_init.c: $(SRCS) | |
| 667 $(MODINIT) --mod-name=$(MODNAME) --mod-version=$(MODVER) \ | |
| 668 --mod-title=$(MODTITLE) --mod-output=$@ $(SRCS) | |
| 669 @end cartouche | |
| 670 @end example | |
| 671 | |
| 672 The above @file{Makefile} is, in fact, complete, and would compile the | |
| 673 sample module, and optionally install it. The @code{--mod-location} | |
| 674 argument to @code{ellcc} will produce, on the standard output, the base | |
| 675 location of the @value{emacs} module directory. Each sub-directory of that | |
| 625 | 676 directory is automatically searched for modules when they are loaded with |
| 677 @code{load-module}. An alternative location would be | |
| 678 @file{/usr/local/lib/xemacs/site-modules}. That path can change depending | |
| 679 on the options the person who compiled @value{emacs} chose, so you can | |
| 680 always determine the correct site location using the | |
| 681 @code{--mod-site-location} option. This directory is treated the same way | |
| 682 as the main module directory. Each sub-directory within it is searched for | |
| 683 a given module when the user attempts to load it. The valid extensions that | |
| 684 the loader attempts to use are @file{.so}, @file{.ell} and @file{.dll}. You | |
| 685 can use any of these extensions, although @file{.ell} is the preferred | |
| 686 extension. | |
| 428 | 687 |
| 688 @node Link Mode, Other ellcc options, Initialization Mode, Using ellcc | |
| 689 @section Link Mode | |
| 690 @cindex linking | |
| 691 | |
| 692 Once all of your source code files have been compiled (including the | |
| 442 | 693 generated init file) you need to link them all together to create the |
| 428 | 694 loadable module. To do this, you invoke @code{ellcc} in link mode, by |
| 450 | 695 passing the @code{--mode=link} option. You need to specify the final |
| 442 | 696 output file using the @code{--mod-output=NAME} option, but other than |
| 428 | 697 that all other arguments are passed on directly to the system compiler |
| 698 or linker, along with any other required arguments to create the | |
| 699 loadable module. | |
| 700 | |
| 701 The module has complete access to all symbols that were present in the | |
| 702 dumped @value{emacs}, so you do not need to link against libraries that were | |
| 703 linked in with the main executable. If your library uses some other | |
| 704 extra libraries, you will need to link with those. There is nothing | |
| 705 particularly complicated about link mode. All you need to do is make | |
| 706 sure you invoke it correctly in the @file{Makefile}. See the sample | |
| 707 @file{Makefile} above for an example of a well constructed | |
| 708 @file{Makefile} that invoked the linker correctly. | |
| 709 | |
| 710 @node Other ellcc options, Environment Variables, Link Mode, Using ellcc | |
| 711 @section Other @code{ellcc} options | |
| 712 @cindex paths | |
| 713 | |
| 714 Aside from the three main @code{ellcc} modes described above, | |
| 715 @code{ellcc} can accept several other options. These are typically used | |
| 442 | 716 in a @file{Makefile} to determine installation paths. @code{ellcc} also |
| 428 | 717 allows you to over-ride several of its built-in compiler and linker |
| 718 options using environment variables. Here is the complete list of | |
| 719 options that @code{ellcc} accepts. | |
| 720 | |
| 721 @table @code | |
| 722 @item --mode=compile | |
| 723 Enables compilation mode. Use this to compile source modules. | |
| 724 | |
| 725 @item --mode=link | |
| 726 Enabled link edit mode. Use this to create the final module. | |
| 727 | |
| 728 @item --mode=init | |
| 729 Used to create the documentation function and to initialize other | |
| 442 | 730 required variables. Produces a C source file that must be compiled with |
| 428 | 731 @code{ellcc} in compile mode before linking the final module. |
| 732 | |
| 733 @item --mode=verbose | |
| 734 Enables verbose mode. This will show you the commands that are being | |
| 442 | 735 executed, as well as the version number of @code{ellcc}. If you specify |
| 428 | 736 this option twice, then some extra debugging information is displayed. |
| 737 | |
| 738 @item --mod-name=NAME | |
| 442 | 739 Sets the short internal module @var{NAME} to the string specified, |
| 428 | 740 which must consist only of valid C identifiers. Required during |
| 741 initialization mode. | |
| 742 | |
| 743 @item --mod-version=VERSION | |
| 744 Sets the internal module @var{VERSION} to the specified string. | |
| 745 Required during initialization mode. | |
| 746 | |
| 747 @item --mod-title=TITLE | |
| 748 Sets the module descriptive @var{TITLE} to the string specified. This | |
| 749 string can contain any printable characters, but should not be too | |
| 750 long. It is required during initialization mode. | |
| 751 | |
| 752 @item --mod-output=FILENAME | |
| 753 Used to control the output file name. This is used during | |
| 754 initialization mode to set the name of the C source file that will be | |
| 755 created to @var{FILENAME}. During link mode, it sets the name of the | |
| 756 final loadable module to @var{FILENAME}. | |
| 757 | |
| 758 @item --mod-location | |
| 442 | 759 This will print the name of the standard module installation path on the |
| 428 | 760 standard output and immediately exit @code{ellcc}. Use this option to |
| 761 determine the directory prefix of where you should install your modules. | |
| 762 | |
| 763 @item --mod-site-location | |
| 764 This will print the name of the site specific module location and exit. | |
| 765 | |
| 766 @item --mod-archdir | |
| 442 | 767 Prints the name of the root of the architecture-dependent directory that |
| 768 @value{emacs} searches for architecture-dependent files. | |
| 428 | 769 |
| 770 @item --mod-config | |
| 442 | 771 Prints the name of the configuration for which @value{emacs} and @code{ellcc} |
| 428 | 772 were compiled. |
| 773 @end table | |
| 774 | |
| 775 @node Environment Variables, , Other ellcc options, Using ellcc | |
| 776 @section Environment Variables | |
| 777 @cindex environment variables | |
| 778 | |
| 779 During its normal operation, @code{ellcc} uses the compiler and linker | |
| 780 flags that were determined at the time @value{emacs} was configured. In | |
| 442 | 781 certain rare circumstances you may wish to over-ride the flags passed to |
| 428 | 782 the compiler or linker, and you can do so using environment variables. |
| 442 | 783 The table below lists all of the environment variables that @code{ellcc} |
| 784 recognizes. | |
| 428 | 785 |
| 786 @table @code | |
| 787 @item ELLCC | |
| 788 @cindex @code{ELLCC} | |
| 789 This is used to over-ride the name of the C compiler that is invoked by | |
| 790 @code{ellcc}. | |
| 791 | |
| 792 @item ELLLD | |
| 793 @cindex @code{ELLLD} | |
| 794 Sets the name of the link editor to use to created the final module. | |
| 795 | |
| 796 @item ELLCFLAGS | |
| 797 @cindex @code{ELLCFLAGS} | |
| 798 Sets the compiler flags passed on when compiling source modules. This | |
| 799 only sets the basic C compiler flags. There are certain hard-coded | |
| 800 flags that will always be passed. | |
| 801 | |
| 802 @item ELLLDFLAGS | |
| 803 @cindex @code{ELLLDFLAGS} | |
| 804 Sets the flags passed on to the linker. This does @strong{not} include | |
| 805 the flags for enabling PIC mode. This just sets basic linker flags. | |
| 806 | |
| 807 @item ELLDLLFLAGS | |
| 808 @cindex @code{ELLDLLFLAGS} | |
| 809 Sets the flags passed to the linker that are required to created shared | |
| 810 and loadable objects. | |
| 811 | |
| 812 @item ELLPICFLAGS | |
| 813 @cindex @code{ELLPICFLAGS} | |
| 814 Sets the C compiler option required to produce an object file that is | |
| 815 suitable for including in a shared library. This option should turn on | |
| 816 PIC mode, or the moral equivalent thereof on the target system. | |
| 817 | |
| 818 @item ELLMAKEDOC | |
| 819 @cindex @code{ELLMAKEDOC} | |
| 820 Sets the name of the @file{make-docfile} program to use. Usually | |
| 821 @code{ellcc} will use the version that was compiled and installed with | |
| 822 @value{emacs}, but this option allows you to specify an alternative path. | |
| 823 Used during the compile phase of @value{emacs} itself. | |
| 824 @end table | |
| 825 | |
| 2972 | 826 @node Distribution with XEmacs, Defining Functions, Using ellcc, Top |
| 827 @chapter Adding Modules to the XEmacs Distribution | |
| 828 @cindex XEmacs integration | |
| 829 @cindex integration, XEmacs | |
| 830 @cindex modules and configure.ac | |
| 831 @cindex configure.ac, modules and | |
| 832 @cindex modules and Makefiles | |
| 833 @cindex Makefiles, modules and | |
| 834 | |
| 835 #### This section needs to be filled out. | |
| 836 | |
| 837 @strong{Warning: The procedure described in the section is subject to | |
| 838 change, as it is very stylized and thus a good candidate for further | |
| 839 automation.} | |
| 840 | |
| 841 Modules distributed with XEmacs are placed in the @file{modules} | |
| 842 subdirectory of the root of the source tree. Each module's code is | |
| 843 placed in a separate subdirectory. The build infrastructure for a | |
| 844 module consists of a @file{Makefile.in.in}, a @file{configure.ac}, and | |
| 845 @file{install-sh}. @file{install-sh} is a constant, and may simply be | |
| 846 copied from an existing module. | |
| 847 | |
| 848 Most of the job of building a module is encapsulated in | |
| 849 @file{modules/common/Makefile.common} and in @file{ellcc}. The module's | |
| 850 @file{Makefile.in.in} normally needs only to define module name and | |
| 851 version information, and include @file{modules/common/Makefile.common}. | |
| 852 The @file{configure.ac} is very module-specific, and little can be said | |
| 853 about its contents. However, since no logic that depends on XEmacs | |
| 854 itself or other modules needs to be present, it is easier to write and | |
| 855 maintain than if it were contained in the XEmacs distribution's | |
| 856 @file{configure.ac}. | |
| 857 | |
| 858 Modules can usually be trivially built in to the XEmacs binary. To make | |
| 859 this work, you need to duplicate the detection logic for any resources | |
| 860 the module requires in the top-level @file{configure.ac}. Since module | |
| 861 objects may be linked into modules or into @file{xemacs}, instead of | |
| 862 adding library path and library information directly to some | |
| 863 @file{@var{subsystem}_libs} variable, you should add them to a | |
| 864 @file{@var{module}_libs} variable, which in turn must be added to | |
| 865 @code{ld_libs_module} in the section ``Compute SUBST-itutable variables.'' | |
| 866 | |
| 867 Furthermore, in @file{src/Makefile.in.in} you add rules to build the | |
| 868 object without the module wrapper, and conditionalize these and the | |
| 869 addition of the object to @code{objs} on @code{HAVE_SHLIB}. The right | |
| 870 way to do this is somewhat indirect. Study the integration of LDAP and | |
| 871 PostgreSQL for the details. | |
| 872 | |
| 873 | |
| 874 @node Defining Functions, Defining Variables, Distribution with XEmacs, Top | |
| 428 | 875 @chapter Defining Functions |
| 876 @cindex defining functions | |
| 877 | |
| 878 One of the main reasons you would ever write a module is to | |
| 879 provide one or more @dfn{functions} for the user or the editor to use. | |
| 442 | 880 The term |
| 428 | 881 @dfn{function} is a bit overloaded here, as it refers to both a C |
| 882 function and the way it appears to Lisp, which is a @dfn{subroutine}, or | |
| 883 simply a @dfn{subr}. A Lisp subr is also known as a Lisp primitive, but | |
| 884 that term applies less to dynamic modules. @xref{Writing Lisp | |
| 885 Primitives,,,internals,@value{emacs} Internals Manual}, for details on how to | |
| 886 declare functions. You should familiarize yourself with the | |
| 442 | 887 instructions there. The format of the function declaration is identical |
| 428 | 888 in modules. |
| 889 | |
| 442 | 890 Normal Lisp primitives document the functions they defining by including |
| 428 | 891 the documentation as a C comment. During the build process, a program |
| 892 called @file{make-docfile} is run, which will extract all of these | |
| 893 comments, build up a single large documentation file, and will store | |
| 894 pointers to the start of each documentation entry in the dumped @value{emacs}. | |
| 895 This, of course, will not work for dynamic modules, as they are loaded | |
| 896 long after @value{emacs} has been dumped. For this reason, we require a | |
| 897 special means for adding documentation for new subrs. This is what the | |
| 898 macro @code{CDOCSUBR} is used for, and this is used extensively during | |
| 899 @code{ellcc} initialization mode. | |
| 900 | |
| 901 When using @code{DEFUN} in normal @value{emacs} C code, the sixth | |
| 902 ``parameter'' is a C comment which documents the function. For a | |
| 903 dynamic module, we of course need to convert the C comment to a usable | |
| 442 | 904 string, and we need to set the documentation pointer of the subr to this |
| 428 | 905 string. As a module programmer, you don't actually need to do any work |
| 906 for this to happen. It is all taken care of in the | |
| 907 @code{docs_of_module} function created by @code{ellcc}. | |
| 908 | |
| 909 @menu | |
| 910 * Using DEFUN:: Using the DEFUN macro to define functions | |
| 911 * Declaring Functions:: Declaring functions to the Lisp reader | |
| 912 @end menu | |
| 913 | |
| 914 @node Using DEFUN, Declaring Functions, Defining Functions, Defining Functions | |
| 915 @section Using @code{DEFUN} | |
| 916 @cindex subrs | |
| 917 @findex DEFUN | |
| 918 @cindex functions, Lisp | |
| 919 @cindex functions, defining | |
| 920 | |
| 775 | 921 The full syntax of a function declaration is discussed in the |
| 922 @value{emacs} internals manual in greater depth. @ref{Writing Lisp | |
| 923 Primitives,,,internals,@value{emacs} Internals Manual}. What follows is | |
| 924 a brief description of how to define and implement a new Lisp primitive | |
| 925 in a module. This is done using the @code{DEFUN} macro. Here is a | |
| 926 small example: | |
| 428 | 927 |
| 928 @example | |
| 929 @cartouche | |
| 930 DEFUN ("my-function", Fmy_function, 1, 1, "FFile name: ", /* | |
| 931 Sample Emacs primitive function. | |
| 932 | |
| 442 | 933 The specified FILE is frobnicated before it is fnozzled. |
| 428 | 934 */ |
| 935 (file)) | |
| 936 @{ | |
| 937 char *filename; | |
| 938 | |
| 939 if (NILP(file)) | |
| 940 return Qnil; | |
| 941 | |
| 942 filename = (char *)XSTRING_DATA(file); | |
| 943 frob(filename); | |
| 944 return Qt; | |
| 945 @} | |
| 946 @end cartouche | |
| 947 @end example | |
| 948 | |
| 949 The first argument is the name of the function as it will appear to the | |
| 442 | 950 Lisp reader. This must be provided as a string. The second argument is |
| 428 | 951 the name of the actual C function that will be created. This is |
| 442 | 952 typically the Lisp function name with a preceding capital @code{F}, with |
| 428 | 953 hyphens converted to underscores. This must be a valid C function |
| 954 name. Next come the minimum and maximum number of arguments, | |
| 955 respectively. This is used to ensure that the correct number of | |
| 956 arguments are passed to the function. Next is the @code{interactive} | |
| 957 definition. If this function is meant to be run by a user | |
| 958 interactively, then you need to specify the argument types and prompts | |
| 959 in this string. Please consult the @value{emacs} Lisp manual for more | |
| 960 details. Next comes a C comment that is the documentation for this | |
| 961 function. This comment @strong{must} exist. Last comes the list of | |
| 962 function argument names, if any. | |
| 963 | |
| 964 @node Declaring Functions, , Using DEFUN, Defining Functions | |
| 965 @section Declaring Functions | |
| 966 @findex DEFSUBR | |
| 967 @cindex functions, declaring | |
| 968 | |
| 969 Simply writing the code for a function is not enough to make it | |
| 442 | 970 available to the Lisp reader. You have to, during module |
| 428 | 971 initialization, let the Lisp reader know about the new function. This |
| 972 is done by calling @code{DEFSUBR} with the name of the function. This | |
| 973 is the sole purpose of the initialization function | |
| 974 @code{syms_of_module}. @xref{Required Functions}, for more details. | |
| 975 | |
| 976 Each call to @code{DEFSUBR} takes as its only argument the name of the | |
| 977 function, which is the same as the second argument to the call to | |
| 978 @code{DEFUN}. Using the example function above, you would insert the | |
| 979 following code in the @code{syms_of_module} function: | |
| 980 | |
| 981 @example | |
| 982 @cartouche | |
| 983 DEFSUBR(Fmy_function); | |
| 984 @end cartouche | |
| 985 @end example | |
| 986 | |
| 987 This call will instruct @value{emacs} to make the function visible to the Lisp | |
| 988 reader and will prepare for the insertion of the documentation into | |
| 989 the right place. Once this is done, the user can call the Lisp | |
| 990 function @code{my-function}, if it was defined as an interactive | |
| 991 function (which in this case it was). | |
| 992 | |
| 4312 | 993 That's all there is to defining and announcing new functions. The rules |
| 428 | 994 for what goes inside the functions, and how to write good modules, is |
| 995 beyond the scope of this document. Please consult the @value{emacs} | |
| 996 internals manual for more details. | |
| 997 | |
| 998 @node Defining Variables, Index, Defining Functions, Top | |
| 999 @chapter Defining Variables | |
| 1000 @cindex defining variables | |
| 1001 @cindex defining objects | |
| 1002 @findex DEFVAR_LISP | |
| 1003 @findex DEFVAR_BOOL | |
| 1004 @findex DEFVAR_INT | |
| 1005 @cindex variables, Lisp | |
| 1006 @cindex variables, defining | |
| 1007 @cindex objects, defining | |
| 1008 @cindex objects, Lisp | |
| 1009 | |
| 1010 Rarely will you write a module that only contains functions. It is | |
| 1011 common to also provide variables which can be used to control the | |
| 442 | 1012 behavior of the function, or store the results of the function being |
| 428 | 1013 executed. The actual C variable types are the same for modules |
| 1014 and internal @value{emacs} primitives, and the declaration of the variables | |
| 1015 is identical. | |
| 1016 | |
| 442 | 1017 @xref{Adding Global Lisp Variables,,,internals,XEmacs Internals Manual}, |
| 428 | 1018 for more information on variables and naming conventions. |
| 1019 | |
| 1020 Once your variables are defined, you need to initialize them and make | |
| 1021 the Lisp reader aware of them. This is done in the | |
| 1022 @code{vars_of_module} initialization function using special @value{emacs} | |
| 442 | 1023 macros such as @code{DEFVAR_LISP}, @code{DEFVAR_BOOL}, @code{DEFVAR_INT} |
| 1024 etc. The best way to see how to use these macros is to look at existing | |
| 428 | 1025 source code, or read the internals manual. |
| 1026 | |
| 1027 One @emph{very} important difference between @value{emacs} variables and | |
| 1028 module variables is how you use pure space. Simply put, you | |
| 1029 @strong{never} use pure space in @value{emacs} modules. The pure space | |
| 442 | 1030 storage is of a limited size, and is initialized properly during the |
| 428 | 1031 dumping of @value{emacs}. Because variables are being added dynamically to |
| 1032 an already running @value{emacs} when you load a module, you cannot use pure | |
| 1033 space. Be warned: @strong{do not use pure space in modules. Repeat, do | |
| 1034 not use pure space in modules.} Once again, to remove all doubts: | |
| 1035 @strong{DO NOT USE PURE SPACE IN MODULES!!!} | |
| 1036 | |
| 1037 Below is a small example which declares and initializes two | |
| 1038 variables. You will note that this code takes into account the fact | |
| 1039 that this module may very well be compiled into @value{emacs} itself. This | |
| 1040 is a prudent thing to do. | |
| 1041 | |
| 1042 @example | |
| 1043 @cartouche | |
| 1044 Lisp_Object Vsample_string; | |
| 1045 int sample_boolean; | |
| 1046 | |
| 1047 void | |
| 1048 vars_of_module() | |
| 1049 @{ | |
| 1050 DEFVAR_LISP ("sample-string", &Vsample_string /* | |
| 1051 This is a sample string, declared in a module. | |
| 1052 | |
| 1053 Nothing magical about it. | |
| 1054 */); | |
| 1055 | |
| 1056 DEFVAR_BOOL("sample-boolean", &sample_boolean /* | |
| 1057 *Sample user-settable boolean. | |
| 1058 */); | |
| 1059 | |
| 1060 sample_boolean = 0; | |
|
4953
304aebb79cd3
function renamings to track names of char typedefs
Ben Wing <ben@xemacs.org>
parents:
4312
diff
changeset
|
1061 Vsample_string = build_ascstring ("My string"); |
| 428 | 1062 @} |
| 1063 @end cartouche | |
| 1064 @end example | |
| 1065 | |
| 1066 @c Print the tables of contents | |
| 1067 @contents | |
| 1068 @c That's all | |
| 1069 | |
| 1070 @node Index, , Defining Variables, Top | |
| 1071 @unnumbered Index | |
| 1072 | |
| 1073 @printindex cp | |
| 1074 | |
| 1075 @bye | |
| 1076 |