====================
LibGG Documentation
====================


.. include:: libgg-functions.txt


LibGG Library
=============

Handy, portable wrappers for several basic OS features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 7 libgg

Description
-----------


`LibGG` provides a portable, unified interface to various very basic
system features, making it easy to write portable programs without
locking the author into a bloated or overbearing development paradigm.

Originally `LibGG` came into being as part of the GGI Project, when 
`LibGII` input functionality was separated from `LibGGI` into a stand-alone 
library, and a place was needed to put functions needed by both libraries.  
(Since then, we have forgotten what "GG" stood for, so don't ask.)

`LibGG` is still distributed as part of `LibGII`, however it is itself a 
stand-alone package of utilities that can be very useful to anyone
writing applications that need to be portable across many different
operating systems environments.

`LibGG` provides the following groups of functions and/or macros.  Some
may not be possible to implement on some operating systems, some may
be possible, just nobody has done so yet.  We try to make them all 
available where we can find the time and/or expertise:

Time functions (`ggUSleep`) to handle high-resolution timing without
busy-looping.

Cleanup callbacks (`ggRegisterCleanup`, `ggUnregisterCleanup`, 
`ggCleanupForceExit`) to allow your application to perform emergency
actions when the program is terminated abnormally.

Timer callbacks (API in development) are in the works to provide
a threads or signal-based periodic/one-shot callback scheduler that 
can be shared between many different areas of the application code 
without fear of interference.

Locking Functions (`ggLock`, `ggLockCreate`, `ggLockDestroy`, `ggTryLock`, 
`ggUnlock`) which are thread-safe mutexes in threaded environments.

System and CPU detection utilities (`ggGetSwarType`, `GG_HAVE_INT64`,
`GG_LITTLE_ENDIAN`) to allow you to detect CPU endianness and the 
presence of features such as SIMD instruction sets (e.g. MMX), and 
to turn on/off or change SWARs for testing or as a workaround.

Pluggable module management functions (`ggLoadModule`, `ggMLoadModule`,
`ggGetSymbolAddress`, `ggFreeModule`) that allow you to create a plugin
system where code is dynamically loaded into and out of your program.
(Support for statically linked emulation for embedded systems is 
planned for the future.)

An option parser (`ggParseOptions`) and configuration file system 
(`ggGetUserDir`, `ggGetFileOpt`, `ggParseTarget`, `ggLoadConfig`, 
`ggFreeConfig`, `ggMatchConfig`, `ggConfigExpandAlias`) which is a 
by-product of the pluggable module support but can be useful for other 
things if you like the format.  (Note this will be undergoing some 
major changes and enhancements soon.)


BUGS:
-----

There is still some legacy to `LibGGI` in some of the namespace, 
especially `GGI_LITTLE_ENDIAN` is currently the real name for
`GG_LITTLE_ENDIAN`, which is an unofficial, new addition destined
to replace it.  Deprecation will take a few revisions as it must 
be done in an orderly fashion.

Likewise the header file is included as `<ggi/gg.h>` but we will 
probably keep that as-is because of the way `LibGG` is distributed and
to avoid adding more clutter in system include directories than 
is necessary.

Several features are incomplete, for example, code is still needed 
to detect SWAR on many of the more obscure architectures.
