/[guile]/guile/guile-core/doc/ref/scheme-modules.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scheme-modules.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.9 by ghouston, Tue Jul 9 22:40:03 2002 UTC revision 1.10 by ghouston, Wed Jul 10 22:21:25 2002 UTC
# Line 76  module system. Line 76  module system.
76    
77  In 1996 Tom Lord implemented a full-featured module system for Guile which  In 1996 Tom Lord implemented a full-featured module system for Guile which
78  allows loading Scheme source files into a private name space.  This system has  allows loading Scheme source files into a private name space.  This system has
79  been in available since Guile version 1.4.  been in available since at least Guile version 1.1.
 @c fixme: Actually, was it available before?  1.4 seems a bit late...  
80    
81  For Guile version 1.5.0 and later, the system has been improved to have better  For Guile version 1.5.0 and later, the system has been improved to have better
82  integration from C code, more fine-grained user control over interfaces, and  integration from C code, more fine-grained user control over interfaces, and
# Line 500  When using the low level procedures to d Line 499  When using the low level procedures to d
499  complete control over which library is loaded when and what gets done  complete control over which library is loaded when and what gets done
500  with it.  with it.
501    
502  @deffn {Scheme Procedure} dynamic-link library  @deffn {Scheme Procedure} dynamic-link filename
503  @deffnx {C Function} scm_dynamic_link (library)  @deffnx {C Function} scm_dynamic_link (filename)
504  Find the shared library denoted by @var{library} (a string) and link it  Find the shared object (shared library) denoted by
505  into the running Guile application.  When everything works out, return a  @var{filename} and link it into the running Guile
506  Scheme object suitable for representing the linked object file.  application.  The returned
507  Otherwise an error is thrown.  How object files are searched is system  scheme object is a ``handle'' for the library which can
508  dependent.  be passed to @code{dynamic-func}, @code{dynamic-call} etc.
509    
510  Normally, @var{library} is just the name of some shared library file  Searching for object files is system dependent.  Normally,
511  that will be searched for in the places where shared libraries usually  if @var{filename} does have an explicit directory it will
512  reside, such as in @file{/usr/lib} and @file{/usr/local/lib}.  be searched for in locations
513    such as @file{/usr/lib} and @file{/usr/local/lib}.
514  @end deffn  @end deffn
515    
516  @deffn {Scheme Procedure} dynamic-object? obj  @deffn {Scheme Procedure} dynamic-object? obj
517  @deffnx {C Function} scm_dynamic_object_p (obj)  @deffnx {C Function} scm_dynamic_object_p (obj)
518  Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}  Return @code{#t} if @var{obj} is a dynamic object handle,
519  otherwise.  or @code{#f} otherwise.
520  @end deffn  @end deffn
521    
522  @deffn {Scheme Procedure} dynamic-unlink dobj  @deffn {Scheme Procedure} dynamic-unlink dobj
523  @deffnx {C Function} scm_dynamic_unlink (dobj)  @deffnx {C Function} scm_dynamic_unlink (dobj)
524  Unlink the indicated object file from the application.  The  Unlink a dynamic object from the application, if possible.  The
525  argument @var{dobj} must have been obtained by a call to  object must have been linked by @code{dynamic-link}, with
526  @code{dynamic-link}.  After @code{dynamic-unlink} has been  @var{dobj} the corresponding handle.  After this procedure
527  called on @var{dobj}, its content is no longer accessible.  is called, the handle can no longer be used to access the
528    object.
529  @end deffn  @end deffn
530    
531  @deffn {Scheme Procedure} dynamic-func name dobj  @deffn {Scheme Procedure} dynamic-func name dobj
532  @deffnx {C Function} scm_dynamic_func (name, dobj)  @deffnx {C Function} scm_dynamic_func (name, dobj)
533  Search the dynamic object @var{dobj} for the C function  Return a ``handle'' for the function @var{name} in the
534  indicated by the string @var{name} and return some Scheme  shared object referred to by @var{dobj}.  The handle
535  handle that can later be used with @code{dynamic-call} to  can be passed to @code{dynamic-call} to actually
536  actually call the function.  call the function.
537    
538  Regardless whether your C compiler prepends an underscore @samp{_} to  Regardless whether your C compiler prepends an underscore
539  the global names in a program, you should @strong{not} include this  @samp{_} to the global names in a program, you should
540  underscore in @var{function}.  Guile knows whether the underscore is  @strong{not} include this underscore in @var{name}
541  needed or not and will add it when necessary.  since it will be added automatically when necessary.
542  @end deffn  @end deffn
543    
544  @deffn {Scheme Procedure} dynamic-call func dobj  @deffn {Scheme Procedure} dynamic-call func dobj
# Line 583  converted to a Scheme number and returne Line 584  converted to a Scheme number and returne
584  When dynamic linking is disabled or not supported on your system,  When dynamic linking is disabled or not supported on your system,
585  the above functions throw errors, but they are still available.  the above functions throw errors, but they are still available.
586    
587  Here is a small example that works on GNU/Linux:  Here is a small example that may work on GNU/Linux:
588    
589  @smallexample  @smallexample
590  (define libc-obj (dynamic-link "libc.so"))  (define libc-obj (dynamic-link "libc.so"))
# Line 657  this current module. Line 658  this current module.
658    
659  Therefore, all we need to do is to make sure that the right module is  Therefore, all we need to do is to make sure that the right module is
660  current when calling @code{gh_new_procedure} for our new primitives.  current when calling @code{gh_new_procedure} for our new primitives.
 Unfortunately, there is not yet an easy way to access the module system  
 from C, so we are better off with a more indirect approach.  Instead of  
 adding our primitives at initialization time we merely register with  
 Guile that we are ready to provide the contents of a certain module,  
 should it ever be needed.  
   
 @deftypefun void scm_register_module_xxx (char *@var{name}, void (*@var{initfunc})(void))  
 Register with Guile that @var{initfunc} will provide the contents of the  
 module @var{name}.  
   
 The function @var{initfunc} should perform the usual initialization  
 actions for your new primitives, like calling @code{gh_new_procedure} or  
 including the file produced by the snarfer.  When @var{initfunc} is  
 called, the current module is a newly created module with a name as  
 indicated by @var{name}.  Each definition that is added to it will be  
 automatically exported.  
   
 The string @var{name} indicates the hierarchical name of the new module.  
 It should consist of the individual components of the module name  
 separated by single spaces.  That is, the Scheme module name @code{(foo  
 bar)}, which is a list, should be written as @code{"foo bar"} for the  
 @var{name} parameter.  
   
 You can call @code{scm_register_module_xxx} at any time, even before  
 Guile has been initialized.  This might be useful when you want to put  
 the call to it in some initialization code that is magically called  
 before main, like constructors for global C++ objects.  
   
 An example for @code{scm_register_module_xxx} appears in the next section.  
 @end deftypefun  
   
 Now, instead of calling the initialization function at program startup,  
 you should simply call @code{scm_register_module_xxx} and pass it the  
 initialization function.  When the named module is later requested by  
 Scheme code with @code{use-modules} for example, Guile will notice that  
 it knows how to create this module and will call the initialization  
 function at the right time in the right context.  
661    
662  @node Dynamic Linking and Compiled Code Modules  @node Dynamic Linking and Compiled Code Modules
663  @subsection Dynamic Linking and Compiled Code Modules  @subsection Dynamic Linking and Compiled Code Modules
# Line 774  Fun, isn't it?  But we are only half way Line 738  Fun, isn't it?  But we are only half way
738  As you can see, @code{j0} is contained in the root module, where all  As you can see, @code{j0} is contained in the root module, where all
739  the other Guile primitives like @code{display}, etc live.  In general,  the other Guile primitives like @code{display}, etc live.  In general,
740  a primitive is put into whatever module is the @dfn{current module} at  a primitive is put into whatever module is the @dfn{current module} at
741  the time @code{gh_new_procedure} is called.  To put @code{j0} into its  the time @code{gh_new_procedure} is called.
742  own module named @samp{(math bessel)}, we need to make a call to  
743  @code{scm_register_module_xxx}.  Additionally, to have Guile perform  A compiled module should have a specially named @dfn{module init
744  the dynamic linking automatically, we need to put @file{libbessel.so}  function}.  Guile knows about this special name and will call that
745  into a place where Guile can find it.  The call to  function automatically after having linked in the shared library.  For
746  @code{scm_register_module_xxx} should be contained in a specially  our example, we add the following code to @file{bessel.c}:
 named @dfn{module init function}.  Guile knows about this special name  
 and will call that function automatically after having linked in the  
 shared library.  For our example, we add the following code to  
 @file{bessel.c}:  
747    
748  @smallexample  @smallexample
749  void scm_init_math_bessel_module ()  void scm_init_math_bessel_module ()
750  @{  @{
751    scm_register_module_xxx ("math bessel", init_math_bessel);     /* contents currently unavailable.  */
752  @}  @}
753  @end smallexample  @end smallexample
754    
755  The general pattern for the name of a module init function is:  The general pattern for the name of a module init function is:
756  @samp{scm_init_}, followed by the name of the module where the  @samp{scm_init_}, followed by the name of the module where the
757  individual hierarchical components are concatenated with underscores,  individual hierarchical components are concatenated with underscores,
758  followed by @samp{_module}.  It should call  followed by @samp{_module}.
 @code{scm_register_module_xxx} with the correct module name and the  
 appropriate initialization function.  When that initialization function  
 will be called, a newly created module with the right name will be the  
 @emph{current module} so that all definitions that the initialization  
 functions makes will end up in the correct module.  
759    
760  After @file{libbessel.so} has been rebuild, we need to place the shared  After @file{libbessel.so} has been rebuild, we need to place the shared
761  library into the right place.  When Guile tries to autoload the  library into the right place.
762  @samp{(math bessel)} module, it looks not only for a file called  
763  @file{math/bessel.scm} in its @code{%load-path}, but also for  Once the module has been correctly installed, it should be possible to
764  @file{math/libbessel.so}.  So all we need to do is to create a directory  use it like this:
 called @file{math} somewhere in Guile's @code{%load-path} and place  
 @file{libbessel.so} there.  Normally, the current directory @file{.} is  
 in the @code{%load-path}, so we just use that for this example.  
765    
766  @smallexample  @smallexample
 % mkdir maths  
 % cd maths  
 % ln -s ../libbessel.so .  
 % cd ..  
 % guile  
767  guile> (use-modules (math bessel))  guile> (use-modules (math bessel))
768  guile> (j0 2)  guile> (j0 2)
769  0.223890779141236  0.223890779141236
# Line 826  guile> (apropos 'j0) Line 773  guile> (apropos 'j0)
773    
774  That's it!  That's it!
775    
 Note that we used a symlink to make @file{libbessel.so} appear in the  
 right spot.  This is probably not a bad idea in general.  The  
 directories that the @file{%load-path} normally contains are supposed to  
 contain only architecture independent files.  They are not really the  
 right place for a shared library.  You might want to install the  
 libraries somewhere below @samp{exec_prefix} and then symlink to them  
 from the architecture independent directory.  This will at least work on  
 heterogenous systems where the architecture dependent stuff resides in  
 the same place on all machines (which seems like a good idea to me  
 anyway).  
   
   
776  @node Variables  @node Variables
777  @section Variables  @section Variables
778  @tpindex Variables  @tpindex Variables

Legend:
Removed from v.1.9  
changed lines
  Added in v.1.10

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26