Title: C++20: A Simple Math Module

Author: Bob Schmidt

Date: 01 August 2020 17:59:51 +01:00 or Sat, 01 August 2020 17:59:51 +01:00

Summary: Modules are one big change introduced by C++20. Rainer Grimm describes how to build a mathematics module.

Body: 

Modules are one of the four prominent features of C++20. They overcome the restrictions of header files and promise a lot: faster build-times, fewer violations of the One-Definition-Rule, less usage of the preprocessor.

The long history of modules in C++

Modules may be older than you think. My short historic detour should give you an idea how long it takes to get something so valuable into the C++ standard.

In 2004, Daveed Vandevoorde wrote proposal N1736.pdf [N1736], which described the idea of modules for the first time. It took until 2012 to get a dedicated Study Group (SG2, Modules) for modules. In 2017, Clang 5.0 and MSVC 19.1 provided the first implementation. One year later, the Modules TS (technical specification) was finalized. Around the same time, Google proposed the so-called ATOM (Another Take On Modules) proposal [P0947] for modules. In 2019, the Modules TS and the ATOM proposal was merged into the C++20 committee draft [N4842], which is the syntax I use when writing about modules.

The C++ standardization process is democratic. The section Standardization [ISO] gives you more information about the standard and the standardization process. Figure 1 shows the various study groups.

Figure 1

Explaining modules from a user’s perspective is quite easy, but this does not hold true for the implementer’s perspective. My plan for this article is to start with a simple modules math and add more features to it as we go.

The math module

First, here is my first module:

  // math.ixx
  export module math;
  export int add(int fir, int sec){
    return fir + sec;
  }

The expression export module math is the module declaration. By putting export before the function add, add is exported and can, therefore, be used by a consumer of my module.

  // client.cpp
  import math;
  int main() {
    add(2000, 20);
  }

import math imports the module math and makes the exported names in the module visible to the client.cpp. Let me say a few words about module declaration files before I build the module.

Module declaration files

Did you noticed the strange name of the module: math.ixx.

• cl.exe (Microsoft) uses the required extension ixx. The ixx stands for a module interface source.
• Clang uses the extension cppm. cppm presumably stands for a cpp module declaration. Wrong!!! The documentation to Clang is misleading. Stop using the cppm extension until have you read my post about my attempt [Rainer20]. Use the extension cpp. I assume you don’t want to make the same Odyssey as me.
• I don’t know of a GCC extension.

Compile the module math

To compile the module, you have to use a very current Clang, GCC, or cl.exe compiler. In this article, I’m using cl.exe on Windows. The Microsoft blog provides two excellent introductions to modules: Overview of modules in C++ [Microsoft-1] and C++ Modules conformance improvements with MSVC in Visual Studio 2019 16.5 [Microsoft-2]. In contrast, the lack of introductions to the Clang and GCC compilers makes it quite difficult to use modules.

Figure 2 shows more details of the Microsoft compiler I used.

Figure 2

These are the steps to compile and use the module with the Microsoft compiler. I only show the minimal command line. With an older Microsoft compiler, you have to use at least /std:cpplatest.

 cl.exe /experimental:module /c math.ixx ①
 cl.exe /experimental:module client.cpp math.obj ②

① Creates an obj file math.obj and an IFC file math.ifc. The IFC file contains the metadata description of the module interface. The binary format of the IFC is modeled after the Internal Program Representation by Gabriel Dos Reis and Bjarne Stroustrup (2004/2005).

② Creates the executable client.exe. Without the implicitly used math.ifc file from the first step, the linker can not find the module (see Figure 3).

Figure 3

For obvious reasons, I am not showing you the output of the program execution. Let me change this.

Global module fragment

The global module fragment is meant to compose module interfaces. It’s a place to use preprocessor directives such as #include so that the module interface can compile. The code in the global module fragment is not exported by the module interface.

The second version of the module math supports the two functions add and getProduct (see Listing 1).

module;              // global module fragment (1)

#include <numeric>
#include <vector>

export module math;  // module declaration (2)

