Re: [Development] Qt Examples need to be self-contained

[Fabian Kosmale via Development]

Hi,

just for clarification: If we factor out shared resources into a library, then 
that wouldn't be one big QtExamplesShared module,
but rather one library per module (unless something actually needs to be shared 
across multiple modules, e.g. icons).
Anything else would require moving examples to a leaf module like qtdoc to 
handle the dependencies in the CI, which isn't
something we want here.

I would argue that putting actually shared resources into such libraries is a 
good idea, regardless of whether we need it for
junctions or not – after all, it promotes a sane way of sharing resources in 
our examples. Whereas I doubt that we want to
promote the relative path inclusion for the projects our users start.

Regards,
Fabian


Von: Development  im Auftrag von Kai Köhne 
via Development 
Gesendet: Donnerstag, 7. März 2024 13:02
An: qt-development
Betreff: [Development] Qt Examples need to be self-contained

Hi,

We have quite a few Qt examples and tutorials that share assets  (images, 
sources, ...) via relative paths in the file system. That is, there's often a 
'shared' directory that multiple examples use by relative paths (see e.g. 
https://code.qt.io/cgit/qt/qtdeclarative.git/tree/examples/quick/shared). My 
suggestion is to officially ban this, and

  *
either duplicate the relevant sources and assets in the respective example 
directories, or
  *
create a static 'QtModuleExamplesPrivate' library that is built as part of Qt, 
and can be referenced by these examples - something we already discussed & 
implemented before e.g. for sharing icons.

Proposed change in QUIP-13  is at 
https://codereview.qt-project.org/c/meta/quips/+/546086

Why this change? Qt Creator 13 will get a feature to shorten build paths by 
creating Junction Points (basically symbolic links) on Windows. This is to 
prevent file paths and build command lines from becoming too long, an issue 
that has been a never-ending source of frustration especially for new users on 
Windows

The issue of long file paths breaking builds is something that has been 
impeding users since forever. It became even more urgent though in the last 
years due to the deep nested structures that Qt Quick and the relevant tooling 
endorses (see e.g. https://bugreports.qt.io/browse/QTBUG-117413). Its root 
cause can arguably only be fixed on Microsoft's side - but chances for this are 
IMO slim ... So, shortening build paths as part of Qt Creator seems our best 
'general' cure for now. As the build path will however not be the source path, 
navigating across the file system with things like

  #include "../../../../shared/shared.h"

will break.

If we agree on this, we would prepare matching bug reports for affected 
examples.

Regards

Kai

PS: To be clear, this is not something we still have to fix for Qt 6.7.0.  For 
now, the use of Junction points in Qt Creator is still opt-in. When we fix 
examples, we should still backport them to older Qt versions though.


--

Kai Köhne, Director R | The Qt Company



The Qt Company GmbH, Erich-Thilo-Str. 10, D-12489 Berlin

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen

Sitz der Gesellschaft: Berlin, Registergericht: Amtsgericht Charlottenburg, HRB 
144331 B


-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

[Development] Qt Examples need to be self-contained

[Kai Köhne via Development]

Hi,

We have quite a few Qt examples and tutorials that share assets  (images, 
sources, ...) via relative paths in the file system. That is, there's often a 
'shared' directory that multiple examples use by relative paths (see e.g. 
https://code.qt.io/cgit/qt/qtdeclarative.git/tree/examples/quick/shared). My 
suggestion is to officially ban this, and

  *
either duplicate the relevant sources and assets in the respective example 
directories, or
  *
create a static 'QtModuleExamplesPrivate' library that is built as part of Qt, 
and can be referenced by these examples - something we already discussed & 
implemented before e.g. for sharing icons.

Proposed change in QUIP-13  is at 
https://codereview.qt-project.org/c/meta/quips/+/546086

Why this change? Qt Creator 13 will get a feature to shorten build paths by 
creating Junction Points (basically symbolic links) on Windows. This is to 
prevent file paths and build command lines from becoming too long, an issue 
that has been a never-ending source of frustration especially for new users on 
Windows

The issue of long file paths breaking builds is something that has been 
impeding users since forever. It became even more urgent though in the last 
years due to the deep nested structures that Qt Quick and the relevant tooling 
endorses (see e.g. https://bugreports.qt.io/browse/QTBUG-117413). Its root 
cause can arguably only be fixed on Microsoft's side - but chances for this are 
IMO slim ... So, shortening build paths as part of Qt Creator seems our best 
'general' cure for now. As the build path will however not be the source path, 
navigating across the file system with things like

  #include "../../../../shared/shared.h"

will break.

If we agree on this, we would prepare matching bug reports for affected 
examples.

Regards

Kai

PS: To be clear, this is not something we still have to fix for Qt 6.7.0.  For 
now, the use of Junction points in Qt Creator is still opt-in. When we fix 
examples, we should still backport them to older Qt versions though.


--

Kai Köhne, Director R | The Qt Company



The Qt Company GmbH, Erich-Thilo-Str. 10, D-12489 Berlin

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen

Sitz der Gesellschaft: Berlin, Registergericht: Amtsgericht Charlottenburg, HRB 
144331 B


-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] Nominating Dr. Máté Barany as an approver for the Qt project

[Mårten Nordheim via Development]

+1


From: Development  on behalf of Tor Arne 
Vestbø via Development 
Sent: Thursday, March 7, 2024 10:27
To: Axel Spoerl
Cc: development@qt-project.org
Subject: Re: [Development]  Nominating Dr. Máté Barany as an approver for the 
Qt project

+1!

On 6 Mar 2024, at 23:09, Axel Spoerl via Development 
 wrote:

Dear Colleagues,

I hereby nominate Dr. Máté Barany as an approver for the Qt project.
Máté has been a valuable contributor and reviewer, providing sound code, 
guidance and input.
As a reference, see his dashboard 
here:https://codereview.qt-project.org/dashboard/1010490

I fully trust his advice, expertise and judgement. I am certain that he will 
exercise approver rights to the benefit of the Qt project.

I am neither working in Máté's team, nor sharing an office with him.
Máté and I do know each other personally.

Kind regards
Axel


--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] Nominating Dr. Máté Barany as an approver for the Qt project

[Tor Arne Vestbø via Development]

+1!

On 6 Mar 2024, at 23:09, Axel Spoerl via Development 
 wrote:

Dear Colleagues,

I hereby nominate Dr. Máté Barany as an approver for the Qt project.
Máté has been a valuable contributor and reviewer, providing sound code, 
guidance and input.
As a reference, see his dashboard 
here:https://codereview.qt-project.org/dashboard/1010490

I fully trust his advice, expertise and judgement. I am certain that he will 
exercise approver rights to the benefit of the Qt project.

I am neither working in Máté's team, nor sharing an office with him.
Máté and I do know each other personally.

Kind regards
Axel


--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] Nominating Dr. Máté Barany as an approver for the Qt project

[Jøger Hansegård via Development]

+1

From: Development  On Behalf Of Matthias 
Rauter via Development
Sent: Thursday, March 7, 2024 7:04 AM
To: development@qt-project.org
Subject: Re: [Development] Nominating Dr. Máté Barany as an approver for the Qt 
project

+1

-Matti

From: Development 
mailto:development-boun...@qt-project.org>> 
on behalf of Timur Pocheptsov via Development 
mailto:development@qt-project.org>>
Sent: Thursday, March 7, 2024 3:11 AM
To: development@qt-project.org 
mailto:development@qt-project.org>>; Axel Spoerl 
mailto:axel.spo...@qt.io>>
Subject: Re: [Development] Nominating Dr. Máté Barany as an approver for the Qt 
project

+1

Best regards,
   Timur.

From: Development 
mailto:development-boun...@qt-project.org>> 
on behalf of Axel Spoerl via Development 
mailto:development@qt-project.org>>
Sent: Wednesday, March 6, 2024 11:09 PM
To: development@qt-project.org 
mailto:development@qt-project.org>>
Subject: [Development] Nominating Dr. Máté Barany as an approver for the Qt 
project

Dear Colleagues,

I hereby nominate Dr. Máté Barany as an approver for the Qt project.
Máté has been a valuable contributor and reviewer, providing sound code, 
guidance and input.
As a reference, see his dashboard 
here:https://codereview.qt-project.org/dashboard/1010490

I fully trust his advice, expertise and judgement. I am certain that he will 
exercise approver rights to the benefit of the Qt project.

I am neither working in Máté's team, nor sharing an office with him.
Máté and I do know each other personally.

Kind regards
Axel

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] On Removing Public Undocumented/\internal APIs

