Alternative way to include unstable declarations

[yfeldblum]

The current way of getting unstable declarations available only in statically-linked code is to set a macro and then include zstd. But this is clumsy for users in larger projects. For example, including one header that includes the zstd header, then including another header that includes the zstd header with unstable declarations, won't work. Effectively, including zstd unstable declarations from a library header is broken. As a workaround, it is often the case that libraries could wrap up the zstd unstable declarations in their own wrappers and only include zstd from a source file owned by the library. But this would not be acceptable for header-only C++ libraries.

An alternative would be to have a separate header for these declarations. Rather than setting a macro and then including zstd, users would just include zstd-static.

This could be done compatibly, where users could do either one at will. Effectively:

// zstd.h
#pragma once
#if ZSTD_STATIC_LINKING_ONLY
#include <zstd/unstable.h>
#endif
// ...

This would not break existing code and the current pattern of setting the macro before including zstd could still be encouraged. But library headers could get an alternative which is not broken.

[Cyan4973]

For example, including one header that includes the zstd header, then including another header that includes the zstd header with unstable declarations, won't work.

Could you describe what is the issue in above scenario ? The current design of zstd.h is supposed to allow such pattern.

[terrelln]

Effectively, including zstd unstable declarations from a library header is broken.

zstd.h handles multiple includes correctly.

#include <zstd.h>
#define ZSTD_STATIC_LINKING_ONLY
#include <zstd.h>

This works as expected (you'll get the static symbols on the 2nd include).

However, I agree that it is non-standard, and that it can cause problems with modules. And it would be nice to switch to a zstd_unstable.h header file.

[yfeldblum]

Okay, this works as expected when directly including zstd.h because zstd.h internally has the required trickery.

However, when a library wraps zstd.h and does not match the required trickery, the library authors and authors of libraries and applications using the wrapping library may run into surprising behavior.

Beyond that, I agree that this interface is unconventional - even taking into account that glibc uses something like it. But, from one perspective, people are machines of convention. Unconventional interfaces require extra documentation, extra learning, and extra trial and error.