home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 1 / GoldFishApril1994_CD1.img / d1xx / d183 / mklib / mklib.man < prev    next >
Text File  |  1989-02-25  |  7KB  |  208 lines
  1. MKLIB(1)                   Library Functions                  MKLIB(1)
  2.  
  3.  
  4.  
  5. NAME
  6.      mklib - a source file generator for Amiga shared libraries
  7.  
  8.  
  9.      mklib file [ file ... ]
  10.  
  11. DESCRIPTION
  12.      Mklib is a utility that allows you to write code for an Amiga shared
  13.      library in C and automatically produce files that allow you to
  14.      generate this library. Normally, Amiga shared libraries are coded in
  15.      assembler, and are passed arguments in registers. These arguments must
  16.      be pushed onto the stack before a C routine in the library can be
  17.      called.
  18.  
  19.      To use mklib, follow this sequence of steps:
  20.  
  21.         1 - code your library routines and save them in any number
  22.             of `.c' files.
  23.  
  24.         2 - make sure the following two variables are defined once
  25.             using these exact names:
  26.  
  27.                 char myname[] = "mylib.library";
  28.                 char myid[] = "mylib 1.0 (23 Oct 1986)\r\n";
  29.  
  30.             The Amiga's OS requires that the name of the library
  31.             be included within the library itself. Myid may
  32.             contain any identifying information that you wish
  33.             to have included.
  34.  
  35.         3 - put your source files in their own directory. This makes
  36.             it easy to contain the various generated files and to
  37.             prevent mklib from overwriting files that may already
  38.             exist. (such as "makefile")
  39.  
  40.         4 - run mklib and specify your source files.
  41.  
  42.         5 - assuming the compiler, the assembler, the linker and
  43.             the librarian are in your search path, you can now
  44.             simply type "make" to automatically generate a library
  45.             file.
  46.  
  47.         6 - Once you have done this, copy the library to the LIBS:
  48.             directory so that AmigaDOS can automatically load it
  49.             when required.
  50.  
  51.      When programming the library functions, remember that stdin, stdout
  52.      and stderr will not be correct. Most clib library routines should be
  53.      avoided.
  54.  
  55.      Also, when coding the library routines, keep in mind that there may be
  56.      more than one process running your library. Therefore, you should make
  57.      your code re-entrant. The use of global variables in a library is a
  58.      Bad Thing if you do not use semaphores or other such techniques to
  59.      prevent race conditions.
  60.  
  61.      To use the final library, a user program must be linked with link.o
  62.      which is generated from the link.asm which, in turn, is generated by
  63.      mklib. Also, the file link.h must be included in the user program to
  64.      declare externally the functions in the the new library.
  65.  
  66.      Open and use the library as you would open and use any other library
  67.      such as the intuition.library. Remember to close the library before
  68.      exiting your function.
  69.  
  70.      The generated makefile contains an example makefile entry for the user
  71.      program, but it is commented out. Take away the comments and add your
  72.      own program name to get make to generate a program that uses the newly
  73.      created library.
  74.  
  75.      The file link.h contains the following declaration:
  76.  
  77.          APTR libbase;
  78.  
  79.      This variable _must_ be used to store your library pointer when your
  80.      library is opened. The routines in the file link.asm use this variable
  81.      to find the exact locations of the functions in the shared library.
  82.  
  83. PARAMETERS
  84.  
  85.      You may call a library generated with mklib as you would any other
  86.      library from either Manx C, Lattice C, assembler or even other
  87.      languages that support libraries. The parameters to the generated
  88.      libraries should be in the following order:
  89.  
  90.          d0  for the first parameter
  91.          d1  second
  92.          a0  third
  93.          a1  fourth
  94.  
  95.      and so on:
  96.  
  97.          d2, d3, d4, d5, d6, d7, a2, a3, a4, a5
  98.  
  99.      There is a maximum of 14 parameters. If you need to pass more
  100.      information, create a structure containing this data and pass a
  101.      pointer to the structure.
  102.  
  103. EXAMPLES
  104.      The following is an example of source that you may use to
  105.      to generate a library.
  106.  
  107.          /* this is a test library */
  108.          #include <exec/types.h>
  109.  
  110.          char myname[] = "mylib.library";
  111.          char myid[] = "mylib 1.0 (23 Oct 1986)\r\n";
  112.  
  113.          LONG GetDown()
  114.          {
  115.                  return (77);
  116.          }
  117.  
  118.          ULONG Double(arg)
  119.          ULONG arg;
  120.          {
  121.                  return (2 * arg);
  122.          }
  123.  
  124.          LONG Triple(arg)
  125.          LONG arg;
  126.          {
  127.              arg *= 3;
  128.  
  129.              return ((LONG)arg);
  130.          }
  131.  
  132.  
  133.      The following is an example program that uses the library
  134.      generated from the source above:
  135.  
  136.          #include <exec/types.h>
  137.          #include <stdio.h>
  138.          #include <functions.h>
  139.          #include "link.h"
  140.  
  141.          #define RTC printf("return to continue - ");fflush(stdout);\
  142.          getchar();
  143.  
  144.          #define DOUBARG 19
  145.  
  146.          main()
  147.          {
  148.                  LONG    retval;
  149.  
  150.                  printf("here we go\n");
  151.                  libbase = (APTR) OpenLibrary("mylib.library", 0L);
  152.                  printf("openlib returns base: %lx\n", libbase);
  153.  
  154.                  RTC;
  155.  
  156.                  if (libbase)
  157.                  {
  158.                          /* test function GetDown()      */
  159.                          retval = GetDown();
  160.                          printf("called getdown, %ld returned\n", retval);
  161.                          RTC;
  162.  
  163.                          /* test function Double()       */
  164.                          printf("double of %d = %ld\n", DOUBARG, Double((LONG)DOUBARG));
  165.                          RTC;
  166.  
  167.                          /* test function Triple()       */
  168.                          printf("Here is three times %d: %ld\n",DOUBARG,
  169.                                  Triple((LONG)DOUBARG));
  170.                          RTC;
  171.  
  172.                          CloseLibrary(libbase);
  173.                  }
  174.          }
  175.  
  176. AUTHOR
  177.      Edwin Hoogerbeets 12/08/88 working from the Elib example on
  178.      Fish 87.
  179.  
  180. FILES
  181.      *.c               - your source files for the library
  182.      interface.asm     - assembler/C interface routines
  183.      lib.c             - required library functions (Open, Close, Expunge)
  184.      lib.h             - header for lib.c
  185.      link.asm          - file to link with code using the generated
  186.                          library
  187.      link.h            - include file for programs using the generated
  188.                          library file
  189.      makefile          - makefile for the generated code
  190.      rtag.asm          - romtag code used to help replace crt0
  191.      startup.asm       - new version of crt0 to replace default crt0
  192.      whatever.library  - final Amiga shared library
  193.  
  194. BUGS
  195.      As yet, all user library routines must be defined as LONG or ULONG and
  196.      must take only arguments of type LONG or ULONG. All functions not
  197.      declared this way will be ignored by mklib. This may be changed in
  198.      subsequent version of mklib.
  199.  
  200.      Mklib is written for Manx Aztec C. Although it has not been tried with
  201.      Lattice, it will should compile fine. However, it may need some
  202.      changes in the output generated to conform to Lattice. Currently,
  203.      mklib has only been tested with Manx version 3.6a.
  204.  
  205.      Mklib does not allow you to specify your own name for the pointer to
  206.      the library in a user program. The variable 'libbase' must always be
  207.      used.
  208.