[Volker Hilsheimer via Development]

> On 4 Mar 2024, at 10:57, Marc Mutz via Development 
>  wrote:
> 
> Hi,
> 
> TL;DR:
> - Treat all APIs not clearly marked as private (private access, *Private
>   namespace or "We mean it!" comment) as public, in particular keep SC/BC
>   and deprecate before remove.
> - Avoid adding APIs that aren't clearly private or public in the future.

[…]

> I would suggest that we treat any entity defined in a header file that 
> is not in a *Private namespace or under the umbrella of an "We mean it!" 
> commant, in short: anything that isn't _visible_ as non-public API _from 
> the header file_, as semi-public, and apply the same rules as for public 
> API: keep BC/SC, deprecate first, remove second, and adjust QUIP-6 
> accordingly.

I think we have to acknowledge that Qt is 30 years old this year, and over the 
decades the capabilities of tools, the features of the languages, and the best 
practices, skills, and awareness of the people working on Qt have changed a 
lot. What usually hasn’t changed is the *intent* of the class author - even 
though it might be buried deep in the historical repositories. Stating now that 
everything that has the technical appearance of a public API cannot be changed, 
and ignoring the author’s intent, does not seem constructive.


> ¹ Off the top of my head: QString::isSimpleText(), QPen::data_ptr(), 
> QDeferredDeleteEvent

