<commit_before>=======
Modules
=======

.. contents::
   :local:

Introduction
============
Most software is built using a number of software libraries, including libraries supplied by the platform, internal libraries built as part of the software itself to provide structure, and third-party libraries. For each library, one needs to access both its interface (API) and its implementation. In the C family of languages, the interface to a library is accessed by including the appropriate header files(s):

.. code-block:: c

  #include <SomeLib.h>

The implementation is handled separately by linking against the appropriate library. For example, by passing ``-lSomeLib`` to the linker.

Modules provide an alternative, simpler way to use software libraries that provides better compile-time scalability and eliminates many of the problems inherent to using the C preprocessor to access the API of a library.

Problems with the Current Model
-------------------------------
The ``#include`` mechanism provided by the C preprocessor is a very poor way to access the API of a library, for a number of reasons:<commit_msg>[docs] Prominently note that modules are expemental.<commit_after>=======
Modules
=======

.. contents::
   :local:

.. warning::
   The functionality described on this page is still experimental! Please
   try it out and send us bug reports!

Introduction
============
Most software is built using a number of software libraries, including libraries supplied by the platform, internal libraries built as part of the software itself to provide structure, and third-party libraries. For each library, one needs to access both its interface (API) and its implementation. In the C family of languages, the interface to a library is accessed by including the appropriate header files(s):

.. code-block:: c

  #include <SomeLib.h>

The implementation is handled separately by linking against the appropriate library. For example, by passing ``-lSomeLib`` to the linker.

Modules provide an alternative, simpler way to use software libraries that provides better compile-time scalability and eliminates many of the problems inherent to using the C preprocessor to access the API of a library.

Problems with the Current Model
-------------------------------
The ``#include`` mechanism provided by the C preprocessor is a very poor way to access the API of a library, for a number of reasons:
{'fraction_non_alphanumeric': 0.09185369908561929, 'fraction_numerical': 0.0, 'mean_word_length': 4.110403397027601, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3256468', 'n_tokens_mistral': 534, 'n_tokens_neox': 520, 'n_words': 336}