Add C++ modules support

[mikomikotaishi]

This pull request adds support for C++20 modules through CMake. It is enabled by the HTTPLIB_BUILD_MODULES option (which requires HTTPLIB_COMPILE to be enabled, though it probably doesn't have to - I only forced this requirement because it seems to make the most sense to force the library to compile if modules are to be compiled).

[Spixmaster]

Great work. I also thought about this.

The approach is very similiar to what was done to https://github.com/nlohmann/json with nlohmann/json#4799. Then, I noticed ...

Is this temporary approach with a file with using ... for the meantime while modules and no modules are supported?

This approach is not using modules natively but rather as an interface to the original way.

Does this method work without disadvantages?

[mikomikotaishi]

This is the best way to my knowledge to support modules on top of a header-only or header/source library, allowing continued support for older versions while providing newer features as an option.

I'm not aware of any disadvantages to it besides a being additional translation unit to compile, but if I am wrong please correct me. The only glaring difference in API is that detail symbols are hidden as they are not exported, but in my opinion that's probably better not to expose detail symbols and flood IDE suggestions with implementation details.

[Spixmaster]

What about compiled libraries? Is it possible to have the traditional method and modules installed in parallel?

I am thinking of repositories that ship compiled .so or .a.

This is relevant here, https://aur.archlinux.org/packages/cpp-httplib-compiled .

[mikomikotaishi]

Yes I believe it's possible to use shared/static libraries with modules, all of my modular projects compiled to shared libraries that an executable consumes

[yhirose]

@mikomikotaishi, thanks for the fine pull request! It's fantastic, but my concern is that someone needs to update modules/httplib.cppm whenever new external symbols are added or existing symbols are removed/renamed, and it could happen quite often. I am not planning to maintain this file. So if you cannot keep maintaining the file, I am probably not merge it since the file can be easily out-of-date. Is there a way to generate modules/httplib.cppm from httplib.h automatically?

@sum01 @jimmy-park @Tachi107 do you have any thought about this pull request?

[mikomikotaishi]

I could create a Python script, or some other kinds of automated means of updating, which you could run every time it is updated. Until then I would be OK with maintaining this file, as it is a simple process. Such a script would probably comb through the file and add any symbols not part of a detail or internal namespace, or prefixed with an underscore, etc.

However, I am curious why it is not feasible to update the file manually. In case it isn't clear how, one can update the file by adding a using httplib::NEW_SYMBOL_HERE; into the export namespace httlib { } block, for each new symbol that is added. Do let me know if any more information is needed.

[mikomikotaishi]

I have also seen some repositories use bots to push some commits too. Potentially one such bot could be set up to automatically populate the module with new changes each time there is a mismatch. I don't know anything about how to set this up, but I have seen this before and it could potentially be a solution (but I think the simplest one is just to run a Python script each time any update to the library happens).

[mikomikotaishi]

Anyway, I think this could be one such way of automatically updating the module.

[yhirose]

@mikomikotaishi thanks for the additional explanation. I am ok with the following your suggestion.

I have also seen some repositories use bots to push some commits too. Potentially one such bot could be set up to automatically populate the module with new changes each time there is a mismatch. I don't know anything about how to set this up, but I have seen this before and it could potentially be a solution.

We could automatically generate modules/httplib.cppm in a GitHub Actions script when httplib.h is pushed. (I can't accept the way to run a script to update the file manually, since I don't maintain any build systems in this repository. Please see #955 (comment).)

[mikomikotaishi]

OK, that makes sense to me. (I don't know anything about how to run GitHub Actions or write scripts for it however, so I'm afraid the most I can do is create a script for this.)

[mikomikotaishi]

I'm not sure why there were failing workflows as I didn't change anything in the core library

[mikomikotaishi]

Never mind, it seems the failing CI is happening upstream too.

[Tachi107]

If the file can be run during the build process (and if the output consists of machine-generated files, it should *only* run during build time), then the destination directory should be configurable (maybe defaulting to the the current working directory). Even better, if the output is a single file, the script should allow the user to specify the output file itself (full path). This is because downstreams (like Debian, which is what I maintain the meson build scripts for) may have some requirements on where build products should be stored.

[mikomikotaishi]

@Tachi107 CMake needs to know what the output directory is ahead of time to compile the module. How do you propose to solve this?

[mikomikotaishi]

@yhirose I think there is one possible solution to allow both the directory to be user-specified while still supporting CMake module building, which is probably just to have the Python script generate the CMake file too. I don't know if this is too convoluted or awkward of a design though, so please do tell me your thoughts.

[Tachi107]

Hi Miko,

On Tue Dec 9, 2025 at 10:46 PM CET, Miko wrote: @Tachi107 CMake needs to know what the output directory is ahead of time to compile the module. How do you propose to solve this?

You should use CMake's add_custom_command() function to invoke the script and pass it the output file path https://cmake.org/cmake/help/latest/command/add_custom_command.html Meson has a similar function, but I can do that myself after this gets merged.

[Tachi107]

Some feedback now that I have been able to look at the whole code :)

[yhirose]

If the following simple approach works, I’m fine with it. I don’t mind exposing the httplib::detail::* symbols, since #including httplib.h exposes the detail functions anyway. Could you please make the change? After that, I’ll take a look at it for review.

module;

// include all included headers seen in <httplib.h>,
// to prevent them from being re-included in the export block
#include <...>

export module httplib;

export {
    #include "../httplib.h"
}

Also, please don’t forget to remove any files that are no longer needed, revert the changes in README.md, and add any necessary comments only to the CMake files. (I intentionally avoid mentioning any build systems in the README, as they are optional and not officially supported by cpp-httplib itself, but are kindly maintained by excellent contributors. Thanks for your understanding.)

[mikomikotaishi]

I did make this change, but we have to re-open the PR for it to appear here. I will update the README as requested.

[mikomikotaishi]

I've removed the changes to the README, but I did notice that the README mentions how to use the script to split the program into .h/.cc file, where would it be appropriate to document that the library contains support for modules features?

[mikomikotaishi]

What if we put all detail namespaces inside an #ifndef HTTPLIB_MODULE_HIDE_DETAILS in the header, and defined that macro at the top of the global module fragment, so that the header exposes details but not the module? Essentially what I'm proposing:

httplib.h:

namespace httplib {
    // ...

    #ifndef HTTPLIB_MODULE_HIDE_DETAILS
    namespace detail {
        // details here
    }
    #endif

    // ...
}

httplib.cppm:

module;

#define HTTPLIB_MODULE_HIDE_DETAILS

// all httplib includes
#include <...>

export module httplib;

export {
    // Because HTTPLIB_MODULE_HIDE_DETAILS is defined, httplib::detail::* symbols aren't exported
    #include "../httplib.h"
}

@yhirose do let me know what you think, I think this wouldn't any more difficult to maintain moving forward, we would just have to ensure that #ifndef HTTPLIB_MODULE_HIDE_DETAILS appears before (or inside) every namespace detail declaration.

[ChuanqiXu9]

https://chuanqixu9.github.io/c++/2025/12/30/C++20-Modules-Best-Practices.en.html#the-export-extern-c-style and https://chuanqixu9.github.io/c++/2025/12/30/C++20-Modules-Best-Practices.en.html#abi-breaking-style may be helpful for you.

[mikomikotaishi]

Thanks, will review tomorrow

[yhirose]

@mikomikotaishi Please don't change httplib.h or README.md at all. Instead, just focus on creating the simpler httplib.cppm, making the smallest possible changes and adding only the minimum necessary usage to the CMake-related files. Thank you.

[mikomikotaishi]

Then the PR is basically in a finished state.

[Tachi107]

where would it be appropriate to document that the library contains support for modules features?

I think the build script itself is fine. Meson has meson_options.txt, which is self-documenting; CMake users can just grep for the available options(), or use some command I don't remember (or the GUI) to have CMake list them. As another example, the project supports system-wide installation, but since this is a build-system-specific feature its "documentation" is, well, the build system itself.

[Tachi107]

As mentioned earlier, would it make sense to change this to the split .h, with less implementation details exposed, or does it require the full header?

In case the smaller header can be used instead, it might make sense to make this file a template httplib.cppm.in and configure it from CMake by including the header produced my execute_process() (which should really be changed to add_custom_command(OUTPUT), but that's a separate issue) via @VAR@ substitutions

[mikomikotaishi]

I would like to do this at some point with the smaller header, seeing as the the library has to be compiled anyway if the module has to be compiled.

[yhirose]

I don't prefer including such a lengthy list of #include ..., because it's not easily maintainable... Is the following enough in this file?

export module httplib;

export {
    #include "../httplib.h"
}

[mikomikotaishi]

The headers above were included first because it activates the header guard preventing it from being pulled in when the actual httplib.h header is included in the export block. If we didn't do that, the module would export stuff like std::* symbols or other headers pulled in.

This can just be copied in when we generate modules with Python instead

[yhirose]

This is too complex and appears difficult to maintain. I'm hesitant to merge this code unless it can be simplified and the code duplication is resolved. Thanks for your understanding.

[mikomikotaishi]

Weren't you originally content with a Python script to generate the module on demand?

[yhirose]

That’s fine. However, I wasn’t satisfied with the update_modules.py script at all. The script should generate the entire httplib.cppm from scratch, rather than updating the existing file using git diff. This would make the script much simpler.

Also, I would prefer not to commit httplib.cppm to this repository. It should be treated the same as httplib.h and httplib.cc, which are generated by split.py. In other words, httplib.cppm is just a build artifact.

[mikomikotaishi]

@yhirose It's now possible just doing cmake -B build -S . -G Ninja -DHTTPLIB_COMPILE=ON -DHTTPLIB_BUILD_MODULES=ON. I hope this is sufficiently simple.

[Spixmaster]

Might I ask a question? Is the currennt approach good for programme packages? Think of https://aur.archlinux.org/packages?O=0&K=cpp-httplib .

Can users who have installed a package use modules and not with one package installed? This is very important because if one software depending on cpp-httplib uses modules and the other not one will need to have two different packages whose files would likely collide.

Alternatively formulated, can no modules and modules exist in parallel?

[mikomikotaishi]

Alternatively formulated, can no modules and modules exist in parallel?

I'm not sure if I entirely understand what you mean. Are you asking if it's possible to #include <httplib/httplib.h> and import httplib; in the same project? I believe the answer is yes.

[mikomikotaishi]

@yhirose Hi, could you please review it again and tell me your thoughts on the current solution? I think this is very simple and should be to your liking.