export int add(int fir, int sec)
{
  return fir + sec;
}
export int getProduct(const std::vector<int>& vec)
{
  return std::accumulate(vec.begin(), vec.end(),
  1, std::multiplies<int>());
}
			

I included the necessary headers between the global module fragment (line 1) and the module declaration (line 2).

The client imports the module math and uses its functionality (see Listing 2 and Figure 4).

#include <iostream>
#include <vector>

import math;

int main() {
  std::cout << std::endl;   
  std::cout << "add(2000, 20): " 
    << add(2000, 20) << std::endl;
  std::vector<int> myVec{1, 2, 3, 4, 5, 6, 7, 8, 
    9, 10};
  std::cout << "getProduct(myVec): " 
    << getProduct(myVec) << std::endl;
  std::cout << std::endl;
}
			

Figure 4

Maybe, you don’t like using a Standard Library Header anymore. Microsoft supports modules for all STL headers. Here is what I found out from the Microsoft C++ team blog [Microsoft-3]:

• std.regex provides the content of the header <regex>
• std.filesystem provides the content of the header <experimental/filesystem>
• std.memory provides the content of the header <memory>
• std.threading provides the contents of headers:
  • <atomic>
  • <condition_variable>
  • <future>
  • <mutex>
  • <shared_mutex>
  • <thread>
• std.core provides everything else in the C++ Standard Library

To use the Microsoft Standard Library modules, you have to specify the exception handling model (/EHsc) and the multithreading library (/MD). Additionally, you have to use the flag /std:c++latest.

Listing 3 and Listing 4 are the modified versions of the interface file math2.ixx and the source file client2.cpp respectively.

module;

import std.core;         // (1)

export module math;

export int add(int fir, int sec)
{
    return fir + sec;
}

export int getProduct(const std::vector<int>& vec)
{
  return std::accumulate(vec.begin(),
                         vec.end(),
                         1,
                         std::multiplies<int>());
}
			

import std.core;         // (1)

import math;

int main() {
  std::cout << std::endl;

  std::cout << "add(2000, 20): " << add(2000, 20)
    << std::endl;

  std::vector<int> myVec{1, 2, 3, 4, 5, 6, 7, 8,
    9, 10};

  std::cout << "getProduct(myVec): " 
    << getProduct(myVec) << std::endl;
 
 std::cout << std::endl;
}
			

Both files use – in line (1) – the module std.core.

This article was first published on Rainer’s blog on 12 May 2020: https://www.modernescpp.com/index.php/cpp20-a-first-module

References

[ISO] ‘Standardization’: https://isocpp.org/std/

[Microsoft-1] ‘Overview of modules in C++’: https://docs.microsoft.com/en-us/cpp/cpp/modules-cpp?view=vs-2019

[Microsoft-2] ‘C++ Modules conformance improvements with MSVC in Visual Studio 2019 16.5’: https://devblogs.microsoft.com/cppblog/c-modules-conformance-improvements-with-msvc-in-visual-studio-2019-16-5/

[Microsoft-3] ‘Using C++ Modules in Visual Studio 2017’: https://devblogs.microsoft.com/cppblog/cpp-modules-in-visual-studio-2017/

[N1736] ‘Modules in C++’: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1736.pdf

[N4842] ‘N4842 Post-Belfast 2019 C++ working draft’: https://github.com/cplusplus/draft/releases/tag/n4842

[P0947] ‘Another take on Modules’: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0947r1.html

[Rainer20] ‘C++20: Module Interface Unit and Module Implementation Unit’ posted 25 May 2020 at: https://www.modernescpp.com/index.php/c-20-module-interface-unit-and-module-implementation-unit

Rainer Grimm Rainer has 20 years of experience as a software developer and software architect, a good 10 years as a training manager and seminar leader, and 3 years as a team leader in software. He has published several books on C ++, 70 articles on C ++, Python and Haskell for Linux-Magazin and iX Magazin and presents at specialist conferences.

Notes: 

More fields may be available via dynamicdata ..