[Development] Higher-Level Docs, possibly Qt-related (was: Re: Qt 4.8.6 Release Plans)

[Charley Bay]

On Wed, Oct 30, 2013 at 1:59 AM, Konrad Rosenbaum <konrad at silmor.de> wrote:

> **
>
> Hi,
>
>
>
> On Wednesday 30 October 2013 00:58:05 Calogero Mauceri wrote:
>
> > The Qt documentation states that QDir::currentPath() returns "The
>
> > application working directory". Shouldn't the workind directory be
>
> > initialized with the path the application was launched from? If that's
>
> > not the case, which is the right way to obtain the working directory?
>
> > (not the executable path as the QApplication::applicationDirPath() is
>
> > returning)
>
>
>
> The current working directory is the directory the application is
> currently working in (I know, it sounds like a tautology). Or in other
> words: if you open a file with a relative path name, the current working
> dir is the one in which your program looks for the file:
>
>
>
> QFile file("myfile");
>
> file.open(QIODevice::ReadOnly);
>
>
>
> is equivalent to:
>
>
>
> QFile file(QDir::current()+"/myfile");
>
> file.open(QIODevice::ReadOnly);
>
>
>
> You can change it with QDir::setCurrent or the underlying OS function
> chdir.
>
>
>
> At application startup the current working directory is the exact same
> directory that the parent was in when it spawned your process (this is
> somewhat simplified). This is the same behavior over all desktop OSes. The
> parent application is free to chose: it can simply refuse to care (result:
> your CWD is more or less random from your programs perspective; this is why
> an app started from a KDE desktop is almost always in $HOME, but sometimes
> somewhere else); it can assume you are a command line tool and want to work
> in the same place the shell is in (that's what happens if you start
> anything from a shell); it can try to be "helpful" and switch to the
> directory the binary is in (apparently what Mac used to do); or it can try
> to make things consistent by switching to the root directory (apparently
> what 10.9 does).
>
>
>
> In short: relying on the CWD at startup is misguided for most GUI apps. If
> you need to be in a specific directory: use some other mechanism to find it
> and then switch there, do not rely on being placed there by magic.
>
>
>
> Places you may want to be:
>
> * somewhere relative to your binary: use QApplication::applicationDirPath()
>
> - I do this in apps that have complex trees of files with data needed at
>
> runtime, apps that work in their own little "universe"
>
> * in the users home directory: QDir::setCurrent(QDir::homePath())
>
> - desktop apps that interact with user files
>
> * in the exact same place you were started from: don't move
>
> - this is true for most command line tools (like qmake, moc, ...)
>
> * in the root directory
>
> - true for most server processes (daemons, middleware, ...)
>
> * in the temp dir: use QDir::setCurrent(QDir::tempPath())
>
> - e.g. simulations that create some throw-away data only
>
> * in some dir that was configured by the user: read the config then switch
>
> - true for other server-like processes (e.g. automation software, ...)
>
>
>
> The tricky question we're trying to coax out of you: does QDir.current()
> really return an empty string "" or the root directory "/"? The former may
> indicate a bug on Apple's part, the latter is a perfectly valid place to be
> in.
>
>
>
>
>
> Konrad
>

This is an outstanding (and thorough/exhaustive/detailed) post on this
topic.

Where can we put this in the Qt Docs or "Guidance-Help" for future users,
and future Qt-internals-implementors?  (I'd really like this
"saved-for-posterity" so as to refer back to it in the future, and it seems
like these are "guiding principles" to which the Qt internals should be
able to "refer" in future discussions to justify design/behavior.)

We do *lots* of Qt-based multi-threaded command-line apps, including
server-and-monitor-processes, and it seems in today's
distributed-and-multi-core-world there will be more of this by more users.
 Since Qt is the *only* real cross-platform solution at present (I'm not
very excited about "Javascript/HTML5"), and Qt's libraries and APIs nicely
bridge the issues on different platforms, it seems like Konrad's
"higher-level-understanding" of this topic is *exactly* the
value-proposition that the Qt Community is able to provide to the industry
-- which is useful even if the reader is previously unaware of Qt.

I understand this example topic ("current-working-dir") is not specifically
a Qt-library (or API) issue, but a
"cross-platform-and-cross-historical-understanding-of-the-problem" issue.
 Do we have documentation that is a good "home" for these higher-level
design/programming discussions, especially as it relates to cross-platform
or cross-historical understanding, which often "touches-on" the issues Qt's
APIs are intended to solve?

Another example of this is Thiago's excellent discussions regarding binary
compatibility.  It's not a Qt-topic directly, but is an issue in which Qt
"leads-the-industry" for understanding to establish convention.  As Qt has
impressively handled compatibility over a long historical period on many
platforms, it is uniquely able to discuss at a "higher-level" these very
practical design and solution issues regarding "more-proper" ways to
address a host of problems.

So, I'm looking for something that might be a "home" for docs like:

*- "Guiding Principles:  Design Decisions In the Qt Internals"

*- "State-Of-The-Art: Good API Design based on Qt"

*- "Lessons Learned: Historical Evolution Of Platform Behaviors (as seen by
Qt)"

*- "Binary Compatibility:  How, Why, And the Cost"

*- "What Works: Designing And Scaling Systems (using Qt)"

*- "Satisfying Today's Advanced User Expectations (using Qt)"

I think any of those would be fun-books-to-write, and I'm sure there are a
number of people on this list highly qualified to do so.  IMHO, most of the
development shops really need to read those books, whether-or-not they use
Qt (a shame these books don't exist at present.)

--charley
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20131030/ce997346/attachment.html>