Make project header only

[wusatosi]

From usage experience, subsequent project usually only put source code in include directory and not touch the src/ folder.

Having current src/ folder increase setup friction, as there's an extra empty src/beman/{NAME}/{NAME}.cpp file that needs to be updated when adopting as subsequent library, and users doesn't realize there's another CMake file under the folder.

I don't think we should endorse header only library, but I think this is the common case.

This does conflict with #104 , @bretbrownjr

[neatudarius]

@wusatosi , I think we discussed and decided not to do this. Please check sync notes.

Also, check with @bretbrownjr about bemanproject/beman#93.

Temporary blocking this PR.

[wusatosi]

@neatudarius yeah I think we discussed this before as well. But I remember the outcome to be neutral.

I did look through the meeting minutes, this is the only piece I found to be potentially relevant to this.

Proposed topic: Header-only libraries deliverable? Static library vs interface (check bemanproject/optional#75).
Darius: Preference - interface, but add it to the Beman Standard
ACTION: Darius, will add and entry to the standard that requires INTERFACE targets for header-only libraries.
David: Maybe we should have a function requiring a .cpp in exemplar.

From usage experience, projects usually start off as header only and rarely use the src folder. It might be easier for us to grow from interface to static library instead of being a static library outright.

[bretbrownjr]

I don't think this change is a good fit for us.

At least some projects would need to provide symbols, so we'd have to support a source directory in the template anyway.

A "header only" option could be added on top, that would only lead to additional complexity... we would have to have a user-facing option to make this choice, conditionals in the templating logic to respect the option, and presumably additional complexity in the testing surface to make sure we cover where this choice intersects with other choices. In particular, CMake style changes with header-only libraries (i.e., INTERFACE option for add_library, no cpp files to build, no PRIVATE target properties, and other things).

I'm willing to discuss any idea, including this one. But keep in mind we have more essential important project structure decisions to focus on for now (see #92, #105, #115) that we should prioritize first.

---

Aside: On header only libraries in Beman

Beyond supporting header-only in the project template, I'm also against header only libraries for Beman libraries altogether. Normally I'm in favor of letting library authors have creativity as long as it's good for users and not disruptive to the rest of the ecosystem, but I don't expect those outcomes here.

To be more specific:

• The standard library implementations are not provided as header only, and being implemented in one of them is the ultimate goal of each Beman library.
• Header-only libraries compile categorically slower to linked libraries in any case where a definition is in a header but could easily be in a source file.
  • This is especially the case when entire dependency headers and their transitive dependencies are all preprocessed in when they don't need to be.
• Header-only as a feature adds new complexity to Beman standard, tooling, and so on when we're already dealing with enough complexity.
• Header-only libraries don't provide a portable upgrade path for C++ modules, at least absent widespread packaging conventions or standards for C++ (ask me for details if this is news to anyone).
• Not having source files and symbols adds friction if the library design evolves to a point where it now makes sense to provide symbols... but now users have a breaking API change because of new linkage requirements.
• They are not any less work... you still need to provide test suites, CMake interfaces, pkg-config support, dependency lists, required compilation settings, and other things
  • So what is "header only" if you have everything else provided?
• One of the "features", the ability to just copy headers around as it's interesting is something we don't want to support.
  • This is user hostile as "diamond dependency" problems are made more hidden
    • The copied headers don't necessarily show up as packages, in software bills of materials, as github downloads, as top-level subdirs under a thirdparty/ project dir, etc.
  • At a minimum, you'd want to copy the header and rename all macros, headers, namespaces, etc., but for some reason I'm skeptical that people that people looking for less dependency management work will do this consistently.

Given all that, I don't see having (in some cases) a basic *.cpp file in a src directory that nobody really touches to be all that problematic.

This is the point where it's fair to say to me:

[wusatosi]

Hey @bretbrownjr ,
Thanks for the long explanation.

I am unfortunately (after learning so much from all the CMake related threads, maybe fortunately) not a CMake guru, and I agree with you this is very minor in comparison to other ambitions we have.

I am not arguing against header only projects.

I am not advocating to make header only library the requirement in beman. This PR is just to switch to it as default. The motivation is to reduce starting friction, as I have seen frustration from people trying to launch some new library using exemplar.

I believe moving the src/beman/.../CMakeLists.txt to include/beman/.../CMakeLists.txt and removing the need to update the no-op file at src/beman/exemplar/identity.cpp (thus voiding the whole src folder) would be a great place to start. People starts customizing exemplar by going through every file and updating every reference to exemplar with the library name of their choosing, moving the default to header only would reduce the number of files to update from 11 files to 9 + 1 folder, and move the CMake file that is under src to include, which people are more likely to be using, so it is more obvious that include/.../CMakeLists.txt is controlling the source set. This is on top of the observation that I think no-one puts anything in the src folder to start.

Well, maybe it is a sign that we desperately needs templates, and the time we spent on writing this should be on envisioning how we want to approach templating.

Let's halt this discussion for now.