[Development] Suggested addition to wiki.qt.io/Coding_Conventions

[Matthew Woehlke]

On 2015-05-13 04:25, Marc Mutz wrote:
> Hi,
> 
> I'd like to suggest the following addition to the Qt Coding Conventions:
> 
> === Exporting Classes ===
> 
> Export polymorphic classes as a whole:
> 
> <code>
>   class Q_LIB_EXPORT QMyWidget : public QWidget
>   { ...
> </code>
> 
> But don't export non-polymorphic classes that way. Instead, only export the 
> following non-inline methods. 
> 
> * public
> * protected
> * private, if called from inline functions (now or in the past)
> 
> Rationale: On Windows, symbols from a DLL that don't have inline linkage 
> (templates or inline functions have inline linkage) need to be exported for 
> clients to link against them, This is what the <tt>Q_*_EXPORT</tt> macros are 
> for. On some Unix systems, the macros map to a similar mechanism that 
> <em>hides</em> symbols not exported that way, positively affecting startup 
> performance and library size.
> 
> But exporting the whole class, while convenient, has several drawback:
> 
> * it exports symbols that don't need exporting:
> ** private methods never called from user code
> ** methods of private nested structs and classes

Many Qt classes have corresponding Private (PIMPL) classes. Private
methods would hopefully be few and far between.

Is it possible to override the export decoration for things like this
that should *not* be exported?

> ** inline methods
> * exporting inline methods makes MSVC call the library implementation in debug 
> builds

That's a feature. There are reasons why debug builds don't inline
(mostly because it makes stack traces unreliable).

> ** a copy of the function is placed in the library even though the library 
> itself may never use it

What if I need to take the address of an inline method (e.g. to use it
as a functor argument)?

> ** exported inline functions can no longer be removed

They can't anyway, as this would be both an API and ABI break; see
previous point.

-- 
Matthew