How to properly organize an open source project?

Question

git

I'm going to spread the library in open source. Having carefully studied the organization of several open source projects that I dealt with, I came to the conclusion that, as a rule, projects have the following structure:
/src --- Sources from which you can build the library
/include --- Interface for accessing the API of the compiled library
/test --- Tests for the project code
/lib --- Compiled library , somehow stable version
/doc --- Documentation for the project
... --- Other folders - what?
README.txt ---Information for the initial acquaintance with the library
INSTALL.txt --- General information about setting up the project
LICENCE.txt --- Information about the license
Here is another example of a project: asio . The structure is not exactly the same, but it will do, as for me.
Usually working with projects organized in this way looked like this for me:
1. Using the . I clone the turnip completely, in the clone I collect the library (source folder), then copy-paste the include folder and the folder with the collected bins to my project, thus losing any connection with the turnip.
2. Testing either. I open a project with tests right in the downloaded version of the repository, manually copy-paste the lib next to the tests, compile it and see how the tests work.
I understand correctly that everything is calculated for a similar way of working with the repository? And is there any other way to organize the repository, which allows you to more tightly connect your project with version control of the library itself when working with it (now there is a copy-paste moment that breaks the connection)?
PS: Yes, perhaps this is also important. The library is written in C++.

Answer 1

Yes, maybe that's important too. The library is written in C++.

Yes, it is important. We also use approximately the same project structure, and try to adhere to it on all platforms used, however, the technical differences between them dictate differences in the structure. For example, the include folder in the .net world is not needed, because all the necessary information about the contents of the library is in the assembly itself. The same applies to Java libraries. In general, I agree with you on the structure of the repository (the only taste for me is to name the docs and tests folders in the plural :)).
Lately, I have found the examples folder with the code of examples for using the library to be extremely useful. It is very convenient when there is a project / file with an example code for the main use cases. You can very quickly go over the capabilities of the library and evaluate the ease of use (the day before, I compared json-libs for C ++ in this way). And for you, this is also a kind of "tests" for convenience. These "tests" do not aim to cover the logic 100%, but to show how to interact with the library in basic, standard scenarios.
I note that you wrote very well about the library API in include. For some reason, many developers put private headers in this folder too . I personally don't see the point in this - all private headers are part of the main sources, and they are in / src.
Frankly speaking, I don’t know why you are doing this - the include and lib folders are just designed to make it convenient to connect them to the compiler and linker - just the paths to these folders are passed when connecting dependent libraries. The only thing that may need to be copied from the library folder is the compiled binaries (dll / so) in case of dynamic linking, if there is no possibility / desire to prescribe paths to dynamic libraries. Well, some data files, if any.
Tests should generally be assembled together with the library (for example, to the / bin folder), and in theory, you don’t need to copy anything anywhere.
In general, your question is strongly related to the organization of the library assembly process and its connection to other projects. In C++, unfortunately, there is still no standard, or at least popular, dependency management convention, in other words, a package manager. Many libraries today are connected through system package managers, if any are present in the OS.
Also, for some reason you did not specify the build system used. In the same CMake, there is a very useful feature called find_package , which is a sin not to use.
In general, I note that there should be a minimum of copy-paste, include and lib should not be copied at all, for this any compiler has switches (for example, -I and -L). Even if copying is unavoidable, it should be automated as much as possible in assembly instructions. Many build systems are able to detect that certain files are out of date (for example, you recompiled a dll), in which case they can be asked to copy those files.
How do you still collect your Liba? This is important because even for experienced developers, building an unfamiliar C++ library can be a chore.
Oh, and by the way, there’s also a moment with includes: precisely because libraries are usually included by specifying paths to the compiler and linker (which will then collect the contents of all include and lib folders into a single namespace), there is a popular convention to create a subfolder in the include folder with the name of the library, for example: one , two , three . This makes it possible to include like this: #include <soci/blob.h>and not like this: #include <blob.h>. This allows the developer to name the files briefly and however he likes (blob.h instead of soci_blob.h), while minimizing the risk of include name conflicts.

Answer 2

The biggest value for me in OS is the ability to abstract away from the implementation and the ability to just use the library in your code without additional complexity. Here's what you need to pay attention to first. What you described, of course, is mostly true, but the main thing is the documentation and the ability to start using the library after 3-5 minutes of familiarizing yourself with the docks.