How to document the functionality in C++20 modules? - c++

When providing a library to others, documentation of e.g. class member functions can be included in the header files which contain the declarations. If properly formatted, this documentation can also be interpreted and displayed by IDEs.
Using C++ modules, how can I pass on information about the functionality in the module without falling back to external documentation, e.g. Doxygen? I assume comments do not make it as such into the compiled interface file?

You are right, this question is actually pointless. I thought that - unless provided with the complete source code - libraries would be provided completely in binary format when using modules. Although the idea of deploying just one library file without additional files has its charme.

Related

Directory structure for a C++ template library

I am creating a C++ template library which I intend to use as a vital component in a number of future projects. Due to the size of the library, I am dividing the code between a number of files, some of which are forward declarations and prototypes and some of which are "implementations." Some classes in the library are strictly internal and are not intended to be directly accessed by users (i.e. future me).
There seems to (more or less) be an accepted standard directory structure for compiled C++ libraries (decent thread on the topic: Directory structure for a C++ library) but in the case of a template library, all files are technically headers.
Is there an accepted directory structure for template libraries? Should I put the public header in /include and private headers and "implementations" in /src ?
P.S.
I'm sorry if this is common knowledge. If there is a resource I have missed that addresses this topic, feel free to link it and this thread can be promptly closed.
There are a few examples of header only libraries which put everything in the include directory. When it comes to private implementations, there may be a sub-directory or namespace which makes this intent clear to the consumer (something like internal, details, or impl).
Adding an accompanying namespace should help separate these implementation details out from the templates the user is expected to consume.
One example I can immediately think of is Cereal.
As a user, when consuming a header only library, I'd expect to just have to add YourProject/include to my include path to be able to consume your templates.

Libraries vs classes in c++

I came across a terminology in C++ which is a library. The book I am reading states that iostream is a library , and it is a system library. Then After that it says in the book, "later, you will create your own library with the extension .h". Is a library the same as class because clearly, when I included my .h library, I actually had created a class.
If a library is the same as a class, what can we say about in C language , is it a class ?
Thank you.
Please note that this is just a simplistic explanation so you can wrap your head around it, not a pedantic or an exact and complete definition of a library.
A library is a collection of functions, classes and other stuff packaged together.
For instance the C++ standard library is (conceptually) composed of many libraries, e.g.:
string library
algorithm library
input/output library
etc.
The IO library contains some classes like:
std::iostream (actually a typedef to std::basic_iostream)
std::ios
std::istream
std::ostream
etc.
In order to use a library you basically need two things: the library headers in order to have access to the declarations and a library which needs to be linked to your project in order to have access to the symbols exported by such library. The OS comes with the C++ Standard Library preinstalled and the compiler -- when in C++ mode -- automatically links to it, so all you have to do is include the necessary headers.
In order to understand what a header is and what's it's role you first need to understand the difference between declaration and definition. You can reefer to What is the difference between a definition and a declaration? or any other reading material.
Then you need to understand the concept of compilation units. You can read What is a “translation unit” in C++ or How is compilation unit defined in c++.
Using all the above you should to be able to compile multiple source files into one executable and understand the basics mechanism involved. You can read Using multiple .cpp files in c++ program or How to use multiple source files to create a single object file with gcc
From here there is a small step to be able to create and use your own static library. You can start here: How to create a static library with g++?
Another important concept to understand is compilation/linking: How does the compilation/linking process work?
...or alternatively all you need to know is that in order to use std::iostream you need to include <iostream>. Ultimately it's up to you how much you want to absorb as "because that's how it's done" and how much you want to understand. Progress can be made only if you chose one of the options (spoiler: it's the latter).

How do you include external libraries into Haxe?

