tr_export.h File Reference

Symbol visibility and compiler annotation macros. More...

Go to the source code of this file.

Macros
#define	TR_EXPORT_SYMBOL
#define	TR_IMPORT_SYMBOL
#define	TR_LOCAL_SYMBOL
#define	TR_API
	Marks a public API symbol for export or import.
#define	TR_INTERNAL   TR_LOCAL_SYMBOL
	Marks a symbol as internal to the library.
#define	TR_DEPRECATED(message)
	Marks a public API function as deprecated.
#define	TR_NODISCARD
	Warns if the return value of a function is ignored.

Detailed Description

Symbol visibility and compiler annotation macros.

Provides macros for controlling symbol visibility across platforms and build types. Supports MSVC, GCC, Clang and unknown compilers with graceful degradation.

The following macros are defined:

• TR_API — marks a public API symbol
• TR_INTERNAL — marks an internal symbol
• TR_DEPRECATED — marks a deprecated symbol
• TR_NODISCARD — warns if return value is ignored

Macro Definition Documentation

TR_API

#define TR_API

Marks a public API symbol for export or import.

When building the library as a shared library:

• Expands to __declspec(dllexport) when building the library (MSVC)
• Expands to __declspec(dllimport) when consuming the library (MSVC)
• Expands to __attribute__((visibility("default"))) on GCC/Clang

When building as a static library expands to nothing.

Apply to all public API function declarations:

TR_NODISCARD TR_API tr_result_t tr_stack_create(...);

TR_DEPRECATED

#define TR_DEPRECATED

(

message

)

Marks a public API function as deprecated.

Emits a compiler warning when the marked function is used, with a message explaining the deprecation.

• Expands to __declspec(deprecated(message)) on MSVC
• Expands to __attribute__((deprecated(message))) on GCC/Clang
• Expands to nothing on unknown compilers

Example usage:

TR_DEPRECATED("Use tr_stack_create instead")
TR_API tr_result_t tr_stack_new(...);

Parameters

message

String literal describing the deprecation reason

TR_INTERNAL

#define TR_INTERNAL   TR_LOCAL_SYMBOL

Marks a symbol as internal to the library.

Prevents the symbol from being visible to consumers of the library even when building as a shared library.

• Expands to __attribute__((visibility("hidden"))) on GCC/Clang
• Not supported on MSVC, expands to nothing

Apply to internal functions that must be visible across translation units within the library but not to consumers:

TR_INTERNAL void tr_internal_helper(void);

TR_NODISCARD

#define TR_NODISCARD

Warns if the return value of a function is ignored.

Apply to all functions returning tr_result_t to enforce error checking at the call site.

• Expands to __attribute__((warn_unused_result)) on GCC/Clang
• Expands to _Check_return_ on MSVC 2012 and later
• Expands to nothing on unknown compilers

Example usage:

TR_NODISCARD TR_API tr_result_t tr_stack_push(...);