- \n
- Tools used.<\/a><\/li>\n
- Project description.<\/a><\/li>\n
- Ball Pit! in C++ without modules.<\/a><\/li>\n
- Ungluing from
#include<\/code><\/a>\n- \n
- Starting small…<\/a><\/li>\n
- Choosing visibility<\/a><\/li>\n
- 3rd party pain.<\/a><\/li>\n
- Polishing with modules.<\/a><\/li>\n<\/ul>\n<\/li>\n
- All together now.<\/a><\/li>\n<\/ul>\n
Tools used<\/span><\/h4>\n
For the purposes of this project, we will be using the following tools:<\/p>\n
- \n
- CMake – Version:
3.20.21032501-MSVC_2<\/code>. Note:<\/em> this is the installed version of CMake which comes with Visual Studio 2019.<\/li>\n- Visual Studio 2019 – Version:
16.11<\/code>.<\/li>\n<\/ul>\nProject description<\/span><\/h4>\n
I remember when I was younger, I used to love doing kid things like eating terrible fast food, but going to these restaurants had an additional perk: the play places! One of my favorite things to do was go to the ball pit, dive in, and make a giant splash of color.<\/p>\n
![\"Ball](\"https:\/\/upload.wikimedia.org\/wikipedia\/commons\/thumb\/3\/3b\/Ball_pit_with_playground_slide.jpg\/512px-Ball_pit_with_playground_slide.jpg\")
<\/a><\/p>\nI shudder to think of going into one nowadays, but I have not forgotten how much fun they were. I have also recently become very inspired by OneLoneCoder on YouTube and his series on programming simple physics engines<\/a>. I decided I would try to take this simple physics engine and make something a little bit fun and a lot more colorful, introducing “Ball Pit!”:<\/p>\n
![\"Image](\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/08\/ball-pit.gif\")
<\/a><\/p>\n“Ball Pit!” is a quite simple program built using the following discrete components:<\/p>\n
- \n
- OneLoneCoder PixelGameEngine<\/a> (PGE) – Drives graphics.<\/li>\n
- A simple physics engine for managing all the objects on screen.<\/li>\n
- A data structure related to handling collisions between objects, a quad-tree<\/a>.<\/li>\n
- A world object to contain our beautiful orbs.<\/li>\n
- Utilities such as common types and functions on those types.<\/li>\n
- The main game object which is responsible for the primary game loop and polling user input.<\/li>\n<\/ul>\n
Ball Pit! in C++ without modules<\/span><\/h4>\n
Since we established a basic design layout in the previous section, let us see what we can produce using C++20 without any modules whatsoever. Without further ado, here is the code in all its
#include<\/code> glory: Ball Pit! Without modules<\/a>. The easiest way to build this project is to\u00a0 use Visual Studio’s open folder<\/a> support.<\/p>\nAlternatively you can do the following (in a VS2019 developer command prompt):<\/p>\n
$ mkdir build & cd build & cmake -G\"Visual Studio 16 2019\" -Ax64 ..\\<\/pre>\n
Once CMake has generated the solution for you can open it using Visual Studio 2019, use the familiar F5 loop and off you go!<\/p>\n
Traditional C++ Structure<\/h5>\n
Let us talk briefly about the traditional project structure of this code. We have the following, familiar, breakdown:<\/p>\n
ball_pit\/\r\n\u251c\u2500 include\/\r\n\u251c\u2500 src\/<\/pre>\n
As you might expect the
include\/<\/code> directory is almost a mirror of some files undersrc\/<\/code>. You also end up with a sizeable set of includes in our primaryball-pit.cpp<\/code> to pull all the pieces together:<\/p>\n#include \"bridges\/pge-bridge.h\"\r\n\r\n#include \"physics\/physics-ball.h\"\r\n#include \"physics\/physics-engine.h\"\r\n#include \"physics\/quad-tree.h\"\r\n#include \"util\/basic-types.h\"\r\n#include \"util\/enum-utils.h\"\r\n#include \"util\/random-generator.h\"\r\n#include \"world\/world.h\"<\/pre>\n
You might notice that these includes directly reflect the design we set out to have:<\/p>\n
- \n
- PGE for graphics:
\"bridges\/pge-bridge.h\"<\/code><\/li>\n- Physics engine:
\"physics\/physics-engine.h\"<\/code><\/li>\n- Quad-tree:
\"physics\/quad-tree.h\"<\/code><\/li>\n- World object:
\"world\/world.h\"<\/code><\/li>\n- Utilities:
\"util\/*<\/code><\/li>\n- Main game: (the current source file:
ball-pit.cpp<\/code><\/a>)<\/li>\n<\/ul>\nSince we made the decision to use header files you will notice that we get some declarations like this:<\/p>\n
inline RandomNumberGenerator& random_generator()<\/pre>\n
Where there is a strong desire not to implement this simple function in its own
.cpp<\/code> file for simplicity’s sake, but if you forget the criticalinline<\/code> keyword or, even worse, mark it asstatic<\/code> you will not get the behavior you expect from this function.<\/p>\nAnother thing which I like to do on my projects is separate 3rd party headers from the rest of the project using these “bridge” header files. The reason is so that I can easily control warning suppression\/isolated requirements for that header. The PGE header is isolated into its own bridge called
pge-bridge.h<\/code><\/a>.<\/p>\nFinally, for projects which utilize
#include<\/code> as a code sharing mechanism, I like to employ the idea that each header file should stand completely on its own, meaning that if a header uses something likestd::vector<\/code> it cannot rely on that container being introduced through some other header, it must include it itself. This is good practice; it makes maintaining headers minimal as you move them around and use them in more places.<\/p>\nUngluing from
#include<\/code><\/span><\/h4>\nAt the beginning it was mentioned that we are using CMake as our configuration system but, as of publishing, CMake’s support for modules is still experimental. What we can<\/em> do is generate build system output for a build system which does<\/em> support modules: MSBuild’s! All we need to do is tell MSBuild that there are module interfaces in this project and “Presto!” we have a modules-compatible project! By default, MSBuild will key off any source files with a
.ixx<\/code> extension to automatically support named modules\u2014exactly what we want! Now, how do we get there?<\/p>\nIf we examine the
include\/<\/code> tree we get a surprisingly promising idea of what module interfaces we need:<\/p>\nball_pit\/\r\n\u251c\u2500 include\/\r\n\u2502 \u251c\u2500 bridges\/\r\n\u2502 \u2502 \u251c\u2500 pge-bridge.h\r\n\u2502 \u251c\u2500 physics\/\r\n\u2502 \u2502 \u251c\u2500 physics-ball.h\r\n\u2502 \u2502 \u251c\u2500 physics-engine.h\r\n\u2502 \u2502 \u251c\u2500 physics-utils.h\r\n\u2502 \u2502 \u251c\u2500 quad-tree.h\r\n\u2502 \u251c\u2500 util\/\r\n\u2502 \u2502 \u251c\u2500 basic-types.h\r\n\u2502 \u2502 \u251c\u2500 enum-utils.h\r\n\u2502 \u2502 \u251c\u2500 random-generator.h\r\n\u2502 \u2502 \u251c\u2500 stopwatch.h\r\n\u2502 \u251c\u2500 world\/\r\n\u2502 \u2502 \u251c\u2500 world.h<\/pre>\n
It is common for mature projects to have a similar structure and breakdown of components and it makes sense for maintainability reasons. As a goal for modularizing this project let us aim to remove the entire directory tree of
include\/<\/code> and take advantage of modules as much as possible. Let us do exactly that by introducing some new files into the directory tree which reflects our header file layout (making them empty for now):<\/p>\nball_pit\/\r\n\u251c\u2500 modules\/\r\n\u2502 \u251c\u2500 bridges\/\r\n\u2502 \u2502 \u251c\u2500 pge-bridge.ixx\r\n\u2502 \u251c\u2500 physics\/\r\n\u2502 \u2502 \u251c\u2500 physics-ball.ixx\r\n\u2502 \u2502 \u251c\u2500 physics-engine.ixx\r\n\u2502 \u2502 \u251c\u2500 physics-utils.ixx\r\n\u2502 \u2502 \u251c\u2500 quad-tree.ixx\r\n\u2502 \u251c\u2500 util\/\r\n\u2502 \u2502 \u251c\u2500 basic-types.ixx\r\n\u2502 \u2502 \u251c\u2500 enum-utils.ixx\r\n\u2502 \u2502 \u251c\u2500 random-generator.ixx\r\n\u2502 \u2502 \u251c\u2500 stopwatch.ixx\r\n\u2502 \u251c\u2500 world\/\r\n\u2502 \u2502 \u251c\u2500 world.ixx<\/pre>\n
Now the process of moving everything over to using modules begins!<\/p>\n
Starting small…<\/span><\/h5>\n
When tackling a project of any size you want to start as small as you possibly can. In the case of “Ball Pit!” I started with
include\/util\/enum-utils.ixx<\/code><\/a> because it did not depend on anything besides a STL header. The first thing you need to do is add the content to your module interface:<\/p>\nmodule;\r\n#include <type_traits>\r\nexport module Util.EnumUtils;\r\n\r\ntemplate <typename T>\r\nconcept Enum = std::is_enum_v<T>;\r\n\r\ntemplate <Enum E>\r\nusing PrimitiveType = std::underlying_type_t<E>;\r\n\r\ntemplate <Enum E>\r\nconstexpr auto rep(E e) { return PrimitiveType<E>(e); }<\/pre>\nThis is almost<\/em> a 1-to-1 copy-paste of the header but with the following exceptions:<\/p>\n
- \n
- Our STL headers are injected into the global module fragment<\/a> (the region between
module;<\/code> andexport module ...)<\/code>.<\/li>\n- We have given a proper name to our module:
Util.EnumUtils<\/code>. Note:<\/em> the.<\/code> separated names do not indicate any filesystem structure.<\/li>\n- We no longer need header include guards.<\/li>\n<\/ul>\n
There is one last thing missing: we did not actually export anything! Since all these names are used around the project, we need to export everything, and the easiest way to export lots of declarations at once is to use the
export { ... }<\/code> syntax. Take a look:<\/p>\nmodule;\r\n#include <type_traits>\r\nexport module Util.EnumUtils;\r\n\r\nexport\r\n{\r\n\r\ntemplate <typename T>\r\nconcept Enum = std::is_enum_v<T>;\r\n\r\ntemplate <Enum E>\r\nusing PrimitiveType = std::underlying_type_t<E>;\r\n\r\ntemplate <Enum E>\r\nconstexpr auto rep(E e) { return PrimitiveType<E>(e); }\r\n\r\n} \/\/ export<\/pre>\nThe next logical step for us is to replace any instance of
#include \"util\/enum-utils.h\"<\/code> withimport Util.EnumUtils;<\/code>. This part is largely mechanical and to play off guidance around mixingimport<\/code> and#include<\/code><\/a> I ensured to place anyimport<\/code> after any#include<\/code>‘s. Finally, we add this new interface to theCMakeLists.txt<\/code> here<\/a>, configure, build and run again. Things should run the same as before except that we are one step closer to modularizing the project!<\/p>\nChoosing visibility<\/span><\/h5>\n
Named modules are all about defining the surface area of your API. Now that we have a tool which allows us to hide implementation details that would otherwise be unnecessary for consumers, we can start to think about what the accessible parts of the API should be. Let us look at modularizing
include\/util\/random-generator.h<\/code><\/a>. In this file we have the following declarations:<\/p>\nenum class RandomSeed : decltype(std::random_device{}()) { };\r\n\r\ntemplate <std::integral I>\r\nusing IntDistribution = std::uniform_int_distribution<I>;\r\n\r\ntemplate <std::floating_point I>\r\nusing RealDistribution = std::uniform_real_distribution<I>;\r\n\r\nclass RandomNumberGenerator\r\n{\r\n ...\r\n};\r\n\r\ninline RandomNumberGenerator& random_generator()\r\n{\r\n ...\r\n}<\/pre>\nOf these declarations the ones we use outside of the header are
IntDistribution<\/code>,RealDistribution<\/code>, andrandom_generator()<\/code> (not even the class name directly). As such we can define the module like so:<\/p>\nexport module Util.RandomGenerator;\r\n\r\nimport Util.EnumUtils;\r\n\r\nenum class RandomSeed : decltype(std::random_device{}()) { };\r\n\r\nexport\r\ntemplate <std::integral I>\r\nusing IntDistribution = std::uniform_int_distribution<I>;\r\n\r\nexport\r\ntemplate <std::floating_point I>\r\nusing RealDistribution = std::uniform_real_distribution<I>;\r\n\r\nclass RandomNumberGenerator\r\n{\r\n ...\r\n};\r\n\r\nexport\r\nRandomNumberGenerator& random_generator()\r\n{\r\n ...\r\n}<\/pre>\nNotice that we do not even need to export the declaration of the class
RandomNumberGenerator<\/code>. We do not need its name; we only need its functionality, and we can prevent users from creating extra instances of it by allowing its use throughrandom_generator()<\/code> only.<\/p>\nFurthermore, we no longer need
random_generator()<\/code> to be marked asinline<\/code> because there is now only one definition in any given translation unit. Do not be afraid to put compiled code in an interface, it is its own translation unit and obeys the rules of compiled code.<\/p>\n3rd party pain<\/span><\/h5>\n
In C++ we deal with sharing code all the time and a lot of the time that code has a distinctive style, compiler requirements, default warning settings, etc. When we move code into a modules world, and in particular 3rd party code, we need to take some things into consideration: what part of the library do we want to expose? What runtime requirements are in the library if it is header only? Do we want to “seal” off bad parts of the library? With modules we start to have answers to these questions based on the requirements of our project. Integrating 3rd party library functionality into modularized projects is one of the most interesting parts of using modules because modules give us tools we never had before to deal with ODR (One Definition Rule) and name resolution. In this section we will focus on modularizing the
include\/bridges\/pge-bridge.h<\/code><\/a>.<\/p>\nThe OneLoneCoder PixelGameEngine is a nice library if you are just starting out exploring games programming. It is easy to integrate into projects (because it is a single header file) and the interfaces are simple–which plays to our advantage in deciding what parts of the library we want to expose. In “Ball Pit!” we use the following functionality from PGE:<\/p>\n
- \n
olc::PixelGameEngine<\/code> — For the main program.<\/li>\nolc::Key<\/code> — For user input.<\/li>\nolc::Pixel<\/code> — For coloring pixels.<\/li>\nolc::vf2d<\/code>\/olc::vi2d<\/code> — Standard vector classes (float<\/code> andint<\/code> respectively).<\/li>\nolc::BLACK<\/code>,olc::WHITE<\/code>,olc::BLUE<\/code>, andolc::RED<\/code> — Color constants.<\/li>\n<\/ul>\nWe can, by default, export each of the above with a using-declaration:<\/p>\n
module;\r\n#pragma warning(push)\r\n#pragma warning(disable: 4201) \/\/ nonstandard extension used: nameless struct\/union\r\n#pragma warning(disable: 4245) \/\/ 'argument': conversion from 'int' to 'uint8_t', possible loss of data\r\n#include \"olcPixelGameEngine.h\"\r\n#pragma warning(pop)\r\nexport module Bridges.PGE;\r\n\r\nexport\r\nnamespace olc\r\n{\r\n \/\/ For game.\r\n using olc::PixelGameEngine;\r\n using olc::Key;\r\n\r\n \/\/ For basic types.\r\n using olc::Pixel;\r\n using olc::vf2d;\r\n using olc::vi2d;\r\n\r\n \/\/ Allow using the multiply operator from olc::v2d_generic.\r\n using olc::operator*;\r\n}<\/pre>\nThe reason we use a using-declaration is because we do not want the module to own all these objects\/functions. By injecting the names through a using-declaration their linkage remains tied to the global module so we can separately compile them in
src\/3rd_party\/olcPixelGameEngine.cpp<\/code><\/a> as before.<\/p>\nYou will immediately notice that the color constants are mysteriously missing. This is because these constants are defined with
static<\/code> linkage in the header file so we cannot export them directly and the reason is buried in standardese<\/a>. It is simpler to remember that you cannot export an internal linkage entity (i.e. one declaredstatic<\/code>). The way to get around this is wrap them in a function which has module linkage:<\/p>\nexport\r\nnamespace olc\r\n{\r\n ...\r\n \/\/ Note: Because these color constants are defined to be static in the header they cannot be\r\n \/\/ directly exported. Instead we export their values through a module-owned variable.\r\n namespace ModuleColors\r\n {\r\n auto Black()\r\n {\r\n return olc::BLACK;\r\n }\r\n\r\n auto White()\r\n {\r\n return olc::WHITE;\r\n }\r\n\r\n auto Blue()\r\n {\r\n return olc::BLUE;\r\n }\r\n\r\n auto Red()\r\n {\r\n return olc::RED;\r\n }\r\n }\r\n ...\r\n}<\/pre>\nOnce we have these functions, we need to replace any instance of
olc::COLOR<\/code> with its respective call to our exported color function.<\/p>\nAnd that is it! We have successfully exported exactly what we need from PGE for our “Ball Pit!” app! Just as before, you add this to the
CMakeLists.txt<\/code>, replace#include \"bridges\/pge-bridge.h\"<\/code> withimport Bridges.PGE;<\/code>.<\/p>\nPolishing with modules<\/span><\/h5>\n
Once you have gone through the exercise of modularizing more and more of the project you might find that your main program begins to reflect the header file version:<\/p>\n
import Bridges.PGE;\r\n\r\nimport Physics.Ball;\r\nimport Physics.Engine;\r\nimport Physics.QuadTree;\r\nimport Util.BasicTypes;\r\nimport Util.EnumUtils;\r\nimport Util.RandomGenerator;\r\nimport World;<\/pre>\n
Dandy! Modules also give us similar tools as header files do in that we can group common sets of modules together into a “package”. To understand what I am talking about let us look at a header file equivalent of grouping common functionality. Here is what a grouping of all the headers under
include\/physics\/*<\/code> might look like:<\/p>\ninclude\/physics\/physics.h<\/code><\/p>\n#ifndef PHYSICS_H\r\n#define PHYSICS_H\r\n\r\n#include \"physics\/physics-ball.h\"\r\n#include \"physics\/physics-engine.h\"\r\n#include \"physics\/physics-utils.h\"\r\n#include \"physics\/quad-tree.h\"\r\n\r\n#endif PHYSICS_H<\/pre>\n
The problem, of course, is while this is convenient and you do not need to think about which specific file to include for your current project, you end up paying the cost of every header file in the package regardless of if you use it or not. It flies in the face of C++’s core concept: pay for what you use. With the introduction of C++20 modules we no longer have this problem because modules do next to zero work when you import them, so we can safely create the following interface without negatively impacting the compile time of consumers:<\/p>\n
modules\/physics\/physics.ixx<\/code><\/p>\nexport module Physics;\r\n\r\nexport import Physics.Ball;\r\nexport import Physics.Engine;\r\nexport import Physics.QuadTree;\r\nexport import Physics.Utils;<\/pre>\n
We can also do the same for anything under
Util.*<\/code>. This leads us to a rather, I think, respectable lookingball-pit.cpp<\/code>:<\/p>\nimport Bridges.PGE;\r\n\r\nimport Physics;\r\nimport Util;\r\nimport World;<\/pre>\n
All together now<\/span><\/h4>\n
It was a little bit of a journey getting here, and there are learnings along the way. I will not dillydally any further, here is the complete, modularized, version of “Ball Pit!”:
ball_pit<\/code><\/a>. You can check out the code, configure, and build it the same as we covered earlier<\/a> using Visual Studio 2019 version 16.11.<\/p>\nThere is one thing I want to mention, because I can all but guarantee it is on everybody’s mind: what is the build throughput? With modules there is an up-front cost in building our interfaces. With the old inclusion model, we did not have to build our include files explicitly (only implicitly). We end up building more up front, but the result is that we can REPL<\/a> our main program and its components much, much faster. Here is a snapshot of the difference:<\/p>\n
Compiling
ball-pit.cpp<\/code>:<\/p>\n
- We have given a proper name to our module:
- Physics engine:
- Visual Studio 2019 – Version:
- Choosing visibility<\/a><\/li>\n
- Project description.<\/a><\/li>\n