Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/493.lha/LibTool/AsmSimple/Simple.DOC

Text File | 1991-04-06 | 8.5 KB | 167 lines

 This document describes how to make the simple.library assembly example.

  A shared library is a disk-based executable file that usually resides in
the LIBS drawer of your boot disk. Such a library contains functions that
your application can call, but which are not a part of your program. Many
other applications can open and use the same shared library (usually simul-
taneously), thus saving memory when the applications are run concurrently.
Also, a shared library can help reduce development time in new products since
you can make a library of commonly used routines, and just open and use it
for each program that you write. There's no need to scavange old code, re-
compile or re-assemble previously written functions, modify code to avoid
conflicting labels and variable names, or re-edit old INCLUDE files. Also,
you can allow other programmers to make use of your libraries without having
to give away source code or object modules of the functions.
  The first step in making a shared library is to write and test the functions
which you intend to put in the library. The easiest way to do this is to
develop a self-contained program to test the functions. When you are finished
modifying the functions and are certain that they work properly, separate them
from the rest of the code along with their variables. When writing lib
functions, it is best to avoid using global variables. Use locals or allocate
mem as needed. This will make your library truly reentrant (many tasks can use
it simultaneously without stomping on each other's variables). The only globals
in your lib code should be pre-initialized variables which never change value
(such as an error message string). Place these functions in their own ascii
text file. Save the remainder of your test program since this will be turned
into a test application to open and use the new library.
  The text file, "Simple.asm", is an example of this. I created 3 routines,
Add2Numbers, Sub2Numbers, and Mult2Numbers which I wish to turn into a shared
library.
  In order to turn these functions into a library, I need to create two more
files: an fd file which describes what args are passed to the functions in
which regs, and a library startup code to be linked with these functions.
  "Simple.fd" is an example of an fd file. Here is the contents of that file:

##base SimpleBase *the name of our base used by C glue code and C PRAGMAS
##name simple     *the name of our library (i.e. simple.library)
##vers 1          *version #
##revs 0          *revision #
##libid  simple asm lib (ver 1.0)
##bias 30         *first function is always at an offset of -30 from lib base
*Here are all of the lib functions callable by an application
* These 3 functions return ULONG
##ret ULONG
Add2Numbers(num1,num2)(D0,D1)
Sub2Numbers(num1,num2)(D0,D1)
Mult2Numbers(num1,num2)(D0,D1)
##end

  Note that some of the lines begin with ##. This indicates that this line is
a command. The command follows the ##.
  For example, the first line begins with ##base. This means that the label
following ##base is the variable which is used in C glue stubs for our library.
I have chosen to name this variable SimpleBase. This is only used by a C app-
lication, but you should always declare it anyway. A good naming method is to
append "Base" to the name of your library. Thus, we come up with SimpleBase
for this example.
  The next line starts with ##name. This means that the following label is what
we intend to call our library (minus the .library extension). So, our library
is going to be named "simple.library".
  The next line, ##vers, indicates what the version of our library is. This
number is what an application uses when it opens our library.
  The next line, ##revs, is the revision number of our library. This should be
incremented everytime we make a new library which is backwardly compatible with
an earlier library, but somehow different.
  The next line, ##libid, is a string which describes our library. This can be
anything you choose, but should include the name of the library and version
and revision. Note that I chose "simple asm lib (ver 1.0)" for this string.
The 1.0 means version 1, revision 0.
  The next line, ##bias, indicates the negative offset from the library base
for its first custom function. This should always be 30 for our purposes.
  The next line, ##ret describes what the following function(s) return. For
example, all 3 functions return ULONG. If I happened to have a fourth function,
Blort() which returned a struct Window *, I would have to add a ##ret before
Blort's function definition as so:

##ret struct Window *
Blort()

  This is only used for C applications which wish to take advantage of LibTool's
ability to generate a C INCLUDE file. If you don't know how to declare a return
value in the C language, then you can omit this command but then LibTool
cannot automatically generate the C INCLUDE.
  The next 3 lines are the descriptions of my 3 library functions. The order
of these is arbitrary. Note that I have the name of the function and its input
args in parenthesis, followed by the respective 68000 regs in which those args
are passed. Note that the regs must line up with the args. For example, in
Add2Numbers, num1 will be passed in D0. If a function doesn't require any input
args, then I would only need 1 set of empty parenthesis. For example,

NoArgsFunc()

  The last line, ##end, just means that this is the end of the fd file.
  You must create this fd file yourself. This file is then used by the LibTool
program to create almost all of the other files needed for this project.
  Now, let's make our simple.library. First, assemble the 3 functions
(Simple.asm) into a resulting object file, Simple.o. Next, invoke LibTool.

LibTool -am Simple.fd

  This will make 2 files, "Simple.i" and "Simple.src". "Simple.i" is the
INCLUDE file for our assembly application. "Simple.src" is the asm
code which gets linked with our 3 functions and turns them into a shared
library. Assemble "Simple.src" into a resulting object called "libstart.o".
Now you must link the files. ALWAYS LINK THE SRC MODULE MADE BY LIBTOOL FIRST.
For example,

blink libstart.o simple.o small.lib NODEBUG TO libs:simple.library

ln -o libs:simple.library libstart.o simple.o -lcl32

small.lib is available from CATS or on Fred Fish #92. We have now made our
shared library and placed it in the LIBS: drawer as "simple.library".
  This is the method you use to make any shared library.

  Now let's make an asm application to test the library. "SimpleApp.asm" is
an example of this. Assemble this file. Link it with any standard startup code
(not libstart.o!!!).  LibTool already made our INCLUDE file for us.

blink startup.o SimpleApp.o small.lib NODEBUG TO ram:TestProgram

ln -o ram:TestProgram ManxStartup.o SimpleApp.o -lcl32

  Now run ram:TestProgram and see how the application uses simple.library.

  Now, you may wish to allow you C and Basic programmer friends to use your
library. You need to make support files for them. C programmers need a glue
module(s) or a PRAGMA file. To make a glue file, do this

LibTool -o glue.asm Simple.fd

  This makes 1 module, glue.asm, containing all of the C stubs for all of the
functions in your library. Make sure to tell your friend what the name of the
library base is (i.e. SimpleBase in this example).

Here's how to make a PRAGMA file, "Simple.pragma", for the Lattice C compiler

LibTool -lp Simple.fd

  If you properly inserted the ##ret commands in the fd file, you can generate
a C INCLUDE file as well.

LibTool -h Simple.fd

  For Basic programmers, you need to make a BMAP file.

LibTool -b Simple.fd

  This makes "Simple.BMAP". Remember that a BMAP file must be the same name as
the library (minus the .library extension). This should be copied to the LIBS:
directory of the boot disk.
  AmigaBasic cannot have imbedded underscores in function names, so you should
avoid having any in your library function names. LibTool will convert imbedded
underscores to the exceptable "." and print an error msg to the CLI.
  You should also avoid naming any lib functions the same as Basic keywords
(i.e. don't call some function "Print").  LibTool also checks for the following
known collisions, and prepends an "x" if found:

  abs,Close,Exit,Input,Open,Output,Read,tan,Translate,Wait,Write

  AmigaBasic cannot support passing any args in a5, a6, or obviously a7. If
a lib function does this, then an error msg is posted to the CLI. There is no
way to call such a function from AmigaBasic.

  After experimenting with creating a few of your own simple libraries, study
the AsmComplex example which demonstrates a few more complicated considerations
in constructing a library.