utfcpp
utfcpp copied to clipboard
nemtrif
Set up correct include structure
What is the intended include for this lib?
#include <utf8/utf8.h>maybe to generic#include <utf8.h>even less generic and can conflict#include <utf8cpp/utf8.h>preferred although does not equal github repo name (see #53), already used for install.
I'd suggest deciding on one and adapting the source and install tree plus includes accordingly
Why not #include <utfcpp/utf8.h> ? While it shouldn't bother too much as far as this is an header only library and everyone can put it somewhere in the filesystem and add the folder to includes with any structure in it, it's true that good practices help especially when the library gets broad success and it's uncomfortable to find it used in different ways.
That is my point. Currently: During development/usage as git submodule you need to use #include <utf8.h>. If you installed the project you need to use #include <utf8cpp/utf8.h> (unless you add the utf8cpp folder directly to the includes, but that shouldn't be required)
For me/us I want to use it as a git submodule directly adding it via add_subdirectory in CMake. And using #include <utf8.h> is not really great as it may conflict.
Having the source tree structure mirror the install tree structure also helps a lot. This means renaming the source folder to include/utf8cpp (with current install path)
The library is older than git submodules and GitHub so fitting into that eco-system was never a goal. That said, what's wrong with #include <utfcpp/utf8.h> ?
That said, what's wrong with #include <utfcpp/utf8.h> ?
Nothing. My point was: When you install this library and use it you use #include <utf8cpp/utf8.h> which is good.
But you can also use the library as a submodule/copy of source tree but then you have to include it differently. If you rename source to include/utf8cpp then you can always use #include <utf8cpp/utf8.h> no matter if you use the installed or source version
The library is older than git submodules and GitHub so fitting into that eco-system was never a goal.
Understood that this is why the library is what it is now. But wouldn't it make sense to support this now? What is the problem you see? It is renaming a folder in a source tree (ok, and adding one) and a simple change the the CMakeLists. So very easy and supports more use cases without breaking any.
@nemtrif I think the point of @Flamefire is that source repository layout of utfcpp, examples and documentation could help to spread best practices about its usage. That is, if you just move all content of source directory to source/utfcpp it would be a smart move to also support usage of the utfcpp repository as a git submodule as one just adds the source directory to includes and uses it with <utfcpp/utf8.h>. Incidentally, I proposed a similar change in another open source project and it was accepted.
@ceztko Exactly. And while there are no sources but only header files ("includes") it makes sense to rename that top-level folder as it is also a clear signal that this should be included. Minor: It is utf8cpp (as per install layout)
@nemtrif as asked by others, with the next version of utfcpp please clarify the expected include directive for external usage and adjust the tree layout so it will be possible to use this directive from tests too. As pointed by others, installing the library with CMake currently will create a include/utf8cpp directory in the prefix. This actually goes against the recommendation of using #include <utfcpp/utf8.h> as per your message. Some linux distributions seem to adhere to the CMake install location so today I was recommended to migrate my #include <utfcpp/utf8.h> to #include <utf8cpp/utf8.h>. I believe you should be the decision maker here, either sticking with the safest choice #include <utf8cpp/utf8.h> or decide to introduce new recommended include directory/header names that are more generic, less utf8-only representative.
I was too bothered by this, but not from the include side, rather from CMake side since I include it directly via its CMake file.
The library is called utfcpp, with the #include <utf8.h>, the CMake target name utf8cpp and the Alias name (which you explicitly link to as a user) utf8::cpp. this is especially strange and whenever I want to link to it I have to look into the CMakeLists to see how the target is called. Ideally if the whole project is named utfcpp or utf8cpp, the CMake target would be called utfcpp::utfcpp or utf8cpp::utf8cpp. This would be reasonable to assume for library users. Since this library only has one module, the prefix and target should be the same.
I am fine with both names, but I am asking you to also change the CMake target name when you do it at some point, please. Thanks.
Apparently, the requested change would make existing users' builds break.
I believe you should take maintaining utfcpp with a little bit more freedom and understand that not properly settling/document the intended way to include utfcpp is actually more concerning than doing nothing. It's obvious some users will break if you change the layout of the source in any way, but ufcpp is a header only library, and if you make settle one change once for all it's an easy fixable build-only issue that in the end will make life easier for everybody. You have multiple options you can pick to improve the situation, as multiple people (including me) voiced in this issue.