Skip to content

Commit b5ecb90

Browse files
committedMar 28, 2014
Document module.private.modulemap and module_private.map.
Requested in <rdar://problem/16188740>. llvm-svn: 205030
1 parent 3907f2a commit b5ecb90

File tree

1 file changed

+58
-1
lines changed

1 file changed

+58
-1
lines changed
 

‎clang/docs/Modules.rst

+58-1
Original file line numberDiff line numberDiff line change
@@ -242,7 +242,7 @@ a module, one must write a ``module.modulemap`` file for that library. The
242242
and is written in the module map language described below.
243243

244244
.. note::
245-
For compatibility with previous releases, if a module map file named ``module.modulemap`` is not found, Clang will also search for a file named ``module.map``. This behavior is deprecated and we plan to eventually remove it.
245+
For compatibility with previous releases, if a module map file named ``module.modulemap`` is not found, Clang will also search for a file named ``module.map``. This behavior is deprecated and we plan to eventually remove it.1
246246

247247
As an example, the module map file for the C standard library might look a bit like this:
248248

@@ -730,6 +730,63 @@ Attributes are used in a number of places in the grammar to describe specific be
730730
731731
Any *identifier* can be used as an attribute, and each declaration specifies what attributes can be applied to it.
732732

733+
Private Module Map Files
734+
------------------------
735+
Module map files are typically named ``module.modulemap`` and live
736+
either alongside the headers they describe or in a parent directory of
737+
the headers they describe. These module maps typically describe all of
738+
the API for the library.
739+
740+
However, in some cases, the presence or absence of particular headers
741+
is used to distinguish between the "public" and "private" APIs of a
742+
particular library. For example, a library may contain the headers
743+
``Foo.h`` and ``Foo_Private.h``, providing public and private APIs,
744+
respectively. Additionally, ``Foo_Private.h`` may only be available on
745+
some versions of library, and absent in others. One cannot easily
746+
express this with a single module map file in the library:
747+
748+
.. parsed-literal::
749+
750+
module Foo {
751+
header "Foo.h"
752+
753+
explicit module Private {
754+
header "Foo_Private.h"
755+
}
756+
}
757+
758+
759+
because the header ``Foo_Private.h`` won't always be available. The
760+
module map file could be customized based on whether
761+
``Foo_Private.h``is available or not, but doing so requires custom
762+
build machinery.
763+
764+
Private module map files, which are named ``module.private.modulemap``
765+
(or, for backward compatibility, ``module_private.map``), allow one to
766+
augment the primary module map file with an additional submodule. For
767+
example, we would split the module map file above into two module map
768+
files:
769+
770+
.. parsed-literal::
771+
772+
/* module.modulemap */
773+
module Foo {
774+
header "Foo.h"
775+
}
776+
777+
/* module.private.modulemap */
778+
explicit module Foo.Private {
779+
header "Foo_Private.h"
780+
}
781+
782+
783+
When a ``module.private.modulemap`` file is found alongside a
784+
``module.modulemap`` file, it is loaded after the ``module.modulemap``
785+
file. In our example library, the ``module.private.modulemap`` file
786+
would be available when ``Foo_Private.h`` is available, making it
787+
easier to split a library's public and private APIs along header
788+
boundaries.
789+
733790
Modularizing a Platform
734791
=======================
735792
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).

0 commit comments

Comments
 (0)