<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2018-02-11 Sun 23:28 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Module TS Supports Legacy Integration</title>
<meta name="generator" content="Org mode" />
<style type="text/css">
 <!--/*--><![CDATA[/*><!--*/
  .title  { text-align: center;
             margin-bottom: .2em; }
  .subtitle { text-align: center;
              font-size: medium;
              font-weight: bold;
              margin-top:0; }
  .todo   { font-family: monospace; color: red; }
  .done   { font-family: monospace; color: green; }
  .priority { font-family: monospace; color: orange; }
  .tag    { background-color: #eee; font-family: monospace;
            padding: 2px; font-size: 80%; font-weight: normal; }
  .timestamp { color: #bebebe; }
  .timestamp-kwd { color: #5f9ea0; }
  .org-right  { margin-left: auto; margin-right: 0px;  text-align: right; }
  .org-left   { margin-left: 0px;  margin-right: auto; text-align: left; }
  .org-center { margin-left: auto; margin-right: auto; text-align: center; }
  .underline { text-decoration: underline; }
  #postamble p, #preamble p { font-size: 90%; margin: .2em; }
  p.verse { margin-left: 3%; }
  pre {
    border: 1px solid #ccc;
    box-shadow: 3px 3px 3px #eee;
    padding: 8pt;
    font-family: monospace;
    overflow: auto;
    margin: 1.2em;
  }
  pre.src {
    position: relative;
    overflow: visible;
    padding-top: 1.2em;
  }
  pre.src:before {
    display: none;
    position: absolute;
    background-color: white;
    top: -10px;
    right: 10px;
    padding: 3px;
    border: 1px solid black;
  }
  pre.src:hover:before { display: inline;}
  /* Languages per Org manual */
  pre.src-asymptote:before { content: 'Asymptote'; }
  pre.src-awk:before { content: 'Awk'; }
  pre.src-C:before { content: 'C'; }
  /* pre.src-C++ doesn't work in CSS */
  pre.src-clojure:before { content: 'Clojure'; }
  pre.src-css:before { content: 'CSS'; }
  pre.src-D:before { content: 'D'; }
  pre.src-ditaa:before { content: 'ditaa'; }
  pre.src-dot:before { content: 'Graphviz'; }
  pre.src-calc:before { content: 'Emacs Calc'; }
  pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
  pre.src-fortran:before { content: 'Fortran'; }
  pre.src-gnuplot:before { content: 'gnuplot'; }
  pre.src-haskell:before { content: 'Haskell'; }
  pre.src-hledger:before { content: 'hledger'; }
  pre.src-java:before { content: 'Java'; }
  pre.src-js:before { content: 'Javascript'; }
  pre.src-latex:before { content: 'LaTeX'; }
  pre.src-ledger:before { content: 'Ledger'; }
  pre.src-lisp:before { content: 'Lisp'; }
  pre.src-lilypond:before { content: 'Lilypond'; }
  pre.src-lua:before { content: 'Lua'; }
  pre.src-matlab:before { content: 'MATLAB'; }
  pre.src-mscgen:before { content: 'Mscgen'; }
  pre.src-ocaml:before { content: 'Objective Caml'; }
  pre.src-octave:before { content: 'Octave'; }
  pre.src-org:before { content: 'Org mode'; }
  pre.src-oz:before { content: 'OZ'; }
  pre.src-plantuml:before { content: 'Plantuml'; }
  pre.src-processing:before { content: 'Processing.js'; }
  pre.src-python:before { content: 'Python'; }
  pre.src-R:before { content: 'R'; }
  pre.src-ruby:before { content: 'Ruby'; }
  pre.src-sass:before { content: 'Sass'; }
  pre.src-scheme:before { content: 'Scheme'; }
  pre.src-screen:before { content: 'Gnu Screen'; }
  pre.src-sed:before { content: 'Sed'; }
  pre.src-sh:before { content: 'shell'; }
  pre.src-sql:before { content: 'SQL'; }
  pre.src-sqlite:before { content: 'SQLite'; }
  /* additional languages in org.el's org-babel-load-languages alist */
  pre.src-forth:before { content: 'Forth'; }
  pre.src-io:before { content: 'IO'; }
  pre.src-J:before { content: 'J'; }
  pre.src-makefile:before { content: 'Makefile'; }
  pre.src-maxima:before { content: 'Maxima'; }
  pre.src-perl:before { content: 'Perl'; }
  pre.src-picolisp:before { content: 'Pico Lisp'; }
  pre.src-scala:before { content: 'Scala'; }
  pre.src-shell:before { content: 'Shell Script'; }
  pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
  /* additional language identifiers per "defun org-babel-execute"
       in ob-*.el */
  pre.src-cpp:before  { content: 'C++'; }
  pre.src-abc:before  { content: 'ABC'; }
  pre.src-coq:before  { content: 'Coq'; }
  pre.src-groovy:before  { content: 'Groovy'; }
  /* additional language identifiers from org-babel-shell-names in
     ob-shell.el: ob-shell is the only babel language using a lambda to put
     the execution function name together. */
  pre.src-bash:before  { content: 'bash'; }
  pre.src-csh:before  { content: 'csh'; }
  pre.src-ash:before  { content: 'ash'; }
  pre.src-dash:before  { content: 'dash'; }
  pre.src-ksh:before  { content: 'ksh'; }
  pre.src-mksh:before  { content: 'mksh'; }
  pre.src-posh:before  { content: 'posh'; }
  /* Additional Emacs modes also supported by the LaTeX listings package */
  pre.src-ada:before { content: 'Ada'; }
  pre.src-asm:before { content: 'Assembler'; }
  pre.src-caml:before { content: 'Caml'; }
  pre.src-delphi:before { content: 'Delphi'; }
  pre.src-html:before { content: 'HTML'; }
  pre.src-idl:before { content: 'IDL'; }
  pre.src-mercury:before { content: 'Mercury'; }
  pre.src-metapost:before { content: 'MetaPost'; }
  pre.src-modula-2:before { content: 'Modula-2'; }
  pre.src-pascal:before { content: 'Pascal'; }
  pre.src-ps:before { content: 'PostScript'; }
  pre.src-prolog:before { content: 'Prolog'; }
  pre.src-simula:before { content: 'Simula'; }
  pre.src-tcl:before { content: 'tcl'; }
  pre.src-tex:before { content: 'TeX'; }
  pre.src-plain-tex:before { content: 'Plain TeX'; }
  pre.src-verilog:before { content: 'Verilog'; }
  pre.src-vhdl:before { content: 'VHDL'; }
  pre.src-xml:before { content: 'XML'; }
  pre.src-nxml:before { content: 'XML'; }
  /* add a generic configuration mode; LaTeX export needs an additional
     (add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
  pre.src-conf:before { content: 'Configuration File'; }

  table { border-collapse:collapse; }
  caption.t-above { caption-side: top; }
  caption.t-bottom { caption-side: bottom; }
  td, th { vertical-align:top;  }
  th.org-right  { text-align: center;  }
  th.org-left   { text-align: center;   }
  th.org-center { text-align: center; }
  td.org-right  { text-align: right;  }
  td.org-left   { text-align: left;   }
  td.org-center { text-align: center; }
  dt { font-weight: bold; }
  .footpara { display: inline; }
  .footdef  { margin-bottom: 1em; }
  .figure { padding: 1em; }
  .figure p { text-align: center; }
  .inlinetask {
    padding: 10px;
    border: 2px solid gray;
    margin: 10px;
    background: #ffffcc;
  }
  #org-div-home-and-up
   { text-align: right; font-size: 70%; white-space: nowrap; }
  textarea { overflow-x: auto; }
  .linenr { font-size: smaller }
  .code-highlighted { background-color: #ffff00; }
  .org-info-js_info-navigation { border-style: none; }
  #org-info-js_console-label
    { font-size: 10px; font-weight: bold; white-space: nowrap; }
  .org-info-js_search-highlight
    { background-color: #ffff00; color: #000000; font-weight: bold; }
  .org-svg { width: 90%; }
  /*]]>*/-->
</style>
<link rel="stylesheet" type="text/css" href="https://raw.githubusercontent.com/steve-downey/css/master/smd-zenburn.css" />
<script type="text/javascript">
/*
@licstart  The following is the entire license notice for the
JavaScript code in this tag.

Copyright (C) 2012-2018 Free Software Foundation, Inc.

The JavaScript code in this tag is free software: you can
redistribute it and/or modify it under the terms of the GNU
General Public License (GNU GPL) as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version.  The code is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU GPL for more details.

As additional permission under GNU GPL version 3 section 7, you
may distribute non-source (e.g., minimized or compacted) forms of
that code without the copy of the GNU GPL normally required by
section 4, provided you include this license notice and a URL
through which recipients can access the Corresponding Source.


@licend  The above is the entire license notice
for the JavaScript code in this tag.
*/
<!--/*--><![CDATA[/*><!--*/
 function CodeHighlightOn(elem, id)
 {
   var target = document.getElementById(id);
   if(null != target) {
     elem.cacheClassElem = elem.className;
     elem.cacheClassTarget = target.className;
     target.className = "code-highlighted";
     elem.className   = "code-highlighted";
   }
 }
 function CodeHighlightOff(elem, id)
 {
   var target = document.getElementById(id);
   if(elem.cacheClassElem)
     elem.className = elem.cacheClassElem;
   if(elem.cacheClassTarget)
     target.className = elem.cacheClassTarget;
 }
/*]]>*///-->
</script>
</head>
<body>
<div id="content">
<h1 class="title">Module TS Supports Legacy Integration</h1>
<ul class="org-ul">
<li>Document number: P0909R0</li>
<li>Date:  2018-02-11</li>
<li>Author: Steve Downey &lt;sdowney2@bloomberg.net&gt;</li>
<li>Audience: LEWG, Core</li>
</ul>


<div id="outline-container-orgb10137e" class="outline-2">
<h2 id="orgb10137e">Abstract</h2>
<div class="outline-text-2" id="text-orgb10137e">
<p>
We believe the model for modules as proposed is fundamentally sound. With the changes published in N4720 it is now minimally possible to convert a very large codebase to use modules in a purely additive manner. Existing code will not require rewrite in order to be exposed through a module interface. A new module interface unit can be written that exports names without requiring that the existing source code be modified. Current consumers of a library can continue to use the existing library and headers without requiring that all are migrated to modules at once.
</p>

<p>
Preprocessor macros are not part of the model for the Modules TS. This will mean there are some libraries that can not be modularized without changes. However, with the wording in earlier versions of the TS, it would not have been feasible for any library.
</p>
</div>
</div>

<div id="outline-container-org87d2bde" class="outline-2">
<h2 id="org87d2bde">Core Use Case</h2>
<div class="outline-text-2" id="text-org87d2bde">
<p>
Bloomberg has a very large existing base of C++ code. We do not believe we are unique, and we do believe our concerns are shared by any entity with a large existing investment in C++.
</p>
</div>
<div id="outline-container-orgef1c0b7" class="outline-3">
<h3 id="orgef1c0b7">Background</h3>
<div class="outline-text-3" id="text-orgef1c0b7">
<ol class="org-ol">
<li>Over 250,000 translation units</li>
<li>Atomic changes across the codebase are not possible</li>
<li>The same code is built on 4 major operating systems using 4 different compilers</li>
</ol>
</div>
</div>
<div id="outline-container-org7ccb340" class="outline-3">
<h3 id="org7ccb340">Business Requirements</h3>
<div class="outline-text-3" id="text-org7ccb340">
<ol class="org-ol">
<li>Core services must always build</li>
<li>Breaking non-core services is discouraged</li>
<li>Both bug fixes and features are delivered at tip of tree, not to old versions</li>
</ol>

<p>
This has several implications for creating a module for an existing facility. The pre-existing header must still work. It must be possible to use both the existing header and the module in one program. It must also be possible to use the header and the module in a single translation unit, mentioning them in either order, as transitive includes are converted to imports.
</p>
</div>
</div>
</div>

<div id="outline-container-org869a2f4" class="outline-2">
<h2 id="org869a2f4">Solution as outlined in N4270</h2>
<div class="outline-text-2" id="text-org869a2f4">
<p>
From [dcl.module.interface] in N4270, in paragraph 2:
</p>
<blockquote>
<p>
If the declaration is a using-declaration (10.3.3), any entity to which the using-declarator ultimately refers shall have been introduced with a name having external linkage. [Example: <br />
    int f() // f has external linkage <br />
    export module M; <br />
    export using ::f; // OK <br />
</p>
</blockquote>

<p>
In the example, the name f from the global namespace is exported from the module with the same semantic properties it had at the point it was exported. For names attached to entities with module linkage this can introduce subtle issues; however  names which are made available by inclusion into the module interface unit from an existing header will be exactly as usable to an importing translation unit as to one that included it. They will have the same semantic properties.
</p>

<p>
The exported using declaration will also have the same associated entities as the original definition. This may allow a tighter control of names made visible to clients through the module interface than through the header file. It may be possible, for example, to choose to not export names from a detail namespace. Those entities will be reachable for use, but not directly usable by clients.
</p>
</div>
</div>

<div id="outline-container-orgb1785b9" class="outline-2">
<h2 id="orgb1785b9">Example</h2>
<div class="outline-text-2" id="text-orgb1785b9">
<div class="org-src-container">
<pre class="src src-C++"><span style="color: #8e908c; font-style: italic;">// </span><span style="color: #8e908c; font-style: italic;">facility.h</span>
<span style="color: #8959a8;">#include</span> <span style="color: #718c00;">&lt;other_library.h&gt;</span>

<span style="color: #8959a8; font-weight: bold;">namespace</span> <span style="color: #3e999f;">facility</span> {
<span style="color: #8959a8; font-weight: bold;">class</span> <span style="color: #eab700;">Foo</span> {};
<span style="color: #eab700;">int</span> <span style="color: #4271ae; font-weight: bold;">func</span>(<span style="color: #eab700;">Foo</span> <span style="color: #8959a8; font-weight: bold;">const</span>&amp; <span style="color: #4d4d4c;">foo</span>);
<span style="color: #eab700;">int</span> <span style="color: #4271ae; font-weight: bold;">func</span>(<span style="color: #eab700;">Foo</span>&amp;&amp; <span style="color: #4d4d4c;">foo</span>);
<span style="color: #8959a8; font-weight: bold;">enum</span> <span style="color: #eab700;">BAR</span> { <span style="color: #4d4d4c;">ONE</span>, <span style="color: #4d4d4c;">TWO</span>, <span style="color: #4d4d4c;">THREE</span> };
<span style="color: #8e908c; font-style: italic;">// </span><span style="color: #8e908c; font-style: italic;">...</span>
} <span style="color: #8e908c; font-style: italic;">// </span><span style="color: #8e908c; font-style: italic;">namespace facility</span>
</pre>
</div>
<div class="org-src-container">
<pre class="src src-C++"><span style="color: #8e908c; font-style: italic;">// </span><span style="color: #8e908c; font-style: italic;">facility module interface unit</span>
<span style="color: #8959a8;">#include</span> <span style="color: #718c00;">&lt;facility.h&gt;</span> <span style="color: #8e908c; font-style: italic;">// </span><span style="color: #8e908c; font-style: italic;">outside the purview of module facility</span>

<span style="color: #8959a8; font-weight: bold;">export</span> <span style="color: #eab700;">module</span> <span style="color: #4d4d4c;">facility</span>;

<span style="color: #eab700;">export</span> <span style="color: #8959a8; font-weight: bold;">namespace</span> <span style="color: #3e999f;">facility</span> {}
<span style="color: #eab700;">export</span> <span style="color: #8959a8; font-weight: bold;">using</span> <span style="color: #3e999f;">facility</span>::Foo;  <span style="color: #8e908c; font-style: italic;">// </span><span style="color: #8e908c; font-style: italic;">exports complete type Foo</span>
<span style="color: #eab700;">export</span> <span style="color: #8959a8; font-weight: bold;">using</span> <span style="color: #3e999f;">facility</span>::func; <span style="color: #8e908c; font-style: italic;">// </span><span style="color: #8e908c; font-style: italic;">exports both func from facility</span>
<span style="color: #eab700;">export</span> <span style="color: #8959a8; font-weight: bold;">using</span> <span style="color: #3e999f;">facility</span>::BAR;  <span style="color: #8e908c; font-style: italic;">// </span><span style="color: #8e908c; font-style: italic;">exports BAR, and associated enumerators</span>
</pre>
</div>
<div class="org-src-container">
<pre class="src src-C++"><span style="color: #8e908c; font-style: italic;">// </span><span style="color: #8e908c; font-style: italic;">main.cpp</span>
<span style="color: #eab700;">import</span> <span style="color: #4d4d4c;">facility</span>;

<span style="color: #eab700;">int</span> <span style="color: #4271ae; font-weight: bold;">main</span>() {
    <span style="color: #3e999f;">facility</span>::<span style="color: #eab700;">Foo</span> <span style="color: #4d4d4c;">f</span>;
    <span style="color: #eab700;">int</span>           <span style="color: #4d4d4c;">i</span> = <span style="color: #3e999f;">facility</span>::func(f);
    <span style="color: #3e999f;">facility</span>::<span style="color: #eab700;">BAR</span> <span style="color: #4d4d4c;">b</span> = <span style="color: #3e999f;">facility</span>::ONE;
    <span style="color: #8959a8; font-weight: bold;">return</span> i;
}
</pre>
</div>

<p>
The <code class="src src-C++">facility.h</code> header is included in the module interface outside the purview of the module. This ensures that none of the entities declared in <code class="src src-C++">facility.h</code> have module linkage. This maintains compatibility with the existing library where the entities from the facility are defined. This is critical for interoperation with translation units using the module interface and translation units using the header. It is important, also, that it is not an error to both import the module and to include the header. The names made available via the module are the same as those declared in the header.
</p>

<p>
The header <code class="src src-C++">other_library.h</code> is not exported at all. However, if any of the names exported from the module have associated entities provided by that header, those will be made available to the importer of the module. This is important, as it bounds the domain the implementor of the module interface unit must consider.
</p>
</div>
</div>

<div id="outline-container-org28a03b0" class="outline-2">
<h2 id="org28a03b0">Conclusion</h2>
<div class="outline-text-2" id="text-org28a03b0">
<p>
The published Modules TS now supports the minimum capabilities necessary for safely modularizing an existing library in an additive manor. Only new code in the module interface unit needs to be written in order for clients to consume the library via import.
</p>

<p>
Libraries that publish macros to clients, such as logging facilities, which typically need to reliably capture file and line information at the invocation site, are still an issue.
</p>
</div>
</div>
</div>
</body>
</html>
