Qt commercial commands renaming

[Kidev]

As mentioned in this PR, @pzhlkj6612 and I feel that the naming of the commands is misleading.
Indeed, some params are questionable, lack consistency, or obscure the fact that the feature can be used by open-source users provided they authenticate.

Since there is no docs yet, it's the good time to change the commands. I would immediately update my PR on the install-qt-action to reflect those changes. What do you think @miurahr ?

Should we rename, and if so, how should we rename...

• install-qt-commercial
• list-qt-commercial
• --override
• --user and --password

For user and password, they are used on aqt side to authenticate, but clash with the params on the Qt side (--email=str and --pw=str). Being two different params also created complications in the code that are now mostly solved, but unifying would reduce the chance of undefined behavior. Example if the issues that creates: if --user is passed, then --override then --pw, should the command be valid? If both are used, which account should it authenticate?

---

Here is a draft of documentation

Qt Commercial Installation Commands

Important

• You can only install for the OS running the CLI
• All commands require authentication:

  • It first looks into the folder of your OS where the file qtaccount.ini can be:

    • Windows: C:\Users\<username>\AppData\Roaming\Qt\qtaccount.ini
    • Linux: /home/<username>/.local/share/Qt/qtaccount.ini
    • MacOS: /Users/<username>/Library/Application Support/Qt/qtaccount.ini

    This file is automatically created when you use the MaintenanceTool binary and log in using the GUI. It is also created the first time you use the CLI or any mean to authenticate. You can simply copy the file that you have on your PC to your CI server, it will work across platforms. Just treat it as a password. Refer to this page for more details.

  • It will also check the value of the environment variable QT_INSTALLER_JWT_TOKEN and use the token if provided.

  • If neither are present, you will need to provide --user <email> --password <password>.
    Note that if --user and --password are provided, they will supersede the qtaccount.ini and the JWT token account. Those also get superseded by --override --email --pw in the CLI

install-qt-commercial

Install Qt commercial packages using the official Qt installer.

aqt install-qt-commercial <target> <arch> <version> [options]

Arguments

• target - Target platform (desktop, android, ios)
• arch - Target architecture
• version - Qt version to install

Options

• --user <username> - Qt account username
• --password <password> - Qt account password
• --modules <module1> <module2> ... - Additional Qt modules to install
  • Very broad meaning, aka packages or components (see here). Extensions, wasm, src... are 'modules'
  • If none are inputed, the package qtX.Y.Z-essentials is downloaded (default Qt install, includes qtcreator...)
  • If all is inputed, the package qtX.Y.Z-full is downloaded (includes everything)

Click to see all the special packages (for Linux Qt 6.8.1)

Name: qt6.8.1-essentials
Display name: Qt 6.8.1 Linux x86_64 Essential Components
Description: Qt 6.8.1 Linux x86_64 Essential Libraries, Headers, and Tools
Version: 6.8.1
Components: qt.qt6.681.linux_gcc_64
========================================
Name: qt6.8.1-essentials-dev
Display name: Qt 6.8.1 Linux x86_64 Essential Components (dev)
Description: Qt 6.8.1 Linux x86_64 Essential Libraries, Headers, and Tools (dev)
Version: 6.8.1
Required aliases: qt6.8.1-essentials
========================================
Name: qt6.8.1-full
Display name: Qt 6.8.1 Linux x86_64 All Components with Sources
Description: Qt 6.8.1 Linux x86_64 All Libraries, Headers, Tools, and Sources
Version: 6.8.1
Components: qt.qt6.681.src,extensions.qtwebengine.681.src
Required aliases: qt6.8.1-essentials,qt6.8.1-addons,qt6.8.1-extensions
Optional components: extensions.qtinsighttracker.681.src
========================================
Name: qt6.8.1-full-dbg
Display name: Qt 6.8.1 Linux x86_64 All Components with Sources and Debug Information Files
Description: Qt 6.8.1 Linux x86_64 All Libraries, Headers, Tools, Sources, and Debug Information Files (dev)
Version: 6.8.1
Components: qt.qt6.681.debug_info.linux_gcc_64,qt.qt6.681.debug_info,extensions.qtwebengine.681.debug_information
Required aliases: qt6.8.1-full-dev
Optional components: 
Optional aliases: 
========================================
Name: qt6.8.1-full-dev
Display name: Qt 6.8.1 Linux x86_64 All Components with Sources (dev)
Description: Qt 6.8.1 Linux x86_64 All Libraries, Headers, Tools, and Sources (dev)
Version: 6.8.1
Required aliases: qt6.8.1-full
========================================
Name: qt6.8.1-sdk
Display name: Qt 6.8.1 Linux x86_64 SDK
Description: Qt 6.8.1 Linux x86_64 SDK Tools (Qt Creator, Ninja, and CMake)
Version: 6.8.1
Components: qt.tools.qtcreator_gui,qt.tools.cmake,qt.tools.ninja
Required aliases: qt6.8.1-full-dev,qt6.8.1-full-dbg

