[Qt Tip] Beware: Starting QML Project Names with Numbers Can Cause Headaches.

 

 

Hello, 

 

 I recently stumbled upon a little-known fact while working with Qt QML projects, and I wanted to share it with you all. If you already know this, consider it a quick confirmation!

 

 I tested this out on Windows 11 with Qt 6.8.3 and 6.9.

 

---

 

1. The Case of the Unbuildable QML Project

 

Typically, when you create a new QML project in Qt Creator, you'd select "Qt Quick Application," right?

 

 

 

 Next up is the "Project Location" screen, and this is where you need to be cautious about the Name field. It's common practice to prefix project names with numbers to indicate progress or categorize projects.

 

In my case, I named a project 01_QMLTest, starting it with 01. I then proceeded to finish the project creation.

 

 

 

 However, what I ended up with was an incomplete project in the project pane, like this:

 

 

 

 Trying to run it was futile; I simply couldn't build the project. Initially, I was completely stumped. I thought perhaps I'd messed up my settings while installing other software or that my environment was somehow corrupted.

 

 

 

2. The Root Cause

 

 I even tried asking GPT and Gemini for solutions, but they couldn't help. I reinstalled Qt several times, only to encounter the same issue.

 Then, out of sheer frustration, I decided to try a random name without a leading number, and boom! It built perfectly.

 

After realizing the problem and doing some more digging, I found some crucial information regarding QML URIs.

 

 

3. The Simple Fix

 

The solution is remarkably straightforward: When creating a QML project, avoid starting the name with numbers or underscores (_). It's highly recommended to begin the name with an alphabetic character. This isn't so much an inherent URI problem as it is an adherence to QML URI naming conventions.

 

 For example, if you name your project something like QML_test01, you'll be able to build it without any issues. While it might require a slight adjustment to your naming conventions, it allows you to create projects smoothly.

 

 

It turns out the issue lies within the URI part of the qt_add_qml_module section in your CMakeLists.txt file.

 

 

 

4. Diving into QML URI "Identified Modules"

For your reference, here's some relevant information about this section:

 

 

(Korean)

대략 해석해보면,

  "구문적으로, URI의 각 점으로 구분된 세그먼트는 유효한 ECMAScript 식별자 이름이어야 합니다. 이는 예를 들어, 세그먼트가 숫자로 시작해서는 안 되며 하이픈(-) 문자를 포함해서는 안 된다는 것을 의미합니다. URI가 디렉터리 이름으로 변환될 것이므로, 라틴 알파벳의 영숫자, 밑줄, 점으로 제한해야 합니다."

 

 Hopefully, this helps others avoid the frustration of reinstalling Qt multiple times, like I did!

 

Thanks for reading!

 

 

<References>

1. Qt 6.9 > Qt Qml > The QML Reference > QML Modules > Identified Modules

https://doc.qt.io/qt-6/qtqml-modules-identifiedmodules.html