Undocumented APIs in any SDK are, IMHO, “use at your own risk”. I (or my IDE) 
might find something promising in some public header, but if I have no 
information about what the author of that thing is promising me, should I use 
it in my code? Sometimes it’s more obvious than other times, but what on earth 
is the semantics of "QString::isSimpleText”? What is that “DataPtr” reference 
returned by "QPen::data_ptr”? Can anyone use QDeferredDeleteEvent::loopLevel() 
in a meaningful way without studying the event delivery code?

> At the same time, we should make sure that we don't accept such 
> semi-public APIs going forward anymore.

I do agree that we shouldn’t add more such stuff, at least not without making 
it visible in the header, ideally in a way that makes it visible to code 
completion (if that’s possible at all).

For stuff that is there today (e.g. various container types’ “isSharedWith” 
public member function, usually documented explicitly as \internal, and often 
used in other modules or in tests so not really practical to do it any other 
way), should we add a "// internal” comment in the header file?

Cheers,
Volker


-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] Using '#pragma once' instead of include guards?

[Marc Mutz via Development]

Hi Tor Arne,

On 06.03.24 09:34, Tor Arne Vestbø wrote:
> The choice of where we use/allow `#pragma once` should not be coupled to 
> whether a header is considered public or not.

Let's be careful with wording here. No-one proposes to use #pragma once 
to distinguish public from private headers!

The proposal is to distinguish installed from non-installed headers, and 
the status quo is already that we can't have #pragma once in installed 
headers.

> Let’s not create even more indirections and inference rules that one has 
> to keep in mind.
> 
> If we want to make it clearer if a header is public or not, let’s make 
> it explicit.
> 
> We already have two established mechanisms:
> 
>   - Header ending in _p.h
>   - "We mean it” comment