• --outputdir <path> - Installation directory (default: current directory)
• --override <args...> - Pass all remaining arguments directly to the Qt installer CLI

list-qt-commercial

Search available Qt commercial packages.

aqt list-qt-commercial [search_terms] [options]

Options

• --user <username> - Qt account username
• --password <password> - Qt account password
• search_terms - Terms to search for in package names (grabs all that is not other options)

Override Mode

install-qt-commercial supports an override mode that passes all arguments after --override directly to the Qt installer CLI, and will ignore all the other params except --user and --password if given prior to it

aqt install-qt-commercial --override [installer_args... --email email --pw password]
aqt install-qt-commercial --user user --password pass --override [installer_args...]

When using override mode:

• All standard command options are ignored
• Arguments are passed directly to the Qt installer
• The --email/--pw flags in the override arguments are used for authentication
• Regular --user/--password can still provide fallback authentication
• More info here

Examples

# Standard installation
aqt install-qt-commercial desktop linux_gcc_64 6.8.0 --user user@example.com --password pass

# Installation with modules
aqt install-qt-commercial desktop linux_gcc_64 6.8.0 --user user@example.com --password pass --modules qtcharts qtnetworkauth

# List packages containing 'wasm'
aqt list-qt-commercial wasm --user user@example.com --password pass

# Override mode
aqt install-qt-commercial --override install qt.qt6.680.gcc_64 --email user@example.com --pw pass

Advanced configs

The file located in ./aqt/settings.ini can be edited in the [qtcommercial] part to fine tune the official installer (more details here):

[qtcommercial]
unattended : True # Removes needs of user interaction, and simplifies the --override option as well by passing flags by default to remain unattended
installer_timeout : 1800
operation_does_not_exist_error : Ignore
overwrite_target_directory : No
stop_processes_for_updates : Ignore
installation_error_with_cancel : Ignore
installation_error_with_ignore : Ignore
associate_common_filetypes : Yes
telemetry : No
cache_path : # When empty, will use ~/.local/share/aqt/cache or equivalent for your OS
temp_dir : # When empty, will use ~/.local/share/aqt/tmp or equivalent for your OS

[Kidev]

Preview visible here: https://demo.kidev.org/aqtinstall/commercial.html

[miurahr]

I don't have a specific preference for the command name. I want to respect a proposal.

[Kidev]

So I slept on it, and came up with:

• install-qt-commercial -> install-qt-official or install-qt-authenticated
• list-qt-commercial -> list-qt-official or list-qt-authenticated
• user password -> email and pw to be less confusing and make it more likely to work
• override -> --bypass-aqt

Thoughts?

[Kidev]

I guess another option that would be the most user friendly would be to also support if in normal CLI, a flag like --use-qt-installer is found, it grabs all relevant params, and make the user automatically call aqt install-qt-official <target...> (ignoring all the host params and so on). It would still require the user to authenticate, which could then be required params of --use-qt-installer <email> <pw>

[pzhlkj6612]

I like --use-qt-installer. That's unambiguous.

And we also need to tell the user some commands don't support --use-qt-installer to avoid abuse.

[Kidev]

To conclude here, I went with install-qt-official, list-qt-official, and later added --use-official-installer (#906) to install-qt

[pzhlkj6612]

Sorry I don't have time to read your new code, but still would like to ask: maybe we can also add --use-official-installer to list-qt?

[Kidev]

Done in #909

[pzhlkj6612]

Whoa, I appreciate your hard work!