diff options
Diffstat (limited to 'docs/Modules.rst')
| -rw-r--r-- | docs/Modules.rst | 88 |
1 files changed, 72 insertions, 16 deletions
diff --git a/docs/Modules.rst b/docs/Modules.rst index fdf597a..9fb4c77 100644 --- a/docs/Modules.rst +++ b/docs/Modules.rst @@ -2,13 +2,13 @@ Modules ======= +.. warning:: + The functionality described on this page is supported for C and + Objective-C. C++ support is experimental. + .. 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): @@ -106,24 +106,25 @@ Using Modules ============= To enable modules, pass the command-line flag ``-fmodules`` [#]_. This will make any modules-enabled software libraries available as modules as well as introducing any modules-specific syntax. Additional `command-line parameters`_ are described in a separate section later. -Import declaration ------------------- -The most direct way to import a module is with an *import declaration*, which imports the named module: +Objective-C Import declaration +------------------------------ +Objective-C provides syntax for importing a module via an *@import declaration*, which imports the named module: .. parsed-literal:: - import std; + @import std; -The import declaration above imports the entire contents of the ``std`` module (which would contain, e.g., the entire C or C++ standard library) and make its API available within the current translation unit. To import only part of a module, one may use dot syntax to specific a particular submodule, e.g., +The @import declaration above imports the entire contents of the ``std`` module (which would contain, e.g., the entire C or C++ standard library) and make its API available within the current translation unit. To import only part of a module, one may use dot syntax to specific a particular submodule, e.g., .. parsed-literal:: - import std.io; + @import std.io; Redundant import declarations are ignored, and one is free to import modules at any point within the translation unit, so long as the import declaration is at global scope. -.. warning:: - The import declaration syntax described here does not actually exist. Rather, it is a straw man proposal that may very well change when modules are discussed in the C and C++ committees. See the section `Includes as imports`_ to see how modules get imported today. +At present, there is no C or C++ syntax for import declarations. Clang +will track the modules proposal in the C++ committee. See the section +`Includes as imports`_ to see how modules get imported today. Includes as imports ------------------- @@ -148,6 +149,8 @@ Module maps are specified as separate files (each named ``module.map``) alongsid .. note:: To actually see any benefits from modules, one first has to introduce module maps for the underlying C standard library and the libraries and headers on which it depends. The section `Modularizing a Platform`_ describes the steps one must take to write these module maps. + +One can use module maps without modules to check the integrity of the use of header files. To do this, use the ``-fmodule-maps`` option instead of the ``-fmodules`` option. Compilation model ----------------- @@ -165,6 +168,9 @@ Command-line parameters ``-fcxx-modules`` Enable the modules feature for C++ (EXPERIMENTAL and VERY BROKEN). +``-fmodule-maps`` + Enable interpretation of module maps (EXPERIMENTAL). This option is implied by ``-fmodules``. + ``-fmodules-cache-path=<directory>`` Specify the path to the modules cache. If not provided, Clang will select a system-appropriate default. @@ -183,6 +189,15 @@ Command-line parameters ``-module-file-info <module file name>`` Debugging aid that prints information about a given module file (with a ``.pcm`` extension), including the language and preprocessor options that particular module variant was built with. +``-fmodules-decluse`` + Enable checking of module ``use`` declarations. + +``-fmodule-name=module-id`` + Consider a source file as a part of the given module. + +``-fmodule-map-file=<file>`` + Load the given module map file if a header from its directory or one of its subdirectories is loaded. + Module Map Language =================== @@ -231,8 +246,9 @@ Module map files use a simplified form of the C99 lexer, with the same rules for ``config_macros`` ``export`` ``module`` ``conflict`` ``framework`` ``requires`` - ``exclude`` ``header`` ``umbrella`` - ``explicit`` ``link`` + ``exclude`` ``header`` ``private`` + ``explicit`` ``link`` ``umbrella`` + ``extern`` ``use`` Module map file --------------- @@ -258,6 +274,7 @@ A module declaration describes a module, including the headers that contribute t *module-declaration*: ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* *attributes*:sub:`opt` '{' *module-member** '}' + ``extern`` ``module`` *module-id* *string-literal* The *module-id* should consist of only a single *identifier*, which provides the name of the module being defined. Each module shall have a single definition. @@ -286,10 +303,13 @@ Modules can have a number of different kinds of members, each of which is descri *umbrella-dir-declaration* *submodule-declaration* *export-declaration* + *use-declaration* *link-declaration* *config-macros-declaration* *conflict-declaration* +An extern module references a module defined by the *module-id* in a file given by the *string-literal*. The file can be referenced either by an absolute path or by a path relative to the current map file. + Requires declaration ~~~~~~~~~~~~~~~~~~~~ A *requires-declaration* specifies the requirements that an importing translation unit must satisfy to use the module. @@ -300,9 +320,12 @@ A *requires-declaration* specifies the requirements that an importing translatio ``requires`` *feature-list* *feature-list*: - *identifier* (',' *identifier*)* + *feature* (',' *feature*)* + + *feature*: + ``!``:sub:`opt` *identifier* -The requirements clause allows specific modules or submodules to specify that they are only accessible with certain language dialects or on certain platforms. The feature list is a set of identifiers, defined below. If any of the features is not available in a given translation unit, that translation unit shall not import the module. +The requirements clause allows specific modules or submodules to specify that they are only accessible with certain language dialects or on certain platforms. The feature list is a set of identifiers, defined below. If any of the features is not available in a given translation unit, that translation unit shall not import the module. The optional ``!`` indicates that a feature is incompatible with the module. The following features are defined: @@ -360,6 +383,7 @@ A header declaration specifies that a particular header is associated with the e *header-declaration*: ``umbrella``:sub:`opt` ``header`` *string-literal* + ``private`` ``header`` *string-literal* ``exclude`` ``header`` *string-literal* A header declaration that does not contain ``exclude`` specifies a header that contributes to the enclosing module. Specifically, when the module is built, the named header will be parsed and its declarations will be (logically) placed into the enclosing submodule. @@ -372,6 +396,8 @@ A header with the ``umbrella`` specifier is called an umbrella header. An umbrel ``-Wincomplete-umbrella`` warning option to ask Clang to complain about headers not covered by the umbrella header or the module map. +A header with the ``private`` specifier may not be included from outside the module itself. + A header with the ``exclude`` specifier is excluded from the module. It will not be included when the module is built, nor will it be considered to be part of the module. **Example**: The C header ``assert.h`` is an excellent candidate for an excluded header, because it is meant to be included multiple times (possibly with different ``NDEBUG`` settings). @@ -521,6 +547,36 @@ Note that, if ``Derived.h`` includes ``Base.h``, one can simply use a wildcard e compatibility for programs that rely on transitive inclusion (i.e., all of them). +Use declaration +~~~~~~~~~~~~~~~ +A *use-declaration* specifies one of the other modules that the module is allowed to use. An import or include not matching one of these is rejected when the option *-fmodules-decluse*. + +.. parsed-literal:: + + *use-declaration*: + ``use`` *module-id* + +**Example**:: In the following example, use of A from C is not declared, so will trigger a warning. + +.. parsed-literal:: + + module A { + header "a.h" + } + + module B { + header "b.h" + } + + module C { + header "c.h" + use B + } + +When compiling a source file that implements a module, use the option ``-fmodule-name=``module-id to indicate that the source file is logically part of that module. + +The compiler at present only applies restrictions to the module directly being built. + Link declaration ~~~~~~~~~~~~~~~~ A *link-declaration* specifies a library or framework against which a program should be linked if the enclosing module is imported in any translation unit in that program. |
