
    How to write applications which use the Dynamicaly Linkable version of DeskLib
    


Julian Smith

If you have any problems with this documentation, please contact me so
that I can improve it.


Terminology


Client - A program which uses the dynamically linked version of
         DeskLib.
DLL    - Dynamically Linked Library.
SDLS   - Straylight Dynamic Linking System.


Introduction


Making an existing application use the DLL version of DeskLib should
be very easy. It involves no change to the application's source code.

All you have to do is recompile with different compiler flags and link
with some different/extra libraries. Note that DRLink doesn't seem to
work with some of the SDLS object files; version 4.00 of Acorns's Link
works ok.

I recommend that you get a normal statically-linked version of your
program working before making a DLL client version.




Installing the SDLS


You will need to have the Straylight Dynamic Linking System (SDLS)
installed on your machine.

It is available from (for example)
micros.hensa.ac.uk/micros/arch/riscos/d/d052. 

You should move the SDLS's 'DLLLib' directory into your C path so that
DeskLib headers can load (for example) the 'dll.h' SDLS header file with
'#include "DLLLib.dll.h"', and the SDLS object files can be specified to
Link with 'Link ... C:DLLLib.o.DLLLib ...' etc.

Also, you should use !DLLMerge (supplied with the SDLS) to merge the
!DeskLib.!DLL resource (which contains all the DeskLib shared libraries)
with the main !DLL application that comes with the SDLS. 

If you are just testing a DeskLib client, then you could simply use the
!DeskLib.!DLL as your master DLL resource directory - it is a complete
SDLS system.  Also, it comes with a later version of the DLLManager than
that supplied in the SDLS 1.02 release. The 1.02-release version won't
work with DeskLib.

Have a look at the documentation that comes with the SDLS, particularly
the info on writing client applications. There is a lot of information
there which will be helpful.



The example DLL version of !TestAp


I've modified DeskLib's !TestApp directory so that one can make various
versions of the application - the normal statically linked one, a
debugging version, and one that uses DeskLib's DLLs.

The file ...!TestApp.!RunDLL runs the SDLS-version of DeskLib's
!TestApp. Try running this to check that you have installed the SDLS
properly.

Below are the full instructions for making a DLL client.



How to remake your application


All that needs to be done is:

1. Recompile the application with '_DeskLib_SDLS_CLIENT'
   predefined.
   eg. cc ... -D_DeskLib_SDLS_CLIENT ...

2. Link with 'DeskLib:o.DLLClient' instead of 'DeskLib:o.DeskLib'

3. Link with 'C:DLLLib.o.dllLib'

4. Link with 'C:DLLLib.o.astubs' instead of the normal o.stubs

5. Link with Acorn's Link 4.00 or later - DRLink 0.27 doesn't like some
   of the SDLS object files.


See the !TestApp.DLL directory for a makefile which does all of this.

You might find it useful to copy !TestApp's directory structure for your
own project, substituting your own .c/.h files and modifying the two
makefiles.

Assuming you have succesfully compiled the SDLS-version of your client,
then your application should run. 

Try starting up other applications (eg a TaskWindow) while your program
is running. Also, try the 'dllapps' command - this should list the name
of your program.

Also check whether you can run two copies of your client application. If
running the second client results in an error from DLLManager, then
please let me know.



Error_ functions


At the moment, all client applications will use the 'Error' DLL, which
contains the standard set of Error_ functions. It isn't possible to
provide a customised set of Error_ functions in the same way as in
normal statically-linked applications.

However, the SDLS does have support for clients to provide functions for
use by DLLs, and future versons of DeskLib will take advantage of this
to enable client applicatons to provide customised Error_ functions.




Other things


Code used with the SDLS must not call 'system', 'OS_CLI',
'Wimp_StartTask' or '_kernel_system' directly. Instead, you must use the
replacement functions '_dll_system', '_dll_oscli', '_dll_starttask' and
'_dll_ksystem' prototyped in 'DLLLib.dll.h'. The SDLS documentation
explains why these restrictions are necessary - basically, the SDLS uses
the application start-time to work out which client is calling a DLL
function, and the standard calls will corrupt this start-time.

In the future, the DeskLib versions of these calls will be modified to
be the SDLS replacements when compilation is for a SDLS client.

Also, SDLS code which uses setjmp/longjmp must use the functions
'_dll_setjmp' and '_dll_longjmped' to preserve the DLL stack. Again, see
the SDLS manual for the details.

