// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page studio-cmake-generator.html
    \previouspage
    \nextpage

    \title CMake Generator

        \section1 Contents converted by CMake Generator

        CMake Generator converts the contents of the \c .qmlproject file to CMake.

        \note A \QDS project can run with a missing path or file filter.
        However, CMake generation can fail due to missing elements in the \c .qmlproject file.

        \section1 Changes tracked by CMake Generator

        CMake Generator tracks all files listed in the \c .qmlproject file. Editing the
        \c .qmlproject file triggers a CMake generation. Adding, removing, and renaming files
        are tracked.

        \section1 Stubb or mock QML data for \QDS

        \QDS doesn't understand C++ code, so CMake Generator ignores any
        components or properties made with C++. If you want a similar
        representation in \QDS for the components or properties created with
        C++, add a QML mock file for \QDS. Store the mock files in a dedicated
        folder in your project folder. You can later add a \c mockImports
        variable in the \c .qmlproject file and include the folder path
        with mock files in the \c mockImports variable. CMake ignores all folders
        and files included in the \c mockImports variable. So they only stay in the
        \QDS space and are not converted with CMake Generator.

        Example:

        \code
            mockImports: [ "MockDatas" ]
        \endcode

        Here, \c MockDatas is a folder in your project folder with all QML mock data files. If you
        include this code in the \c .qmlproject file, CMake Generator ignores everything inside
        the \c MockDatas folder.

        \section1 Manually changing the contents of the \c CMakeLists.txt files

        You can change the \c CMakeLists.txt files in the
        \c App and the \c Root folders of your project. The \c CMakeLists.txt files
        in other folders of your project are overwritten when
        CMake generator runs next time. Only the \c CMakeLists.txt files in
        the \c App and the \c Root folders of your project are not overwritten.

        \section1 Changes in the project structure since \QDS 4.5

        The \QDS project structure was changed in \QDS 4.5. Now, there is
        only a common import path (\c{./}) in the root of the project. This makes
        the project in line with the QML compiler and tooling. To learn more about
        the QML compiler, see \l {Qt Quick Compiler}.

        The differences between the project structures:

        \table
            \header
                \li Project structure before \QDS 4.5
                \li Project structure since \QDS 4.5
            \row
                \li Two import folders: \c imports and \c assets_imports.
                \li Imports directly to the root project folder.
            \row
                \li 2D assets imported to \c assets _imports.
                \li 2D assets imported to \c Generated.
            \row
                \li 3D assets imported to \c assets_imports/QtQuick3DAssets.
                \li 3D assets imported to \c Generated/QtQuick3D.
        \endtable

        \section1 Converting a project to the current \QDS project structure

        To convert the structure of a project created with \QDS 4.5 or earlier to the current
        project structure:

        \list 1
            \li Move the project files from \c ./import/ProjectName to \c ./ProjectName. If you
            have additional modules in \c {./import/}, move them too. You do not need to adjust the
            URI.
            \li Move the project files from \c ./assets_imports to \c ./Generated. Adjust the import
                URIs throughout the project.
            \li Rename \c ./content to \c ./<ProjectName>Content. Adjust the import URIs throughout
                the project.
            \li Make sure that URIs in \c qmldir files match the folder structure.
                \note  A qmldir defined in \c ./Generated/QtQuick3D/DangerArrow/qmldir
                should be defined as \c {module Generated.QtQuick3D.DangerArrow}.
                This ensures the same URIs between \QDS and the generated
                \c CMakeLists files. Ensure that \c import in \c .qml files
                matches these URIs.
            \li Add missing filters to the \c .qmlproject file.
                \list
                    \li If a folder contains QML and JavaScript files, define
                        \c QMLFiles and \c JavaScriptFiles in the \c .qmlproject file.
                    \li For the files that don't have dedicated keywords, such as
                        \c ImageFiles or \c FontFiles, add them to the
                        \c .qmlproject as a filter. To add WAV or MP3 files,
                        define filters in the \c .qmlproject file like this:
                        \code
                           Files {
                                filter: "*.wav;*.mp3"
                            }
                        \endcode
                        To learn more about the defined file formats, see
                        \l {https://doc.qt.io/archives/QtForMCUs-2.5/qtul-qmlproject-reference.html#imagefiles}.
                \endlist
            \li Remove all the \c CMakeLists.txt files. The \c CMakeLists.txt files are
                automatically generated when you access CMake generation using
                \uicontrol File > \uicontrol {Export Project} >
                \uicontrol {Enable CMake Generator}.
            \li In the \c examples/dataImports/DataModels/ folder, update the
                \c ExamplesModel.qml and \c ExamplesModelV2.qml files to reflect
                \c qmlFileName correctly after a successful CMake generation.
            \li If the project uses shaders, add the following snippet to the
                \c .qmlproject file:
                \code
                    ShaderTool {
                        args: "-s --glsl \"100 es,120,150\" --hlsl 50 --msl 12"
                        files: [ "UntitledProject3DContent/shaders/*" ]
                        }
                \endcode
        \endlist

        \section1 Importing Qt Quick Designer Components with CMake Generator

        Some Qt Quick components, such as \uicontrol {Pie}, \uicontrol {Regular Polygon}, and
        \uicontrol Star, are exclucive to \QDS. For more information, see
        \l {https://doc.qt.io/qtquickstudiocomponents/qtquickstudio-components-index.html}{Qt Quick Studio Components}.

        You find these components in the \c Dependencies folder after the CMake generation.

        In previous versions of \QDS, you had to manually include these components
        from a \l {https://github.com/qt-labs/qtquickdesigner-components}{git repository}
        after the CMake generation.

        \image studio-cmake-dependencies.webp {The Dependencies folder with all the exclusive Qt Design Studio components after CMake generation.}

*/
