From d3e2ae35cb4259e3312967a1a0a50ca6e6300292 Mon Sep 17 00:00:00 2001 From: hjk Date: Thu, 20 May 2021 13:35:47 +0200 Subject: [PATCH] Doc: Add some rules about use of Utils::FilePath and Utils::QtcProcess Change-Id: I6c21fe0bc795a24ce6b61d739f221f28cefc6df2 Reviewed-by: Christian Kandeler Reviewed-by: Leena Miettinen Reviewed-by: Alessandro Portale --- doc/qtcreatordev/src/coding-style.qdoc | 35 +++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/doc/qtcreatordev/src/coding-style.qdoc b/doc/qtcreatordev/src/coding-style.qdoc index d429ea917ca..6b87163baf5 100644 --- a/doc/qtcreatordev/src/coding-style.qdoc +++ b/doc/qtcreatordev/src/coding-style.qdoc @@ -574,7 +574,7 @@ void SomeThing::bar() { - FileName f; // or Utils::FileName f + FilePath f; // or Utils::FilePath f ... } ... @@ -637,12 +637,39 @@ instead of backslashes (\\) even on Windows. To pass a file name from the user to the API, convert it with QDir::fromNativeSeparators first. To present a file name to the user, convert it back to native format with - QDir::toNativeSeparators. Consider using Utils::FileName::fromUserInput(QString) - and Utils::FileName::toUserOutput() for these tasks. + QDir::toNativeSeparators. Consider using Utils::FilePath::fromUserInput(QString) + and Utils::FilePath::toUserOutput() for these tasks. - Use Utils::FileName when comparing file names, because that takes case sensitivity into account. + Use Utils::FilePath when comparing file names, because that takes case sensitivity into account. Also make sure that you compare clean paths (QDir::cleanPath()). + + \section2 Classes to Use and Classes Not to Use + + A significant portion of Qt Creator code handles data on devices that are not + the same as the development machine. These may differ in aspects like path + separator, line endings, process launching details and so on. + + However, some basic Qt classes assume that a Qt application is only + concerned with machines that are similar to the development machine. + + These classes are therefore not appropriate to use in the part of Qt Creator that + is concerned with non-local code. Instead, Qt Creator's Utils library provides + substitutes, leading to the following rules: + + \list + \li Use Utils::FilePath for any QString that semantically is a file or directory, + see also \l{Passing File Names}. + \li Prefer using Utils::FilePath over any use of QDir and QFileInfo. + \li Prefer using Utils::QtcProcess over QProcess. + \li If Utils::FilePath or Utils::QtcProcess functionality is not sufficient + for your purpose, prefer enhancing them over falling back to QString + or QProcess. + \li Avoid platform #ifdefs unless they are absolutely needed for locally + executed code, and even then prefer Utils::HostInfo over #ifdefs. + \endlist + + \section2 Plugin Extension Points A plugin extension point is an interface that is provided by one plugin