These are for installed headers, and I'm actually proposing that the 
rules don't change for _those_, only for uninstalled headers.

> Renaming files may be too much churn, so let’s add more "We mean it” 
> comments.
> 
> It doesn’t matter whether header will be installed or not.

I beg to differ. The whole topic came up because it _is_ currently 
unclear whether a public-looking header is actually public (because it's 
installed) or not (because it's not), and you have to look at the 
location in the file system and/or the directory's CMakeLists.txt to 
understand which one it is.

> The 
> documentation is for whoever is going to look at the header, i.e us (and 
> our tools) for non-installed headers, and for us and users for installed 
> headers. Both groups would benefit from clarification of whether the 
> header is public API or not.

If we were to add "We mean it" comments to uninstalled headers, don't 
you think that would cause ambiguity in the other direction? Like "Oh, 
this is a public header, why isn't it called _p.h"?

> I’m fine with using `#pragma once` more, but that discussion is 
> orthogonal to how we clarify the status of a header.

It's not orthogonal for the reasons given in the first paragraph of this 
email, but it also need not be parallel, indeed.

I just feel that the transition from a non-installed to an installed 
header should leave some trace in header itself. #pragma once as a 
static assertion that the header isn't installed means we need to port 
to traditional header guards to make it installable, lest syncqt rejects it.

And, again: existing non-installed headers aside, which I mention I 
don't propose to port, isn't it much simpler to write #pragma once than 
to write a correct traditional header guard? So why wouldn't one use the 
pragma for new headers? And if one would naturally do, why require to 
add a (redundant) comment, too?

I feel that would be just more work for reviewers and authors. Any 
header needs an inclusion guard, so one would suppose that authors and 
reviewers already take care of that. The new thing is that installed 
headers cannot use #pragma once, and that's enforced by tooling, so 
can't be forgotten. Adding a comment to such headers is something 
additional that authors and reviewers need to keep in mind.

I'd prefer the path of least resistance here.

Thanks,
Marc

> Cheers,
> Tor Arne
> 
>> On 6 Mar 2024, at 07:57, Marc Mutz via Development 
>>  wrote:
>>
>> Hi,
>>
>> TL;DR: I'd maintain that #pragma once to mark non-installed headers is
>> a) the least-intrusive change of all that's been proposed, b) targeting
>> the non-public headers only (so don't disturb e.g. the API reviews (or
>> customer's validation...)), which c) are the minority of Qt headers
>> (minimizing work) and d) has benefits other than as a static assertion
>> against header installation.
>>
>> Longer version:
>>
>> Given that there are, in general, many more public and _p.h private
>> headers in Qt (outside tools), I'd think the prudent approach is to
>> modify the (fewer) non-installed headers.
>>
>> As for using a comment: We have the "We mean it" comment in _installed_
>> non-public headers, because installed headers are _accessible_ to users.
>> I see no value in adding such comments to headers that are never
>> installed, and are therefore _in_accessible to users.
>>
>> OTOH, #pragma once has benefits other than acting as a static assertion
>> against header installation. In my forays into "leaf" modules, but even
>> in qtbase, misnamed (header guard name doesn't match file name) and
>> non-Q-namespaced or overly-generic header guard macro names abound, and
>> I even found a downright broken header guard that had only
>> #ifndef/#endif and was missing the #define. If we can make it easier for
>> Qt devs to protect headers, we should do it. #pragma once also doesn't
>> change when the file is renamed or otherwise moved.
>>
>> Note to self: make sanity bot check that header guards start with a Q
>> and end in the file's name xor contain #pragma once, except in /3rdparty/.
>>
>> Thanks,
>> Marc
>>
>> On 05.03.24 11:43, Volker Hilsheimer wrote:
 On 4 Mar 2024, at 15:56, Kai Köhne via Development
  wrote:

 Hi Marc,