Mercurial > hg > xemacs-beta
annotate man/emodules.texi @ 4953:304aebb79cd3
function renamings to track names of char typedefs
-------------------- ChangeLog entries follow: --------------------
man/ChangeLog addition:
2010-01-27 Ben Wing <ben@xemacs.org>
* internals/internals.texi (lrecords):
* internals/internals.texi (The DFC API):
* internals/internals.texi (Conversion to and from External Data):
* internals/internals.texi (Mule-izing Code):
* internals/internals.texi (Pervasive changes throughout XEmacs sources):
* internals/internals.texi (Ben's README):
* internals/internals.texi (Future Work -- Localized Text/Messages):
* emodules.texi (Defining Variables):
Rename:
write_c_string -> write_cistring
build_intstring -> build_istring
build_string -> build_cistring
build_ext_string -> build_extstring
make_ext_string -> make_extstring
buffer_insert_c_string -> buffer_insert_ascstring
intern_int -> intern_istring
See comment in src/ChangeLog about this.
modules/ChangeLog addition:
2010-01-27 Ben Wing <ben@xemacs.org>
* postgresql/postgresql.c (print_pgconn):
* postgresql/postgresql.c (print_pgresult):
* postgresql/postgresql.c (Fpq_conn_defaults):
* postgresql/postgresql.c (Fpq_pgconn):
* postgresql/postgresql.c (Fpq_res_status):
* postgresql/postgresql.c (Fpq_result_error_message):
* postgresql/postgresql.c (Fpq_fname):
* postgresql/postgresql.c (Fpq_get_value):
* postgresql/postgresql.c (Fpq_cmd_status):
* postgresql/postgresql.c (Fpq_cmd_tuples):
* postgresql/postgresql.c (Fpq_notifies):
* postgresql/postgresql.c (Fpq_get_line):
* postgresql/postgresql.c (Fpq_get_line_async):
* postgresql/postgresql.c (FROB):
* postgresql/postgresql.c (init_postgresql_from_environment):
* ldap/eldap.c:
* ldap/eldap.c (Fldap_open):
* ldap/eldap.c (Fldap_search_basic):
* canna/canna_api.c:
* canna/canna_api.c (make_euc_string):
Rename:
write_c_string -> write_cistring
build_intstring -> build_istring
build_string -> build_cistring
build_ext_string -> build_extstring
make_ext_string -> make_extstring
buffer_insert_c_string -> buffer_insert_ascstring
intern_int -> intern_istring
See comment in src/ChangeLog about this.
src/ChangeLog addition:
2010-01-27 Ben Wing <ben@xemacs.org>
* .gdbinit.in.in:
* README:
* abbrev.c (write_abbrev):
* abbrev.c (describe_abbrev):
* alloc.c (make_extstring):
* alloc.c (build_istring):
* alloc.c (build_cistring):
* alloc.c (build_ascstring):
* alloc.c (build_extstring):
* alloc.c (build_msg_istring):
* alloc.c (build_defer_istring):
* buffer.c (Fgenerate_new_buffer_name):
* buffer.c (init_buffer_2):
* console-tty.c (tty_init_console):
* console-x.c (get_display_arg_connection):
* console-x.c (x_perhaps_init_unseen_key_defaults):
* database.c (dbm_map):
* database.c (dbm_get):
* database.c (berkdb_get):
* database.c (berkdb_map):
* device-gtk.c (FROB_PIXMAP):
* device-gtk.c (Fgtk_style_info):
* device-msw.c (msprinter_default_printer):
* device-msw.c (sync_printer_with_devmode):
* device-x.c (coding_system_of_xrm_database):
* device-x.c (x_init_device):
* device-x.c (signal_if_x_error):
* device-x.c (Fx_get_resource):
* device-x.c (Fx_server_vendor):
* device-x.c (Fx_get_font_path):
* dialog-x.c (maybe_run_dbox_text_callback):
* doc.c (extract_object_file_name):
* doc.c (unparesseuxify_doc_string):
* doc.c (get_doc_string):
* doc.c (get_object_file_name):
* doc.c (Fdocumentation):
* doc.c (Fsnarf_documentation):
* doc.c (Fsubstitute_command_keys):
* editfns.c (init_editfns):
* editfns.c (Ftemp_directory):
* editfns.c (Fuser_login_name):
* editfns.c (Fuser_real_login_name):
* editfns.c (Fuser_home_directory):
* editfns.c (Fformat_time_string):
* editfns.c (Fcurrent_time_string):
* editfns.c (Fcurrent_time_zone):
* emacs.c:
* emacs.c (main_1):
* emodules.c (Flist_modules):
* emodules.c (emodules_load):
* emodules.c (emodules_doc_sym):
* emodules.c (vars_of_module):
* event-Xt.c (x_has_keysym):
* event-gtk.c (emacs_gtk_format_magic_event):
* event-gtk.c (dragndrop_data_received):
* event-gtk.c (gtk_reset_key_mapping):
* event-msw.c (mswindows_dde_callback):
* event-msw.c (mswindows_wnd_proc):
* faces.c (complex_vars_of_faces):
* file-coding.c (find_coding_system):
* file-coding.c (setup_eol_coding_systems):
* file-coding.c (make_coding_system_1):
* file-coding.c (snarf_coding_system):
* fileio.c:
* fileio.c (lisp_strerror):
* fileio.c (Ffile_name_directory):
* fileio.c (Ffile_name_as_directory):
* fileio.c (Fdirectory_file_name):
* fileio.c (if):
* fileio.c (Ffile_symlink_p):
* fileio.c (Fencrypt_string):
* fileio.c (Fdecrypt_string):
* filelock.c (lock_file):
* filelock.c (Ffile_locked_p):
* floatfns.c (matherr):
* font-mgr.c (build_fcapi_string):
* font-mgr.c (make_xlfd_font_regexp):
* frame-msw.c (mswindows_window_id):
* frame-msw.c (mswindows_frame_property):
* frame-x.c:
* frame-x.c (color_to_string):
* frame-x.c (maybe_set_frame_title_format):
* frame-x.c (x_cde_transfer_callback):
* frame-x.c (Fx_window_id):
* glade.c (connector):
* glade.c (Fglade_xml_textdomain):
* glade.c (syms_of_glade):
* glyphs-eimage.c (jpeg_instantiate):
* glyphs-eimage.c (png_instantiate):
* glyphs-eimage.c (tiff_instantiate):
* glyphs-gtk.c (font_instantiate):
* glyphs-gtk.c (BUILD_GLYPH_INST):
* glyphs-x.c (x_locate_pixmap_file):
* glyphs-x.c (font_instantiate):
* glyphs-x.c (x_widget_property):
* glyphs-x.c (BUILD_GLYPH_INST):
* glyphs.c (print_image_instance):
* glyphs.c (bitmap_to_lisp_data):
* glyphs.c (pixmap_to_lisp_data):
* gpmevent.c (turn_off_gpm):
* gpmevent.c (Fgpm_enabled_p):
* gpmevent.c (Fgpm_enable):
* gtk-glue.c (__make_string_mapper):
* gtk-glue.c (xemacs_gtklist_to_list):
* gtk-xemacs.c (FROB_FACE):
* gtk-xemacs.c (xemacs_gtk_convert_color):
* hpplay.c (player_error_internal):
* hpplay.c (myHandler):
* insdel.c (buffer_insert_ascstring_1):
* insdel.h:
* insdel.h (buffer_insert_ascstring):
* intl.c (Fcurrent_locale):
* intl.c (Fset_current_locale):
* keymap.c (make_key_description):
* keymap.c (Ftext_char_description):
* keymap.c (describe_command):
* keymap.c (describe_map):
* lisp.h:
* lread.c:
* lread.c (locate_file_in_directory_mapper):
* lread.c (locate_file_construct_suffixed_files_mapper):
* mule-charset.c (Fmake_charset):
* nt.c (Fmswindows_short_file_name):
* nt.c (Fmswindows_long_file_name):
* objects-gtk.c (__get_gtk_font_truename):
* objects-gtk.c (__gtk_font_list_internal):
* objects-msw.c (font_enum_callback_2):
* objects-msw.c (create_hfont_from_font_spec):
* objects-msw.c (mswindows_font_list):
* objects-msw.c (mswindows_font_spec_matches_charset_stage_2):
* objects-tty.c (tty_initialize_font_instance):
* objects-x.c (x_font_truename):
* objects-x.c (x_font_instance_truename):
* objects-x.c (x_font_instance_properties):
* objects-x.c (x_font_list):
* print.c (write_cistring):
* print.c (print_vector_internal):
* print.c (print_cons):
* process-nt.c (nt_canonicalize_host_name):
* process-unix.c (unix_create_process):
* process-unix.c (unix_canonicalize_host_name):
* process.c (status_message):
* process.c (status_notify):
* process.c (init_xemacs_process):
* process.c (syms_of_process):
* redisplay-tty.c (term_get_fkeys_1):
* redisplay-tty.c (CONDITIONAL_REASSIGN):
* search.c (compile_pattern_1):
* select-common.h (selection_data_to_lisp_data):
* select-gtk.c (atom_to_symbol):
* select-gtk.c (PROCESSING_GTK_CODE):
* select-msw.c (mswindows_get_foreign_selection):
* select-x.c (x_atom_to_symbol):
* select-x.c (Fx_get_cutbuffer_internal):
* symbols.c (intern_istring):
* symbols.c (intern):
* symbols.c (intern_converting_underscores_to_dashes):
* symbols.c (Fintern):
* sysdep.c (init_system_name):
* sysdll.c (dll_error):
* sysdll.c (dll_open):
* syswindows.h:
* syswindows.h (build_tstr_string):
* tests.c (DFC_CHECK_LENGTH):
* tests.c (DFC_CHECK_CONTENT):
* tests.c (DFC_RESULT_PASS):
* tests.c (Ftest_data_format_conversion):
* text.c:
* text.c (new_dfc_convert_now_damn_it):
* text.h:
* text.h (build_wext_string):
* tooltalk.c (tt_build_c_string):
* tooltalk.c (Ftooltalk_default_procid):
* tooltalk.c (Ftooltalk_default_session):
* tooltalk.c (init_tooltalk):
* ui-byhand.c (Fgtk_clist_get_text):
* ui-byhand.c (Fgtk_clist_get_pixtext):
* ui-byhand.c (Fgtk_label_get):
* ui-byhand.c (Fgtk_notebook_query_tab_label_packing):
* ui-gtk.c (emacs_gtk_object_printer):
* ui-gtk.c (emacs_gtk_boxed_printer):
* ui-gtk.c (gtk_type_to_lisp):
* ui-gtk.c (symbol_to_enum):
* ui-gtk.c (enum_to_symbol):
* unexaix.c (report_error):
* unexaix.c (ERROR0):
* unexec.c (report_error):
* unexec.c (ERROR0):
* unicode.c (unicode_to_ichar):
* win32.c (tstr_to_local_file_format):
* win32.c (Fmswindows_cygwin_to_win32_path):
* win32.c (struct read_link_hash):
* xemacs.def.in.in:
Rename:
write_c_string -> write_cistring
build_intstring -> build_istring
build_string -> build_cistring
build_ext_string -> build_extstring
make_ext_string -> make_extstring
buffer_insert_c_string -> buffer_insert_ascstring
intern_int -> intern_istring
These functions have been renamed so that the naming harmonizes
with the typedefs for strings: `cistring' along with CIbyte *,
`istring' along with Ibyte *, `extstring' along with Extbyte *,
`ascstring' along with Ascbyte *.
Also make buffer_insert_ascstring take Ascbyte * and assert
that its argument is ASCII.
| author | Ben Wing <ben@xemacs.org> |
|---|---|
| date | Wed, 27 Jan 2010 00:35:36 -0600 |
| parents | 1094d6d400fb |
| 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 |