Hi all
I will add this text to the wiki and upload the wrapper code. Is it
OK to put the code (structure below) in a subdir of each supported
library? Any suggestions as to name? "amiga_lib"?
I suspect the makefile/code can be cleaned up a bit, and possibly
integrated somewhat with the core library buildsystem - but I haven't
investigated as makefiles tend to break if I attempt to change them.
AmigaOS libraries have been created for the main NetSurf project
libraries:
libwapcaplet (wapcaplet.library)
libhubbub (hubbub.library)
libnsbmp (nsbmp.library)
libnsgif (nsgif.library)
libparserutils (parserutils.library)
libcss (css.library)
These comprise of the library itself and a stub C link library, which
opens the AmigaOS library and redirects function calls to the correct
place, negating the need to add additional code to applications to use
it.
Source structure
include/ Includes for building the library
interfaces/ and using without the stub link library
libname.h FUNCTION TABLE
proto/
libname.h
init.c Library init code
makefile.lib Makefile (named so as not to confuse core build system)
libname.library_rev.* Version numbering
stubs/ Stub link library
auto.c Code to open the .library
funcs.c STUB FUNCTIONS
vectors.c FUNCTION TABLE
Building the library
Build the static version of the library as usual:
gmake COMPONENT_TYPE=lib-static BUILD=release
Then cd to the directory containing the AmigaOS library code and run:
make -fmakefile.lib revision (bumps the library revision number)
make -fmakefile.lib (builds the library)
make -fmakefile.lib libname.a (builds the stub link library)
Adding new functions
If a new function is added to the original library, the AmigaOS
library wrapper needs to be updated in the three files marked in
capitals above.
New functions *must* be added to the end of the two function tables
(they must match in both tables, if one is missing from either table
the library will crash unexpectedly!), and a stub function added.
The version numbers in makefile.lib and in the OpenLibrary() call in
stubs/auto.c *must* be increased (this can wait until the next release
of the library/NetSurf - it only needs to be increased if new
functions are added between releases)
Modified API
If the API of a function is modified, it will need to be added as per
a new function in the instructions above. The previous incarnation of
the function will need to be renamed in the two function tables, and
the stub library function amended so it will still work as expected
from old code.
Major incompatible API changes may need a different approach (such as
a "v2" main interface, or a brand new .library with a different name)
Caveats
Amiga libraries have global shared data, rather than per-instance
data. This means some minor modifications have had to be made (within
the AmigaOS library interface, not the original link libraries):
_initialise and _finalise
These routines are called within the library initialisation/exit
code, rather than by the caller. This ensures the library is only
initialised once, and in a consistent state for all users of that
library.
parserutils.library
The initialisation code is hard-coded to read a central aliases file
(L:CharSets/Aliases). Any users of this library needing a custom
aliases file will fail (or the file will need to be merged with the
central one). Such usage is expected to be extremely rare.
wapcaplet.library
There is a security flaw in this library due to the implementation
and its translation to a system global context. All users of this
library get the same context and thus, the same linked-list set of
strings. This has the advantage of greater efficiency, and is
necessary so both (eg) css.library and NetSurf can share strings. Any
sensitive data stored in lwc_strings can easily be extracted by a
malicious user of the library. The nature of wapcaplet.library does
not lend itself to storage of personal information, so it is not
expected that any application will intentionally do this. As
wapcaplet.library could easily be patched to intercept strings as they
are being set, and - in a system without memory protection - any
application can read strings from memory regardless, this additional
problem is deemed insignificant. The warning "do not use
wapcaplet.library for sensitive data" should be heeded (instead link
libwapcaplet.a, or better yet use something more appropriate). This
will be revisited if it is deemed a significant risk.
Regards
Chris
