Yorick in its original version can include user defined C function in its kernel. This however has to be done by recompiling a full toplevel executable which is linked with the user provided functions. In this page, we give an overview of this classical approach, and of how the shared library approach differs, and what it provides.
Here is an example of how this can be done. You have a function my_func defined in one or several C source files. E.g. in files mf1.c and mf2.c
double my_func(double *v, int n)
{
[...]
return r;
}
|
you want to use under yorick.
To interface this with yorick, you write a yorick script file mf.i containing special comments:
/* MAKE-INSTRUCTIONS SRCS=mf1.c mf2.c */ extern myf; /* PROTOTYPE double my_func(double array v, int n); */ |
The SRCS entry lists the C files containing the functions, and the extern line is used to declare a yorick function implemented in C. The following prototype comment is used to specify the C prototype and name of the function you want to interface. So the function is called my_func in C, and will be named myf in yorick scripting.
Then, you type the three following commands:
[shell]$ rm -f Makefile [shell]$ yorick -batch make.i mf [shell]$ make |
The first command generates a makefile, and the second one compiles your code and links it with yorick to provide a new toplevel called mf.
You then launch the new toplevel yorick executable, which has a new function myf:
[shell]$ ./mf Copyright (c) 1996-2000. The Regents of the University of California. Copyright (c) 2000-2001. Centre de Morphologie Mathématique. All rights reserved. Yorick 1.5 ready. For help type 'help' > myf([1,2,3,4],4) 24 > |
This approach has a number of drawbacks: you have to build a new executable each time you want to have new functions into yorick. Also, if you want to use together C functions from different source at the same time you have to combine them together into a single project, manage conflicts, etc.
This is why a shared library building facility was added to Yorick-MB.
The method is similar to the previous one. We use the same files as above, the building process differs slightly:
[shell]$ rm -f Makefile [shell]$ yorick -batch make.i mf.so [shell]$ make |
Now, instead of having built an executable toplevel, you get a shared library mf.so. So you launch the standard yorick executable, and ask him to open the new shared library, which goes as follows:
[shell]$ yorick Copyright (c) 1996-2000. The Regents of the University of California. Copyright (c) 2000-2001. Centre de Morphologie Mathématique. All rights reserved. Yorick 1.5 ready. For help type 'help' > #include "mf.so" > myf([1,2,3,4],4) 24 > |
With this new facility, you can now package various functions into a shared library which will be used only on demand. You can of course use simultaneously several such shared libraries that have been built independently. The only (obvious) constraint is that you should not give the same yorick name to different functions. Additional functions can be distributed separately, which can be useful if there are license conflicts, or if some libraries have additional requirements.
As an example, a library providing jpeg image reading and writing to yorick is available from sourceforge. Typically, this functionality is packaged separately, and is only available on platforms where the jpeg library (libjpeg.so) is installed.
It is possible (from version 1.5.10) to reload shared libraries without quitting and restarting the yorick-mb session. yorick-mb takes cares ofthe necessary cleanups before actually unloading the older shared library and loading the new one.
This is useful in a development cycle where you are testing a function you wrote and update its C code and want to use it inside the same session without restarting yorick-mb
This works this way:
[shell]$ yorick Copyright (c) 1996-2000. The Regents of the University of California. Copyright (c) 2000-2001. Centre de Morphologie Mathématique. All rights reserved. Yorick 1.5 ready. For help type 'help' > #include "mf.so" > myf([1,2,3,4],4) 20 > |
Now at this point, you modify myf.c and myf.i to update the definition of myf and remake the library. Then to reload the newer version, type
> #include "myf.so" Reloading shared library "/home/user/yorick-files/myf.so" > myf([1,2,3,4],4) 24 |
Now suppose that another function 'mysum' was provided in the older version of myf.so and is not defined in the newer version any more. When you try to call mysum, you get
> mysum([1,2,3,4],4) ERROR (*main*) The shared object defining this function has been closed. WARNING source code unavailable (try dbdis function) now at pc= 1 (of 8), failed at pc= 3 To enter debug mode, type |