I'm trying to write a program for which I would like to use some external C++ libraries in Haxe. I can't really figure it out since the official documentation is old (http://old.haxe.org/doc/cpp/ffi) and I'm not familiar with C++ either.
So how do you do that in Haxe? I suppose I'll need to install hxcpp via haxelib, but that's about as much as I know.
For a start, check out C++ Magic by Hugh Sanderson. Much of the mentioned Compiler Metadata in that talk can be found at the Built-in Compiler Metadata page in the Haxe Manual.
He then talks briefly about metadata magic. He provides metadata for classes and functions. For classes you have the following:
#:headerClassCode(...) which injects member variables and inline functions.
#:headerCode(...) which includes external headers.
#:headerNamespaceCode(...) which allows you to add to the global namespace.
#:cppFileCode(...) which allows you to include external headers only in C++ files.
#:cppNamespaceCode(...) which implements static variables.
#:buildXml(...) which allows you to add to the build.xml file.
For function metadata you get the following:
#:functionCode(...)
#:functionTailCode(...)
Hugh states these are largely redundant as you should use untyped
__cpp_(...) instead.

Best practice to partially change a C++ library while keeping the rest of the library intact

What is the best practice to add or modify a single class method in a well-established C++ library like OpenCV, while still reusing the remaining of the library code, preferably in the lib format.
At this point the only way I know is to copy all the source and header files that belong to the specific library (let's say OpenCV's core library) to the current source folder, modify that one function and recompile the module with the rest of the code. Ideally, I want to be able to link all the current .lib files the way they are, but simply define a new method (or modify a current method) for a class defined inside those libs in a way that my implementation of the method supersedes the implementation of the default library files.
Inheritance doesn't always seem to be an option, since sometimes the base class has private members that are required for the correct inherited class implementation.
I'm not aware of a clean way in C++ to accomplish what you're asking. What you're really asking to do (given that you need to use or modify private methods) is violate encapsulation, and the C++ language is designed to not let you do that.
A few options exist:
A .lib file is simply a collection of .obj files. Your compiler toolchain should have a command-line program for adding, deleting, and replacing .obj files in a .lib, so you could build one or two .obj files and merge them into the .lib. I suspect that this solution would be ugly and fragile.
If there's something that the library doesn't do and should do, then there's always a chance that you can submit a patch or feature request to the library authors to get that change made. Of course, this can take a while, if it works at all.
As #fatih_k suggests, adding your changes as friend classes would work. If the only change you make to OpenCV is to add a friend line to the header file, then the library's ABI will be unchanged, and you won't have to touch the .lib.
The cleanest option is to simply accept that you need to modify the OpenCV library and track its source code, along with your modifications, along with the source code you develop yourself, and build it along with the source code you build yourself. This is a very common approach, and various patterns and techniques exist to help you do it; for example, Subversion has the concept of vendor branches. This approach is more work to set up but is definitely the cleanest in the long run.
If the library is already compiled, there is not much you can do portably and cleanly.
If you know the specific target architecture the program will be runnning on, you could get the pointer to the member function and monkey patch the instructions with a jmp instruction to your own version of the method. If the method is virtual, you can modify the vtable. Those requires a lot of compiler-specific knowledge and would not be portable.
If the library ships in dynamic link archive, you could extract the archive and replace the method with your own version, and repack the archive.
Another method is you can copy the class' declaration from the header and add a friend declaration. Alternatively, you can do #define private public or #define private protected before including a header file. These will give you access to their private members.
With any of the above, you need to be careful that your changes does not modify the ABI of the library.
Well, OpenCV is licensed under BSD so you can make your changes without worries about republishing them.
You could always follow the Proxy design pattern and add the new method external to the library, and call into the library from there. That means you don't need to worry about maintaining your own version of OpenCV and distributing it as well. There's more information about Proxy patterns on Wiki to get you started.

What's the difference between a header file and a library?

One of the things I'm having a hard time understanding is how the compiler works. I'm having a lot of difficulties with it, but in particular I keep getting headers and libraries mixed up. If somebody could clear things up a bit, that'd be great.
Think of both like this (Disclaimer: this is a really high-level analogy ;) ..
The header is a phone number you can call, while...
...the library is the actual person you can reach there!
It's the fundamental difference between "interface" and "implementation"; the interface (header) tells you how to call some functionality (without knowing how it works), while the implementation (library) is the actual functionality.
Note: The concept is so fundamental, because it allows you flexibility: you can have the same header for different libraries (i.e. the functionality is exactly called in the same way), and each library may implement the functionality in a different way. By keeping the same interface, you can replace the libraries without changing your code.
And: you can change the implementation of the library without breaking the calling code!
A header file is generally used to define an interface or set of interfaces within an application. Think of a header file as something which shows the external functionality of a program while omitting the technical implementation details.
For example, if you were optimising a program, you would most likely modify the source (.cpp) file to improve the algorithm, but the header file wouldn't change, because external clients still call the methods using the same set of parameters and return values.
In an object-oriented language like C++, a header file generally includes the following:
Class description and inheritance hierarchy
Class data members and types
Class methods
While there is nothing stopping code from being implemented in a header file, this is generally not favoured as it can introduce extra coupling and dependencies in the code.
In some cases (e.g. templated classes) the implementation must be defined in the header file for technical reasons.
A library is a collection of code which you want to make available to a program or group of programs. It includes the implementation of a particular interface or set of interfaces.
Code is defined in a library to prevent code duplication and encourage re-use. A library can be statically-linked (.lib) or dynamically-linked (.dll):
A statically-linked library defines a set of export symbols (which can be thought of as method definitions) which are then linked into the final executable (.exe) during the linking stage of the build process. It has the advantage of faster execution time (as the library doesn't need to be dynamically loaded), at the expense of a larger binary (because the methods are essentially replicated in the executable file).
A dynamically-linked library is linked during the execution of a program, rather than the linking of a program. It is useful when multiple programs need to re-use the same methods, and is used extensively in technologies such as COM.
One thing that may be confusing you is that the word library can have several meanings in C++. One meaning has been well-discussed here:
A linkable set of functions in a binary file. These can be statically linked or dynamically linked.
But there is another type of library: so-called header-only libraries (including parts of STL, TR1 and Boost). These do not exist in a separate binary form so the word library does not refer to a particular binary file but rather to a set of included header files.
Hope this helps.
Header only contains the declaration, whereas libraries also contains the implementaion.
A library is code, compiled into a set of object files. The object files contain the compiled machine code and the data declarations used by the code.
A header file defines the interface to a library: it tells you how to use the library correctly. In C/C++, a header file gives you a list of function names and how to call those functions: the number and types of parameters they take, the return type, the calling convention, etc. Header files have a lot of other stuff in them, too, but in the end, what it boils down is a set of rules for calling library code.
If Library in programming languages is a general library , then many books present in the library can be compared with functions/methods in languages . And also header files can be compared with the row number of the book
Suppose there is a book in some library in Hyderabad and in that library , that book is present in row Number 24 ...
The same way the address of the library is given by using the namespace std (for standard library) and row No is given by header file where all the books(methods in this case) of same time(all methods related to input/output streams) are put up
Header is typically used to contain the prototypes. Headers expand at pre-processing time so that at compile time, the code may have access to relevant function declarations/ prototypes.
Library is the actual software that contains the definitions of the function prototypes (present in the header). Library is used at link time. The definitions (present in library) are resolved at link time.
A header file describes how to call the functionality, a library contains the compiled code that implements this functionality.
HEADER FILE is that in which declaration of a function is written.By using header file we can access a particular function
while
LIBRARY FILE is that in which definition of a particular function is written.
MATH.H is a HEADER FILE while MATH.LIB is library file.
Working of HEADER File and LIBRARY in a Program.
A header file contains the links to libraries(libraries contain standard functions and methods), a compiler recognizes the standard functions used in the source code via a preprocessor, that resolves all the directives(directives are the lines in program preceded by # sign that include ) before the actual compilation of the program.
Thanks for reading!
I think library as a package of code which is reused many times and and that code is precompiled , hence it is available in standard form so that we do not have to write that code for every program that we develop .
And header file contain the reference to that code in simple way the functions we use in our program like "cin" and "cout" are fully defined in a standard library ,and header files like iostream header file contains the reference to that code.
So when we compile our code it we just get the precompiled for cin and cout, and we do not have to write the code for cin and cout for every time we use it.
Or In a more simple way we can say that a library contain codes for all the functions and a header file is way to reach that code.
A library is a collection of similar objects for occasional use . It usually contains programmes in object or source code form, templates, etc.
A header file is the location (interface) of the library
To paraphrase a classical joke, the difference is that the library has a header file while the header file doesn't have a library.
Libraries are like dead mummies,wrapped in white long threads. They are dead. Only way to release them is through header files. Header files contain ways to bring them to life and they can be brought to life many times(code reuse).
You can consider this example to understand- Math.h is a header file which includes the prototype for function calls like sqrt(), pow() etc, whereas libm.lib, libmmd.lib, libmmd.dll are some of the math libraries. In simple terms a header file is like a visiting card and libraries are like a real person, so we use visiting card(Header file) to reach to the actual person(Library).
Code from libraries will only be stored as needed for a header file. The whole header file will be stored, which saves processor storage area.