Global object handlings of SigScheme
====================================


About
-----

SigScheme has a portable mechanism that controls global symbols hiding. This
document describes its necessity and usage.


The problem
-----------

Since SigScheme uses semi-common 'scm_' and 'Scm' prefixes for exported
symbols, it may conflict with other libraries if the client application is also
directly or indirectly linked with another Scheme implementation such as
libguile. This is a serious problem when implementing a fundamental library
based on libsscm, such as libuim.

To avoid such conflict, many platforms provide symbol exportation control
ability. For example, GNU ld and Windows DLL can handle it based on a optional
file which contains the symbol information. And libtool provides an useful
option `-export-symbols-regex` for such purpose to make the handlings
platform-independent. However, unfortunately libtool does not ensure its
portability. Currently supported platforms are considerably limited (at least
on version 2.1a 2006-03-30) and some platforms seems that can never be
supported.

Since primal portability is indispensable value of SigScheme to be being an
useful embedded Scheme implementation, we cannot depend on such problematic
toolchain-based symbol exportation control.


Solution
--------

An alternative special compilation method called 'combined-source mode' is
provided.

It combines all source code of SigScheme into single file, and makes all global
objects static. So no symbols will be exposed. A client of libsscm can use this
combined version of the library by including the file `sigscheme-combined.c`
directly into a C/C++ source of the client. Once it included, all configured
SigScheme features can be used as file-local code, and it can also be linked
with other arbitrary objects via user-written wrapper.


Combined-source mode usage for libsscm users
--------------------------------------------

Preparation
~~~~~~~~~~~

The combined-source version of the library is optional and not built by
default. Instruct as follows to build it.

----------------------------------------------------------------
  $ make -C src combined
----------------------------------------------------------------

It results the file `src/sigscheme-combined.c`. Since the generated code
reflects user-configuration, it must be rebuilt every after `configure`.

Compilation
~~~~~~~~~~~

Include the `sigscheme-combined.c` directly into a C/C++ code, as following
example. Ordinary separated compilation and linking does not work because of
its "all global objects made static" nature.

.a C code using combined-source mode of the SigScheme
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#include "sigscheme-combined.c"

#include <config.h> /* client's own config.h */

#include <stdlib.h>
#include <stdio.h>

#include "my-header.h"

