duktape/doc/c-module-convention.rst

===========================
Duktape C module convention
===========================

Overview
========

This document provides a recommended convention for writing an init function
for a C module.  The convention allows modules to be used with both static
linking and DLL loading, and either as part of Duktape's CommonJS module
loading or outside of it.

The convention is in no way mandatory and it's perfectly fine to use a
different module loader convention for your project.  However, modules
following this convention will be easier to share between projects.

Module init function
====================

The init function for a module ``my_module`` should have the following form::

    duk_ret_t dukopen_my_module(duk_context *ctx) {
        /* Initialize module in whatever way is most appropriate.
         * Called as a Duktape/C function.
         *
         * Push the module result (e.g. an object with exported symbols or
         * a function) on top of the value stack and return 1 to indicate
         * there's a return value.  Temporary values can be left below
         * the return value like in normal Duktape/C functions.
         */

        duk_push_object(ctx);  /* module result */

        duk_put_function_list(ctx, -1, my_module_funcs);

        duk_push_int(ctx, 42);
        duk_put_prop_string(ctx, -2, "meaningOfLife");

        return 1;  /* return module value */
    }

The init function is called as a Duktape/C function.  When initializing
the module manually, you should use::

    duk_push_c_function(ctx, dukopen_my_module, 0 /*nargs*/);
    duk_call(ctx, 0);  /* or duk_pcall() if you want to catch errors */

    /* Stack top contains module value */

A DLL loader should use the same convention to call the init function
after figuring out the init function name and locating it from the DLL
symbol table.

DLL name
========

When a C module is compiled into a DLL, the DLL filename should include
the module name (``my_module`` in the running example) with any platform
specific prefix and suffix.  For example::

    my_module.so   # Linux
    my_module.dll  # Windows

A DLL loader should assume that the init function name is ``dukopen_``
followed by the module name part extracted from the DLL filename (here,
``dukopen_my_module()``).

Module name
===========

To avoid case conversion and special character issues, module names should
have the form::

    [a-zA-Z_][0-9a-zA-Z_-]*

This should minimize platform issues.

Mixed ECMAScript / C modules
============================

When a module is being initialized by a CommonJS aware module loader, the
loader can support mixed modules containing both C and ECMAScript code.
For example::

    my_module.so   # C module
    my_module.js   # ECMAScript module (CommonJS)

To support mixed modules, a Duktape 1.x ``modSearch()`` function should:

* First load the C module normally, yielding a return value RET.

* If RET is an object, copy the own properties of RET into the ``exports``
  value created by Duktape.  It should then return the source code of the
  ECMAScript module; when executed, further symbols get added to the same
  ``exports`` value.

* If RET is not an object, ignore it and load the ECMAScript module normally.
  (Alternatively, write RET to a fixed export name to make it accessible,
  e.g. ``exports.value``.)

The algorithm for Duktape 2.0 is still under design, but at a high level:

* First load the C module normally, yielding a return value RET.

* If RET is an object, use it to initialize the CommonJS ``exports`` value
  before loading the ECMAScript module.  The ECMAScript module can then
  use whatever symbols the C modules registered, and add further symbols to
  the same ``exports`` value.

* If RET is not an object, ignore it and load the ECMAScript module normally.
  (Alternatively, expose RET with a fixed name, e.g. initialize ``exports``
  as ``{ value: RET }``.)

Since Duktape 1.3 the ``modSearch()`` function can overwrite ``module.exports``
which allows you to implement the Duktape 2.0 approach in Duktape 1.x too.

Duktape 1.x CommonJS notes
==========================

Duktape 1.3 and above
---------------------

In Duktape 1.3 you can replace ``module.exports`` with the object returned
by the native module initialization function.  That value then becomes the
result of the original ``require()`` call.

For an example, see: https://github.com/svaarala/duktape/blob/master/tests/api/test-dev-cmodule-guide.c.

Prior to Duktape 1.3
--------------------

Prior to Duktape 1.3 the module ``exports`` value is always an object created
by Duktape, and cannot be replaced by modSearch().  modSearch() can only add
symbols to the pre-created object.  This has two implications for
implementing modSearch():

- When a C module returns an object, the symbols from the object must be
  copied to the pre-created ``exports`` value manually by the modSearch()
  function.

- When a C module returns a non-object, there are several alternatives:

  + The modSearch() function can ignore the module value.  This will make
    the module value inaccessible (unless the C module init function registered
    symbols directly to the global object or similar).

  + The modSearch() function can copy the module value into a fixed name in
    the ``exports`` table.  Suggested name is ``exports.value``.

Limitations
===========

* The convention may not work on all platforms where Duktape itself ports to.
  For instance, a platform might have no DLL support or have filename
  restrictions that don't allow DLLs to be named as specified above.

* The convention is not "CommonJS native": a C module doesn't get an exports
  table and cannot load sub-modules (at least relative to its own CommonJS
  identifier).  This trade-off is intentional to keep the C module convention
  as simple as possible.

* CommonJS module loading prior to Duktape 1.3 doesn't support modules with
  a non-object return value (i.e. all modules return an ``exports`` table).
  This module convention is not limited to object return values so that
  non-object modules can be supported in Duktape 1.3 and above.