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

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \page creator-project-generic.html
    \previouspage creator-reference.html

    \ingroup creator-how-to-projects

    \title Import an existing project

    Import existing projects that do not use CMake, qmake, or one of the other
    directly supported build tools to use \QC as a code editor and to fully
    control the steps and commands for building the project.
    To change the way the project is built, change the \c make command
    in the \uicontrol{Projects} mode under \uicontrol{Build Settings}.

    With the following files, you can specify which files belong to your project
    and which include directories or defines to pass to your compiler:
    \c {.files}, \c {.includes}, and \c {.config}.

    To import an existing generic project:

    \list 1

        \li Select \uicontrol File > \uicontrol{New Project} > \uicontrol{Import Project}
            > \uicontrol{Import Existing Project}.

        \li In \uicontrol{Import Existing Project}, enter the project name
            and select the location of the project file you want to import.

           \QC automatically generates the following files in the
           project directory and shows them in the \l Projects view:

           \list

               \li  \c {.files}

               \li  \c {.includes}

               \li  \c {.config}

               \li  \c .creator

               \li  \c {.cflags}

               \li  \c {.cxxflags}

           \endlist

    \endlist

    The \c .creator file is considered the \e {project file}, so you need to open
    it when you want to open the project later.

    \section1 Specify files

    For a generic project, you have to manually specify which files belong to
    your project in the \c {.files} file. When you import a generic project,
    \QC adds any files it recognizes to your project.

    To add or remove files, edit the \c {.files} file in \QC. \QC updates the
    contents of \uicontrol Projects when you save the \c {.files} file.
    Or, use the context menu in \uicontrol Projects to add and remove files or
    directories.

    \section2 Use a script

    If you frequently need to update the \c {.files} file, use a script. If the
    file is modified externally, you have to close and reopen the project for the
    changes to take effect.

    To update the \c {.files} file in the \uicontrol Git repository, use the
    following script:

    \code
    git ls-files "*.cpp" "*.h" > MyProject.files
    \endcode

    \section2 Precompiled headers

    To use precompiled headers in a generic project, add the \c pch tag after
    a file path in the \c .files file, separated by the pipe character (|).
    For example:

    \badcode
    src/pch.h|pch
    \endcode

    \section1 Specify include paths and framework paths

    Specify include paths in the \c {.includes} file, one include
    path per line. The paths can be either absolute or relative to the
    \c {.includes} file.

    Lines starting with \c -F are interpreted as framework paths.

    \section1 Specify defines

    Specify defines in the \c {.config} file. It is
    a regular C++ file, prepended to all your source files when they are parsed.
    Only use the \c {.config} file to add lines as in the example below:

    \code
    #define NAME value
    \endcode

    \section1 Forward flags to Clang code model

    The \c {.cxxflags} and \c {.cflags} files have command-line flags for the
    Clang code model on a single line.

    For example, add the \c {-std=c++11} line to set the language version
    for parsing as C++11.

    \section1 Provide deployment information

    To run an application on a remote Linux device,
    you first need to deploy your executable and possibly other files.
    \QC does that for you automatically if you enter the necessary
    information. This works the same way as explained for CMake in
    \l {Remote Linux Deploy Configuration},
    except that you also need to include your application binary in the list.

    \section1 Create a run configuration

    \QC cannot automatically determine which executable to run, so you must
    set the executable in \uicontrol {Projects} > \uicontrol {Run} >
    \uicontrol Add > \uicontrol {Custom Executable}.

    \sa {Specify a custom executable to run},  {Use project wizards},
    {Configuring Projects}
*/