static ScmObj
my_function(int val)
{
    return SCM_MAKE_INT(val * 2);
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Requirements:

  - `sigscheme-combined.c` must be included prior to client's own `config.h`
    since many autoconf-defined macros of SigScheme must appropriately be
    undefined in the file to avoid conflicting with the client-side ones

  - Add include path to `sigscheme/include` and `sigscheme/src` since the
    `sigscheme-combined.c` includes various source files in the directories

Other notes:

  - The client code can use all of public SigScheme API defined in
    `sigscheme.h`, `scmint.h`, `encoding.h`, `global.h` and SigScheme's own
    `condig.h`. Any other interfaces should not be used even if accessible

  - All of SigScheme's internal macros are undefined and hidden at the end of
    `sigscheme-combined.c` inclusion, to reduce namespace pollution

  - Many internal variables and functions of SigScheme are exposed to the
    client code. Be careful of conflict


Combined-source mode with exported API symbols
----------------------------------------------

To export SigScheme API symbols against the combined-source mode, define
`SCM_EXPORT_API` to 1 prior to including the `sigscheme-combined.c`, as
follows.

.instructs that export SigScheme API
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#define SCM_EXPORT_API 1
#include "sigscheme-combined.c"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Non-static functions handling for SigScheme developers
------------------------------------------------------

To control global symbol exportation, any non-static function declaration and
definition need little modification. For both prototype declaration and actual
definition, prepend `SCM_EXPORT` to the function. There is no distinction
between public API and library-internal API on the exportation control. Use
`SCM_EXPORT` for both type of functions.

The `SCM_EXPORT` macro is replaced with `static` when the combined-source mode
without `SCM_EXPORT_API`.

.symbol exportation control for functions
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/* declaration */
SCM_EXPORT void scm_set_lib_path(const char *path);
SCM_EXPORT ScmObj scm_p_load(ScmObj filename);

/* definition */
SCM_EXPORT void
scm_set_lib_path(const char *path)
{
    ...
}

SCM_EXPORT ScmObj
scm_p_load(ScmObj filename)
{
    ...
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Global variables handling for SigScheme developers
--------------------------------------------------

All global variables used in SigScheme must be written with the following
macros to make them static in the combined-source mode. Although it tries to
keep original usage of the global variables, some rewrite of source codes
declaring and defining the variables are needed because of the limitation of C
macro ability.

Constant global variables
~~~~~~~~~~~~~~~~~~~~~~~~~

Constant global variables can safely be used in all platforms regardless of
whether static or not. But a little modification of `extern` declaration is
needed for the combined-source mode treatment.

Be careful about all part of the variables are certainly qualified as
const.

.a constant global variables declaration and definition
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/* declaration */
extern const char *const names[];

/* definition */
const char *const names[] = {
  "foo", "bar", NULL
};

static const char *const other_names[] = {
  "baz", "quux", NULL
};
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.rewritten declaration and definition
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/* declaration */
SCM_EXTERN(const char *const names[]);

/* definition */
const char *const names[] = {
  "foo", "bar", NULL
};

static const char *const other_names[] = {
  "baz", "quux", NULL
};
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Writable extern variables
~~~~~~~~~~~~~~~~~~~~~~~~~

Writable and exported global variables need more complex rewriting.

.a writable extern variables declaration and definition
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/* declaration */
extern int foo bar;
extern ScmObj obj_a, obj_b;
extern void (*func)(void);

/* definition */
int foo bar;
ScmObj obj_a, obj_b;
void (*func)(void);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.rewritten declaration and definition
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/* declaration */
SCM_GLOBAL_VARS_BEGIN(srfi99);
int foo bar;
ScmObj obj_a, obj_b;
void (*func)(void);
SCM_GLOBAVARS_END(srfi99);
#define foo   SCM_GLOBAL_VAR(srfi99, foo)
#define bar   SCM_GLOBAL_VAR(srfi99, bar)
#define obj_a SCM_GLOBAL_VAR(srfi99, obj_a)
#define obj_b SCM_GLOBAL_VAR(srfi99, obj_b)
#define func  SCM_GLOBAL_VAR(srfi99, func)

/* definition */
SCM_DEFINE_EXPORTED_VARS(srfi99);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The identifier 'srfi99' in above example specifies a namespace which the
variables are placed into. It is recommended that
the name is taken from the filename which the definition is placed.

The macros defined immediately after the SCM_GLOBAVARS_END() are conventional
accessors for the variables. The proper accessing method for the variables is
SCM_GLOBAL_VAR(namespace, varname), but it unacceptably bothers code
writing. So such macros should be defined. The macros make rewriting of codes
operate on the variables unneeded. The SCM_GLOBAL_VAR() allows being accessed
as lvalue.

But since it may obviously cause unexpected replacement if any of the names are
appeared as a non-global-variable object in a code, such as local variable or
struct member. The macro definition may affect to all source files even if the
header defines the macro is not included by a file, because of the unified
translation unit formed by the combined-source. To avoid such unwanted
replacement, The variable names should be prefixed to be unique over all
sources.

.prefixing each variables is recommended
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/* declaration */
SCM_GLOBAL_VARS_BEGIN(srfi99);
int scm_foo scm_bar;
ScmObj scm_obj_a, scm_obj_b;
void (*scm_func)(void);
SCM_GLOBAVARS_END(srfi99);
#define scm_foo   SCM_GLOBAL_VAR(srfi99, scm_foo)
#define scm_bar   SCM_GLOBAL_VAR(srfi99, scm_bar)
#define scm_obj_a SCM_GLOBAL_VAR(srfi99, scm_obj_a)
#define scm_obj_b SCM_GLOBAL_VAR(srfi99, scm_obj_b)
#define scm_func  SCM_GLOBAL_VAR(srfi99, scm_func)

/* definition */
SCM_DEFINE_EXPORTED_VARS(srfi99);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Finally, conditional compilation is allowed even if in the declaration.

.conditional compilation is allowed
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/* declaration */
SCM_GLOBAL_VARS_BEGIN(srfi99);
int scm_foo scm_bar;
#if SCM_USE_FOO
ScmObj scm_obj_a, scm_obj_b;
void (*scm_func)(void);
#endif
SCM_GLOBAVARS_END(srfi99);
#define scm_foo   SCM_GLOBAL_VAR(srfi99, scm_foo)
#define scm_bar   SCM_GLOBAL_VAR(srfi99, scm_bar)
#define scm_obj_a SCM_GLOBAL_VAR(srfi99, scm_obj_a)
#define scm_obj_b SCM_GLOBAL_VAR(srfi99, scm_obj_b)
#define scm_func  SCM_GLOBAL_VAR(srfi99, scm_func)

/* definition */
SCM_DEFINE_EXPORTED_VARS(srfi99);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Static variables
~~~~~~~~~~~~~~~~

Static variables handling is similar to external one, but some additional
treatment is needed.

.a static variables definition
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
static int foo bar;
static ScmObj obj_a, obj_b;
static void (*func)(void);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.rewritten definition
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
SCM_GLOBAL_VARS_BEGIN(static_srfi99);
#define static
static int l_foo l_bar;
static ScmObj l_obj_a, l_obj_b;
static void (*l_func)(void);
#undef static
SCM_GLOBAL_VARS_END(static_srfi99);
#define l_foo   SCM_GLOBAL_VAR(static_srfi99, l_foo)
#define l_bar   SCM_GLOBAL_VAR(static_srfi99, l_bar)
#define l_obj_a SCM_GLOBAL_VAR(static_srfi99, l_obj_a)
#define l_obj_b SCM_GLOBAL_VAR(static_srfi99, l_obj_b)
#define l_func  SCM_GLOBAL_VAR(static_srfi99, l_func)
SCM_DEFINE_STATIC_VARS(static_srfi99);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The technical difference to external one is:

  - Use SCM_DEFINE_STATIC_VARS() instead of SCM_DEFINE_EXPORTED_VARS() to
    define declared variables

And some more conventions:

  - Enclose the declaration with `#define static` and `#undef static` to keep
    indicating that the variables are static

    * The `static` specifier is technically not allowed here

    * The `#define` and `#undef` must be placed inside
      `SCM_GLOBAL_VARS_{BEGIN,END}()`. Placing outside of them makes the
      declaration broken

  - The namespace should be prefixed with `static_`

  - The variable names should be prefixed with `l_` (stands for 'local')

Common restrictions
~~~~~~~~~~~~~~~~~~~

  - Reserved namespaces

    * `dummy`
    * `dummy_*`
    * `instance`
    * `instance_*`

Initialization and finalization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The global variables *MUST* be initialized with `SCM_GLOBAL_VARS_INIT()` prior
to being used. Before the initialization, accessing the variables is invalid
since they contain unspecified value.

.initialization of a set of variables
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
void
scm_srfi99_init(void)
{
    SCM_GLOBAL_VARS_INIT(srfi99);
    SCM_GLOBAL_VARS_INIT(static_srfi99);
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After the initialization, the variables contained in the namespace specified by
the `SCM_GLOBAL_VARS_INIT()` are zero-cleared. If you want that
an variable is initialized, assign the value by hand after the
initialization. Load-time initialization is not allowed and technically does
not work.

.initialization is not allowed (and does not work)
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
SCM_GLOBAL_VARS_BEGIN(static_srfi99);
#define static
static int l_foo = 100;
#undef static
SCM_GLOBAL_VARS_END(static_srfi99);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The by-function initialization ensures that cyclic finalization ->
re-initialization loop works properly without careful initial value treatment
of global variables. It is helpful to ensure that SigScheme is
re-initialization safe.

Finalization macro is also provided and usable. But since it is currently empty
expression, and most code modules do not have finalization
function, no finalization is performed for global variables to keep footprint
shrunk. But the macro should be added if a code module has finalization
function.

.finalization of the variables
[C]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
void
scm_srfi99_fin(void)
{
    SCM_GLOBAL_VARS_FIN(srfi99);
    SCM_GLOBAL_VARS_FIN(static_srfi99);
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
