MKLIB(1) Library Functions MKLIB(1) NAME mklib - a source file generator for Amiga shared libraries mklib file [ file ... ] DESCRIPTION Mklib is a utility that allows you to write code for an Amiga shared library in C and automatically produce files that allow you to generate this library. Normally, Amiga shared libraries are coded in assembler, and are passed arguments in registers. These arguments must be pushed onto the stack before a C routine in the library can be called. To use mklib, follow this sequence of steps: 1 - code your library routines and save them in any number of `.c' files. 2 - make sure the following two variables are defined once using these exact names: char myname[] = "mylib.library"; char myid[] = "mylib 1.0 (23 Oct 1986)\r\n"; The Amiga's OS requires that the name of the library be included within the library itself. Myid may contain any identifying information that you wish to have included. 3 - put your source files in their own directory. This makes it easy to contain the various generated files and to prevent mklib from overwriting files that may already exist. (such as "makefile") 4 - run mklib and specify your source files. 5 - assuming the compiler, the assembler, the linker and the librarian are in your search path, you can now simply type "make" to automatically generate a library file. 6 - Once you have done this, copy the library to the LIBS: directory so that AmigaDOS can automatically load it when required. When programming the library functions, remember that stdin, stdout and stderr will not be correct. Most clib library routines should be avoided. Also, when coding the library routines, keep in mind that there may be more than one process running your library. Therefore, you should make your code re-entrant. The use of global variables in a library is a Bad Thing if you do not use semaphores or other such techniques to prevent race conditions. To use the final library, a user program must be linked with link.o which is generated from the link.asm which, in turn, is generated by mklib. Also, the file link.h must be included in the user program to declare externally the functions in the the new library. Open and use the library as you would open and use any other library such as the intuition.library. Remember to close the library before exiting your function. The generated makefile contains an example makefile entry for the user program, but it is commented out. Take away the comments and add your own program name to get make to generate a program that uses the newly created library. The file link.h contains the following declaration: APTR libbase; This variable _must_ be used to store your library pointer when your library is opened. The routines in the file link.asm use this variable to find the exact locations of the functions in the shared library. PARAMETERS You may call a library generated with mklib as you would any other library from either Manx C, Lattice C, assembler or even other languages that support libraries. The parameters to the generated libraries should be in the following order: d0 for the first parameter d1 second a0 third a1 fourth and so on: d2, d3, d4, d5, d6, d7, a2, a3, a4, a5 There is a maximum of 14 parameters. If you need to pass more information, create a structure containing this data and pass a pointer to the structure. EXAMPLES The following is an example of source that you may use to to generate a library. /* this is a test library */ #include char myname[] = "mylib.library"; char myid[] = "mylib 1.0 (23 Oct 1986)\r\n"; LONG GetDown() { return (77); } ULONG Double(arg) ULONG arg; { return (2 * arg); } LONG Triple(arg) LONG arg; { arg *= 3; return ((LONG)arg); } The following is an example program that uses the library generated from the source above: #include #include #include #include "link.h" #define RTC printf("return to continue - ");fflush(stdout);\ getchar(); #define DOUBARG 19 main() { LONG retval; printf("here we go\n"); libbase = (APTR) OpenLibrary("mylib.library", 0L); printf("openlib returns base: %lx\n", libbase); RTC; if (libbase) { /* test function GetDown() */ retval = GetDown(); printf("called getdown, %ld returned\n", retval); RTC; /* test function Double() */ printf("double of %d = %ld\n", DOUBARG, Double((LONG)DOUBARG)); RTC; /* test function Triple() */ printf("Here is three times %d: %ld\n",DOUBARG, Triple((LONG)DOUBARG)); RTC; CloseLibrary(libbase); } } AUTHOR Edwin Hoogerbeets 12/08/88 working from the Elib example on Fish 87. FILES *.c - your source files for the library interface.asm - assembler/C interface routines lib.c - required library functions (Open, Close, Expunge) lib.h - header for lib.c link.asm - file to link with code using the generated library link.h - include file for programs using the generated library file makefile - makefile for the generated code rtag.asm - romtag code used to help replace crt0 startup.asm - new version of crt0 to replace default crt0 whatever.library - final Amiga shared library BUGS As yet, all user library routines must be defined as LONG or ULONG and must take only arguments of type LONG or ULONG. All functions not declared this way will be ignored by mklib. This may be changed in subsequent version of mklib. Mklib is written for Manx Aztec C. Although it has not been tried with Lattice, it will should compile fine. However, it may need some changes in the output generated to conform to Lattice. Currently, mklib has only been tested with Manx version 3.6a. Mklib does not allow you to specify your own name for the pointer to the library in a user program. The variable 'libbase' must always be used.