Programming advices

The LDG principles come from many constations:

How shared between several application a same function built using different compiler and programming language ?
How extended easy the operating system, using GEM, without trap any functions or vector exceptions ?
How a software could enhanced its capability without new compilation (the plugin method) and using a special processor feature like PPC on MagiC Mac (who will create a mathematic library using PPC)?
How keeps, with a such system, a good performance compare to a standard application ?
How deals with the 16 bits and 32 bits mode of the Gnu C Compiler ?

When you'll write a LDG-library, keep in mind theses motivations !

Rules to create a LDG-library

There are severals rules to respect :

The functions of the library have to be prototyped as CDECL,
With some compilers, Gcc for e.g, parameters have a 32 bits size. Use 32-bit size parameters in your function (to be compatible with Gcc 32 bits). However, Gcc can compile in 16 bits mode and accept 16-bit size.
The double format can create many problem with different compiler. Often, real data can be encapsuled using a union with a long value:
```
        typedef union {
            double real;
            long   dummy;
        } Real;
```
A best solution is to use the LDG 'double' library (written by Olivier Landemarre) (see http://ldg.atari.org)
Each LDG function should be documented! Remember that the LDG format allows to document your fonction inside the library itself.
After compilation, a LDG-library should be loaded in shareable memory. For that purpose, use the PRGFLAGS program to change its MiNT protection mode.
Remember your library may be shareable by severals applications. Keep careful with global and static variables. If a function cannot support a multiple call, it should handle a wait loop.

About memory allocation

Memory allocation with the standard C function or with the Malloc() GEMDOS function and exchange of these data with the client are forbiden because the memory should be shareable (specially with MiNT). For that purpose you can use the functions ldg_Malloc(), ldg_Realloc(), ldg_Calloc() and ldg_Free() provided with the C-library developper.
These memory functions make directly usage of the GEMDOS function. A frequent usage of these functions can dangerously fragment the memory. It is more insteresting (and more efficient) to use the functions of the LDG memory manager (MEM.LDG) provided with the LDG distribution.
Exchange data from a client to a library is correct if the LDG-library is a GEMDOS executable with a MiNT mode set to GLOBAL. We provide in the distribution an utility (prgflags) to set the flags of GEMDOS executable.

A typically example of a LDG library distribution

If you create and diffuse a LDG-library, the archive file should have the following structure :

  MYLDGLIB.LZH :

    \gemsys\ldg\myldglib.ldg  ; The LDG library
    \include\ldg\myldglib.h   ; The C header containing the prototype
                              ; of the functions of MYLDGLIB.LDG
    \lib\myldglib.c           ; Binding of the functions in portable C
                              ; You can provide compiled library too.
    \man\man3l\myldglib.3l    ; manuel page nroff format
    \hyp\myldglib.hyp         ; hypertext documentation of the library
    \readme                   ; details for installation
    \install                  ; if possible a script or an installer program

By convention, the C-header file containing the definition of the function of a LDG-library should be placed in a subdirectory of your include folder. These file are included by client using these libraries. The C-library (here MYLDGLIB.LIB or LYLDGLIB.O) contains the binding of the functions. It is usally a function (eg init_myldglib()) initializing the LDG functions using the function ldg_find(). This file should be linked with the client.

If you create and diffuse a LDG-library, please contact us and we will create a link from our LDG internet site.

Have fun !