home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 493.lha / LibTool / CSimple / SimpleC.DOC < prev    next >
Encoding:
Text File  |  1991-04-06  |  8.7 KB  |  160 lines
  1.   This document describes how to make the simple.library C example.
  2.  
  3.   A shared library is a disk-based executable file that usually resides in
  4. the LIBS drawer of your boot disk. Such a library contains functions that
  5. your application can call, but which are not a part of your program. Many
  6. other applications can open and use the same shared library (usually simul-
  7. taneously), thus saving memory when the applications are run concurrently.
  8. Also, a shared library can help reduce development time in new products since
  9. you can make a library of commonly used routines, and just open and use it
  10. for each program that you write. There's no need to scavange old code, re-
  11. compile or re-assemble previously written functions, modify code to avoid
  12. conflicting labels and variable names, or re-edit old INCLUDE files. Also,
  13. you can allow other programmers to make use of your libraries without having
  14. to give away source code or object modules of the functions.
  15.   The first step in making a shared library is to write and test the functions
  16. which you intend to put in the library. The easiest way to do this is to
  17. develop a self-contained program to test the functions. When you are finished
  18. modifying the functions and are certain that they work properly, separate them
  19. from the rest of the code along with their variables. When writing lib
  20. functions, it is best to avoid using global variables. Use locals or allocate
  21. mem as needed. This will make your library truly reentrant (many tasks can use
  22. it simultaneously without stomping on each other's variables). The only globals
  23. in your lib code should be pre-initialized variables which never change value
  24. (such as an error message string). Place these functions in their own ascii
  25. text file. Save the remainder of your test program since this will be turned
  26. into a test application to open and use the new library.
  27.   The text file, "Simple.c", is an example of this. I created 3 routines,
  28. Add2Numbers, Sub2Numbers, and Mult2Numbers which I wish to turn into a shared
  29. library.
  30.   In order to turn these functions into a library, I need to create two more
  31. files: an fd file which describes what args are passed to the functions in
  32. which regs, and a library startup code to be linked with these functions.
  33.   "SimpleC.fd" is an example of an fd file. Here is the contents of that file:
  34.  
  35. ##base SimpleBase *the name of our base used by C glue code and C PRAGMAS
  36. ##name simple     *the name of our library (i.e. simple.library)
  37. ##vers 1          *version #
  38. ##revs 0          *revision #
  39. ##libid  simple C lib (ver 1.0)
  40. ##bias 30         *first function is always at an offset of -30 from lib base
  41. *Here are all of the lib functions callable by an application
  42. *All 3 functions return ULONG
  43. ##ret ULONG
  44. Add2Numbers(num1,num2)
  45. Sub2Numbers(num1,num2)
  46. Mult2Numbers(num1,num2)
  47. ##end
  48.  
  49.   Note that some of the lines begin with ##. This indicates that this line is
  50. a command. The command follows the ##.
  51.   For example, the first line begins with ##base. This means that the label
  52. following ##base is the variable which is used in C glue stubs for our library.
  53. I have chosen to name this variable SimpleBase. This is the name of the global
  54. variable you must declare in your application, and is where you store the
  55. returned lib base from OpenLibrary(). A good naming method is to append "Base"
  56. to the name of your library. Thus, we come up with SimpleBase for this example.
  57. Your application will then do the following:
  58.  
  59. struct SimpleBase *SimpleBase = 0L;
  60.  
  61.   SimpleBase = (struct SimpleBase *) OpenLibrary("simple.library", 0L)
  62.  
  63.   Note that if you take advantage of LibTool's C Include file making capability,
  64. the above code will automatically be created for you.
  65.   The next line starts with ##name. This means that the following label is what
  66. we intend to call our library (minus the .library extension). So, our library
  67. is going to be named "simple.library".
  68.   The next line, ##vers, indicates what the version of our library is. This
  69. number is what an application uses when it opens our library.
  70.   The next line, ##revs, is the revision number of our library. This should be
  71. incremented everytime we make a new library which is backwardly compatible with
  72. an earlier library, but somehow different.
  73.   The next line, ##libid, is a string which describes our library. This can be
  74. anything you choose, but should include the name of the library and version
  75. and revision. Note that I chose "simple C lib (ver 1.0)" for this string.
  76. The 1.0 means version 1, revision 0.
  77.   The next line, ##bias, indicates the negative offset from the library base
  78. for its first custom function. This should always be 30 for our purposes.
  79.   The next line, ##ret describes what the following function(s) return. For
  80. example, all 3 functions return ULONG. If I happened to have a fourth function,
  81. Blort() which returned a struct Window *, I would have to add a ##ret before
  82. Blort's function definition as so:
  83.  
  84. ##ret struct Window *
  85. Blort()
  86.  
  87.   The next 3 lines are the descriptions of my 3 library functions. The order
  88. of these is arbitrary. Note that I have the name of the function and its input
  89. args in parenthesis. The args are being passed on the stack since our lib is
  90. written in C. If a function doesn't require any input args, then I would only
  91. need 1 set of empty parenthesis. For example,
  92.  
  93. NoArgsFunc()
  94.  
  95.   The last line, ##end, just means that this is the end of the fd file.
  96.   You must create this fd file yourself. This file is then used by the LibTool
  97. program to create almost all of the other files needed for this project.
  98.   Now, let's make our simple.library. First, compile and assemble the 3
  99. functions (Simple.c) into a resulting object file, Simple.o. For Manx, make
  100. sure that you compile with +b to eliminate the .begin statement. LibTool will
  101. generate the proper startup code for us. Use LARGE CODE, LARGE DATA for this
  102. example lib. Thats -b0 for Lattice and +p for Manx. If you use SMALL CODE/DATA,
  103. then every callable lib function would have to setup its data base reg (usually
  104. a4) at the start, and upon return, restore that reg. Consult your C manual for
  105. directions.
  106.   Next, invoke LibTool.
  107.  
  108. LibTool -cmho glue.asm SimpleC.fd
  109.  
  110.   The -c option tells LibTool that our lib is written in C and consequently
  111. expects an application to pass args on the stack (not in 68000 regs as is
  112. normally the case). The glue stubs or PRAGMAS which are created will adjust for
  113. args expected on the stack. The -h option means to make a C INCLUDE file for
  114. our test application. The -m option means to make the startup code for our
  115. library functions. The -o glue.asm means to make 1 file with all of the glue
  116. stubs in it instead of separate files for each function. We won't use PRAGMAS
  117. for this example.
  118.   This will make 3 files, "glue.asm", "SimpleC.h", and "SimpleC.src". "glue.asm"
  119. is the glue code that will be linked with our C application. "SimpleC.src" is
  120. the asm code which gets linked with our 3 functions and turns them into a
  121. shared library. "SimpleC.h" is the C include file for our test application.
  122. Assemble "SimpleC.src" into a resulting object called "libstart.o". Now you must
  123. link the files. ALWAYS LINK THE SRC MODULE MADE BY LIBTOOL FIRST. For example,
  124.  
  125. blink libstart.o simple.o LIB lib:lcnb.lib NODEBUG TO libs:simple.library
  126.  
  127. ln -o libs:simple.library libstart.o simple.o -lcl32
  128.  
  129.   Note that we do not need the standard startup code "lib:c.o". For Manx, you
  130. need to specify the +b option when compiling to get rid of the .begin statement.
  131.  
  132.   We have now made our shared library and placed it in the LIBS: drawer as
  133. "simple.library".
  134.   This is the method you use to make any shared library.
  135.  
  136.   Now let's make a C application to test the library. "SimpleCApp.c" is
  137. an example of this. Compile and assemble this file. Link it with any standard
  138. startup code (not libstart.o!!!).  LibTool already made our glue file and
  139. INCLUDE file. Note that the INCLUDE file has two functions in it, OpenSimpleBase
  140. and CloseSimpleBase. It also declares SimpleBase. These functions allow you
  141. to easily open and close the new library. The name of the functions are created
  142. by appending the lib base name (declared in the fd file) to "Open" and "Close".
  143. Simply open the library by calling OpenSimpleBase(). If this returns TRUE, then
  144. the library opened. Later, you can close the library with CloseSimpleBase. The
  145. INCLUDE file also declares all of the lib functions as extern.
  146.  
  147. blink lib:c.o SimpleCApp.o glue.o LIB lib:lcnb.lib NODEBUG TO ram:TestProgram
  148.  
  149. ln -o ram:TestProgram SimpleCApp.o glue.o -lcl32
  150.  
  151.   Now run ram:TestProgram and see how the application uses simple.library.
  152.  
  153. Here's how to make a PRAGMA file, "Simple.pragma", for the Lattice C compiler
  154.  
  155. LibTool -lp SimpleC.fd
  156.  
  157.   After experimenting with creating a few of your own simple libraries, study
  158. the CComplex example which demonstrates a few more complicated considerations
  159. in constructing a library.
  160.