CbC/CbC_llvm: tools/clang/docs/Modules.rst annotate

annotate tools/clang/docs/Modules.rst @ 3:9ad51c7bc036

1st commit. remove git dir and add all files.

author	Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
date	Wed, 15 May 2013 06:43:32 +0900
parents
children

rev	line source
3 9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	1 =======
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	2 Modules
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	3 =======
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	4
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	5 .. contents::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	6 :local:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	7
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	8 .. warning::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	9 The functionality described on this page is still experimental! Please
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	10 try it out and send us bug reports!
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	11
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	12 Introduction
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	13 ============
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	14 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):
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	15
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	16 .. code-block:: c
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	17
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	18 #include <SomeLib.h>
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	19
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	20 The implementation is handled separately by linking against the appropriate library. For example, by passing ``-lSomeLib`` to the linker.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	21
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	22 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.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	23
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	24 Problems with the current model
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	25 -------------------------------
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	26 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:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	27
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	28 * Compile-time scalability: Each time a header is included, the
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	29 compiler must preprocess and parse the text in that header and every
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	30 header it includes, transitively. This process must be repeated for
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	31 every translation unit in the application, which involves a huge
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	32 amount of redundant work. In a project with N translation units
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	33 and M headers included in each translation unit, the compiler is
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	34 performing M x N work even though most of the M headers are
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	35 shared among multiple translation units. C++ is particularly bad,
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	36 because the compilation model for templates forces a huge amount of
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	37 code into headers.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	38
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	39 * Fragility: ``#include`` directives are treated as textual
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	40 inclusion by the preprocessor, and are therefore subject to any
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	41 active macro definitions at the time of inclusion. If any of the
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	42 active macro definitions happens to collide with a name in the
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	43 library, it can break the library API or cause compilation failures
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	44 in the library header itself. For an extreme example,
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	45 ``#define std "The C++ Standard"`` and then include a standard
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	46 library header: the result is a horrific cascade of failures in the
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	47 C++ Standard Library's implementation. More subtle real-world
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	48 problems occur when the headers for two different libraries interact
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	49 due to macro collisions, and users are forced to reorder
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	50 ``#include`` directives or introduce ``#undef`` directives to break
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	51 the (unintended) dependency.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	52
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	53 * Conventional workarounds: C programmers have
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	54 adopted a number of conventions to work around the fragility of the
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	55 C preprocessor model. Include guards, for example, are required for
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	56 the vast majority of headers to ensure that multiple inclusion
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	57 doesn't break the compile. Macro names are written with
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	58 ``LONG_PREFIXED_UPPERCASE_IDENTIFIERS`` to avoid collisions, and some
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	59 library/framework developers even use ``__underscored`` names
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	60 in headers to avoid collisions with "normal" names that (by
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	61 convention) shouldn't even be macros. These conventions are a
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	62 barrier to entry for developers coming from non-C languages, are
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	63 boilerplate for more experienced developers, and make our headers
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	64 far uglier than they should be.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	65
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	66 * Tool confusion: In a C-based language, it is hard to build tools
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	67 that work well with software libraries, because the boundaries of
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	68 the libraries are not clear. Which headers belong to a particular
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	69 library, and in what order should those headers be included to
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	70 guarantee that they compile correctly? Are the headers C, C++,
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	71 Objective-C++, or one of the variants of these languages? What
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	72 declarations in those headers are actually meant to be part of the
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	73 API, and what declarations are present only because they had to be
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	74 written as part of the header file?
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	75
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	76 Semantic import
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	77 ---------------
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	78 Modules improve access to the API of software libraries by replacing the textual preprocessor inclusion model with a more robust, more efficient semantic model. From the user's perspective, the code looks only slightly different, because one uses an ``import`` declaration rather than a ``#include`` preprocessor directive:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	79
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	80 .. code-block:: c
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	81
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	82 import std.io; // pseudo-code; see below for syntax discussion
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	83
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	84 However, this module import behaves quite differently from the corresponding ``#include <stdio.h>``: when the compiler sees the module import above, it loads a binary representation of the ``std.io`` module and makes its API available to the application directly. Preprocessor definitions that precede the import declaration have no impact on the API provided by ``std.io``, because the module itself was compiled as a separate, standalone module. Additionally, any linker flags required to use the ``std.io`` module will automatically be provided when the module is imported [#]_
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	85 This semantic import model addresses many of the problems of the preprocessor inclusion model:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	86
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	87 * Compile-time scalability: The ``std.io`` module is only compiled once, and importing the module into a translation unit is a constant-time operation (independent of module system). Thus, the API of each software library is only parsed once, reducing the M x N compilation problem to an M + N problem.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	88
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	89 * Fragility: Each module is parsed as a standalone entity, so it has a consistent preprocessor environment. This completely eliminates the need for ``__underscored`` names and similarly defensive tricks. Moreover, the current preprocessor definitions when an import declaration is encountered are ignored, so one software library can not affect how another software library is compiled, eliminating include-order dependencies.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	90
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	91 * Tool confusion: Modules describe the API of software libraries, and tools can reason about and present a module as a representation of that API. Because modules can only be built standalone, tools can rely on the module definition to ensure that they get the complete API for the library. Moreover, modules can specify which languages they work with, so, e.g., one can not accidentally attempt to load a C++ module into a C program.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	92
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	93 Problems modules do not solve
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	94 -----------------------------
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	95 Many programming languages have a module or package system, and because of the variety of features provided by these languages it is important to define what modules do not do. In particular, all of the following are considered out-of-scope for modules:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	96
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	97 * Rewrite the world's code: It is not realistic to require applications or software libraries to make drastic or non-backward-compatible changes, nor is it feasible to completely eliminate headers. Modules must interoperate with existing software libraries and allow a gradual transition.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	98
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	99 * Versioning: Modules have no notion of version information. Programmers must still rely on the existing versioning mechanisms of the underlying language (if any exist) to version software libraries.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	100
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	101 * Namespaces: Unlike in some languages, modules do not imply any notion of namespaces. Thus, a struct declared in one module will still conflict with a struct of the same name declared in a different module, just as they would if declared in two different headers. This aspect is important for backward compatibility, because (for example) the mangled names of entities in software libraries must not change when introducing modules.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	102
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	103 * Binary distribution of modules: Headers (particularly C++ headers) expose the full complexity of the language. Maintaining a stable binary module format across architectures, compiler versions, and compiler vendors is technically infeasible.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	104
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	105 Using Modules
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	106 =============
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	107 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.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	108
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	109 Import declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	110 ------------------
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	111 The most direct way to import a module is with an import declaration, which imports the named module:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	112
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	113 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	114
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	115 import std;
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	116
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	117 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.,
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	118
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	119 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	120
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	121 import std.io;
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	122
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	123 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.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	124
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	125 .. warning::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	126 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.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	127
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	128 Includes as imports
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	129 -------------------
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	130 The primary user-level feature of modules is the import operation, which provides access to the API of software libraries. However, today's programs make extensive use of ``#include``, and it is unrealistic to assume that all of this code will change overnight. Instead, modules automatically translate ``#include`` directives into the corresponding module import. For example, the include directive
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	131
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	132 .. code-block:: c
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	133
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	134 #include <stdio.h>
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	135
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	136 will be automatically mapped to an import of the module ``std.io``. Even with specific ``import`` syntax in the language, this particular feature is important for both adoption and backward compatibility: automatic translation of ``#include`` to ``import`` allows an application to get the benefits of modules (for all modules-enabled libraries) without any changes to the application itself. Thus, users can easily use modules with one compiler while falling back to the preprocessor-inclusion mechanism with other compilers.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	137
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	138 .. note::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	139
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	140 The automatic mapping of ``#include`` to ``import`` also solves an implementation problem: importing a module with a definition of some entity (say, a ``struct Point``) and then parsing a header containing another definition of ``struct Point`` would cause a redefinition error, even if it is the same ``struct Point``. By mapping ``#include`` to ``import``, the compiler can guarantee that it always sees just the already-parsed definition from the module.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	141
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	142 Module maps
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	143 -----------
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	144 The crucial link between modules and headers is described by a module map, which describes how a collection of existing headers maps on to the (logical) structure of a module. For example, one could imagine a module ``std`` covering the C standard library. Each of the C standard library headers (``<stdio.h>``, ``<stdlib.h>``, ``<math.h>``, etc.) would contribute to the ``std`` module, by placing their respective APIs into the corresponding submodule (``std.io``, ``std.lib``, ``std.math``, etc.). Having a list of the headers that are part of the ``std`` module allows the compiler to build the ``std`` module as a standalone entity, and having the mapping from header names to (sub)modules allows the automatic translation of ``#include`` directives to module imports.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	145
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	146 Module maps are specified as separate files (each named ``module.map``) alongside the headers they describe, which allows them to be added to existing software libraries without having to change the library headers themselves (in most cases [#]_). The actual `Module map language`_ is described in a later section.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	147
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	148 .. note::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	149
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	150 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.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	151
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	152 Compilation model
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	153 -----------------
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	154 The binary representation of modules is automatically generated by the compiler on an as-needed basis. When a module is imported (e.g., by an ``#include`` of one of the module's headers), the compiler will spawn a second instance of itself [#]_, with a fresh preprocessing context [#]_, to parse just the headers in that module. The resulting Abstract Syntax Tree (AST) is then persisted into the binary representation of the module that is then loaded into translation unit where the module import was encountered.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	155
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	156 The binary representation of modules is persisted in the module cache. Imports of a module will first query the module cache and, if a binary representation of the required module is already available, will load that representation directly. Thus, a module's headers will only be parsed once per language configuration, rather than once per translation unit that uses the module.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	157
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	158 Modules maintain references to each of the headers that were part of the module build. If any of those headers changes, or if any of the modules on which a module depends change, then the module will be (automatically) recompiled. The process should never require any user intervention.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	159
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	160 Command-line parameters
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	161 -----------------------
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	162 ``-fmodules``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	163 Enable the modules feature (EXPERIMENTAL).
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	164
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	165 ``-fcxx-modules``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	166 Enable the modules feature for C++ (EXPERIMENTAL and VERY BROKEN).
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	167
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	168 ``-fmodules-cache-path=<directory>``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	169 Specify the path to the modules cache. If not provided, Clang will select a system-appropriate default.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	170
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	171 ``-fno-autolink``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	172 Disable automatic linking against the libraries associated with imported modules.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	173
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	174 ``-fmodules-ignore-macro=macroname``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	175 Instruct modules to ignore the named macro when selecting an appropriate module variant. Use this for macros defined on the command line that don't affect how modules are built, to improve sharing of compiled module files.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	176
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	177 ``-fmodules-prune-interval=seconds``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	178 Specify the minimum delay (in seconds) between attempts to prune the module cache. Module cache pruning attempts to clear out old, unused module files so that the module cache itself does not grow without bound. The default delay is large (604,800 seconds, or 7 days) because this is an expensive operation. Set this value to 0 to turn off pruning.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	179
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	180 ``-fmodules-prune-after=seconds``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	181 Specify the minimum time (in seconds) for which a file in the module cache must be unused (according to access time) before module pruning will remove it. The default delay is large (2,678,400 seconds, or 31 days) to avoid excessive module rebuilding.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	182
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	183 ``-module-file-info <module file name>``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	184 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.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	185
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	186 Module Map Language
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	187 ===================
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	188
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	189 The module map language describes the mapping from header files to the
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	190 logical structure of modules. To enable support for using a library as
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	191 a module, one must write a ``module.map`` file for that library. The
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	192 ``module.map`` file is placed alongside the header files themselves,
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	193 and is written in the module map language described below.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	194
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	195 As an example, the module map file for the C standard library might look a bit like this:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	196
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	197 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	198
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	199 module std [system] {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	200 module complex {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	201 header "complex.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	202 export *
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	203 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	204
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	205 module ctype {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	206 header "ctype.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	207 export *
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	208 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	209
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	210 module errno {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	211 header "errno.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	212 header "sys/errno.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	213 export *
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	214 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	215
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	216 module fenv {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	217 header "fenv.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	218 export *
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	219 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	220
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	221 // ...more headers follow...
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	222 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	223
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	224 Here, the top-level module ``std`` encompasses the whole C standard library. It has a number of submodules containing different parts of the standard library: ``complex`` for complex numbers, ``ctype`` for character types, etc. Each submodule lists one of more headers that provide the contents for that submodule. Finally, the ``export *`` command specifies that anything included by that submodule will be automatically re-exported.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	225
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	226 Lexical structure
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	227 -----------------
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	228 Module map files use a simplified form of the C99 lexer, with the same rules for identifiers, tokens, string literals, ``/* */`` and ``//`` comments. The module map language has the following reserved words; all other C identifiers are valid identifiers.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	229
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	230 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	231
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	232 ``config_macros`` ``export`` ``module``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	233 ``conflict`` ``framework`` ``requires``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	234 ``exclude`` ``header`` ``umbrella``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	235 ``explicit`` ``link``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	236
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	237 Module map file
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	238 ---------------
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	239 A module map file consists of a series of module declarations:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	240
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	241 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	242
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	243 module-map-file:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	244 module-declaration*
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	245
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	246 Within a module map file, modules are referred to by a module-id, which uses periods to separate each part of a module's name:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	247
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	248 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	249
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	250 module-id:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	251 identifier ('.' identifier)*
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	252
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	253 Module declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	254 ------------------
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	255 A module declaration describes a module, including the headers that contribute to that module, its submodules, and other aspects of the module.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	256
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	257 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	258
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	259 module-declaration:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	260 ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` module-id attributes:sub:`opt` '{' module-member* '}'
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	261
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	262 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.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	263
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	264 The ``explicit`` qualifier can only be applied to a submodule, i.e., a module that is nested within another module. The contents of explicit submodules are only made available when the submodule itself was explicitly named in an import declaration or was re-exported from an imported module.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	265
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	266 The ``framework`` qualifier specifies that this module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on Mac OS X and iOS) is contained entirely in directory ``Name.framework``, where ``Name`` is the name of the framework (and, therefore, the name of the module). That directory has the following layout:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	267
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	268 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	269
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	270 Name.framework/
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	271 module.map Module map for the framework
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	272 Headers/ Subdirectory containing framework headers
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	273 Frameworks/ Subdirectory containing embedded frameworks
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	274 Resources/ Subdirectory containing additional resources
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	275 Name Symbolic link to the shared library for the framework
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	276
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	277 The ``system`` attribute specifies that the module is a system module. When a system module is rebuilt, all of the module's header will be considered system headers, which suppresses warnings. This is equivalent to placing ``#pragma GCC system_header`` in each of the module's headers. The form of attributes is described in the section Attributes_, below.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	278
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	279 Modules can have a number of different kinds of members, each of which is described below:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	280
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	281 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	282
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	283 module-member:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	284 requires-declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	285 header-declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	286 umbrella-dir-declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	287 submodule-declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	288 export-declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	289 link-declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	290 config-macros-declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	291 conflict-declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	292
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	293 Requires declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	294 ~~~~~~~~~~~~~~~~~~~~
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	295 A requires-declaration specifies the requirements that an importing translation unit must satisfy to use the module.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	296
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	297 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	298
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	299 requires-declaration:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	300 ``requires`` feature-list
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	301
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	302 feature-list:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	303 identifier (',' identifier)*
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	304
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	305 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.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	306
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	307 The following features are defined:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	308
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	309 altivec
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	310 The target supports AltiVec.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	311
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	312 blocks
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	313 The "blocks" language feature is available.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	314
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	315 cplusplus
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	316 C++ support is available.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	317
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	318 cplusplus11
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	319 C++11 support is available.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	320
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	321 objc
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	322 Objective-C support is available.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	323
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	324 objc_arc
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	325 Objective-C Automatic Reference Counting (ARC) is available
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	326
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	327 opencl
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	328 OpenCL is available
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	329
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	330 tls
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	331 Thread local storage is available.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	332
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	333 target feature
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	334 A specific target feature (e.g., ``sse4``, ``avx``, ``neon``) is available.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	335
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	336
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	337 Example: The ``std`` module can be extended to also include C++ and C++11 headers using a requires-declaration:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	338
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	339 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	340
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	341 module std {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	342 // C standard library...
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	343
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	344 module vector {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	345 requires cplusplus
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	346 header "vector"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	347 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	348
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	349 module type_traits {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	350 requires cplusplus11
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	351 header "type_traits"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	352 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	353 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	354
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	355 Header declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	356 ~~~~~~~~~~~~~~~~~~
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	357 A header declaration specifies that a particular header is associated with the enclosing module.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	358
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	359 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	360
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	361 header-declaration:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	362 ``umbrella``:sub:`opt` ``header`` string-literal
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	363 ``exclude`` ``header`` string-literal
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	364
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	365 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.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	366
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	367 A header with the ``umbrella`` specifier is called an umbrella header. An umbrella header includes all of the headers within its directory (and any subdirectories), and is typically used (in the ``#include`` world) to easily access the full API provided by a particular library. With modules, an umbrella header is a convenient shortcut that eliminates the need to write out ``header`` declarations for every library header. A given directory can only contain a single umbrella header.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	368
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	369 .. note::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	370 Any headers not included by the umbrella header should have
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	371 explicit ``header`` declarations. Use the
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	372 ``-Wincomplete-umbrella`` warning option to ask Clang to complain
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	373 about headers not covered by the umbrella header or the module map.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	374
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	375 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.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	376
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	377 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).
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	378
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	379 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	380
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	381 module std [system] {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	382 exclude header "assert.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	383 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	384
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	385 A given header shall not be referenced by more than one header-declaration.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	386
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	387 Umbrella directory declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	388 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	389 An umbrella directory declaration specifies that all of the headers in the specified directory should be included within the module.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	390
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	391 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	392
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	393 umbrella-dir-declaration:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	394 ``umbrella`` string-literal
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	395
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	396 The string-literal refers to a directory. When the module is built, all of the header files in that directory (and its subdirectories) are included in the module.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	397
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	398 An umbrella-dir-declaration shall not refer to the same directory as the location of an umbrella header-declaration. In other words, only a single kind of umbrella can be specified for a given directory.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	399
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	400 .. note::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	401
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	402 Umbrella directories are useful for libraries that have a large number of headers but do not have an umbrella header.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	403
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	404
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	405 Submodule declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	406 ~~~~~~~~~~~~~~~~~~~~~
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	407 Submodule declarations describe modules that are nested within their enclosing module.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	408
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	409 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	410
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	411 submodule-declaration:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	412 module-declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	413 inferred-submodule-declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	414
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	415 A submodule-declaration that is a module-declaration is a nested module. If the module-declaration has a ``framework`` specifier, the enclosing module shall have a ``framework`` specifier; the submodule's contents shall be contained within the subdirectory ``Frameworks/SubName.framework``, where ``SubName`` is the name of the submodule.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	416
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	417 A submodule-declaration that is an inferred-submodule-declaration describes a set of submodules that correspond to any headers that are part of the module but are not explicitly described by a header-declaration.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	418
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	419 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	420
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	421 inferred-submodule-declaration:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	422 ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` '' attributes:sub:`opt` '{' inferred-submodule-member** '}'
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	423
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	424 inferred-submodule-member:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	425 ``export`` '*'
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	426
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	427 A module containing an inferred-submodule-declaration shall have either an umbrella header or an umbrella directory. The headers to which the inferred-submodule-declaration applies are exactly those headers included by the umbrella header (transitively) or included in the module because they reside within the umbrella directory (or its subdirectories).
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	428
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	429 For each header included by the umbrella header or in the umbrella directory that is not named by a header-declaration, a module declaration is implicitly generated from the inferred-submodule-declaration. The module will:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	430
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	431 * Have the same name as the header (without the file extension)
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	432 * Have the ``explicit`` specifier, if the inferred-submodule-declaration has the ``explicit`` specifier
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	433 * Have the ``framework`` specifier, if the
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	434 inferred-submodule-declaration has the ``framework`` specifier
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	435 * Have the attributes specified by the \ inferred-submodule-declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	436 * Contain a single header-declaration naming that header
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	437 * Contain a single export-declaration ``export ``, if the \ inferred-submodule-declaration* contains the \ inferred-submodule-member ``export *``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	438
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	439 Example: If the subdirectory "MyLib" contains the headers ``A.h`` and ``B.h``, then the following module map:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	440
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	441 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	442
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	443 module MyLib {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	444 umbrella "MyLib"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	445 explicit module * {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	446 export *
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	447 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	448 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	449
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	450 is equivalent to the (more verbose) module map:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	451
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	452 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	453
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	454 module MyLib {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	455 explicit module A {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	456 header "A.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	457 export *
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	458 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	459
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	460 explicit module B {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	461 header "B.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	462 export *
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	463 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	464 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	465
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	466 Export declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	467 ~~~~~~~~~~~~~~~~~~
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	468 An export-declaration specifies which imported modules will automatically be re-exported as part of a given module's API.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	469
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	470 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	471
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	472 export-declaration:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	473 ``export`` wildcard-module-id
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	474
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	475 wildcard-module-id:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	476 identifier
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	477 '*'
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	478 identifier '.' wildcard-module-id
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	479
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	480 The export-declaration names a module or a set of modules that will be re-exported to any translation unit that imports the enclosing module. Each imported module that matches the wildcard-module-id up to, but not including, the first ``*`` will be re-exported.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	481
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	482 Example:: In the following example, importing ``MyLib.Derived`` also provides the API for ``MyLib.Base``:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	483
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	484 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	485
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	486 module MyLib {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	487 module Base {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	488 header "Base.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	489 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	490
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	491 module Derived {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	492 header "Derived.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	493 export Base
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	494 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	495 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	496
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	497 Note that, if ``Derived.h`` includes ``Base.h``, one can simply use a wildcard export to re-export everything ``Derived.h`` includes:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	498
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	499 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	500
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	501 module MyLib {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	502 module Base {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	503 header "Base.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	504 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	505
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	506 module Derived {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	507 header "Derived.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	508 export *
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	509 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	510 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	511
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	512 .. note::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	513
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	514 The wildcard export syntax ``export *`` re-exports all of the
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	515 modules that were imported in the actual header file. Because
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	516 ``#include`` directives are automatically mapped to module imports,
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	517 ``export *`` provides the same transitive-inclusion behavior
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	518 provided by the C preprocessor, e.g., importing a given module
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	519 implicitly imports all of the modules on which it depends.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	520 Therefore, liberal use of ``export *`` provides excellent backward
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	521 compatibility for programs that rely on transitive inclusion (i.e.,
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	522 all of them).
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	523
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	524 Link declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	525 ~~~~~~~~~~~~~~~~
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	526 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.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	527
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	528 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	529
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	530 link-declaration:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	531 ``link`` ``framework``:sub:`opt` string-literal
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	532
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	533 The string-literal specifies the name of the library or framework against which the program should be linked. For example, specifying "clangBasic" would instruct the linker to link with ``-lclangBasic`` for a Unix-style linker.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	534
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	535 A link-declaration with the ``framework`` specifies that the linker should link against the named framework, e.g., with ``-framework MyFramework``.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	536
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	537 .. note::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	538
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	539 Automatic linking with the ``link`` directive is not yet widely
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	540 implemented, because it requires support from both the object file
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	541 format and the linker. The notion is similar to Microsoft Visual
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	542 Studio's ``#pragma comment(lib...)``.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	543
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	544 Configuration macros declaration
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	545 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	546 The config-macros-declaration specifies the set of configuration macros that have an effect on the the API of the enclosing module.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	547
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	548 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	549
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	550 config-macros-declaration:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	551 ``config_macros`` attributes:sub:`opt` config-macro-list:sub:`opt`
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	552
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	553 config-macro-list:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	554 identifier (',' identifier)*
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	555
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	556 Each identifier in the config-macro-list specifies the name of a macro. The compiler is required to maintain different variants of the given module for differing definitions of any of the named macros.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	557
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	558 A config-macros-declaration shall only be present on a top-level module, i.e., a module that is not nested within an enclosing module.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	559
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	560 The ``exhaustive`` attribute specifies that the list of macros in the config-macros-declaration is exhaustive, meaning that no other macro definition is intended to have an effect on the API of that module.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	561
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	562 .. note::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	563
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	564 The ``exhaustive`` attribute implies that any macro definitions
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	565 for macros not listed as configuration macros should be ignored
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	566 completely when building the module. As an optimization, the
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	567 compiler could reduce the number of unique module variants by not
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	568 considering these non-configuration macros. This optimization is not
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	569 yet implemented in Clang.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	570
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	571 A translation unit shall not import the same module under different definitions of the configuration macros.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	572
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	573 .. note::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	574
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	575 Clang implements a weak form of this requirement: the definitions
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	576 used for configuration macros are fixed based on the definitions
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	577 provided by the command line. If an import occurs and the definition
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	578 of any configuration macro has changed, the compiler will produce a
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	579 warning (under the control of ``-Wconfig-macros``).
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	580
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	581 Example: A logging library might provide different API (e.g., in the form of different definitions for a logging macro) based on the ``NDEBUG`` macro setting:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	582
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	583 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	584
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	585 module MyLogger {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	586 umbrella header "MyLogger.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	587 config_macros [exhaustive] NDEBUG
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	588 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	589
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	590 Conflict declarations
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	591 ~~~~~~~~~~~~~~~~~~~~~
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	592 A conflict-declaration describes a case where the presence of two different modules in the same translation unit is likely to cause a problem. For example, two modules may provide similar-but-incompatible functionality.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	593
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	594 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	595
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	596 conflict-declaration:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	597 ``conflict`` module-id ',' string-literal
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	598
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	599 The module-id of the conflict-declaration specifies the module with which the enclosing module conflicts. The specified module shall not have been imported in the translation unit when the enclosing module is imported.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	600
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	601 The string-literal provides a message to be provided as part of the compiler diagnostic when two modules conflict.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	602
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	603 .. note::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	604
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	605 Clang emits a warning (under the control of ``-Wmodule-conflict``)
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	606 when a module conflict is discovered.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	607
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	608 Example:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	609
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	610 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	611
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	612 module Conflicts {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	613 explicit module A {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	614 header "conflict_a.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	615 conflict B, "we just don't like B"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	616 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	617
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	618 module B {
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	619 header "conflict_b.h"
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	620 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	621 }
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	622
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	623
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	624 Attributes
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	625 ----------
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	626 Attributes are used in a number of places in the grammar to describe specific behavior of other declarations. The format of attributes is fairly simple.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	627
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	628 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	629
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	630 attributes:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	631 attribute attributes:sub:`opt`
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	632
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	633 attribute:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	634 '[' identifier ']'
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	635
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	636 Any identifier can be used as an attribute, and each declaration specifies what attributes can be applied to it.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	637
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	638 Modularizing a Platform
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	639 =======================
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	640 To get any benefit out of modules, one needs to introduce module maps for software libraries starting at the bottom of the stack. This typically means introducing a module map covering the operating system's headers and the C standard library headers (in ``/usr/include``, for a Unix system).
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	641
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	642 The module maps will be written using the `module map language`_, which provides the tools necessary to describe the mapping between headers and modules. Because the set of headers differs from one system to the next, the module map will likely have to be somewhat customized for, e.g., a particular distribution and version of the operating system. Moreover, the system headers themselves may require some modification, if they exhibit any anti-patterns that break modules. Such common patterns are described below.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	643
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	644 Macro-guarded copy-and-pasted definitions
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	645 System headers vend core types such as ``size_t`` for users. These types are often needed in a number of system headers, and are almost trivial to write. Hence, it is fairly common to see a definition such as the following copy-and-pasted throughout the headers:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	646
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	647 .. parsed-literal::
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	648
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	649 #ifndef _SIZE_T
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	650 #define _SIZE_T
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	651 typedef __SIZE_TYPE__ size_t;
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	652 #endif
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	653
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	654 Unfortunately, when modules compiles all of the C library headers together into a single module, only the first actual type definition of ``size_t`` will be visible, and then only in the submodule corresponding to the lucky first header. Any other headers that have copy-and-pasted versions of this pattern will not have a definition of ``size_t``. Importing the submodule corresponding to one of those headers will therefore not yield ``size_t`` as part of the API, because it wasn't there when the header was parsed. The fix for this problem is either to pull the copied declarations into a common header that gets included everywhere ``size_t`` is part of the API, or to eliminate the ``#ifndef`` and redefine the ``size_t`` type. The latter works for C++ headers and C11, but will cause an error for non-modules C90/C99, where redefinition of ``typedefs`` is not permitted.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	655
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	656 Conflicting definitions
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	657 Different system headers may provide conflicting definitions for various macros, functions, or types. These conflicting definitions don't tend to cause problems in a pre-modules world unless someone happens to include both headers in one translation unit. Since the fix is often simply "don't do that", such problems persist. Modules requires that the conflicting definitions be eliminated or that they be placed in separate modules (the former is generally the better answer).
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	658
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	659 Missing includes
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	660 Headers are often missing ``#include`` directives for headers that they actually depend on. As with the problem of conflicting definitions, this only affects unlucky users who don't happen to include headers in the right order. With modules, the headers of a particular module will be parsed in isolation, so the module may fail to build if there are missing includes.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	661
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	662 Headers that vend multiple APIs at different times
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	663 Some systems have headers that contain a number of different kinds of API definitions, only some of which are made available with a given include. For example, the header may vend ``size_t`` only when the macro ``__need_size_t`` is defined before that header is included, and also vend ``wchar_t`` only when the macro ``__need_wchar_t`` is defined. Such headers are often included many times in a single translation unit, and will have no include guards. There is no sane way to map this header to a submodule. One can either eliminate the header (e.g., by splitting it into separate headers, one per actual API) or simply ``exclude`` it in the module map.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	664
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	665 To detect and help address some of these problems, the ``clang-tools-extra`` repository contains a ``modularize`` tool that parses a set of given headers and attempts to detect these problems and produce a report. See the tool's in-source documentation for information on how to check your system or library headers.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	666
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	667 Future Directions
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	668 =================
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	669 Modules is an experimental feature, and there is much work left to do to make it both real and useful. Here are a few ideas:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	670
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	671 Detect unused module imports
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	672 Unlike with ``#include`` directives, it should be fairly simple to track whether a directly-imported module has ever been used. By doing so, Clang can emit ``unused import`` or ``unused #include`` diagnostics, including Fix-Its to remove the useless imports/includes.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	673
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	674 Fix-Its for missing imports
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	675 It's fairly common for one to make use of some API while writing code, only to get a compiler error about "unknown type" or "no function named" because the corresponding header has not been included. Clang should detect such cases and auto-import the required module (with a Fix-It!).
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	676
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	677 Improve modularize
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	678 The modularize tool is both extremely important (for deployment) and extremely crude. It needs better UI, better detection of problems (especially for C++), and perhaps an assistant mode to help write module maps for you.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	679
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	680 C++ Support
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	681 Modules clearly has to work for C++, or we'll never get to use it for the Clang code base.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	682
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	683 Where To Learn More About Modules
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	684 =================================
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	685 The Clang source code provides additional information about modules:
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	686
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	687 ``clang/lib/Headers/module.map``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	688 Module map for Clang's compiler-specific header files.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	689
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	690 ``clang/test/Modules/``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	691 Tests specifically related to modules functionality.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	692
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	693 ``clang/include/clang/Basic/Module.h``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	694 The ``Module`` class in this header describes a module, and is used throughout the compiler to implement modules.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	695
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	696 ``clang/include/clang/Lex/ModuleMap.h``
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	697 The ``ModuleMap`` class in this header describes the full module map, consisting of all of the module map files that have been parsed, and providing facilities for looking up module maps and mapping between modules and headers (in both directions).
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	698
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	699 PCHInternals_
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	700 Information about the serialized AST format used for precompiled headers and modules. The actual implementation is in the ``clangSerialization`` library.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	701
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	702 .. [#] Automatic linking against the libraries of modules requires specific linker support, which is not widely available.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	703
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	704 .. [#] Modules are only available in C and Objective-C; a separate flag ``-fcxx-modules`` enables modules support for C++, which is even more experimental and broken.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	705
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	706 .. [#] There are certain anti-patterns that occur in headers, particularly system headers, that cause problems for modules. The section `Modularizing a Platform`_ describes some of them.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	707
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	708 .. [#] The second instance is actually a new thread within the current process, not a separate process. However, the original compiler instance is blocked on the execution of this thread.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	709
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	710 .. [#] The preprocessing context in which the modules are parsed is actually dependent on the command-line options provided to the compiler, including the language dialect and any ``-D`` options. However, the compiled modules for different command-line options are kept distinct, and any preprocessor directives that occur within the translation unit are ignored. See the section on the `Configuration macros declaration`_ for more information.
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	711
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	712 .. _PCHInternals: PCHInternals.html
9ad51c7bc036 1st commit. remove git dir and add all files. Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp> parents: diff changeset	713

Mercurial > hg > CbC > CbC_llvm

annotate tools/clang/docs/Modules.rst @ 3:9ad51c7bc036